00001 /* +---------------------------------------------------------------------------+ 00002 | The Mobile Robot Programming Toolkit (MRPT) C++ library | 00003 | | 00004 | http://mrpt.sourceforge.net/ | 00005 | | 00006 | Copyright (C) 2005-2010 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 */ 00101 CRawlog(); 00102 00103 /** Copy operator: 00104 * \sa moveFrom 00105 */ 00106 // No need from introduction of smart pointers 00107 // CRawlog& operator =(const CRawlog &o); 00108 00109 /** Destructor: 00110 */ 00111 virtual ~CRawlog(); 00112 00113 /** Clear the sequence of actions/observations, freeing the memory of all the objects in the list. 00114 */ 00115 void clear(); 00116 00117 /** 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). 00118 */ 00119 void clearWithoutDelete(); 00120 00121 /** Add an action to the sequence: a collection of just one element is created. 00122 * The object is duplicated, so the original one can be free if desired. 00123 */ 00124 void addAction( CAction &action ); 00125 00126 /** Add a set of actions to the sequence; the object is duplicated, so the original one can be free if desired. 00127 * \sa addObservations, addActionsMemoryReference 00128 */ 00129 void addActions( CActionCollection &action ); 00130 00131 /** Add a set of observations to the sequence; the object is duplicated, so the original one can be free if desired. 00132 * \sa addActions, addObservationsMemoryReference 00133 */ 00134 void addObservations( CSensoryFrame &observations ); 00135 00136 /** Add a set of actions to the sequence, using a smart pointer to the object to add. 00137 * \sa addActions, addObservationsMemoryReference, addObservationMemoryReference 00138 */ 00139 void addActionsMemoryReference( const CActionCollectionPtr &action ); 00140 00141 /** Add a set of observations to the sequence, using a smart pointer to the object to add. 00142 * \sa addObservations, addActionsMemoryReference, addObservationMemoryReference 00143 */ 00144 void addObservationsMemoryReference( const CSensoryFramePtr &observations ); 00145 00146 /** Add a single observation to the sequence, using a smart pointer to the object to add. 00147 * \sa addObservations, addActionsMemoryReference 00148 */ 00149 void addObservationMemoryReference( const CObservationPtr &observation ); 00150 00151 /** Load the contents from a file containing one of these possibilities: 00152 * - A "CRawlog" object. 00153 * - Directly "CSensoryFrame" and "CActionCollection" objects. In this case the method stops reading on EOF of an unrecogniced class name. 00154 * \returns It returns false if the file does not exists. 00155 */ 00156 bool loadFromRawLogFile( const std::string &fileName ); 00157 00158 /** Saves the contents to a rawlog-file, compatible with RawlogViewer (As the sequence of internal objects). 00159 * The file is saved with gz-commpressed is MRPT has gz-streams. 00160 * \returns It returns false if the file does not exists. 00161 */ 00162 bool saveToRawLogFile( const std::string &fileName ) const; 00163 00164 /** Returns the number of actions / observations object in the sequence. 00165 */ 00166 size_t size() const; 00167 00168 /** Returns the type of a given element. 00169 * \sa isAction, isObservation 00170 */ 00171 TEntryType getType( size_t index ) const; 00172 00173 /** Delete the action or observation stored in the given index. 00174 * \exception std::exception If index is out of bounds 00175 */ 00176 void remove( size_t index ); 00177 00178 /** Delete the elements stored in the given range of indices (including both the first and last one). 00179 * \exception std::exception If any index is out of bounds 00180 */ 00181 void remove( size_t first_index, size_t last_index ); 00182 00183 /** Returns the i'th element in the sequence, as being actions, where index=0 is the first object. 00184 * If it is not a CActionCollection, it throws an exception. Do neighter modify nor delete the returned pointer. 00185 * \sa size, isAction, getAsObservations, getAsObservation 00186 * \exception std::exception If index is out of bounds 00187 */ 00188 CActionCollectionPtr getAsAction( size_t index ) const; 00189 00190 /** Returns the i'th element in the sequence, as being an action, where index=0 is the first object. 00191 * If it is not an CSensoryFrame, it throws an exception. Do neighter modify nor delete the returned pointer. 00192 * \sa size, isAction, getAsAction, getAsObservation 00193 * \exception std::exception If index is out of bounds 00194 */ 00195 CSensoryFramePtr getAsObservations( size_t index ) const; 00196 00197 /** Returns the i'th element in the sequence, being its class whatever. 00198 * \sa size, isAction, getAsAction, getAsObservations 00199 * \exception std::exception If index is out of bounds 00200 */ 00201 CSerializablePtr getAsGeneric( size_t index ) const; 00202 00203 /** Returns the i'th element in the sequence, as being an observation, where index=0 is the first object. 00204 * If it is not an CObservation, it throws an exception. Do neighter modify nor delete the returned pointer. 00205 * This is the proper method to obtain the objects stored in a "only observations"-rawlog file (named "format #2" above. 00206 * \sa size, isAction, getAsAction 00207 * \exception std::exception If index is out of bounds 00208 */ 00209 CObservationPtr getAsObservation( size_t index ) const; 00210 00211 00212 /** A normal iterator, plus the extra methods "isAction", "isObservation" to determine the type of each entry in the sequence. 00213 */ 00214 class iterator 00215 { 00216 protected: 00217 TListObjects::iterator m_it; 00218 00219 public: 00220 iterator() : m_it() { } 00221 iterator(const TListObjects::iterator& it) : m_it(it) { } 00222 virtual ~iterator() { } 00223 00224 iterator & operator = (const iterator& o) { m_it = o.m_it; return *this; } 00225 00226 bool operator == (const iterator& o) { return m_it == o.m_it; } 00227 bool operator != (const iterator& o) { return m_it != o.m_it; } 00228 00229 CSerializablePtr operator *() { return *m_it; } 00230 00231 iterator operator ++(int) { m_it++; return *this; } 00232 iterator operator --(int) { m_it--; return *this; } 00233 00234 TEntryType getType() const 00235 { 00236 if ( (*m_it)->GetRuntimeClass()->derivedFrom( CLASS_ID(CObservation) ) ) 00237 return etObservation; 00238 else if ( (*m_it)->GetRuntimeClass()->derivedFrom( CLASS_ID(CSensoryFrame) ) ) 00239 return etSensoryFrame; 00240 else 00241 return etActionCollection; 00242 } 00243 00244 static iterator erase( TListObjects& lst, const iterator &it) { return lst.erase(it.m_it); } 00245 }; 00246 00247 /** A normal iterator, plus the extra methods "isAction", "isObservation" to determine the type of each entry in the sequence. 00248 */ 00249 class const_iterator 00250 { 00251 protected: 00252 TListObjects::const_iterator m_it; 00253 00254 public: 00255 const_iterator() : m_it() { } 00256 const_iterator(const TListObjects::const_iterator& it) : m_it(it) { } 00257 virtual ~const_iterator() { } 00258 00259 bool operator == (const const_iterator& o) { return m_it == o.m_it; } 00260 bool operator != (const const_iterator& o) { return m_it != o.m_it; } 00261 00262 const CSerializablePtr operator *() const { return *m_it; } 00263 00264 const_iterator operator ++(int) { m_it++; return *this; } 00265 const_iterator operator --(int) { m_it--; return *this; } 00266 00267 TEntryType getType() const 00268 { 00269 if ( (*m_it)->GetRuntimeClass()->derivedFrom( CLASS_ID(CObservation) ) ) 00270 return etObservation; 00271 else if ( (*m_it)->GetRuntimeClass()->derivedFrom( CLASS_ID(CSensoryFrame) ) ) 00272 return etSensoryFrame; 00273 else 00274 return etActionCollection; 00275 } 00276 00277 }; 00278 00279 00280 const_iterator begin() const { return m_seqOfActObs.begin(); } 00281 iterator begin() { return m_seqOfActObs.begin(); } 00282 const_iterator end() const { return m_seqOfActObs.end(); } 00283 iterator end() { return m_seqOfActObs.end(); } 00284 00285 iterator erase(const iterator &it) { return iterator::erase(m_seqOfActObs, it); } 00286 00287 /** Returns the sub-set of observations of a given class whose time-stamp t fulfills time_start <= t < time_end. 00288 * This method requires the timestamps of the sensors to be in strict ascending order (which should be the normal situation). 00289 * Otherwise, the output is undeterminate. 00290 * \sa findClosestObservationsByClass 00291 */ 00292 void findObservationsByClassInRange( 00293 mrpt::system::TTimeStamp time_start, 00294 mrpt::system::TTimeStamp time_end, 00295 const mrpt::utils::TRuntimeClassId *class_type, 00296 TListTimeAndObservations &out_found, 00297 size_t guess_start_position = 0 00298 ) const; 00299 00300 /** 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). 00301 */ 00302 void moveFrom( CRawlog &obj); 00303 00304 /** Efficiently swap the contents of two existing objects. 00305 */ 00306 void swap( CRawlog &obj); 00307 00308 /** Reads a consecutive pair action / observation from the rawlog opened at some input stream. 00309 * Previous contents of action and observations are discarded (using stlplus::smart_ptr::clear_unique), and 00310 * at exit they contain the new objects read from the rawlog file. 00311 * The input/output variable "rawlogEntry" is just a counter of the last rawlog entry read, for logging or monitoring purposes. 00312 * \return false if there was some error, true otherwise. 00313 * \sa getActionObservationPair, getActionObservationPairOrObservation 00314 */ 00315 static bool readActionObservationPair( 00316 CStream &inStream, 00317 CActionCollectionPtr &action, 00318 CSensoryFramePtr &observations, 00319 size_t & rawlogEntry ); 00320 00321 /** Reads a consecutive pair action/sensory_frame OR an observation, depending of the rawlog format, from the rawlog opened at some input stream. 00322 * Previous contents of action and observations are discarded (using stlplus::smart_ptr::clear_unique), and 00323 * at exit they contain the new objects read from the rawlog file. 00324 * 00325 * At return, one of this will happen: 00326 * - action/observations contain objects (i.e. action.present() evaluates as true). 00327 * - observation contains an object (i.e. observation.present() evaluates as true). 00328 * 00329 * The input/output variable "rawlogEntry" is just a counter of the last rawlog entry read, for logging or monitoring purposes. 00330 * \return false if there was some error, true otherwise. 00331 * \sa getActionObservationPair 00332 */ 00333 static bool getActionObservationPairOrObservation( 00334 CStream &inStream, 00335 CActionCollectionPtr &action, 00336 CSensoryFramePtr &observations, 00337 CObservationPtr &observation, 00338 size_t & rawlogEntry ); 00339 00340 /** Gets the next consecutive pair action / observation from the rawlog loaded into this object. 00341 * Previous contents of action and observations are discarded (using stlplus::smart_ptr::clear_unique), and 00342 * at exit they contain the new objects read from the rawlog file. 00343 * The input/output variable "rawlogEntry" is just a counter of the last rawlog entry read, for logging or monitoring purposes. 00344 * \return false if there was some error, true otherwise. 00345 * \sa readActionObservationPair 00346 */ 00347 bool getActionObservationPair( 00348 CActionCollectionPtr &action, 00349 CSensoryFramePtr &observations, 00350 size_t &rawlogEntry ) const; 00351 00352 /** Tries to auto-detect the external-images directory of the given rawlog file. 00353 * This searches for the existence of the directories: 00354 * - "<rawlog_file_path>/<rawlog_filename>_Images" 00355 * - "<rawlog_file_path>/<rawlog_filename>_images" 00356 * - "<rawlog_file_path>/<rawlog_filename>_IMAGES" 00357 * - "<rawlog_file_path>/Images" (This one is returned if none of the choices actually exists). 00358 * 00359 * The results from this function should be written into mrpt::utils::CImage::IMAGES_PATH_BASE to enable automatic 00360 * loading of extenrnally-stored images in rawlogs. 00361 */ 00362 static std::string detectImagesDirectory(const std::string &rawlogFilename); 00363 00364 }; // End of class def. 00365 00366 } // End of namespace 00367 } // End of namespace 00368 00369 #endif
| Page generated by Doxygen 1.6.1 for MRPT 0.9.0 SVN: at Mon Jun 7 06:47:58 UTC 2010 |
