You’re reading an older version of the Slamcore SDK documenation. The latest one is 23.04.

SLAM Configuration

The following parameters can be used to change the configuration of the SLAM algorithm.

Parameters

Default Value

Type

Base.ProfileName

"default"

String

Position.PositioningMode

"SLAM"

String

Position.Estimator.NumKeyFrames

5

Integer

Position.Estimator.NumIMUFrames

5

Integer

Position.Estimator.TimeBudget

"18ms"

String

Position.Frontend.FeatureExtractionROI.{X, Y}

0

Integer

Position.Frontend.FeatureExtractionROI.Width

848

Integer

Position.Frontend.FeatureExtractionROI.Height

480

Integer

Position.Frontend.NumKeypoints

100

Integer

Position.Frontend.MaxDepthUncertaintyRatio

0.3

Float

Position.Frontend.RadiusANMS

17

Integer

Position.Frontend.TrackingOnPlane.DetectionMethod

"RANSAC"

String

Position.Frontend.TrackingOnPlane.DoTrackingOnPlane

false

Boolean

Position.Frontend.TrackingOnPlane.PriorPlaneNormal

[0.0, 0.0, 1.0]

Array

Position.MultiSession.GBAUseInertialFactors

false

Boolean

An example of a JSON configuration file
{
    "Version": "1.0.0",
    "Base":
    {
    "ProfileName": "high_accuracy"
    },
    "Position":
    {
    "Estimator":
    {
        "NumKeyFrames": 9,
        "NumIMUFrames": 5,
        "TimeBudget": "33ms"
    },
    "Frontend":
    {
        "NumKeypoints": 250,
        "MaxDepthUncertaintyRatio": 2.0,
        "RadiusANMS": 11.0
    },
    "MultiSession":
    {
        "GBAUseInertialFactors": true
    }
    }
}

Display Name

The ProfileName field changes the Preset Name displayed on the SLAMcore Visualiser information panel.

_images/visualiser_preset.png

Fig. 20 SLAMcore Visualiser - Display name of the preset

Positioning Mode

Changes the positioning mode of the SLAMcore software between "SLAM" or "ODOMETRY_ONLY".

  • PositioningMode
    • Type: String

    • Default: “SLAM”

    • Description: Changes the positioning mode of the SLAMcore software.

    • Options:
      • "SLAM" (Default)

        Run in visual-inertial SLAM mode. The algorithm will be able to relocalise or close loops when visiting an area it has visited before. In this mode of operation the algorithm will be able to correct any drift accumulated over time and will be more accurate overall.

      • "ODOMETRY_ONLY"

        Run in visual-inertial odometry mode. During this mode of operation, the algorithm will not relocalise or close any loops, thus there will be no jumps in the pose estimation. However, the global pose estimation may drift more over time.

Estimator Parameters

  • NumKeyFrames
    • Type: Integer

    • Default: 5

    • Description: Specifies the number of keyframes in the local sliding window optimiser.

  • NumIMUFrames
    • Type: Integer

    • Default: 3

    • Description: Specifies the number of frames linked by the most recent non-linear IMU error terms in the local sliding window optimiser.

  • TimeBudget
    • Type: String

    • Default: “18ms”

    • Description: Specifies maximum allowed time of optimisation [ms]

Frontend Parameters

_images/featureextraction-roi.png

Fig. 21 Default vs Custom ROI

  • FeatureExtractionROI
    • Type: Integer

    • Default: { "X" : 0, "Y" : 0, "Width" : <image-width>, "Height" : <image-height> }

    • Description: Set the region of interest (ROI) in pixels for feature extraction, where "X" : 0, "Y" : 0 is the top left corner of the image. For example, the default for sequences recorded with SLAMcore Dataset Recorder are "Width" : 848, "Height" : 480 Setting the ROI may be useful when part of an image should not be used for feature detection due to permanent obstruction in the area.

  • NumKeypoints
    • Type: Integer

    • Default: 100

    • Description: Specifies the maximum number of keypoints that the SLAM algorithm is instructed to detect in each frame. The more features the algorithm detects, the more it will be able to track, and the more accurate the overall pose estimation will be. Note that by increasing the number of keypoints the processing time required for each frame also goes up.

  • MaxDepthUncertaintyRatio
    • Type: Float

    • Default: 0.3

    • Description: Specifies the coefficient of variation of the depth measurement, or the ratio of the standard deviation of the depth measurement to the mean of the measurement. Increasing the maximum allowed ratio allows detection of more features far away from the camera.

  • RadiusANMS
    • Type: Integer

    • Default: 17

    • Description: Specifies the suppression radius (in pixels) of interest points extracted from each image of the adaptive non-maximal suppression (ANMS) interest point selection strategy.

Tracking On Plane

Tracking On Plane may be used for situations where a robot is operating in 2D, on a flat planar environment. This feature constrains vertical displacement with respect to the plane origin as well as roll and pitch angles.

_images/trackingonplane-diagram.png

Fig. 22 Constrained factors with Tracking On Plane enabled.

The plane origin can be defined using two different methods. The default method uses RANSAC plane estimation to determine the dominant ground plane. Alternatively, for situations where plane estimation via RANSAC may be sub-optimal, the user can manually define the normal of the dominant plane in SLAM world coordinates (See figure above or Frames of Reference Convention), using the PriorPlaneNormal parameter. In most cases, the parameter will be set as [0, 0, 1] as the normal to the ground plane is usually the Z axis (vertical direction), the last element of the array.

Warning

If a session is saved with Tracking on Plane enabled, then future localisation runs with that session map will use the existing plane from that mapping run and it will neither estimate a new plane nor discard the plane information from the loaded map, even if you pass in a configuration file with DoTrackingOnPlane set to false.

  • DoTrackingOnPlane
    • Type: Boolean

    • Default: false

    • Description: Set to true to enable detection of a single dominant ground plane.

  • DetectionMethod
    • Type: String

    • Default: "RANSAC"

    • Description: Changes the plane detection method.

    • Options:

      • "RANSAC" (Default) The system accumulates poses from the keyframes and triggers a RANSAC step when sufficient pose and motion information has been collected.

      • "USE_PRIOR_PLANE_NORMAL" Since plane estimation via RANSAC may be sub-optimal during challenging sequences, this option may be used to skip the RANSAC step and track on a plane based on the PriorPlaneNormal provided. By default the prior plane normal is aligned with the gravity direction.

    _images/trackingonplane-detectionmethod.png

    Fig. 23 “Use Prior Plane Normal” vs “RANSAC” Detection Method

  • PriorPlaneNormal
    • Type: Array

    • Default: [0.0, 0.0, 1.0]

    • Description: If using "USE_PRIOR_PLANE_NORMAL" detection method, set the prior plane normal vector.

Multisession Parameters

  • GBAUseInertialFactors
    • Type: Boolean

    • Default: false

    • Description: Set to true to enable the use of inertial factors during GBA for multisession, to constrain the orientation relative to the gravity direction.