Home | History | Annotate | Download | only in camera
      1 /*
      2  * Copyright (C) 2013 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;
     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_mosaic");
     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      */
    105     public native void allocateMosaicMemory(int width, int height);
    106 
    107     /**
    108      * Free memory allocated by allocateMosaicMemory.
    109      *
    110      */
    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      */
    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      */
    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      */
    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      */
    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      */
    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      */
    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      */
    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      */
    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      */
    205     public native int reportProgress(boolean hires, boolean cancelComputation);
    206 }
    207