Planar tracker polish.
[blender.git] / extern / libmv / libmv / tracking / track_region.h
1 // Copyright (c) 2012 libmv authors.
2 //
3 // Permission is hereby granted, free of charge, to any person obtaining a copy
4 // of this software and associated documentation files (the "Software"), to
5 // deal in the Software without restriction, including without limitation the
6 // rights to use, copy, modify, merge, publish, distribute, sublicense, and/or
7 // sell copies of the Software, and to permit persons to whom the Software is
8 // furnished to do so, subject to the following conditions:
9 //
10 // The above copyright notice and this permission notice shall be included in
11 // all copies or substantial portions of the Software.
12 //
13 // THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
14 // IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
15 // FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
16 // AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
17 // LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING
18 // FROM, OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS
19 // IN THE SOFTWARE.
20
21 #ifndef LIBMV_TRACKING_TRACK_REGION_H_
22
23 // Necessary for M_E when building with MSVC.
24 #define _USE_MATH_DEFINES
25
26 #include "libmv/tracking/esm_region_tracker.h"
27
28 #include "libmv/image/image.h"
29 #include "libmv/image/sample.h"
30 #include "libmv/numeric/numeric.h"
31
32 namespace libmv {
33
34 struct TrackRegionOptions {
35   TrackRegionOptions();
36
37   enum Mode {
38     TRANSLATION,
39     TRANSLATION_ROTATION,
40     TRANSLATION_SCALE,
41     TRANSLATION_ROTATION_SCALE,
42     AFFINE,
43     HOMOGRAPHY,
44   };
45   Mode mode;
46
47   double minimum_correlation;
48   int max_iterations;
49
50   // Use the "Efficient Second-order Minimization" scheme. This increases
51   // convergence speed at the cost of more per-iteration work.
52   bool use_esm;
53
54   // If true, apply a brute-force translation-only search before attempting the
55   // full search. This is not enabled if the destination image ("image2") is
56   // too small; in that case eithen the basin of attraction is close enough
57   // that the nearby minima is correct, or the search area is too small.
58   bool use_brute_initialization;
59
60   // If true, normalize the image patches by their mean before doing the sum of
61   // squared error calculation. This is reasonable since the effect of
62   // increasing light intensity is multiplicative on the pixel intensities.
63   //
64   // Note: This does nearly double the solving time, so it is not advised to
65   // turn this on all the time.
66   bool use_normalized_intensities;
67
68   // The size in pixels of the blur kernel used to both smooth the image and
69   // take the image derivative.
70   double sigma;
71
72   // Extra points that should get transformed by the warp. This is useful
73   // because the actual warp parameters are not exposed.
74   int num_extra_points;
75
76   // If non-null, this is used as the pattern mask. It should match the size of
77   // image1, even though only values inside the image1 quad are examined. The
78   // values must be in the range 0.0 to 0.1.
79   FloatImage *image1_mask;
80 };
81
82 struct TrackRegionResult {
83   enum Termination {
84     // Ceres termination types, duplicated; though, not the int values.
85     PARAMETER_TOLERANCE,
86     FUNCTION_TOLERANCE,
87     GRADIENT_TOLERANCE,
88     NO_CONVERGENCE,
89     DID_NOT_RUN,
90     NUMERICAL_FAILURE,
91
92     // Libmv specific errors.
93     SOURCE_OUT_OF_BOUNDS,
94     DESTINATION_OUT_OF_BOUNDS,
95     FELL_OUT_OF_BOUNDS,
96     INSUFFICIENT_CORRELATION,
97     CONFIGURATION_ERROR,
98   };
99   Termination termination;
100
101   int num_iterations;
102   double correlation;
103
104   // Final parameters?
105   bool used_brute_translation_initialization;
106 };
107
108 // Always needs 4 correspondences.
109 void TrackRegion(const FloatImage &image1,
110                  const FloatImage &image2,
111                  const double *x1, const double *y1,
112                  const TrackRegionOptions &options,
113                  double *x2, double *y2,
114                  TrackRegionResult *result);
115
116 // Sample a "canonical" version of the passed planar patch, using bilinear
117 // sampling. The passed corners must be within the image, and have at least two
118 // pixels of border around them. (so e.g. a corner of the patch cannot lie
119 // directly on the edge of the image). Four corners are always required. All
120 // channels are interpolated.
121 bool SamplePlanarPatch(const FloatImage &image,
122                        const double *xs, const double *ys,
123                        int num_samples_x, int num_samples_y,
124                        FloatImage *patch);
125
126 }  // namespace libmv
127
128 #endif  // LIBMV_TRACKING_TRACK_REGION_H_