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///////////////////////////////////////////////////
18// Mosaic.h
19// S.O. # :
20// Author(s): zkira
21// $Id: Mosaic.h,v 1.16 2011/06/24 04:22:14 mbansal Exp $
22
23#ifndef MOSAIC_H
24#define MOSAIC_H
25
26#include "ImageUtils.h"
27#include "AlignFeatures.h"
28#include "Blend.h"
29#include "MosaicTypes.h"
30
31/*! \mainpage Mosaic
32
33    \section intro Introduction
34    The class Mosaic provides a simple interface to the panoramic mosaicing algorithm. The class allows passing in individual image frames to be stitched together, computes the alignment transformation between them, and then stitches and blends them together into a single panoramic output which can then be accessed as a single image. \
35
36    \section usage Usage
37    The class methods need to be called as outlined in the sample application which is created from the mosaic_main.cpp file in the directory src/mosaic/. A brief snapshot of the flow is given below:
38
39    \code
40    Mosaic mosaic;
41    // Define blending types to use, and the frame dimensions
42    int blendingType = Blend::BLEND_TYPE_CYLPAN;
43    int stripType = Blend::STRIP_TYPE_THIN;
44    int width = 640;
45    int height = 480;
46
47    while (<image frames are available>)
48    {
49        // Check for initialization and if not, initialize
50        if (!mosaic.isInitialized())
51        {
52          // Initialize mosaic processing
53          mosaic.initialize(blendingType, stripType, width, height, -1, false, 5.0f);
54        }
55
56        // Add to list of frames
57        mosaic.addFrameRGB(imageRGB);
58
59        // Free image
60        ImageUtils::freeImage(imageRGB);
61    }
62
63    // Create the mosaic
64    ret = mosaic.createMosaic();
65
66    // Get back the result
67    resultYVU = mosaic.getMosaic(mosaicWidth, mosaicHeight);
68
69    printf("Got mosaic of size %d,%d\n", mosaicWidth, mosaicHeight);
70
71    \endcode
72*/
73
74/*!
75 *  Main class that creates a mosaic by creating an aligner and blender.
76 */
77class Mosaic
78{
79
80public:
81
82  Mosaic();
83  ~Mosaic();
84
85   /*!
86    *   Creates the aligner and blender and initializes state.
87    *   \param blendingType Type of blending to perform
88    *   \param stripType    Type of strip to use. 0: thin, 1: wide. stripType
89    *                       is effective only when blendingType is CylPan or
90    *                       Horz. Otherwise, it is set to thin irrespective of the input.
91    *   \param width        Width of input images (note: all images must be same size)
92    *   \param height       Height of input images (note: all images must be same size)
93    *   \param nframes      Number of frames to pre-allocate; default value -1 will allocate each frame as it comes
94    *   \param quarter_res  Whether to compute alignment at quarter the input resolution (default = false)
95    *   \param thresh_still Minimum number of pixels of translation detected between the new frame and the last frame before this frame is added to be mosaiced. For the low-res processing at 320x180 resolution input, we set this to 5 pixels. To reject no frames, set this to 0.0 (default value).
96    *   \return             Return code signifying success or failure.
97    */
98  int initialize(int blendingType, int stripType, int width, int height, int nframes = -1, bool quarter_res = false, float thresh_still = 0.0);
99
100   /*!
101    *   Adds a YVU frame to the mosaic.
102    *   \param imageYVU     Pointer to a YVU image.
103    *   \return             Return code signifying success or failure.
104    */
105  int addFrame(ImageType imageYVU);
106
107   /*!
108    *   Adds a RGB frame to the mosaic.
109    *   \param imageRGB     Pointer to a RGB image.
110    *   \return             Return code signifying success or failure.
111    */
112  int addFrameRGB(ImageType imageRGB);
113
114   /*!
115    *   After adding all frames, call this function to perform the final blending.
116    *   \param progress     Variable to set the current progress in.
117    *   \return             Return code signifying success or failure.
118    */
119  int createMosaic(float &progress, bool &cancelComputation);
120
121    /*!
122    *   Obtains the resulting mosaic and its dimensions.
123    *   \param width        Width of the resulting mosaic (returned)
124    *   \param height       Height of the resulting mosaic (returned)
125    *   \return             Pointer to image.
126    */
127  ImageType getMosaic(int &width, int &height);
128
129    /*!
130    *   Provides access to the internal alignment object pointer.
131    *   \return             Pointer to the aligner object.
132    */
133  Align* getAligner() { return aligner; }
134
135    /*!
136    *   Obtain initialization state.
137    *
138    *   return              Returns true if initialized, false otherwise.
139    */
140  bool isInitialized() { return initialized; }
141
142
143  /*!
144   *  Return codes for mosaic.
145   */
146  static const int MOSAIC_RET_OK    = 1;
147  static const int MOSAIC_RET_ERROR = -1;
148  static const int MOSAIC_RET_CANCELLED = -2;
149  static const int MOSAIC_RET_LOW_TEXTURE = -3;
150  static const int MOSAIC_RET_FEW_INLIERS = 2;
151
152protected:
153
154  /**
155   * Size of image frames making up mosaic
156   */
157  int width, height;
158
159  /**
160   * Size of actual mosaic
161   */
162  int mosaicWidth, mosaicHeight;
163
164  /**
165   * Bounding box to crop the mosaic when the gray border is not desired.
166   */
167  MosaicRect mosaicCroppingRect;
168
169  ImageType imageMosaicYVU;
170
171  /**
172   * Collection of frames that will make up mosaic.
173   */
174  MosaicFrame **frames;
175
176  /**
177    * Subset of frames that are considered as relevant.
178    */
179  MosaicFrame **rframes;
180
181  int frames_size;
182  int max_frames;
183
184  /**
185   * Initialization state.
186   */
187  bool initialized;
188
189  /**
190   *  Type of blending to perform.
191   */
192  int blendingType;
193
194  /**
195    * Type of strip to use. 0: thin (default), 1: wide
196    */
197  int stripType;
198
199  /**
200   *  Pointer to aligner.
201   */
202  Align *aligner;
203
204  /**
205   *  Pointer to blender.
206   */
207  Blend *blender;
208
209  /**
210   *  Modifies TRS matrices so that rotations are balanced
211   *  about center of mosaic
212   *
213   * Side effect: TRS matrices of all mosaic frames
214   *              are modified
215   */
216  int balanceRotations();
217
218};
219
220#endif
221