Weighted tracks
[blender.git] / extern / libmv / libmv / simple_pipeline / tracks.h
1 // Copyright (c) 2011 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_SIMPLE_PIPELINE_TRACKS_H_
22 #define LIBMV_SIMPLE_PIPELINE_TRACKS_H_
23
24 #include "libmv/base/vector.h"
25 #include "libmv/numeric/numeric.h"
26
27 namespace libmv {
28
29 /*!
30     A Marker is the 2D location of a tracked point in an image.
31
32     \a x, \a y is the position of the marker in pixels from the top left corner
33     in the image identified by \a image. All markers for to the same target
34     form a track identified by a common \a track number.
35
36     \a weight is used by bundle adjustment and weight means how much the
37     track affects on a final solution.
38
39     \note Markers are typically aggregated with the help of the \l Tracks class.
40
41     \sa Tracks
42 */
43 // TODO(sergey): Consider using comment for every member separately
44 //               instead of having one giantic comment block.
45 struct Marker {
46   int image;
47   int track;
48   double x, y;
49   double weight;
50 };
51
52 /*!
53     The Tracks class stores \link Marker reconstruction markers \endlink.
54
55     The Tracks container is intended as the store of correspondences between
56     images, which must get created before any 3D reconstruction can take place.
57
58     The container has several fast lookups for queries typically needed for
59     structure from motion algorithms, such as \l MarkersForTracksInBothImages().
60
61     \sa Marker
62 */
63 class Tracks {
64  public:
65   Tracks() { }
66
67   // Copy constructor for a tracks object.
68   Tracks(const Tracks &other);
69
70   /// Construct a new tracks object using the given markers to start.
71   Tracks(const vector<Marker> &markers);
72
73   /*!
74       Inserts a marker into the set. If there is already a marker for the given
75       \a image and \a track, the existing marker is replaced. If there is no
76       marker for the given \a image and \a track, a new one is added.
77
78       \a image and \a track are the keys used to retrieve the markers with the
79       other methods in this class.
80
81       \a weight is used by bundle adjustment and weight means how much the
82       track affects on a final solution.
83
84       \note To get an identifier for a new track, use \l MaxTrack() + 1.
85   */
86   // TODO(sergey): Consider using InsetWeightedMarker istead of using
87   //               stupid default value?
88   void Insert(int image, int track, double x, double y, double weight = 1.0);
89
90   /// Returns all the markers.
91   vector<Marker> AllMarkers() const;
92
93   /// Returns all the markers belonging to a track.
94   vector<Marker> MarkersForTrack(int track) const;
95
96   /// Returns all the markers visible in \a image.
97   vector<Marker> MarkersInImage(int image) const;
98
99   /// Returns all the markers visible in \a image1 and \a image2.
100   vector<Marker> MarkersInBothImages(int image1, int image2) const;
101
102   /*!
103       Returns the markers in \a image1 and \a image2 which have a common track.
104
105       This is not the same as the union of the markers in \a image1 and \a
106       image2; each marker is for a track that appears in both images.
107   */
108   vector<Marker> MarkersForTracksInBothImages(int image1, int image2) const;
109
110   /// Returns the marker in \a image belonging to \a track.
111   Marker MarkerInImageForTrack(int image, int track) const;
112
113   /// Removes all the markers belonging to \a track.
114   void RemoveMarkersForTrack(int track);
115
116   /// Removes the marker in \a image belonging to \a track.
117   void RemoveMarker(int image, int track);
118
119   /// Returns the maximum image identifier used.
120   int MaxImage() const;
121
122   /// Returns the maximum track identifier used.
123   int MaxTrack() const;
124
125   /// Returns the number of markers.
126   int NumMarkers() const;
127
128  private:
129   vector<Marker> markers_;
130 };
131
132 void CoordinatesForMarkersInImage(const vector<Marker> &markers,
133                                   int image,
134                                   Mat *coordinates);
135
136 }  // namespace libmv
137
138 #endif  // LIBMV_SIMPLE_PIPELINE_MARKERS_H_