Main MRPT website > C++ reference
MRPT logo

CRawlog.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 #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.3 for MRPT 0.9.4 SVN:exported at Tue Jan 25 21:56:31 UTC 2011