struct mola::IncrementalPointCloud::TCreationOptions

Overview

All parameters specific to this class. The standard insertionOptions, likelihoodOptions and renderOptions groups inherited from mrpt::maps::CPointsMap apply as usual.

Changing any of the k-d tree parameters (async_rebuild, alpha_*, reserve_points) on an already-populated map is fine: trySetCreationOptions() compacts and rebuilds the index with the new values, so no point is lost, but the point indices previously returned by the nn_* methods are invalidated.

See also:

compact()

#include <IncrementalPointCloud.h>

struct TCreationOptions: public mrpt::config::CLoadableOptions
{
    // fields

    double remove_points_farther_than = .0;
    bool async_rebuild = false;
    float alpha_balance = 0.75f;
    float alpha_deleted = 0.5f;
    uint64_t reserve_points = 0;
    uint32_t k_correspondences_for_cov = 20;
    uint32_t min_correspondences_for_cov = 5;
    double max_distance_for_cov = 1.0;
    double max_plane_deviation_for_cov = 0;
    double plane_regularization_lambda = 1e-3;
    bool serialize_kdtree = false;

    // methods

    void loadFromConfigFile(
        const mrpt::config::CConfigFileBase& source,
        const std::string& section
        );

    void dumpToTextStream(std::ostream& out) const;
    void writeToStream(mrpt::serialization::CArchive& out) const;
    void readFromStream(mrpt::serialization::CArchive& in);
};

Fields

double remove_points_farther_than = .0

If !=0, on each insertion with a known robot pose, keep only the points inside the axis-aligned cube of this half side [m] around it. This is the sliding-window trim of FAST-LIO-style local maps, the analogous of HashedVoxelPointCloud::remove_voxels_farther_than.

bool async_rebuild = false

Perform the k-d tree balancing rebuilds on a background thread. Bounds the mapping-thread tail latency (on a LiDAR-odometry local map this turns ~300 ms insertion spikes into a flat ~10 ms), at the cost of roughly twice the index memory.

The worker reads the inherited coordinate buffers, so they must not be reallocated while it runs. reserve(), resize() and setSize() wait for it, which covers insertObservation() and insertAnotherMap(); a hand-written insertPointFast() loop bypasses them, so either reserve the storage up front (reserve_points) or grow it through reserve().

float alpha_balance = 0.75f

Weight-balance rebuild threshold: a subtree is rebuilt when its larger child holds more than this fraction of its points. Lower keeps queries faster and rebuilds more frequent.

float alpha_deleted = 0.5f

Tombstone rebuild threshold: a subtree is rebuilt, physically dropping removed points, once this fraction of it is dead.

uint64_t reserve_points = 0

If !=0, pre-allocate storage for this many points. Recommended together with async_rebuild, since it avoids reallocating the coordinate buffers the background worker reads.

uint32_t k_correspondences_for_cov = 20

Number of neighbors used to estimate each point covariance for nn_search_cov2cov().

See also:

mola::KeyframePointCloudMap

uint32_t min_correspondences_for_cov = 5

Below this number of neighbors actually found, a plane fit is deemed unreliable and an isotropic covariance is used instead.

double max_distance_for_cov = 1.0

Maximum distance [m] to search neighbors for the covariance estimate.

double max_plane_deviation_for_cov = 0

Maximum distance [m] any neighbor may sit from the least-squares plane through the neighborhood for that neighborhood to receive the plane regularization below. 0 (default) disables the test. Same semantics as the option of the same name on KeyframePointCloudMap.

double plane_regularization_lambda = 1e-3

Variance asserted along the estimated surface normal, the other two being 1, i.e. the plane confidence ratio written as its reciprocal. The shipped 1e-3 asserts 1000:1. Must be in (0, 1].

bool serialize_kdtree = false

If true, the k-d tree index is serialized alongside the points (see IncrementalPointCloud serialization), so it does NOT have to be rebuilt (an O(N log N) bulk build) when the map is loaded. Requires an MRPT/nanoflann build providing the incremental index’s save/load API (feature-detected at compile time via MOLA_METRIC_MAPS_HAS_INCREMENTAL_KDTREE_BAKE); when unavailable this option is silently a no-op on write, and a reader without the feature skips any baked blob found in the file. Default false. Typically enabled offline by the mm-ipc-bake-kdtree tool: the map is always serialized compacted (no tombstoned slots, see IncrementalPointCloud::serializeTo()), so baking rebuilds the index once over that compacted point order at save time instead of leaving the O(N log N) build for every subsequent load.