class mrpt::obs::CRawlog

The main class for loading and processing robotics datasets, or “rawlogs”.

Please, refer to the rawlog format specification.

In short, this class stores a sequence of objects, in one of two possible formats:

Format #1: A sequence of actions and observations. There is a sequence of objects, where each one can be of one type:
- An action: Implemented as a CActionCollection object, the actuation of the robot (i.e. odometry increment).
- Observations: Implemented as a CSensoryFrame, refering to a set of robot observations from the same pose.
Format #2: A sequence of actions and observations. There is a sequence of objects, where each one can be of one type:

See also RawLogViewer for a GUI application for quick inspection and analysis of rawlogs.

There is a field for dataset plain-text comments (human-friendly description, blocks of parameters, etc.) accessible through CRawlog::getCommentText() and CRawlog::setCommentText().

This container provides a STL container-like interface (see CRawlog::begin, CRawlog::iterator, …).

There is a static helper method CRawlog::detectImagesDirectory() to identify the directory where external images are stored.

See also:

CSensoryFrame, Dataset file format.

#include <mrpt/obs/CRawlog.h>

class CRawlog: public mrpt::serialization::CSerializable
{
public:
    // enums

    enum TEntryType;

    // classes

    class const_iterator;
    class iterator;

    // construction

    CRawlog();

    //
methods

    void getCommentText(std::string& t) const;
    std::string getCommentText() const;
    void setCommentText(const std::string& t);
    void getCommentTextAsConfigFile(mrpt::config::CConfigFileMemory& memCfg) const;
    void clear();
    bool empty() const;
    void insert(CAction& action);
    void insert(CActionCollection& action);
    void insert(CSensoryFrame& observations);
    void insert(const mrpt::serialization::CSerializable::Ptr& obj);
    bool loadFromRawLogFile(const std::string& fileName, bool non_obs_objects_are_legal = false);
    bool saveToRawLogFile(const std::string& fileName) const;
    size_t size() const;
    TEntryType getType(size_t index) const;
    void remove(size_t index);
    void remove(size_t first_index, size_t last_index);
    CActionCollection::Ptr getAsAction(size_t index) const;
    CSensoryFrame::Ptr getAsObservations(size_t index) const;
    mrpt::serialization::CSerializable::Ptr getAsGeneric(size_t index) const;
    CObservation::Ptr getAsObservation(size_t index) const;

    template <class T>
    T::ConstPtr asObservation(size_t index) const;

    template <class T>
    T::Ptr asObservation(size_t index);

    const_iterator begin() const;
    iterator begin();
    const_iterator end() const;
    iterator end();
    iterator erase(const iterator& it);

    void findObservationsByClassInRange(
        mrpt::system::TTimeStamp time_start,
        mrpt::system::TTimeStamp time_end,
        const mrpt::rtti::TRuntimeClassId* class_type,
        TListTimeAndObservations& out_found,
        size_t guess_start_position = 0
        ) const;

    void swap(CRawlog& obj);
    bool getActionObservationPair(CActionCollection::Ptr& action, CSensoryFrame::Ptr& observations, size_t& rawlogEntry) const;
    static bool readActionObservationPair(mrpt::serialization::CArchive& inStream, CActionCollection::Ptr& action, CSensoryFrame::Ptr& observations, size_t& rawlogEntry);

    static bool getActionObservationPairOrObservation(
        mrpt::serialization::CArchive& inStream,
        CActionCollection::Ptr& action,
        CSensoryFrame::Ptr& observations,
        CObservation::Ptr& observation,
        size_t& rawlogEntry
        );

    static std::tuple<bool, size_t, CActionCollection::Ptr, CSensoryFrame::Ptr, CObservation::Ptr> ReadFromArchive(
        mrpt::serialization::CArchive& inStream,
        const size_t rawlogEntryIndex
        );

    static std::string detectImagesDirectory(const std::string& rawlogFilename);
};

Methods

void getCommentText(std::string& t) const

Returns the block of comment text for the rawlog.

std::string getCommentText() const

Returns the block of comment text for the rawlog.

void setCommentText(const std::string& t)

Changes the block of comment text for the rawlog.

void getCommentTextAsConfigFile(mrpt::config::CConfigFileMemory& memCfg) const

Saves the block of comment text for the rawlog into the passed config file object.

void clear()

Clear the sequence of actions/observations.

Smart pointers to objects previously in the rawlog will remain being valid.

bool empty() const

Returns true if the rawlog is empty.

void insert(CAction& action)

Add an action to the sequence: a collection of just one element is created.

The object is duplicated, so the original one can be freed if desired.

void insert(CActionCollection& action)

Add a set of actions to the sequence; the object is duplicated, so the original one can be freed if desired.

See also:

insert, insert

void insert(CSensoryFrame& observations)

Add a set of observations to the sequence; the object is duplicated, so the original one can be free if desired.

void insert(const mrpt::serialization::CSerializable::Ptr& obj)

Generic add for a smart pointer to a CSerializable object:

bool loadFromRawLogFile(
    const std::string& fileName,
    bool non_obs_objects_are_legal = false
    )

Load the contents from a file containing one of these possibilities:

A “CRawlog” object.
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.
Only if non_obs_objects_are_legal is true, any CSerializable object is allowed in the log file. Otherwise, the read stops on classes different from the ones listed in the item above.

Returns:

It returns false upon error reading or accessing the file.

bool saveToRawLogFile(const std::string& fileName) const

Saves the contents to a rawlog-file, compatible with RawlogViewer (As the sequence of internal objects).

The file is saved with gz-commpressed if MRPT has gz-streams.

Returns:

It returns false if any error is found while writing/creating the target file.

size_t size() const

Returns the number of actions / observations object in the sequence.

TEntryType getType(size_t index) const

Returns the type of a given element.

See also:

isAction, isObservation

void remove(size_t index)

Delete the action or observation stored in the given index.

Parameters:

std::exception

If index is out of bounds

void remove(size_t first_index, size_t last_index)

Delete the elements stored in the given range of indices (including both the first and last one).

Parameters:

std::exception

If any index is out of bounds

CActionCollection::Ptr getAsAction(size_t index) const

Returns the i’th element in the sequence, as being actions, where index=0 is the first object.

If it is not a CActionCollection, it throws an exception. Do neighter modify nor delete the returned pointer.

Parameters:

std::exception

If index is out of bounds

CSensoryFrame::Ptr getAsObservations(size_t index) const

Returns the i’th element in the sequence, as being an action, where index=0 is the first object.

If it is not an CSensoryFrame, it throws an exception.

Parameters:

std::exception

If index is out of bounds

See also:

size, isAction, getAsAction, getAsObservation

mrpt::serialization::CSerializable::Ptr getAsGeneric(size_t index) const

Returns the i’th element in the sequence, being its class whatever.

Parameters:

std::exception

If index is out of bounds

See also:

size, isAction, getAsAction, getAsObservations

CObservation::Ptr getAsObservation(size_t index) const

Returns the i’th element in the sequence, as being an observation, where index=0 is the first object.

If it is not an CObservation, it throws an exception. Do neighter modify nor delete the returned pointer. This is the proper method to obtain the objects stored in a “only observations”-rawlog file (named “format #2” above.

Parameters:

std::exception

If index is out of bounds

See also:

size, isAction, getAsAction

template <class T>
T::ConstPtr asObservation(size_t index) const

Get the i’th observation as an observation of the given type.

Parameters:

std::exception

If index is out of bounds, or type not compatible.

void findObservationsByClassInRange(
    mrpt::system::TTimeStamp time_start,
    mrpt::system::TTimeStamp time_end,
    const mrpt::rtti::TRuntimeClassId* class_type,
    TListTimeAndObservations& out_found,
    size_t guess_start_position = 0
    ) const

Returns the sub-set of observations of a given class whose time-stamp t fulfills time_start <= t < time_end.

This method requires the timestamps of the sensors to be in strict ascending order (which should be the normal situation). Otherwise, the output is undeterminate.

See also:

findClosestObservationsByClass

void swap(CRawlog& obj)

Efficiently swap the contents of two existing objects.

bool getActionObservationPair(CActionCollection::Ptr& action, CSensoryFrame::Ptr& observations, size_t& rawlogEntry) const

Gets the next consecutive pair action / observation from the rawlog loaded into this object.

Previous contents of action and observations are discarded, and upon return they contain smart pointers to the next objects read from the rawlog dataset. The input/output variable “rawlogEntry” is just a counter of the last rawlog entry read, for logging or monitoring purposes.

Returns:

false if there was some error, true otherwise.

See also:

readActionObservationPair

static bool readActionObservationPair(
    mrpt::serialization::CArchive& inStream,
    CActionCollection::Ptr& action,
    CSensoryFrame::Ptr& observations,
    size_t& rawlogEntry
    )

Reads a consecutive pair action / observation from the rawlog opened at some input stream.

Previous contents of action and observations are discarded, and upon exit they contain smart pointers to the new objects read from the rawlog file. The input/output variable “rawlogEntry” is just a counter of the last rawlog entry read, for logging or monitoring purposes.

Returns:

false if there was some error, true otherwise.

static bool getActionObservationPairOrObservation(
    mrpt::serialization::CArchive& inStream,
    CActionCollection::Ptr& action,
    CSensoryFrame::Ptr& observations,
    CObservation::Ptr& observation,
    size_t& rawlogEntry
    )

Reads a consecutive pair action/sensory_frame OR an observation, depending of the rawlog format, from the rawlog opened at some input stream.

Previous contents of action and observations are discarded, and upon return they contain smart pointers to the new objects read from the rawlog file.

Depending on the rawlog file format, at return either:

action/observations contain objects, or
observation contains an object.

The input/output variable “rawlogEntry” is just a counter of the last rawlog entry read, for logging or monitoring purposes.

Returns:

false if there was some error, true otherwise.

See also:

getActionObservationPair

static std::tuple<bool, size_t, CActionCollection::Ptr, CSensoryFrame::Ptr, CObservation::Ptr> ReadFromArchive(
    mrpt::serialization::CArchive& inStream,
    const size_t rawlogEntryIndex
    )

Alternative to getActionObservationPairOrObservation() returning the tuple [readOk, rawlogEntryIndex, action,sf, obs], with either (action,sf) or (obs) as empty smart pointers depending on the rawlog file format.

readOk is false on EOF or any other error.

static std::string detectImagesDirectory(const std::string& rawlogFilename)

Tries to auto-detect the external-images directory of the given rawlog file.

This searches for the existence of the directories:

“<rawlog_file_path>/<rawlog_filename>_Images”
“<rawlog_file_path>/<rawlog_filename>_images”
“<rawlog_file_path>/<rawlog_filename>_IMAGES”
“<rawlog_file_path>/Images” (This one is returned if none of the choices actually exists).

The results from this function should be written into mrpt::img::CImage::getImagesPathBase() to enable automatic loading of extenrnally-stored images in rawlogs.