CObservation.h

Go to the documentation of this file.

/* +------------------------------------------------------------------------+
   |                     Mobile Robot Programming Toolkit (MRPT)            |
   |                          https://www.mrpt.org/                         |
   |                                                                        |
   | Copyright (c) 2005-2020, Individual contributors, see AUTHORS file     |
   | See: https://www.mrpt.org/Authors - All rights reserved.               |
   | Released under BSD License. See: https://www.mrpt.org/License          |
   +------------------------------------------------------------------------+ */
#pragma once

#include <mrpt/math/TPose3D.h>
#include <mrpt/math/math_frwds.h>
#include <mrpt/poses/poses_frwds.h>
#include <mrpt/serialization/CSerializable.h>
#include <mrpt/system/datetime.h>

namespace mrpt
{
/** This namespace contains representation of robot actions and observations */
namespace obs
{
/** Used for CObservationBeaconRange, CBeacon, etc. \ingroup mrpt_obs_grp */
#define INVALID_BEACON_ID (-1)

/** Used for CObservationBearingRange::TMeasurement::beaconID and others.
 * \ingroup mrpt_obs_grp */
#define INVALID_LANDMARK_ID (-1)

/** Declares a class that represents any robot's observation.
 *  This is a base class for many types of sensor observations.
 *  Users can add new observation types creating a new class deriving from this
 * one.
 *
 *  <b>IMPORTANT</b>: Observations don't include any information about the robot
 * pose,
 *   just  raw sensory data and, where aplicable, information about the sensor
 * position and
 *   orientation in the local frame of the robot.
 *
 * \sa CSensoryFrame, CMetricMap
 * \ingroup mrpt_obs_grp
 */
class CObservation : public mrpt::serialization::CSerializable
{
    DEFINE_VIRTUAL_SERIALIZABLE(CObservation)

   protected:
    /** Swap with another observation, ONLY the data defined here in the base
     * class CObservation. It's protected since it'll be only called from child
     * classes that should know what else to swap appart from these common data.
     */
    void swap(CObservation& o);

   public:
    /** @name Data common to any observation
        @{ */
    /** The associated UTC time-stamp. Where available, this should contain the
     * accurate satellite-based timestamp of the sensor reading. \sa
     * getOriginalReceivedTimeStamp(), getTimeStamp() */
    mrpt::system::TTimeStamp timestamp{mrpt::system::now()};
    /** An arbitrary label that can be used to identify the sensor. */
    std::string sensorLabel;

    /** Returns CObservation::timestamp for all kind of observations \sa
     * getOriginalReceivedTimeStamp() */
    mrpt::system::TTimeStamp getTimeStamp() const { return timestamp; }
    /** By default, returns CObservation::timestamp but in sensors capable of
     * satellite (or otherwise) accurate UTC timing of readings, this contains
     * the computer-based timestamp of reception, which may be slightly
     * different than \a timestamp \sa getTimeStamp()  */
    virtual mrpt::system::TTimeStamp getOriginalReceivedTimeStamp() const
    {
        return timestamp;
    }
    /** @} */

    /** Constructor: It sets the initial timestamp to current time */
    CObservation() = default;

    /** This method is equivalent to:
     * \code
     *      map->insertObservation(this, robotPose)
     * \endcode
     * \param theMap The map where this observation is to be inserted: the map
     *will be updated.
     * \param robotPose The pose of the robot base for this observation,
     *relative to the target metric map. Set to nullptr (default) to use
     *(0,0,0deg)
     *
     * \return Returns true if the map has been updated, or false if this
     *observations
     *          has nothing to do with a metric map (for example, a sound
     *observation).
     *
     * See: \ref maps_observations
     * \sa CMetricMap, CMetricMap::insertObservation
     */
    template <class METRICMAP>
    inline bool insertObservationInto(
        METRICMAP* theMap,
        const mrpt::poses::CPose3D* robotPose = nullptr) const
    {
        return theMap->insertObservation(*this, robotPose);
    }

    /** A general method to retrieve the sensor pose on the robot.
     *  Note that most sensors will return a full (6D) CPose3D, but see the
     * derived classes for more details or special cases.
     * \sa setSensorPose
     */
    virtual void getSensorPose(mrpt::poses::CPose3D& out_sensorPose) const = 0;

    /** A general method to retrieve the sensor pose on the robot.
     *  Note that most sensors will return a full (6D) CPose3D, but see the
     * derived classes for more details or special cases.
     * \sa setSensorPose
     */
    void getSensorPose(mrpt::math::TPose3D& out_sensorPose) const;

    /** A general method to change the sensor pose on the robot.
     *  Note that most sensors will use the full (6D) CPose3D, but see the
     * derived classes for more details or special cases.
     * \sa getSensorPose
     */
    virtual void setSensorPose(const mrpt::poses::CPose3D& newSensorPose) = 0;

    /** A general method to change the sensor pose on the robot.
     *  Note that most sensors will use the full (6D) CPose3D, but see the
     * derived classes for more details or special cases.
     * \sa getSensorPose
     */
    void setSensorPose(const mrpt::math::TPose3D& newSensorPose);

    /** Build a detailed, multi-line textual description of the observation
     * contents and dump it to the output stream.
     * \note If overried by derived classes, call base
     * CObservation::getDescriptionAsText() first to show common information.
     * \note This is the text that appears in RawLogViewer when selecting an
     * object in the dataset */
    virtual void getDescriptionAsText(std::ostream& o) const;

    /** Return by value version of getDescriptionAsText(std::ostream&) */
    std::string getDescriptionAsTextValue() const;

    /** @name Delayed-load manual control methods.
        @{ */

    /** Makes sure all images and other fields which may be externally stored
     * are loaded in memory.
     *  Note that for all CImages, calling load() is not required since the
     * images will be automatically loaded upon first access, so load()
     * shouldn't be needed to be called in normal cases by the user.
     *  If all the data were alredy loaded or this object has no externally
     * stored data fields, calling this method has no effects.
     * \sa unload
     */
    virtual void load() const
    { /* Default implementation: do nothing */
    }
    /** Unload all images, for the case they being delayed-load images stored in
     * external files (othewise, has no effect).
     * \sa load
     */
    virtual void unload()
    { /* Default implementation: do nothing */
    }

    /** @} */

};  // End of class def.

}  // namespace obs
}  // namespace mrpt