1 /*
2  * Copyright (C) 2011 The Android Open Source Project
3  *
4  * Licensed under the Apache License, Version 2.0 (the "License");
5  * you may not use this file except in compliance with the License.
6  * You may obtain a copy of the License at
7  *
8  *      http://www.apache.org/licenses/LICENSE-2.0
9  *
10  * Unless required by applicable law or agreed to in writing, software
11  * distributed under the License is distributed on an "AS IS" BASIS,
12  * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
13  * See the License for the specific language governing permissions and
14  * limitations under the License.
15  */
16 
17 package com.android.camera.panorama;
18 
19 /**
20  * The Java interface to JNI calls regarding mosaic stitching.
21  *
22  * A high-level usage is:
23  *
24  * Mosaic mosaic = new Mosaic();
25  * mosaic.setSourceImageDimensions(width, height);
26  * mosaic.reset(blendType);
27  *
28  * while ((pixels = hasNextImage()) != null) {
29  *    mosaic.setSourceImage(pixels);
30  * }
31  *
32  * mosaic.createMosaic(highRes);
33  * byte[] result = mosaic.getFinalMosaic();
34  *
35  */
36 public class Mosaic {
37     /**
38      * In this mode, the images are stitched together in the same spatial arrangement as acquired
39      * i.e. if the user follows a curvy trajectory, the image boundary of the resulting mosaic will
40      * be curved in the same manner. This mode is useful if the user wants to capture a mosaic as
41      * if "painting" the scene using the smart-phone device and does not want any corrective warps
42      * to distort the captured images.
43      */
44     public static final int BLENDTYPE_FULL = 0;
45 
46     /**
47      * This mode is the same as BLENDTYPE_FULL except that the resulting mosaic is rotated
48      * to balance the first and last images to be approximately at the same vertical offset in the
49      * output mosaic. This is useful when acquiring a mosaic by a typical panning-like motion to
50      * remove a one-sided curve in the mosaic (typically due to the camera not staying horizontal
51      * during the video capture) and convert it to a more symmetrical "smiley-face" like output.
52      */
53     public static final int BLENDTYPE_PAN = 1;
54 
55     /**
56      * This mode compensates for typical "smiley-face" like output in longer mosaics and creates
57      * a rectangular mosaic with minimal black borders (by unwrapping the mosaic onto an imaginary
58      * cylinder). If the user follows a curved trajectory (instead of a perfect panning trajectory),
59      * the resulting mosaic here may suffer from some image distortions in trying to map the
60      * trajectory to a cylinder.
61      */
62     public static final int BLENDTYPE_CYLINDERPAN = 2;
63 
64     /**
65      * This mode is basically BLENDTYPE_CYLINDERPAN plus doing a rectangle cropping before returning
66      * the mosaic. The mode is useful for making the resulting mosaic have a rectangle shape.
67      */
68     public static final int BLENDTYPE_HORIZONTAL =3;
69 
70     /**
71      * This strip type will use the default thin strips where the strips are
72      * spaced according to the image capture rate.
73      */
74     public static final int STRIPTYPE_THIN = 0;
75 
76     /**
77      * This strip type will use wider strips for blending. The strip separation
78      * is controlled by a threshold on the native side. Since the strips are
79      * wider, there is an additional cross-fade blending step to make the seam
80      * boundaries smoother. Since this mode uses lesser image frames, it is
81      * computationally more efficient than the thin strip mode.
82      */
83     public static final int STRIPTYPE_WIDE = 1;
84 
85     /**
86      * Return flags returned by createMosaic() are one of the following.
87      */
88     public static final int MOSAIC_RET_OK = 1;
89     public static final int MOSAIC_RET_ERROR = -1;
90     public static final int MOSAIC_RET_CANCELLED = -2;
91     public static final int MOSAIC_RET_LOW_TEXTURE = -3;
92     public static final int MOSAIC_RET_FEW_INLIERS = 2;
93 
94 
95     static {
96         System.loadLibrary("jni_legacymosaic");
97     }
98 
99     /**
100      * Allocate memory for the image frames at the given resolution.
101      *
102      * @param width width of the input frames in pixels
103      * @param height height of the input frames in pixels
104      */
allocateMosaicMemory(int width, int height)105     public native void allocateMosaicMemory(int width, int height);
106 
107     /**
108      * Free memory allocated by allocateMosaicMemory.
109      *
110      */
freeMosaicMemory()111     public native void freeMosaicMemory();
112 
113     /**
114      * Pass the input image frame to the native layer. Each time the a new
115      * source image t is set, the transformation matrix from the first source
116      * image to t is computed and returned.
117      *
118      * @param pixels source image of NV21 format.
119      * @return Float array of length 11; first 9 entries correspond to the 3x3
120      *         transformation matrix between the first frame and the passed frame;
121      *         the 10th entry is the number of the passed frame, where the counting
122      *         starts from 1; and the 11th entry is the returning code, whose value
123      *         is one of those MOSAIC_RET_* returning flags defined above.
124      */
setSourceImage(byte[] pixels)125     public native float[] setSourceImage(byte[] pixels);
126 
127     /**
128      * This is an alternative to the setSourceImage function above. This should
129      * be called when the image data is already on the native side in a fixed
130      * byte array. In implementation, this array is filled by the GL thread
131      * using glReadPixels directly from GPU memory (where it is accessed by
132      * an associated SurfaceTexture).
133      *
134      * @return Float array of length 11; first 9 entries correspond to the 3x3
135      *         transformation matrix between the first frame and the passed frame;
136      *         the 10th entry is the number of the passed frame, where the counting
137      *         starts from 1; and the 11th entry is the returning code, whose value
138      *         is one of those MOSAIC_RET_* returning flags defined above.
139      */
setSourceImageFromGPU()140     public native float[] setSourceImageFromGPU();
141 
142     /**
143      * Set the type of blending.
144      *
145      * @param type the blending type defined in the class. {BLENDTYPE_FULL,
146      *        BLENDTYPE_PAN, BLENDTYPE_CYLINDERPAN, BLENDTYPE_HORIZONTAL}
147      */
setBlendingType(int type)148     public native void setBlendingType(int type);
149 
150     /**
151      * Set the type of strips to use for blending.
152      * @param type the blending strip type to use {STRIPTYPE_THIN,
153      * STRIPTYPE_WIDE}.
154      */
setStripType(int type)155     public native void setStripType(int type);
156 
157     /**
158      * Tell the native layer to create the final mosaic after all the input frame
159      * data have been collected.
160      * The case of generating high-resolution mosaic may take dozens of seconds to finish.
161      *
162      * @param value True means generating a high-resolution mosaic -
163      *        which is based on the original images set in setSourceImage().
164      *        False means generating a low-resolution version -
165      *        which is based on 1/4 downscaled images from the original images.
166      * @return Returns a status code suggesting if the mosaic building was
167      *        successful, in error, or was cancelled by the user.
168      */
createMosaic(boolean value)169     public native int createMosaic(boolean value);
170 
171     /**
172      * Get the data for the created mosaic.
173      *
174      * @return Returns an integer array which contains the final mosaic in the ARGB_8888 format.
175      *         The first MosaicWidth*MosaicHeight values contain the image data, followed by 2
176      *         integers corresponding to the values MosaicWidth and MosaicHeight respectively.
177      */
getFinalMosaic()178     public native int[] getFinalMosaic();
179 
180     /**
181      * Get the data for the created mosaic.
182      *
183      * @return Returns a byte array which contains the final mosaic in the NV21 format.
184      *         The first MosaicWidth*MosaicHeight*1.5 values contain the image data, followed by
185      *         8 bytes which pack the MosaicWidth and MosaicHeight integers into 4 bytes each
186      *         respectively.
187      */
getFinalMosaicNV21()188     public native byte[] getFinalMosaicNV21();
189 
190     /**
191      * Reset the state of the frame arrays which maintain the captured frame data.
192      * Also re-initializes the native mosaic object to make it ready for capturing a new mosaic.
193      */
reset()194     public native void reset();
195 
196     /**
197      * Get the progress status of the mosaic computation process.
198      * @param hires Boolean flag to select whether to report progress of the
199      *              low-res or high-res mosaicer.
200      * @param cancelComputation Boolean flag to allow cancelling the
201      *              mosaic computation when needed from the GUI end.
202      * @return Returns a number from 0-100 where 50 denotes that the mosaic
203      *          computation is 50% done.
204      */
reportProgress(boolean hires, boolean cancelComputation)205     public native int reportProgress(boolean hires, boolean cancelComputation);
206 }
207