struct mola::KeyframeDecisionOptions

Overview

Options of the keyframe-creation policy shared by the local metric map and the simplemap / central-mapper keyframe deciders.

Both Parameters::MapUpdateOptions and Parameters::SimpleMapOptions derive from this struct, so all fields keep being plain, non-nested YAML keys of their respective sections.

#include <KeyframeDecider.h>

struct KeyframeDecisionOptions
{
    // fields

    double min_translation_between_keyframes = 1.0;
    double min_rotation_between_keyframes = 30.0;
    bool measure_from_last_kf_only = false;
    uint32_t min_nearby_poses_occupied = 1;
    double nearby_keyframe_time_window = 0;
};

// direct descendants

struct MapUpdateOptions;
struct SimpleMapOptions;

Fields

double min_translation_between_keyframes = 1.0

Minimum Euclidean distance (x,y,z) between keyframes [meters].

double min_rotation_between_keyframes = 30.0

Minimum rotation (in 3D space, yaw, pitch, roll altogether) between keyframes [degrees].

bool measure_from_last_kf_only = false

If true, only the distance to the LAST keyframe is considered. Use if mostly mapping without “closed loops”.

If false (default), a KD-tree is used to check the distance to all past keyframe poses. See also nearby_keyframe_time_window, which bounds how far back in time that search reaches. Combining both is allowed but redundant: the last keyframe is always inside the window, so the window has no additional effect.

uint32_t min_nearby_poses_occupied = 1

Minimum number of stored poses within the threshold distance before a volume is considered “occupied” and no new keyframe is inserted there. Default=1 gives the classic behavior. Increase to 2+ for non-repetitive-scan lidars (e.g. Livox) so multiple scans are taken from each location.

double nearby_keyframe_time_window = 0

Time window [seconds] for the “is there already a keyframe here?” test. 0 (default) disables it: the test then reaches ALL past keyframes.

With the default, purely spatial policy, revisiting a mapped area creates NO new keyframes, since the previous pass’ keyframes are the nearest neighbors. That is the desired behavior for a local metric map (a revisit adds no coverage), but it starves loop closure: a loop can only be detected if BOTH of its endpoints exist as keyframes, so the revisit that should close the loop produces nothing to close it with.

When set to a positive value, only keyframes newer than this many seconds take part in the test (plus the most recent one, always, so a stationary vehicle does not emit one keyframe per window). Older keyframes become invisible to it, so a revisit spawns fresh keyframes.

Read once, at KeyframeDecider construction time: unlike the two distance thresholds, this one cannot be a per-scan dynamic expression, since it selects which of the two policies (and which storage) the decider uses.