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 #ifndef CRawlog_H 00029 #define CRawlog_H 00030 00031 #include <mrpt/poses/CPose2D.h> 00032 #include <mrpt/slam/CSensoryFrame.h> 00033 #include <mrpt/slam/CActionCollection.h> 00034 #include <mrpt/slam/CObservationComment.h> 00035 #include <mrpt/utils/CConfigFileMemory.h> 00036 00037 00038 namespace mrpt 00039 { 00040 namespace slam 00041 { 00042 DEFINE_SERIALIZABLE_PRE_CUSTOM_BASE_LINKAGE( CRawlog, mrpt::utils::CSerializable, OBS_IMPEXP ) 00043 00044 using namespace mrpt::utils; 00045 00046 typedef std::pair<mrpt::system::TTimeStamp, CObservationPtr> TTimeObservationPair; //!< For usage with CRawlog classes. 00047 typedef std::multimap<mrpt::system::TTimeStamp, CObservationPtr> TListTimeAndObservations; //!< For usage with CRawlog classes. 00048 00049 00050 /** This class stores a rawlog (robotic datasets) in one of two possible formats: 00051 * - Format #1: A sequence of actions and observations. There is a sequence of objects, where each one can be of one type: 00052 * - An action: Implemented as a CActionCollection object, the actuation of the robot (i.e. odometry increment). 00053 * - Observations: Implemented as a CSensoryFrame, refering to a set of robot observations from the same pose. 00054 * - Format #2: A sequence of actions and observations. There is a sequence of objects, where each one can be of one type: 00055 * 00056 * Refer to the wiki page about <a href="http://www.mrpt.org/Rawlog_Format">rawlog files</a>. 00057 * 00058 * See also the application <a href="http://www.mrpt.org/Application:RawLogViewer" >RawLogViewer</a > for the GUI program that visualizes and manages rawlogs. 00059 * 00060 * This class also publishes a static helper method for loading rawlog files in format #1: see CRawlog::readActionObservationPair 00061 * 00062 * There is a field for comments and blocks of parameters (in ini-like format) accessible through getCommentText and setCommentText 00063 * (introduced in MRPT 0.6.4). When serialized to a rawlog file, the commens are saved as an additional observation of the 00064 * type CObservationComments at the beginning of the file, but this observation does not appear after loading for clarity. 00065 * 00066 * \note Since MRPT version 0.5.5, this class also provides a STL container-like interface (see CRawlog::begin, CRawlog::iterator, ...). 00067 * \note The format #2 is supported since MRPT version 0.6.0. 00068 * \note There is a static helper method "detectImagesDirectory" for localizing the external images directory of a rawlog. 00069 * 00070 * \sa CSensoryFrame, CPose2D, <a href="http://www.mrpt.org/Rawlog_Format">RawLog file format</a>. 00071 */ 00072 class OBS_IMPEXP CRawlog : public mrpt::utils::CSerializable 00073 { 00074 // This must be added to any CSerializable derived class: 00075 DEFINE_SERIALIZABLE( CRawlog ) 00076 00077 private: 00078 typedef std::vector<CSerializablePtr> TListObjects; 00079 TListObjects m_seqOfActObs; //!< The list where the objects really are in. 00080 00081 CObservationComment m_commentTexts; //!< Comments of the rawlog. 00082 00083 public: 00084 void getCommentText( std::string &t) const; //!< Returns the block of comment text for the rawlog 00085 std::string getCommentText() const; //!< Returns the block of comment text for the rawlog 00086 void setCommentText( const std::string &t); //!< Changes the block of comment text for the rawlog 00087 void getCommentTextAsConfigFile( mrpt::utils::CConfigFileMemory &memCfg ) const; //!< Saves the block of comment text for the rawlog into the passed config file object. 00088 00089 /** The type of each entry in a rawlog. 00090 * \sa CRawlog::getType 00091 */ 00092 enum TEntryType 00093 { 00094 etSensoryFrame = 0, 00095 etActionCollection, 00096 etObservation 00097 }; 00098 00099 /** Default constructor */ 00100 CRawlog(); 00101 00102 00103 /** Destructor: */ 00104 virtual ~CRawlog(); 00105 00106 /** Clear the sequence of actions/observations, freeing the memory of all the objects in the list. */ 00107 void clear(); 00108 00109 /** Clear the sequence of actions/observations, without deleting the objects themselves (USE ONLY IF YOU KNOW WHAT YOU DO, NORMALLY YOU'LL CALL "clear" INSTEAD). */ 00110 void clearWithoutDelete(); 00111 00112 /** Add an action to the sequence: a collection of just one element is created. 00113 * The object is duplicated, so the original one can be free if desired. 00114 */ 00115 void addAction( CAction &action ); 00116 00117 /** Add a set of actions to the sequence; the object is duplicated, so the original one can be free if desired. 00118 * \sa addObservations, addActionsMemoryReference 00119 */ 00120 void addActions( CActionCollection &action ); 00121 00122 /** Add a set of observations to the sequence; the object is duplicated, so the original one can be free if desired. 00123 * \sa addActions, addObservationsMemoryReference 00124 */ 00125 void addObservations( CSensoryFrame &observations ); 00126 00127 /** Add a set of actions to the sequence, using a smart pointer to the object to add. 00128 * \sa addActions, addObservationsMemoryReference, addObservationMemoryReference 00129 */ 00130 void addActionsMemoryReference( const CActionCollectionPtr &action ); 00131 00132 /** Add a set of observations to the sequence, using a smart pointer to the object to add. 00133 * \sa addObservations, addActionsMemoryReference, addObservationMemoryReference 00134 */ 00135 void addObservationsMemoryReference( const CSensoryFramePtr &observations ); 00136 00137 /** Add a single observation to the sequence, using a smart pointer to the object to add. 00138 * \sa addObservations, addActionsMemoryReference 00139 */ 00140 void addObservationMemoryReference( const CObservationPtr &observation ); 00141 00142 /** Load the contents from a file containing one of these possibilities: 00143 * - A "CRawlog" object. 00144 * - Directly the sequence of objects (pairs CSensoryFrame/CActionCollection or CObservation* objects). In this case the method stops reading on EOF of an unrecogniced class name. 00145 * \returns It returns false if the file does not exists. 00146 */ 00147 bool loadFromRawLogFile( const std::string &fileName ); 00148 00149 /** Saves the contents to a rawlog-file, compatible with RawlogViewer (As the sequence of internal objects). 00150 * The file is saved with gz-commpressed if MRPT has gz-streams. 00151 * \returns It returns false if the file does not exists. 00152 */ 00153 bool saveToRawLogFile( const std::string &fileName ) const; 00154 00155 /** Returns the number of actions / observations object in the sequence. */ 00156 size_t size() const; 00157 00158 /** Returns the type of a given element. 00159 * \sa isAction, isObservation 00160 */ 00161 TEntryType getType( size_t index ) const; 00162 00163 /** Delete the action or observation stored in the given index. 00164 * \exception std::exception If index is out of bounds 00165 */ 00166 void remove( size_t index ); 00167 00168 /** Delete the elements stored in the given range of indices (including both the first and last one). 00169 * \exception std::exception If any index is out of bounds 00170 */ 00171 void remove( size_t first_index, size_t last_index ); 00172 00173 /** Returns the i'th element in the sequence, as being actions, where index=0 is the first object. 00174 * If it is not a CActionCollection, it throws an exception. Do neighter modify nor delete the returned pointer. 00175 * \sa size, isAction, getAsObservations, getAsObservation 00176 * \exception std::exception If index is out of bounds 00177 */ 00178 CActionCollectionPtr getAsAction( size_t index ) const; 00179 00180 /** Returns the i'th element in the sequence, as being an action, where index=0 is the first object. 00181 * If it is not an CSensoryFrame, it throws an exception. Do neighter modify nor delete the returned pointer. 00182 * \sa size, isAction, getAsAction, getAsObservation 00183 * \exception std::exception If index is out of bounds 00184 */ 00185 CSensoryFramePtr getAsObservations( size_t index ) const; 00186 00187 /** Returns the i'th element in the sequence, being its class whatever. 00188 * \sa size, isAction, getAsAction, getAsObservations 00189 * \exception std::exception If index is out of bounds 00190 */ 00191 CSerializablePtr getAsGeneric( size_t index ) const; 00192 00193 /** Returns the i'th element in the sequence, as being an observation, where index=0 is the first object. 00194 * If it is not an CObservation, it throws an exception. Do neighter modify nor delete the returned pointer. 00195 * This is the proper method to obtain the objects stored in a "only observations"-rawlog file (named "format #2" above. 00196 * \sa size, isAction, getAsAction 00197 * \exception std::exception If index is out of bounds 00198 */ 00199 CObservationPtr getAsObservation( size_t index ) const; 00200 00201 00202 /** A normal iterator, plus the extra method "getType" to determine the type of each entry in the sequence. */ 00203 class iterator 00204 { 00205 protected: 00206 TListObjects::iterator m_it; 00207 00208 public: 00209 iterator() : m_it() { } 00210 iterator(const TListObjects::iterator& it) : m_it(it) { } 00211 virtual ~iterator() { } 00212 00213 iterator & operator = (const iterator& o) { m_it = o.m_it; return *this; } 00214 00215 bool operator == (const iterator& o) { return m_it == o.m_it; } 00216 bool operator != (const iterator& o) { return m_it != o.m_it; } 00217 00218 CSerializablePtr operator *() { return *m_it; } 00219 00220 inline iterator operator ++(int) { iterator aux =*this; m_it++; return aux; } // Post 00221 inline iterator& operator ++() { m_it++; return *this; } // Pre 00222 inline iterator operator --(int) { iterator aux = *this; m_it--; return aux; } // Post 00223 inline iterator& operator --() { m_it--; return *this; } // Pre 00224 00225 TEntryType getType() const 00226 { 00227 if ( (*m_it)->GetRuntimeClass()->derivedFrom( CLASS_ID(CObservation) ) ) 00228 return etObservation; 00229 else if ( (*m_it)->GetRuntimeClass()->derivedFrom( CLASS_ID(CSensoryFrame) ) ) 00230 return etSensoryFrame; 00231 else 00232 return etActionCollection; 00233 } 00234 00235 static iterator erase( TListObjects& lst, const iterator &it) { return lst.erase(it.m_it); } 00236 }; 00237 00238 /** A normal iterator, plus the extra method "getType" to determine the type of each entry in the sequence. */ 00239 class const_iterator 00240 { 00241 protected: 00242 TListObjects::const_iterator m_it; 00243 00244 public: 00245 const_iterator() : m_it() { } 00246 const_iterator(const TListObjects::const_iterator& it) : m_it(it) { } 00247 virtual ~const_iterator() { } 00248 00249 bool operator == (const const_iterator& o) { return m_it == o.m_it; } 00250 bool operator != (const const_iterator& o) { return m_it != o.m_it; } 00251 00252 const CSerializablePtr operator *() const { return *m_it; } 00253 00254 inline const_iterator operator ++(int) { const_iterator aux =*this; m_it++; return aux; } // Post 00255 inline const_iterator& operator ++() { m_it++; return *this; } // Pre 00256 inline const_iterator operator --(int) { const_iterator aux = *this; m_it--; return aux; } // Post 00257 inline const_iterator& operator --() { m_it--; return *this; } // Pre 00258 00259 TEntryType getType() const 00260 { 00261 if ( (*m_it)->GetRuntimeClass()->derivedFrom( CLASS_ID(CObservation) ) ) 00262 return etObservation; 00263 else if ( (*m_it)->GetRuntimeClass()->derivedFrom( CLASS_ID(CSensoryFrame) ) ) 00264 return etSensoryFrame; 00265 else 00266 return etActionCollection; 00267 } 00268 00269 }; 00270 00271 00272 const_iterator begin() const { return m_seqOfActObs.begin(); } 00273 iterator begin() { return m_seqOfActObs.begin(); } 00274 const_iterator end() const { return m_seqOfActObs.end(); } 00275 iterator end() { return m_seqOfActObs.end(); } 00276 00277 iterator erase(const iterator &it) { return iterator::erase(m_seqOfActObs, it); } 00278 00279 /** Returns the sub-set of observations of a given class whose time-stamp t fulfills time_start <= t < time_end. 00280 * This method requires the timestamps of the sensors to be in strict ascending order (which should be the normal situation). 00281 * Otherwise, the output is undeterminate. 00282 * \sa findClosestObservationsByClass 00283 */ 00284 void findObservationsByClassInRange( 00285 mrpt::system::TTimeStamp time_start, 00286 mrpt::system::TTimeStamp time_end, 00287 const mrpt::utils::TRuntimeClassId *class_type, 00288 TListTimeAndObservations &out_found, 00289 size_t guess_start_position = 0 00290 ) const; 00291 00292 /** Efficiently copy the contents from other existing object, and remove the data from the origin (after calling this, the original object will have no actions/observations). 00293 */ 00294 void moveFrom( CRawlog &obj); 00295 00296 /** Efficiently swap the contents of two existing objects. 00297 */ 00298 void swap( CRawlog &obj); 00299 00300 /** Reads a consecutive pair action / observation from the rawlog opened at some input stream. 00301 * Previous contents of action and observations are discarded (using stlplus::smart_ptr::clear_unique), and 00302 * at exit they contain the new objects read from the rawlog file. 00303 * The input/output variable "rawlogEntry" is just a counter of the last rawlog entry read, for logging or monitoring purposes. 00304 * \return false if there was some error, true otherwise. 00305 * \sa getActionObservationPair, getActionObservationPairOrObservation 00306 */ 00307 static bool readActionObservationPair( 00308 CStream &inStream, 00309 CActionCollectionPtr &action, 00310 CSensoryFramePtr &observations, 00311 size_t & rawlogEntry ); 00312 00313 /** Reads a consecutive pair action/sensory_frame OR an observation, depending of the rawlog format, from the rawlog opened at some input stream. 00314 * Previous contents of action and observations are discarded (using stlplus::smart_ptr::clear_unique), and 00315 * at exit they contain the new objects read from the rawlog file. 00316 * 00317 * At return, one of this will happen: 00318 * - action/observations contain objects (i.e. action.present() evaluates as true). 00319 * - observation contains an object (i.e. observation.present() evaluates as true). 00320 * 00321 * The input/output variable "rawlogEntry" is just a counter of the last rawlog entry read, for logging or monitoring purposes. 00322 * \return false if there was some error, true otherwise. 00323 * \sa getActionObservationPair 00324 */ 00325 static bool getActionObservationPairOrObservation( 00326 CStream &inStream, 00327 CActionCollectionPtr &action, 00328 CSensoryFramePtr &observations, 00329 CObservationPtr &observation, 00330 size_t & rawlogEntry ); 00331 00332 /** Gets the next consecutive pair action / observation from the rawlog loaded into this object. 00333 * Previous contents of action and observations are discarded (using stlplus::smart_ptr::clear_unique), and 00334 * at exit they contain the new objects read from the rawlog file. 00335 * The input/output variable "rawlogEntry" is just a counter of the last rawlog entry read, for logging or monitoring purposes. 00336 * \return false if there was some error, true otherwise. 00337 * \sa readActionObservationPair 00338 */ 00339 bool getActionObservationPair( 00340 CActionCollectionPtr &action, 00341 CSensoryFramePtr &observations, 00342 size_t &rawlogEntry ) const; 00343 00344 /** Tries to auto-detect the external-images directory of the given rawlog file. 00345 * This searches for the existence of the directories: 00346 * - "<rawlog_file_path>/<rawlog_filename>_Images" 00347 * - "<rawlog_file_path>/<rawlog_filename>_images" 00348 * - "<rawlog_file_path>/<rawlog_filename>_IMAGES" 00349 * - "<rawlog_file_path>/Images" (This one is returned if none of the choices actually exists). 00350 * 00351 * The results from this function should be written into mrpt::utils::CImage::IMAGES_PATH_BASE to enable automatic 00352 * loading of extenrnally-stored images in rawlogs. 00353 */ 00354 static std::string detectImagesDirectory(const std::string &rawlogFilename); 00355 00356 }; // End of class def. 00357 00358 } // End of namespace 00359 } // End of namespace 00360 00361 #endif
Page generated by Doxygen 1.7.2 for MRPT 0.9.4 SVN: at Mon Jan 10 22:46:17 UTC 2011 |