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



Page generated by Doxygen 1.8.15 for MRPT 1.4.0 SVN: at Sat Aug 3 20:09:00 UTC 2019