Slamcore CLI

The Slamcore command line tools are installed via the Slamcore Tools package for your chosen platforms. There are three CLI applications:

  • slamcore_dataset_recorder_cli

  • slamcore_dataset_compressor

  • slamcore_dataset_processor

Note

Run the tool(s) with --help-all for more information and options.

Dataset Recorder CLI

Note

It is possible to record a dataset whilst running live SLAM. See Dataset Recording during a SLAM Run for more information.

To record a dataset using your camera without using a GUI, run the following from a terminal window:

$ slamcore_dataset_recorder_cli -o <output/directory>

Ctrl + c to stop recording.

Command-Line Options

At start-up, the Slamcore Dataset Recorder accepts the following command-line options:

-h,--help

Print this help message and exit

--help-all

Expand all help

-v,--version

Display the version

-c,--config-file :FILE ...

Path to the configuration file(s)

-k,--write-kinematics,--no-k{false},--no-kinematics{false}

Enable/disable kinematics sensor stream

-o,--output-dir REQUIRED

Path to the directory to generate the recorded dataset

RealSense Subcommand Options

The following options only apply to RealSense cameras.

realsense

Detect RealSense camera

--dev,--device

Integer device index for multiple reader types

--color,--no-color

Enable or disable the colour stream

--depth,--no-depth

Enable or disable the depth stream (See FAQs for detailed explanation)

--ir,--no-ir

Enable or disable the infrared stream

--fps

Override reader’s FPS (See FAQs for options)

OAK-D S2 Fixed-Focus Subcommand Options

The following options only apply to OAK-D S2 Fixed-Focus cameras.

oakd

Detect OAK-D S2 Fixed-Focus camera

--dev,--device

Integer device index for multiple reader types

--fps

Override reader’s FPS (See FAQs for options)

--rectify,--no-rectify{false}

Whether the reader should provide rectified stereo images

Dataset Compressor

The dataset compressor is a command line tool that allows PNG compression in a recorded dataset, and thus saves storage space on your machine. The generated compressed dataset will take up less space and will still be processable by the Slamcore SLAM software.

To compress a dataset, run the following from a terminal window:

$ slamcore_dataset_compressor -l <level> -j <jobs> -u <path/to/dataset> -o <output/dir>

Note

When processing a compressed dataset, a slightly higher CPU consumption is expected due to the “uncompress” step.

The -l flag allows you to set the compression level. We suggest a compression level of -l 3 as it tends to reduce datasets to 1/3 of the size without impacting decoding time for processing.

The -j flag allows you to set the number of simultaneous CPU threads used to compress the dataset. This can be set to nproc if no other applications are running on the machine (see nproc Linux manual page):

$ slamcore_dataset_compressor -j $(nproc) -l 3 -u <path/to/dataset> -o <output/dir>

Or a recommended half of nproc during normal CPU usage:

$ num_procs=$(nproc)
$ slamcore_dataset_compressor -j $((num_procs / 2)) -l 3 -u <path/to/dataset> -o <output/dir>

Command-Line Options

At start-up, the Slamcore Dataset Processor accepts the following command-line options:

-h,--help

Print this help message and exit

-u, --euroc-dataset TEXT:DIR

Path to dataset directory

-o,--output-dir TEXT REQUIRED

Path to output dataset directory

-j INT

How many threads to use (uses all if not specified)

--delete-src BOOLEAN

Delete source directory after successful compression

-l,--compression-level INT

PNG compression level (0 = no compression to 9 = best compression) (set to 3 if not specified)

Dataset Processor

The dataset processor is a command line tool that generates a session map from the SLAM run and saves the trajectories in CSV files, without using a GUI. This allows for more systematic evaluation of our tracking/positioning system. The optimised and unoptimised trajectories are recorded in two separate CSV files (more details in the Guide to Trajectories).

$ slamcore_dataset_processor dataset -u <path/to/dataset> -o
<output/directory>

Starting Slamcore Dataset Processor...
[00:10] OK       | Distance [m]:    1.28 | XYZ [m]   -0.52     0.45     0.76
[00:21] OK       | Distance [m]:    4.44 | XYZ [m]   -0.32    -0.04     0.15
[00:30] OK       | Distance [m]:    7.31 | XYZ [m]   -0.27    -0.04     0.23
[00:39] OK       | Distance [m]:   10.31 | XYZ [m]   -0.33     0.03     0.27
[00:46] OK       | Distance [m]:   12.79 | XYZ [m]   -0.59     0.30     0.53
[00:53] OK       | Distance [m]:   15.15 | XYZ [m]   -1.87     0.17     0.33
[01:01] OK       | Distance [m]:   17.69 | XYZ [m]   -1.31     0.53     0.27
[01:10] OK       | Distance [m]:   20.11 | XYZ [m]   -0.57     0.41     0.52
[01:18] OK       | Distance [m]:   22.63 | XYZ [m]   -0.85     0.48     0.61
[01:24] OK       | Distance [m]:   24.59 | XYZ [m]   -1.30     0.55     0.28
[01:31] OK       | Distance [m]:   26.33 | XYZ [m]   -1.40     0.38     0.28
[01:38] OK       | Distance [m]:   27.89 | XYZ [m]   -1.22     0.59     0.27
[01:45] OK       | Distance [m]:   29.83 | XYZ [m]    0.01    -0.03     0.02
Done.

Saving trajectories to "<output/directory>"...Done.
Please check the logs at:
/tmp/slamcore_dataset_processor.*

The dataset processor is able to process data from either a live camera feed or a recorded dataset.

SLAM, Localisation, Mapping and Odometry Mode

There are four main ways to run our system:

Mode

Description

SLAM

A sparse map is built on the go, without any prior knowledge about the environment.

Localisation

Use a sparse map previously created in SLAM mode.

Height Mapping

Build a height and occupancy map for autonomous navigation.

Panoptic Segmentation

Segment and detect object instances. See Panoptic Segmentation API for requirements and installation.

Odometry

Positioning without using a map. See Positioning Mode to use this mode.

SLAM Mode

Run SLAM on a Live Camera feed

To run in live SLAM mode, where a sparse map is built on the go, from the terminal window run:

$ slamcore_dataset_processor -o <output/directory> -s

Ctrl + c to stop the SLAM session. A session file and the optimised and unoptimised trajectories will be saved in the specified output directory.

If no -s flag is provided, no session file will be generated.

Note

The optimised trajectories differ when the -s flag is and isn’t provided when saving a session.

Run SLAM on a recorded dataset

To run the dataset processor on a prerecorded dataset, use the dataset subcommand and specify the dataset to use with the -u flag.

$ slamcore_dataset_processor dataset -u <path/to/dataset> -o <output/directory> -s

Localisation Mode

Note

In localisation mode, no optimised trajectory or session file will be generated, only a CSV file of the unoptimised trajectory.

Warning

Slamcore SDK v23.01 brings several breaking changes, one of them being the session file format. Session files (.session) generated using older software versions (v21.06) will no longer be usable with v23.01 and above. You may use the new software to generate a new session file if you have retained the original dataset.

Please contact support@slamcore.com, providing your Slamcore account email address, if you require access to the v21.06 SDK packages and its supporting documentation to use in conjunction with your old session files.

Live Localisation

To run the dataset processor on a previously created map, load a session file with the -l flag.

$ slamcore_dataset_processor -l <path/to/session/file> -o <output/directory>
Localisation using a recorded dataset

To run SLAM on a recorded dataset using a previously created map, use the dataset subcommand, specify the dataset and session file to use with the -u and -l flag respectively.

$ slamcore_dataset_processor dataset -u <path/to/dataset> -l <path/to/session/file> -o <output/directory>

Height Mapping Mode

Live Mapping

To generate a height map with a live camera feed, enable session saving and map generation with the -s and -m flags respectively:

$ slamcore_dataset_processor -m -s -o <output/directory>
Mapping using a prerecorded dataset

To generate a height/occupancy map from a dataset that contains depth information, run:

$ slamcore_dataset_processor dataset -u <path/to/dataset> -m -s -o <output/directory>

Dataset Recording during a SLAM Run

The dataset processor also supports recording a dataset while simultaneously running SLAM on a live camera. To do so, specify the directory to write the dataset to with the --dataset-write-dir flag:

$ slamcore_visualiser --dataset-write-dir </output/directory>

Note

Recording a dataset while simultaneously running SLAM on a live camera is compatible with any of the Slamcore software modes: SLAM, Localisation, Mapping and Odometry Mode.

Command-Line Options

At start-up, the Slamcore Dataset Processor accepts the following command-line options:

-h,--help

Print this help message and exit

--help-all

Expand all help

-v,--version

Display the version

-c,--config-file :FILE ...

Path to the configuration file(s)

-k,--write-kinematics,--no-k{false},--no-kinematics{false}

Enable/disable kinematics sensor stream

--enable-panoptic-plugin

Enable Panoptic Segmentation plugin

-l,--load-session :FILE

Path to the session file to load

-o,--output-dir DIR REQUIRED

Path to output directory

-s,--save-session Excludes: --load-session

Generate session (“-s” to enable)

--dataset-write-dir

Directory to write dataset to

-m,--generate-map2d

Produce a new 2D map (depth stream must be enabled --depth)

Dataset Subcommand Options

The dataset subcommand allows dataset processing via the Slamcore Dataset Processor tool.

$ slamcore_dataset_processor dataset -u <path/to/dataset> -o <output/directory> -s
-u,--euroc-dataset :DIR

Dataset reader path

--ts,--timescale FLOAT

Timescale for dataset reader, for real time processing set to 1.0

RealSense Subcommand Options

The following options only apply to RealSense cameras.

realsense

Detect RealSense camera

--dev,--device

Integer device index for multiple reader types

--color,--no-color

Enable or disable the colour stream

--depth,--no-depth

Enable or disable the depth stream (See FAQs for detailed explanation)

--ir,--no-ir

Enable or disable the infrared stream

--fps

Override reader’s FPS (See FAQs for options)

OAK-D S2 Fixed-Focus Subcommand Options

The following options only apply to OAK-D S2 Fixed-Focus cameras.

oakd

Detect OAK-D S2 Fixed-Focus camera

--dev,--device

Integer device index for multiple reader types

--fps

Override reader’s FPS (See FAQs for options)

--rectify,--no-rectify{false}

Whether the reader should provide rectified stereo images