Main MRPT website > C++ reference
MRPT logo
CRawlog.h
Go to the documentation of this file.
1 /* +---------------------------------------------------------------------------+
2  | The Mobile Robot Programming Toolkit (MRPT) C++ library |
3  | |
4  | http://www.mrpt.org/ |
5  | |
6  | Copyright (C) 2005-2012 University of Malaga |
7  | |
8  | This software was written by the Machine Perception and Intelligent |
9  | Robotics Lab, University of Malaga (Spain). |
10  | Contact: Jose-Luis Blanco <jlblanco@ctima.uma.es> |
11  | |
12  | This file is part of the MRPT project. |
13  | |
14  | MRPT is free software: you can redistribute it and/or modify |
15  | it under the terms of the GNU General Public License as published by |
16  | the Free Software Foundation, either version 3 of the License, or |
17  | (at your option) any later version. |
18  | |
19  | MRPT is distributed in the hope that it will be useful, |
20  | but WITHOUT ANY WARRANTY; without even the implied warranty of |
21  | MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the |
22  | GNU General Public License for more details. |
23  | |
24  | You should have received a copy of the GNU General Public License |
25  | along with MRPT. If not, see <http://www.gnu.org/licenses/>. |
26  | |
27  +---------------------------------------------------------------------------+ */
28 #ifndef CRawlog_H
29 #define CRawlog_H
30 
31 #include <mrpt/poses/CPose2D.h>
32 #include <mrpt/slam/CSensoryFrame.h>
33 #include <mrpt/slam/CActionCollection.h>
34 #include <mrpt/slam/CObservationComment.h>
35 #include <mrpt/utils/CConfigFileMemory.h>
36 
37 
38 namespace mrpt
39 {
40  namespace slam
41  {
42  DEFINE_SERIALIZABLE_PRE_CUSTOM_BASE_LINKAGE( CRawlog, mrpt::utils::CSerializable, OBS_IMPEXP )
43 
44  using namespace mrpt::utils;
45 
46  typedef std::pair<mrpt::system::TTimeStamp, CObservationPtr> TTimeObservationPair; //!< For usage with CRawlog classes.
47  typedef std::multimap<mrpt::system::TTimeStamp, CObservationPtr> TListTimeAndObservations; //!< For usage with CRawlog classes.
48 
49 
50  /** This class stores a rawlog (robotic datasets) in one of two possible formats:
51  * - Format #1: A sequence of actions and observations. There is a sequence of objects, where each one can be of one type:
52  * - An action: Implemented as a CActionCollection object, the actuation of the robot (i.e. odometry increment).
53  * - Observations: Implemented as a CSensoryFrame, refering to a set of robot observations from the same pose.
54  * - Format #2: A sequence of actions and observations. There is a sequence of objects, where each one can be of one type:
55  *
56  * Refer to the wiki page about <a href="http://www.mrpt.org/Rawlog_Format" >rawlog files</a>.
57  *
58  * See also the application <a href="http://www.mrpt.org/Application:RawLogViewer" >RawLogViewer</a > for the GUI program that visualizes and manages rawlogs.
59  *
60  * This class also publishes a static helper method for loading rawlog files in format #1: see CRawlog::readActionObservationPair
61  *
62  * There is a field for comments and blocks of parameters (in ini-like format) accessible through getCommentText and setCommentText
63  * (introduced in MRPT 0.6.4). When serialized to a rawlog file, the commens are saved as an additional observation of the
64  * type CObservationComments at the beginning of the file, but this observation does not appear after loading for clarity.
65  *
66  * \note Since MRPT version 0.5.5, this class also provides a STL container-like interface (see CRawlog::begin, CRawlog::iterator, ...).
67  * \note The format #2 is supported since MRPT version 0.6.0.
68  * \note There is a static helper method "detectImagesDirectory" for localizing the external images directory of a rawlog.
69  *
70  * \sa CSensoryFrame, CPose2D, <a href="http://www.mrpt.org/Rawlog_Format"> RawLog file format</a>.
71  * \ingroup mrpt_obs_grp
72  */
73  class OBS_IMPEXP CRawlog : public mrpt::utils::CSerializable
74  {
75  // This must be added to any CSerializable derived class:
76  DEFINE_SERIALIZABLE( CRawlog )
77 
78  private:
79  typedef std::vector<CSerializablePtr> TListObjects;
80  TListObjects m_seqOfActObs; //!< The list where the objects really are in.
81 
82  CObservationComment m_commentTexts; //!< Comments of the rawlog.
83 
84  public:
85  void getCommentText( std::string &t) const; //!< Returns the block of comment text for the rawlog
86  std::string getCommentText() const; //!< Returns the block of comment text for the rawlog
87  void setCommentText( const std::string &t); //!< Changes the block of comment text for the rawlog
88  void getCommentTextAsConfigFile( mrpt::utils::CConfigFileMemory &memCfg ) const; //!< Saves the block of comment text for the rawlog into the passed config file object.
89 
90  /** The type of each entry in a rawlog.
91  * \sa CRawlog::getType
92  */
93  enum TEntryType
94  {
95  etSensoryFrame = 0,
96  etActionCollection,
97  etObservation
98  };
99 
100  /** Default constructor */
101  CRawlog();
102 
103 
104  /** Destructor: */
105  virtual ~CRawlog();
106 
107  /** Clear the sequence of actions/observations, freeing the memory of all the objects in the list. */
108  void clear();
109 
110  /** 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). */
111  void clearWithoutDelete();
112 
113  /** Add an action to the sequence: a collection of just one element is created.
114  * The object is duplicated, so the original one can be free if desired.
115  */
116  void addAction( CAction &action );
117 
118  /** Add a set of actions to the sequence; the object is duplicated, so the original one can be free if desired.
119  * \sa addObservations, addActionsMemoryReference
120  */
121  void addActions( CActionCollection &action );
122 
123  /** Add a set of observations to the sequence; the object is duplicated, so the original one can be free if desired.
124  * \sa addActions, addObservationsMemoryReference
125  */
126  void addObservations( CSensoryFrame &observations );
127 
128  /** Add a set of actions to the sequence, using a smart pointer to the object to add.
129  * \sa addActions, addObservationsMemoryReference, addObservationMemoryReference
130  */
131  void addActionsMemoryReference( const CActionCollectionPtr &action );
132 
133  /** Add a set of observations to the sequence, using a smart pointer to the object to add.
134  * \sa addObservations, addActionsMemoryReference, addObservationMemoryReference
135  */
136  void addObservationsMemoryReference( const CSensoryFramePtr &observations );
137 
138  /** Add a single observation to the sequence, using a smart pointer to the object to add.
139  * \sa addObservations, addActionsMemoryReference
140  */
141  void addObservationMemoryReference( const CObservationPtr &observation );
142 
143  /** Load the contents from a file containing one of these possibilities:
144  * - A "CRawlog" object.
145  * - 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.
146  * \returns It returns false if the file does not exists.
147  */
148  bool loadFromRawLogFile( const std::string &fileName );
149 
150  /** Saves the contents to a rawlog-file, compatible with RawlogViewer (As the sequence of internal objects).
151  * The file is saved with gz-commpressed if MRPT has gz-streams.
152  * \returns It returns false if any error is found while writing/creating the target file.
153  */
154  bool saveToRawLogFile( const std::string &fileName ) const;
155 
156  /** Returns the number of actions / observations object in the sequence. */
157  size_t size() const;
158 
159  /** Returns the type of a given element.
160  * \sa isAction, isObservation
161  */
162  TEntryType getType( size_t index ) const;
163 
164  /** Delete the action or observation stored in the given index.
165  * \exception std::exception If index is out of bounds
166  */
167  void remove( size_t index );
168 
169  /** Delete the elements stored in the given range of indices (including both the first and last one).
170  * \exception std::exception If any index is out of bounds
171  */
172  void remove( size_t first_index, size_t last_index );
173 
174  /** Returns the i'th element in the sequence, as being actions, where index=0 is the first object.
175  * If it is not a CActionCollection, it throws an exception. Do neighter modify nor delete the returned pointer.
176  * \sa size, isAction, getAsObservations, getAsObservation
177  * \exception std::exception If index is out of bounds
178  */
179  CActionCollectionPtr getAsAction( size_t index ) const;
180 
181  /** Returns the i'th element in the sequence, as being an action, where index=0 is the first object.
182  * If it is not an CSensoryFrame, it throws an exception. Do neighter modify nor delete the returned pointer.
183  * \sa size, isAction, getAsAction, getAsObservation
184  * \exception std::exception If index is out of bounds
185  */
186  CSensoryFramePtr getAsObservations( size_t index ) const;
187 
188  /** Returns the i'th element in the sequence, being its class whatever.
189  * \sa size, isAction, getAsAction, getAsObservations
190  * \exception std::exception If index is out of bounds
191  */
192  CSerializablePtr getAsGeneric( size_t index ) const;
193 
194  /** Returns the i'th element in the sequence, as being an observation, where index=0 is the first object.
195  * If it is not an CObservation, it throws an exception. Do neighter modify nor delete the returned pointer.
196  * This is the proper method to obtain the objects stored in a "only observations"-rawlog file (named "format #2" above.
197  * \sa size, isAction, getAsAction
198  * \exception std::exception If index is out of bounds
199  */
200  CObservationPtr getAsObservation( size_t index ) const;
201 
202 
203  /** A normal iterator, plus the extra method "getType" to determine the type of each entry in the sequence. */
204  class iterator
205  {
206  protected:
207  TListObjects::iterator m_it;
208 
209  public:
210  iterator() : m_it() { }
211  iterator(const TListObjects::iterator& it) : m_it(it) { }
212  virtual ~iterator() { }
213 
214  iterator & operator = (const iterator& o) { m_it = o.m_it; return *this; }
215 
216  bool operator == (const iterator& o) { return m_it == o.m_it; }
217  bool operator != (const iterator& o) { return m_it != o.m_it; }
218 
219  CSerializablePtr operator *() { return *m_it; }
220 
221  inline iterator operator ++(int) { iterator aux =*this; m_it++; return aux; } // Post
222  inline iterator& operator ++() { m_it++; return *this; } // Pre
223  inline iterator operator --(int) { iterator aux = *this; m_it--; return aux; } // Post
224  inline iterator& operator --() { m_it--; return *this; } // Pre
225 
226  TEntryType getType() const
227  {
228  if ( (*m_it)->GetRuntimeClass()->derivedFrom( CLASS_ID(CObservation) ) )
229  return etObservation;
230  else if ( (*m_it)->GetRuntimeClass()->derivedFrom( CLASS_ID(CSensoryFrame) ) )
231  return etSensoryFrame;
232  else
233  return etActionCollection;
234  }
235 
236  static iterator erase( TListObjects& lst, const iterator &it) { return lst.erase(it.m_it); }
237  };
238 
239  /** A normal iterator, plus the extra method "getType" to determine the type of each entry in the sequence. */
240  class const_iterator
241  {
242  protected:
243  TListObjects::const_iterator m_it;
244 
245  public:
246  const_iterator() : m_it() { }
247  const_iterator(const TListObjects::const_iterator& it) : m_it(it) { }
248  virtual ~const_iterator() { }
249 
250  bool operator == (const const_iterator& o) { return m_it == o.m_it; }
251  bool operator != (const const_iterator& o) { return m_it != o.m_it; }
252 
253  const CSerializablePtr operator *() const { return *m_it; }
254 
255  inline const_iterator operator ++(int) { const_iterator aux =*this; m_it++; return aux; } // Post
256  inline const_iterator& operator ++() { m_it++; return *this; } // Pre
257  inline const_iterator operator --(int) { const_iterator aux = *this; m_it--; return aux; } // Post
258  inline const_iterator& operator --() { m_it--; return *this; } // Pre
259 
260  TEntryType getType() const
261  {
262  if ( (*m_it)->GetRuntimeClass()->derivedFrom( CLASS_ID(CObservation) ) )
263  return etObservation;
264  else if ( (*m_it)->GetRuntimeClass()->derivedFrom( CLASS_ID(CSensoryFrame) ) )
265  return etSensoryFrame;
266  else
267  return etActionCollection;
268  }
269 
270  };
271 
272 
273  const_iterator begin() const { return m_seqOfActObs.begin(); }
274  iterator begin() { return m_seqOfActObs.begin(); }
275  const_iterator end() const { return m_seqOfActObs.end(); }
276  iterator end() { return m_seqOfActObs.end(); }
277 
278  iterator erase(const iterator &it) { return iterator::erase(m_seqOfActObs, it); }
279 
280  /** Returns the sub-set of observations of a given class whose time-stamp t fulfills time_start <= t < time_end.
281  * This method requires the timestamps of the sensors to be in strict ascending order (which should be the normal situation).
282  * Otherwise, the output is undeterminate.
283  * \sa findClosestObservationsByClass
284  */
285  void findObservationsByClassInRange(
286  mrpt::system::TTimeStamp time_start,
287  mrpt::system::TTimeStamp time_end,
288  const mrpt::utils::TRuntimeClassId *class_type,
289  TListTimeAndObservations &out_found,
290  size_t guess_start_position = 0
291  ) const;
292 
293  /** 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).
294  */
295  void moveFrom( CRawlog &obj);
296 
297  /** Efficiently swap the contents of two existing objects.
298  */
299  void swap( CRawlog &obj);
300 
301  /** Reads a consecutive pair action / observation from the rawlog opened at some input stream.
302  * Previous contents of action and observations are discarded (using stlplus::smart_ptr::clear_unique), and
303  * at exit they contain the new objects read from the rawlog file.
304  * The input/output variable "rawlogEntry" is just a counter of the last rawlog entry read, for logging or monitoring purposes.
305  * \return false if there was some error, true otherwise.
306  * \sa getActionObservationPair, getActionObservationPairOrObservation
307  */
308  static bool readActionObservationPair(
309  CStream &inStream,
310  CActionCollectionPtr &action,
311  CSensoryFramePtr &observations,
312  size_t & rawlogEntry );
313 
314  /** Reads a consecutive pair action/sensory_frame OR an observation, depending of the rawlog format, from the rawlog opened at some input stream.
315  * Previous contents of action and observations are discarded (using stlplus::smart_ptr::clear_unique), and
316  * at exit they contain the new objects read from the rawlog file.
317  *
318  * At return, one of this will happen:
319  * - action/observations contain objects (i.e. action.present() evaluates as true).
320  * - observation contains an object (i.e. observation.present() evaluates as true).
321  *
322  * The input/output variable "rawlogEntry" is just a counter of the last rawlog entry read, for logging or monitoring purposes.
323  * \return false if there was some error, true otherwise.
324  * \sa getActionObservationPair
325  */
326  static bool getActionObservationPairOrObservation(
327  CStream &inStream,
328  CActionCollectionPtr &action,
329  CSensoryFramePtr &observations,
330  CObservationPtr &observation,
331  size_t & rawlogEntry );
332 
333  /** Gets the next consecutive pair action / observation from the rawlog loaded into this object.
334  * Previous contents of action and observations are discarded (using stlplus::smart_ptr::clear_unique), and
335  * at exit they contain the new objects read from the rawlog file.
336  * The input/output variable "rawlogEntry" is just a counter of the last rawlog entry read, for logging or monitoring purposes.
337  * \return false if there was some error, true otherwise.
338  * \sa readActionObservationPair
339  */
340  bool getActionObservationPair(
341  CActionCollectionPtr &action,
342  CSensoryFramePtr &observations,
343  size_t &rawlogEntry ) const;
344 
345  /** Tries to auto-detect the external-images directory of the given rawlog file.
346  * This searches for the existence of the directories:
347  * - "<rawlog_file_path>/<rawlog_filename>_Images"
348  * - "<rawlog_file_path>/<rawlog_filename>_images"
349  * - "<rawlog_file_path>/<rawlog_filename>_IMAGES"
350  * - "<rawlog_file_path>/Images" (This one is returned if none of the choices actually exists).
351  *
352  * The results from this function should be written into mrpt::utils::CImage::IMAGES_PATH_BASE to enable automatic
353  * loading of extenrnally-stored images in rawlogs.
354  */
355  static std::string detectImagesDirectory(const std::string &rawlogFilename);
356 
357  }; // End of class def.
358 
359  } // End of namespace
360 } // End of namespace
361 
362 #endif


Page generated by Doxygen 1.8.3 for MRPT 0.9.6 SVN: at Fri Feb 15 22:05:02 EST 2013