Main MRPT website > C++ reference
MRPT logo

types.h

Go to the documentation of this file.
00001 /* +---------------------------------------------------------------------------+
00002    |          The Mobile Robot Programming Toolkit (MRPT) C++ library          |
00003    |                                                                           |
00004    |                   http://mrpt.sourceforge.net/                            |
00005    |                                                                           |
00006    |   Copyright (C) 2005-2011  University of Malaga                           |
00007    |                                                                           |
00008    |    This software was written by the Machine Perception and Intelligent    |
00009    |      Robotics Lab, University of Malaga (Spain).                          |
00010    |    Contact: Jose-Luis Blanco  <jlblanco@ctima.uma.es>                     |
00011    |                                                                           |
00012    |  This file is part of the MRPT project.                                   |
00013    |                                                                           |
00014    |     MRPT is free software: you can redistribute it and/or modify          |
00015    |     it under the terms of the GNU General Public License as published by  |
00016    |     the Free Software Foundation, either version 3 of the License, or     |
00017    |     (at your option) any later version.                                   |
00018    |                                                                           |
00019    |   MRPT is distributed in the hope that it will be useful,                 |
00020    |     but WITHOUT ANY WARRANTY; without even the implied warranty of        |
00021    |     MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the         |
00022    |     GNU General Public License for more details.                          |
00023    |                                                                           |
00024    |     You should have received a copy of the GNU General Public License     |
00025    |     along with MRPT.  If not, see <http://www.gnu.org/licenses/>.         |
00026    |                                                                           |
00027    +---------------------------------------------------------------------------+ */
00028 
00029 #ifndef mrpt_vision_types_H
00030 #define mrpt_vision_types_H
00031 
00032 #include <mrpt/utils/CImage.h>
00033 #include <mrpt/utils/CLoadableOptions.h>
00034 #include <mrpt/utils/TMatchingPair.h>
00035 
00036 #include <mrpt/vision/link_pragmas.h>
00037 
00038 namespace mrpt
00039 {
00040         namespace vision
00041         {
00042                 using std::vector;
00043                 using namespace mrpt::slam;
00044                 using namespace mrpt::math;
00045                 using namespace mrpt::utils;
00046 
00047 
00048                 typedef uint64_t TLandmarkID;   //!< Unique IDs for landmarks
00049                 typedef uint64_t TCameraPoseID; //!< Unique IDs for camera frames (poses)
00050 
00051                 typedef std::map<TCameraPoseID,CPose3D>  TFramePosesMap;        //!< A list of camera frames (6D poses) indexed by unique IDs.
00052                 typedef std::vector<CPose3D>             TFramePosesVec;        //!< A list of camera frames (6D poses), which assumes indexes are unique, consecutive IDs.
00053 
00054                 typedef std::map<TLandmarkID,TPoint3D>   TLandmarkLocationsMap; //!< A list of landmarks (3D points) indexed by unique IDs.
00055                 typedef std::vector<TPoint3D>            TLandmarkLocationsVec; //!< A list of landmarks (3D points), which assumes indexes are unique, consecutive IDs.
00056 
00057                 /** One feature observation entry, used within sequences with TSequenceFeatureObservations */
00058                 struct VISION_IMPEXP TFeatureObservation
00059                 {
00060                         inline TFeatureObservation() { }
00061                         inline TFeatureObservation(const TLandmarkID _id_feature, const TCameraPoseID  _id_frame, const TPixelCoordf _px) : id_feature(_id_feature), id_frame(_id_frame), px(_px) { }
00062 
00063                         TLandmarkID    id_feature;  //!< A unique ID of this feature
00064                         TCameraPoseID  id_frame;    //!< A unique ID of a "frame" (camera position) from where the feature was observed.
00065                         TPixelCoordf   px;          //!< The pixel coordinates of the observed feature
00066                 };
00067 
00068                 /** One relative feature observation entry, used with some relative bundle-adjustment functions.
00069                   */
00070                 struct TRelativeFeaturePos
00071                 {
00072                         inline TRelativeFeaturePos() { }
00073                         inline TRelativeFeaturePos(const mrpt::vision::TCameraPoseID  _id_frame_base, const mrpt::math::TPoint3D _pos) : id_frame_base(_id_frame_base), pos(_pos) {  }
00074 
00075                         mrpt::vision::TCameraPoseID  id_frame_base;     //!< The ID of the camera frame which is the coordinate reference of \a pos
00076                         mrpt::math::TPoint3D         pos;  //!< The (x,y,z) location of the feature, wrt to the camera frame \a id_frame_base
00077                 };
00078 
00079                 /** An index of feature IDs and their relative locations */
00080                 typedef std::map<mrpt::vision::TFeatureID, TRelativeFeaturePos>  TRelativeFeaturePosMap;
00081 
00082                 /** A complete sequence of observations of features from different camera frames (poses).
00083                   *  This structure is the input to some (Bundle-adjustment) methods in mrpt::vision
00084                   *  \note Pixel coordinates can be either "raw" or "undistorted". Read the doc of functions handling this structure to see what they expect.
00085                   *  \sa mrpt::vision::bundle_adj_full
00086                   */
00087                 struct VISION_IMPEXP TSequenceFeatureObservations : public std::vector<TFeatureObservation>
00088                 {
00089                         typedef std::vector<TFeatureObservation> BASE;
00090 
00091                         inline TSequenceFeatureObservations() {}
00092                         inline TSequenceFeatureObservations(size_t size) : BASE(size) {}
00093                         inline TSequenceFeatureObservations(const TSequenceFeatureObservations& o) : BASE(o) {}
00094 
00095                         /** Saves all entries to a text file, with each line having this format: #FRAME_ID  #FEAT_ID  #PIXEL_X  #PIXEL_Y
00096                           * The file is self-descripting, since the first line contains a comment line (starting with '%') explaining the format.
00097                           * Generated files can be loaded from MATLAB.
00098                           * \sa loadFromTextFile \exception std::exception On I/O error  */
00099                         void saveToTextFile(const std::string &filName, bool skipFirstCommentLine = false) const;
00100 
00101                         /** Load from a text file, in the format described in \a saveToTextFile \exception std::exception On I/O or format error */
00102                         void loadFromTextFile(const std::string &filName);
00103 
00104                         /** Remove all those features that don't have a minimum number of observations from different camera frame IDs.
00105                           * \return the number of erased entries.
00106                           * \sa After calling this you may want to call \a compressIDs */
00107                         size_t removeFewObservedFeatures(size_t minNumObservations = 3);
00108 
00109                         /** Remove all but one out of \a decimate_ratio camera frame IDs from the list (eg: from N camera pose IDs at return there will be just N/decimate_ratio)
00110                           * The algorithm first builds a sorted list of frame IDs, then keep the lowest ID, remove the next "decimate_ratio-1", and so on.
00111                           * \sa After calling this you may want to call \a compressIDs */
00112                         void decimateCameraFrames(const size_t decimate_ratio);
00113 
00114                         /** Rearrange frame and feature IDs such as they start at 0 and there are no gaps.
00115                           * \param old2new_camIDs If provided, the mapping from old to new IDs is stored here.
00116                           * \param old2new_lmIDs If provided, the mapping from old to new IDs is stored here. */
00117                         void compressIDs(
00118                                 std::map<TCameraPoseID,TCameraPoseID>  *old2new_camIDs=NULL,
00119                                 std::map<TLandmarkID,TLandmarkID>      *old2new_lmIDs=NULL );
00120 
00121                 };
00122 
00123                 /** Data returned by  mrpt::vision::camera_calib_ba */
00124                 struct VISION_IMPEXP TCamCalibBAResults
00125                 {
00126                         std::vector<mrpt::poses::CPose3DQuat,Eigen::aligned_allocator<mrpt::poses::CPose3DQuat> >       camera_poses;
00127                         std::vector<mrpt::math::TPoint3D>               landmark_positions;
00128                 };
00129 
00130 
00131 
00132                 /** Parameters associated to a stereo system
00133                   */
00134                 struct VISION_IMPEXP TStereoSystemParams : public mrpt::utils::CLoadableOptions
00135                 {
00136                         /** Initilization of default parameters
00137                          */
00138                         TStereoSystemParams(    );
00139 
00140                         /** See utils::CLoadableOptions
00141                           */
00142                         void  loadFromConfigFile(
00143                                 const mrpt::utils::CConfigFileBase      &source,
00144                                 const std::string               &section);
00145 
00146                         /** See utils::CLoadableOptions
00147                           */
00148                         void  dumpToTextStream(CStream  &out) const;
00149 
00150                         /** Method for propagating the feature's image coordinate uncertainty into 3D space. Default value: Prop_Linear
00151                           */
00152                         enum TUnc_Prop_Method
00153                         {
00154                                 /** Linear propagation of the uncertainty
00155                                   */
00156                                 Prop_Linear = -1,
00157                                 /** Uncertainty propagation through the Unscented Transformation
00158                                   */
00159                                 Prop_UT,
00160                                 /** Uncertainty propagation through the Scaled Unscented Transformation
00161                                   */
00162                                 Prop_SUT
00163                         };
00164 
00165                         TUnc_Prop_Method uncPropagation;
00166 
00167                         /** Stereo Fundamental matrix */
00168                         CMatrixDouble33 F;
00169 
00170                         /** Intrinsic parameters
00171                           */
00172                         CMatrixDouble33 K;
00173                         /** Baseline. Default value: baseline = 0.119f; [Bumblebee]
00174                           */
00175                         float           baseline;
00176                         /** Standard deviation of the error in feature detection. Default value: stdPixel = 1
00177                           */
00178                         float           stdPixel;
00179                         /** Standard deviation of the error in disparity computation. Default value: stdDisp = 1
00180                           */
00181                         float           stdDisp;
00182                         /** Maximum allowed distance. Default value: maxZ = 20.0f
00183                           */
00184                         float           maxZ;
00185                         /** Maximum allowed distance. Default value: minZ = 0.5f
00186                           */
00187                         float           minZ;
00188                         /** Maximum allowed height. Default value: maxY = 3.0f
00189                           */
00190                         float           maxY;
00191                         /** K factor for the UT. Default value: k = 1.5f
00192                           */
00193                         float           factor_k;
00194                         /** Alpha factor for SUT. Default value: a = 1e-3
00195                           */
00196                         float           factor_a;
00197                         /** Beta factor for the SUT. Default value: b = 2.0f
00198                           */
00199                         float           factor_b;
00200 
00201                         /** Parameters initialization
00202                           */
00203                         //TStereoSystemParams();
00204 
00205                 }; // End struct TStereoSystemParams
00206 
00207                 /** A structure for storing a 3D ROI
00208                   */
00209                 struct VISION_IMPEXP TROI
00210                 {
00211                         // Constructors
00212                         TROI();
00213                         TROI(float x1, float x2, float y1, float y2, float z1, float z2);
00214 
00215                         // Members
00216                         float   xMin;
00217                         float   xMax;
00218                         float   yMin;
00219                         float   yMax;
00220                         float   zMin;
00221                         float   zMax;
00222                 }; // end struct TROI
00223 
00224                 /** A structure for defining a ROI within an image
00225                   */
00226                 struct VISION_IMPEXP TImageROI
00227                 {
00228                         // Constructors
00229                         TImageROI();
00230                         TImageROI( float x1, float x2, float y1, float y2 );
00231 
00232                         // Members
00233                         /** X coordinate limits [0,imageWidth)
00234                           */
00235                         float   xMin, xMax;
00236                         /** Y coordinate limits [0,imageHeight)
00237                           */
00238                         float   yMin, yMax;
00239                 }; // end struct TImageROI
00240 
00241                 /** A structure containing options for the matching
00242                   */
00243                 struct VISION_IMPEXP TMatchingOptions : public mrpt::utils::CLoadableOptions
00244                 {
00245 
00246                         /** Method for propagating the feature's image coordinate uncertainty into 3D space. Default value: Prop_Linear
00247                           */
00248                         enum TMatchingMethod
00249                         {
00250                                 /** Matching by cross correlation of the image patches
00251                                   */
00252                                 mmCorrelation = 0,
00253                                 /** Matching by Euclidean distance between SIFT descriptors
00254                                   */
00255                                 mmDescriptorSIFT,
00256                                 /** Matching by Euclidean distance between SURF descriptors
00257                                   */
00258                                 mmDescriptorSURF,
00259                                 /** Matching by sum of absolute differences of the image patches
00260                                   */
00261                                 mmSAD
00262                         };
00263 
00264                         // For determining
00265                         bool    useEpipolarRestriction;         //!< Whether or not take into account the epipolar restriction for finding correspondences
00266                         bool    hasFundamentalMatrix;           //!< Whether or not there is a fundamental matrix
00267                         bool    parallelOpticalAxis;            //!< Whether or not the stereo rig has the optical axes parallel
00268                         bool    useXRestriction;                        //!< Whether or not employ the x-coord restriction for finding correspondences (bumblebee camera, for example)
00269                         bool    addMatches;                 //!< Whether or not to add the matches found into the input matched list (if false the input list will be cleared before being filled with the new matches)
00270 
00271                         CMatrixDouble33 F;
00272 
00273                         // General
00274                         TMatchingMethod matching_method;        //!< Matching method
00275                         float   epipolar_TH;                            //!< Epipolar constraint (rows of pixels)
00276 
00277                         // SIFT
00278                         float   maxEDD_TH;                                      //!< Maximum Euclidean Distance Between SIFT Descriptors
00279                         float   EDD_RATIO;                                      //!< Boundary Ratio between the two lowest EDD
00280 
00281                         // KLT
00282                         float   minCC_TH;                                       //!< Minimum Value of the Cross Correlation
00283                         float   minDCC_TH;                                      //!< Minimum Difference Between the Maximum Cross Correlation Values
00284                         float   rCC_TH;                                         //!< Maximum Ratio Between the two highest CC values
00285 
00286                         // SURF
00287                         float   maxEDSD_TH;                                     //!< Maximum Euclidean Distance Between SURF Descriptors
00288                         float   EDSD_RATIO;                                     //!< Boundary Ratio between the two lowest SURF EDSD
00289 
00290                         // SAD
00291                         double  maxSAD_TH;                  //!< Minimum Euclidean Distance Between Sum of Absolute Differences
00292                         double  SAD_RATIO;                  //!< Boundary Ratio between the two highest SAD
00293 
00294 //                      // To estimate depth
00295                         bool    estimateDepth;              //!< Whether or not estimate the 3D position of the real features for the matches (only with parallelOpticalAxis by now).
00296                         double  maxDepthThreshold;          //!< The maximum allowed depth for the matching. If its computed depth is larger than this, the match won't be considered.
00297 //            double  fx,cx,cy,baseline;          //!< Intrinsic parameters of the stereo rig
00298 
00299                         /** Constructor
00300                           */
00301                         TMatchingOptions( );
00302 
00303                         /** See utils::CLoadableOptions
00304                           */
00305                         void  loadFromConfigFile(
00306                                 const mrpt::utils::CConfigFileBase      &source,
00307                                 const std::string               &section);
00308 
00309                         /** See utils::CLoadableOptions
00310                           */
00311                         void  dumpToTextStream(CStream  &out) const;
00312 
00313                 }; // end struct TMatchingOptions
00314 
00315         /** Struct containing the output after matching multi-resolution SIFT-like descriptors
00316                 */
00317         struct VISION_IMPEXP TMultiResMatchingOutput
00318         {
00319             int                     nMatches;
00320 
00321             std::vector<int>        firstListCorrespondences;    //!< Contains the indexes within the second list corresponding to the first one.
00322             std::vector<int>        secondListCorrespondences;   //!< Contains the indexes within the first list corresponding to the second one.
00323             std::vector<int>        firstListFoundScales;        //!< Contains the scales of the first list where the correspondence was found.
00324             std::vector<double>     firstListDistance;           //!< Contains the distances between the descriptors.
00325 
00326             TMultiResMatchingOutput() : nMatches(0),
00327                 firstListCorrespondences(), secondListCorrespondences(),
00328                 firstListFoundScales(), firstListDistance() {}
00329 
00330         }; // end struct TMultiResMatchingOutput
00331 
00332         /** Struct containing the options when matching multi-resolution SIFT-like descriptors
00333                 */
00334                 struct VISION_IMPEXP TMultiResDescMatchOptions : public mrpt::utils::CLoadableOptions
00335                 {
00336             bool            useOriFilter;           //!< Whether or not use the filter based on orientation test
00337             double          oriThreshold;           //!< The threshold for the orientation test
00338 
00339             bool            useDepthFilter;         //!< Whether or not use the filter based on the depth test
00340 
00341             double          matchingThreshold;      //!< The absolute threshold in descriptor distance for considering a match
00342             double          matchingRatioThreshold; //!< The ratio between the two lowest distances threshold for considering a match
00343             unsigned int    lowScl1, lowScl2;       //!< The lowest scales in the two features to be taken into account in the matching process
00344             unsigned int    highScl1, highScl2;     //!< The highest scales in the two features to be taken into account in the matching process
00345 
00346             int             searchAreaSize;         //!< Size of the squared area where to search for a match.
00347             int             lastSeenThreshold;      //!< The allowed number of frames since a certain feature was seen for the last time.
00348             int             timesSeenThreshold;     //!< The minimum number of frames for a certain feature to be considered stable.
00349 
00350             int             minFeaturesToFind;      //!< The minimum number of features allowed in the system. If current number is below this value, more features will be found.
00351             int             minFeaturesToBeLost;    //!< The minimum number of features allowed in the system to not be considered to be lost.
00352 
00353             /** Default constructor
00354               */
00355             TMultiResDescMatchOptions() :
00356                 useOriFilter( true ), oriThreshold( 0.2 ),
00357                 useDepthFilter( true ), matchingThreshold( 1e4 ), matchingRatioThreshold( 0.5 ),
00358                 lowScl1(0), lowScl2(0), highScl1(6), highScl2(6), searchAreaSize(20), lastSeenThreshold(10), timesSeenThreshold(5),
00359                 minFeaturesToFind(30), minFeaturesToBeLost(5) {}
00360 
00361             TMultiResDescMatchOptions(
00362                 const bool &_useOriFilter, const double &_oriThreshold, const bool &_useDepthFilter,
00363                 const double &_th, const double &_th2, const unsigned int &_lwscl1, const unsigned int &_lwscl2,
00364                 const unsigned int &_hwscl1, const unsigned int &_hwscl2, const int &_searchAreaSize, const int &_lsth, const int &_tsth,
00365                 const int &_minFeaturesToFind, const int &_minFeaturesToBeLost ) :
00366                 useOriFilter( _useOriFilter ), oriThreshold( _oriThreshold ), useDepthFilter( _useDepthFilter ),
00367                 matchingThreshold ( _th ), matchingRatioThreshold ( _th2 ), lowScl1( _lwscl1 ), lowScl2( _lwscl2 ),
00368                 highScl1( _hwscl1 ), highScl2( _hwscl2 ), searchAreaSize( _searchAreaSize ), lastSeenThreshold( _lsth ), timesSeenThreshold( _tsth ),
00369                 minFeaturesToFind( _minFeaturesToFind ), minFeaturesToBeLost(_minFeaturesToBeLost)  {}
00370 
00371             void  loadFromConfigFile( const mrpt::utils::CConfigFileBase &cfg, const std::string &section );
00372                         void  saveToConfigFile( mrpt::utils::CConfigFileBase &cfg, const std::string &section );
00373             void  dumpToTextStream( mrpt::utils::CStream &out) const;
00374 
00375                 }; // end TMultiResDescMatchOptions
00376 
00377         /** Struct containing the options when computing the multi-resolution SIFT-like descriptors
00378                 */
00379         struct VISION_IMPEXP TMultiResDescOptions : public mrpt::utils::CLoadableOptions
00380         {
00381             unsigned int    basePSize;          //!< The size of the base patch
00382             vector<double>  scales;             //!< The set of scales relatives to the base patch
00383             unsigned int    comLScl, comHScl;   //!< The subset of scales for which to compute the descriptors
00384             double          sg1, sg2, sg3;      //!< The sigmas for the Gaussian kernels
00385             bool            computeDepth;       //!< Whether or not compute the depth of the feature
00386             double          fx,cx,cy,baseline;  //!< Intrinsic stereo pair parameters for computing the depth of the feature
00387             bool            computeHashCoeffs;  //!< Whether or not compute the coefficients for mantaining a HASH table of descriptors (for relocalization)
00388 
00389             double          cropValue;          //!< The SIFT-like descriptor is cropped at this value during normalization
00390 
00391             /** Default constructor
00392               */
00393             TMultiResDescOptions() :
00394                 basePSize(23), sg1 (0.5), sg2(7.5), sg3(8.0), computeDepth(true), fx(0.0), cx(0.0), cy(0.0), baseline(0.0), computeHashCoeffs(false), cropValue(0.2)
00395             {
00396                 scales.resize(7);
00397                 scales[0] = 0.5;
00398                 scales[1] = 0.8;
00399                 scales[2] = 1.0;
00400                 scales[3] = 1.2;
00401                 scales[4] = 1.5;
00402                 scales[5] = 1.8;
00403                 scales[6] = 2.0;
00404                 comLScl = 0;
00405                 comHScl = 6;
00406             }
00407 
00408             TMultiResDescOptions( const unsigned int &_basePSize, const vector<double> &_scales,
00409                 const unsigned int &_comLScl, const unsigned int &_comHScl,
00410                 const double &_sg1, const double &_sg2, const double &_sg3,
00411                 const bool &_computeDepth, const double &_fx, const double &_cx, const double &_cy, const double &_baseline, const bool &_computeHashCoeffs, const double &_cropValue ):
00412                 basePSize( _basePSize ), comLScl( _comLScl ), comHScl( _comHScl ),
00413                 sg1( _sg1 ), sg2( _sg2 ), sg3( _sg3 ),
00414                 computeDepth( _computeDepth ), fx( _fx ), cx( _cx ), cy( _cy ), baseline( _baseline ), computeHashCoeffs( _computeHashCoeffs), cropValue( _cropValue )
00415             {
00416                 scales.resize( _scales.size() );
00417                 for(unsigned int k = 0; k < _scales.size(); ++k)
00418                     scales[k] = _scales[k];
00419             }
00420 
00421             void  loadFromConfigFile( const mrpt::utils::CConfigFileBase &cfg, const std::string &section );
00422                         void  saveToConfigFile( mrpt::utils::CConfigFileBase &cfg, const std::string &section );
00423             void  dumpToTextStream( mrpt::utils::CStream &out) const;
00424 
00425         }; // end TMultiResDescOptions
00426 
00427 
00428         }
00429 }
00430 
00431 
00432 #endif



Page generated by Doxygen 1.7.3 for MRPT 0.9.4 SVN: at Sat Mar 26 06:16:28 UTC 2011