class mrpt::maps::CRandomFieldGridMap3D

Overview

CRandomFieldGridMap3D represents a 3D regular grid where each voxel is associated one real-valued property which is to be estimated by this class.

This class implements a Gaussian Markov Random Field (GMRF) estimator, with each voxel being connected to its 6 immediate neighbors (Up, down, left, right, front, back).

• See papers:

  • “Time-variant gas distribution mapping with obstacle information”, Monroy, J. G., Blanco, J. L., & Gonzalez-Jimenez, J. Autonomous Robots, 40(1), 1-16, 2016.

Note that this class does not derive from mrpt::maps::CMetricMap since the estimated values do not have sensor-especific semantics, i.e. the grid can be used to estimate temperature, gas concentration, etc.

Usage:

• Define grid size with either constructor or via setSize().

• Initialize the map with initialize(). This resets the contents of the map, so previously-added observations will be lost.

• Add observations of 3D voxels with insertIndividualReading()

Custom connectivity patterns can be defined with setVoxelsConnectivity().

See also:

mrpt::maps::CRandomFieldGridMap3D

#include <mrpt/maps/CRandomFieldGridMap3D.h>

class CRandomFieldGridMap3D:
    public mrpt::containers::CDynamicGrid3D,
    public mrpt::serialization::CSerializable,
    public mrpt::system::COutputLogger,
    public mrpt::config::OptionsCapable
{
public:
    // typedefs

    typedef std::shared_ptr<mrpt::maps ::CRandomFieldGridMap3D> Ptr;
    typedef std::shared_ptr<const mrpt::maps ::CRandomFieldGridMap3D> ConstPtr;
    typedef std::unique_ptr<mrpt::maps ::CRandomFieldGridMap3D> UniquePtr;
    typedef std::unique_ptr<const mrpt::maps ::CRandomFieldGridMap3D> ConstUniquePtr;

    // enums

    enum TVoxelInterpolationMethod;

    // structs

    struct ConnectivityDescriptor;
    struct TInsertionOptions;
    struct TObservationGMRF;
    struct TPriorFactorGMRF;

    // fields

    static constexpr const char* className = "mrpt::maps" "::" "CRandomFieldGridMap3D";
    static bool ENABLE_GMRF_PROFILER;
    TInsertionOptions insertionOptions;

    // construction

    CRandomFieldGridMap3D(
        double x_min = -2,
        double x_max = 2,
        double y_min = -2,
        double y_max = 2,
        double z_min = -2,
        double z_max = 2,
        double voxel_size = 0.5,
        bool call_initialize_now = true
        );

    // methods

    static constexpr auto getClassName();
    static const mrpt::rtti::TRuntimeClassId& GetRuntimeClassIdStatic();
    static std::shared_ptr<CObject> CreateObject();

    template <typename... Args>
    static Ptr Create(Args&&... args);

    template <typename Alloc, typename... Args>
    static Ptr CreateAlloc(
        const Alloc& alloc,
        Args&&... args
        );

    template <typename... Args>
    static UniquePtr CreateUnique(Args&&... args);

    virtual const mrpt::rtti::TRuntimeClassId* GetRuntimeClass() const;
    virtual mrpt::rtti::CObject* clone() const;
    virtual void clear();

    bool saveAsCSV(
        const std::string& filName_mean,
        const std::string& filName_stddev = std::string()
        ) const;

    virtual std::map<std::string, mrpt::config::CLoadableOptions*> optionsByName();

    void resize(
        double new_x_min,
        double new_x_max,
        double new_y_min,
        double new_y_max,
        double new_z_min,
        double new_z_max,
        const TRandomFieldVoxel& defaultValueNewvoxels,
        double additionalMarginMeters = 2.0
        );

    void setSize(
        const double x_min,
        const double x_max,
        const double y_min,
        const double y_max,
        const double z_min,
        const double z_max,
        const double resolution_xy,
        const double resolution_z = -1.0,
        const TRandomFieldVoxel* fill_value = nullptr
        );

    void setVoxelsConnectivity(const ConnectivityDescriptor::Ptr& new_connectivity_descriptor);

    bool insertIndividualReading(
        const double sensorReading,
        const double sensorVariance,
        const mrpt::math::TPoint3D& point,
        const TVoxelInterpolationMethod method,
        const bool update_map
        );

    void updateMapEstimation();
};

Inherited Members

public:
    // typedefs

    typedef std::vector<T> grid_data_t;
    typedef typename grid_data_t::iterator iterator;
    typedef typename grid_data_t::const_iterator const_iterator;
    typedef std::shared_ptr<CObject> Ptr;
    typedef std::shared_ptr<const CObject> ConstPtr;
    typedef std::unique_ptr<CObject> UniquePtr;
    typedef std::unique_ptr<const CObject> ConstUniquePtr;
    typedef std::shared_ptr<CSerializable> Ptr;
    typedef std::shared_ptr<const CSerializable> ConstPtr;

    // structs

    struct TMsg;

    // fields

    static const size_t INVALID_VOXEL_IDX = size_t(-1);
    bool logging_enable_console_output {true};
    bool logging_enable_keep_record {false};

    // methods

    const grid_data_t& data() const;
    iterator begin();
    iterator end();
    const_iterator begin() const;
    const_iterator end() const;

    virtual void resize(
        coord_t new_x_min,
        coord_t new_x_max,
        coord_t new_y_min,
        coord_t new_y_max,
        coord_t new_z_min,
        coord_t new_z_max,
        const T& defaultValueNewCells,
        coord_t additionalMarginMeters = 2
        );

    virtual void setSize(
        const coord_t x_min,
        const coord_t x_max,
        const coord_t y_min,
        const coord_t y_max,
        const coord_t z_min,
        const coord_t z_max,
        const coord_t resolution_xy,
        const coord_t resolution_z_ = -1.0,
        const T* fill_value = nullptr
        );

    virtual void clear();
    void fill(const T& value);
    bool isOutOfBounds(const int cx, const int cy, const int cz) const;
    size_t cellAbsIndexFromCXCYCZ(const int cx, const int cy, const int cz) const;
    T* cellByPos(coord_t x, coord_t y, coord_t z);
    const T* cellByPos(coord_t x, coord_t y, coord_t z) const;
    T& cellRefByPos(coord_t x, coord_t y, coord_t z);
    const T& cellRefByPos(coord_t x, coord_t y, coord_t z) const;
    T* cellByIndex(unsigned int cx, unsigned int cy, unsigned int cz);
    const T* cellByIndex(unsigned int cx, unsigned int cy, unsigned int cz) const;
    const T* cellByIndex(size_t cidx) const;
    T* cellByIndex(size_t cidx);
    size_t getSizeX() const;
    size_t getSizeY() const;
    size_t getSizeZ() const;
    size_t getVoxelCount() const;
    coord_t getXMin() const;
    coord_t getXMax() const;
    coord_t getYMin() const;
    coord_t getYMax() const;
    coord_t getZMin() const;
    coord_t getZMax() const;
    coord_t getResolutionXY() const;
    coord_t getResolutionZ() const;
    int x2idx(coord_t x) const;
    int y2idx(coord_t y) const;
    int z2idx(coord_t z) const;
    coord_t idx2x(int cx) const;
    coord_t idx2y(int cy) const;
    coord_t idx2z(int cz) const;

    template <class ARCHIVE>
    void dyngridcommon_writeToStream(ARCHIVE& out) const;

    template <class ARCHIVE>
    void dyngridcommon_readFromStream(ARCHIVE& in);

    mrpt::rtti::CObject::Ptr duplicateGetSmartPtr() const;
    static const mrpt::rtti::TRuntimeClassId& GetRuntimeClassIdStatic();
    virtual const mrpt::rtti::TRuntimeClassId* GetRuntimeClass() const;
    virtual CObject* clone() const = 0;
    virtual const mrpt::rtti::TRuntimeClassId* GetRuntimeClass() const;
    static const mrpt::rtti::TRuntimeClassId& GetRuntimeClassIdStatic();
    void logStr(const VerbosityLevel level, std::string_view msg_str) const;
    void logFmt(const VerbosityLevel level, const char* fmt, ...) const;
    void void logCond(const VerbosityLevel level, bool cond, const std::string& msg_str) const;
    void setLoggerName(const std::string& name);
    std::string getLoggerName() const;
    void setVerbosityLevel(const VerbosityLevel level);
    void setVerbosityLevelForCallbacks(const VerbosityLevel level);
    void setMinLoggingLevel(const VerbosityLevel level);
    VerbosityLevel getMinLoggingLevel() const;
    VerbosityLevel getMinLoggingLevelForCallbacks() const;
    bool isLoggingLevelVisible(VerbosityLevel level) const;
    void getLogAsString(std::string& log_contents) const;
    std::string getLogAsString() const;
    void writeLogToFile(const std::optional<std::string>& fname_in = std::nullopt) const;
    void dumpLogToConsole() const;
    std::string getLoggerLastMsg() const;
    void getLoggerLastMsg(std::string& msg_str) const;
    void loggerReset();
    void logRegisterCallback(output_logger_callback_t userFunc);
    bool logDeregisterCallback(output_logger_callback_t userFunc);
    COutputLogger& operator = (const COutputLogger&);
    COutputLogger& operator = (COutputLogger&&);
    static std::array<mrpt::system::ConsoleForegroundColor, NUMBER_OF_VERBOSITY_LEVELS>& logging_levels_to_colors();
    static const std::array<const char*, NUMBER_OF_VERBOSITY_LEVELS>& logging_levels_to_names();
    OptionsCapable& operator = (const OptionsCapable&);
    OptionsCapable& operator = (OptionsCapable&&);
    virtual std::map<std::string, mrpt::config::CLoadableOptions*> optionsByName() = 0;
    virtual bool trySetCreationOptions(] const mrpt::config::CConfigFileBase& cfg, ] const std::string& section);

Typedefs

typedef std::shared_ptr<mrpt::maps ::CRandomFieldGridMap3D> Ptr

A type for the associated smart pointer.

Fields

static bool ENABLE_GMRF_PROFILER

[default:false] Enables a profiler to show a performance report at application end.

TInsertionOptions insertionOptions

See also:

updateMapEstimation()

Construction

CRandomFieldGridMap3D(
    double x_min = -2,
    double x_max = 2,
    double y_min = -2,
    double y_max = 2,
    double z_min = -2,
    double z_max = 2,
    double voxel_size = 0.5,
    bool call_initialize_now = true
    )

Constructor.

If you set call_initialize_now to false, the object will be initialized immediately (without the heavy initialization of the GMRF), but you then must call setSize() or clear() later to properly initialize the object before using it to insert observations.

Methods

virtual const mrpt::rtti::TRuntimeClassId* GetRuntimeClass() const

Returns information about the class of an object in runtime.

virtual mrpt::rtti::CObject* clone() const

Returns a deep copy (clone) of the object, indepently of its class.

virtual void clear()

Erases all added observations and start again with an empty gridmap.

bool saveAsCSV(
    const std::string& filName_mean,
    const std::string& filName_stddev = std::string()
    ) const

Save the current estimated mean values to a CSV file (compatible with Paraview) with fields x y z mean_value.

Optionally, std deviations can be also saved to another file with fields x y z stddev_value, if filName_stddev is provided.

Returns:

false on error writing to file

virtual std::map<std::string, mrpt::config::CLoadableOptions*> optionsByName()

Maps an options-group name (e.g.

“insertionOptions”) to a pointer to the corresponding, live CLoadableOptions member. Pointers remain valid as long as this is alive, and point directly to the actual option members (no copies), so writes through them (e.g. via loadFromConfigFile()) take effect immediately.

Implementations should list every CLoadableOptions member they define, INCLUDING “creationOptions” if present (so it can be discovered/exported generically); however, callers must use trySetCreationOptions(), not a direct write through this pointer, to safely modify creation options.

void resize(
    double new_x_min,
    double new_x_max,
    double new_y_min,
    double new_y_max,
    double new_z_min,
    double new_z_max,
    const TRandomFieldVoxel& defaultValueNewvoxels,
    double additionalMarginMeters = 2.0
    )

Changes the size of the grid, maintaining previous contents.

See also:

setSize

void setSize(
    const double x_min,
    const double x_max,
    const double y_min,
    const double y_max,
    const double z_min,
    const double z_max,
    const double resolution_xy,
    const double resolution_z = -1.0,
    const TRandomFieldVoxel* fill_value = nullptr
    )

Changes the size of the grid, erasing previous contents.If resolution_z <0, the same resolution will be used for all dimensions x,y,z as given in resolution_xy

Changes the size of the grid, erasing previous contents.

See also:

resize.

void setVoxelsConnectivity(const ConnectivityDescriptor::Ptr& new_connectivity_descriptor)

Sets a custom object to define the connectivity between voxels.

Must call clear() or setSize() afterwards for the changes to take place.

bool insertIndividualReading(
    const double sensorReading,
    const double sensorVariance,
    const mrpt::math::TPoint3D& point,
    const TVoxelInterpolationMethod method,
    const bool update_map
    )

Direct update of the map with a reading in a given position of the map.

Returns:

false if point is out of the grid extension.

void updateMapEstimation()

Run the method-specific procedure required to ensure that the mean & variances are up-to-date with all inserted observations, using parameters in insertionOptions.