Mosaic.h revision b28b9c0fa991bc97e8aa11da83d27f71fdfef6da 
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
150protected:
151
152  /**
153   * Size of image frames making up mosaic
154   */
155  int width, height;
156
157  /**
158   * Size of actual mosaic
159   */
160  int mosaicWidth, mosaicHeight;
161
162  /**
163   * Bounding box to crop the mosaic when the gray border is not desired.
164   */
165  MosaicRect mosaicCroppingRect;
166
167  ImageType imageMosaicYVU;
168
169  /**
170   * Collection of frames that will make up mosaic.
171   */
172  MosaicFrame **frames;
173
174  /**
175    * Subset of frames that are considered as relevant.
176    */
177  MosaicFrame **rframes;
178
179  int frames_size;
180  int max_frames;
181
182  /**
183   * Initialization state.
184   */
185  bool initialized;
186
187  /**
188   *  Type of blending to perform.
189   */
190  int blendingType;
191
192  /**
193    * Type of strip to use. 0: thin (default), 1: wide
194    */
195  int stripType;
196
197  /**
198   *  Pointer to aligner.
199   */
200  Align *aligner;
201
202  /**
203   *  Pointer to blender.
204   */
205  Blend *blender;
206
207  /**
208   *  Modifies TRS matrices so that rotations are balanced
209   *  about center of mosaic
210   *
211   * Side effect: TRS matrices of all mosaic frames
212   *              are modified
213   */
214  int balanceRotations();
215
216};
217
218#endif
219