Speckle-Scanner/05_disparity/libsgm

installation process for US:

Install Anaconda and CUDA Toolkit (compute capability >= 3.5) Check if cmake is installed.

$ cmake --version

if version is <3.18

$ sudo apt remove cmake #Only if cmake is installed with <3.18 version
$ wget https://github.com/Kitware/CMake/releases/download/v3.21.5/cmake-3.21.5.tar.gz
$ tar -xzvf cmake-3.21.5.tar.gz
$ cd cmake-3.21.5
$ ./bootstrap
$ make
$ sudo make install
$ cmake --version

Now if it is giving error of not found

$ find /usr/local/bin -name cmake

if path exists then close the terminal and open new terminal then again check the version.

$ cmake --version

Environment:

Create an environment (named libsgm) in conda

$ conda create --name libsgm
$ conda activate libsgm

Installing Fixstars LibSGM:

$ git clone https://gitea.subseascanning.com/dejhost/libSGM.git
$ cd libSGM
$ git submodule update --init
$ mkdir build  
$ cd build
$ cmake ../
$ make

Sample Execution

$ pwd
.../libSGM
$ cd build
$ cmake .. -DENABLE_SAMPLES=on
$ make
$ cd sample

place /data folder in libSGM/build/sample/data.

Now run the command once to confirm the installation and working of LibSGM. For single image pair you use this stereosgm_new file The disparity map will be saved on the same path which contains the executeable stereosgm_new file (.../libSGM/build/sample)

$ ./stereosgm_new data/lc00012.bmp data/rc00012.bmp

For multiple pairs one after another you can use stereosgm_image it will save disparity.xml files in output directory.

$ ./stereosgm_image data/lc%05d.bmp data/rc%05d.bmp

---

Pipeline Usage (Automated Path Resolution)

Use run_sgm_pipeline.py to run libSGM across the project folder structure automatically. It picks the last rectified image pair (highest timestamp) from each scan's 02_rect_images/ folder, runs stereosgm_new, and saves results to 03_sgm_disp_map/.

Folder structure assumed

~/Speckle-Scanner_Processing_data/
└── <project>/
    └── <date>/
        └── <session>/
            └── <ScanXXXXXX>/
                ├── 02_rect_images/     ← lc_ts<last>.png + rc_ts<same>.png (input)
                ├── 03_sgm_disp_map/    ← disparity.xml + disparity_color.png (created)
                └── 05_sgm_pcl/         ← untouched

Pairs are matched on the shared ts token (e.g. ts1634840093). Both formats work: lc_ts1634840093_ck….png / rc_ts1634840093_ck….png and lc_ts1634840093.png / rc_ts1634840093.png.

Commands

cd ~/Speckle-Scanner/05_disparity/libsgm

# Process ALL scans in a session
python run_sgm_pipeline.py \
  --project Olsen_wings \
  --date    2026-05-12 \
  --session session1

# Process ALL sessions on a date (omit --session)
python run_sgm_pipeline.py \
  --project Olsen_wings \
  --date    2026-05-12

# Process a SINGLE scan
python run_sgm_pipeline.py \
  --project Olsen_wings \
  --date    2026-05-12 \
  --session session1 \
  --scan    Scan000001

# Custom SGM parameters
python run_sgm_pipeline.py \
  --project    Olsen_wings \
  --date       2026-05-12 \
  --session    session1 \
  --disp_size  128 \
  --P1         8 \
  --P2         32 \
  --min_disp   0 \
  --num_paths  8 \
  --census_type 1

Pipeline parameters

Parameter	Default	Description
--project	—	Project name (e.g. Olsen_wings)
--date	—	Date string (e.g. 2026-05-12)
--session	all	Session name (e.g. session1); omit to process all sessions on that date
--scan	all	Single scan (e.g. Scan000001); omit to process all scans in the session
--disp_size	256	Maximum disparity value (64, 128, or 256)
--P1	10	SGM penalty for disparity change of ±1
--P2	120	SGM penalty for disparity change > 1
--uniqueness	0.80	Uniqueness ratio threshold
--num_paths	8	Scanlines for cost aggregation (4 or 8)
--min_disp	-160	Minimum disparity value
--LR_max_diff	1	Maximum allowed left-right disparity difference
--census_type	1	Census transform type: 0=CENSUS_9x7, 1=SYMMETRIC_CENSUS_9x7

What gets saved in 03_sgm_disp_map/

File	Description
disparity.xml	Raw disparity matrix (OpenCV FileStorage format, CV_16S)
disparity_color.png	Colorized disparity image (TURBO colormap, 8-bit)

---

Direct Binary Usage

Run stereosgm_new manually with explicit paths (must run from the build/sample directory or use full paths):

cd ~/Speckle-Scanner/05_disparity/libsgm/build/sample

# Default parameters, save to current directory
./stereosgm_new data/lc00012.bmp data/rc00012.bmp

# Save to a specific output folder, no display window
./stereosgm_new \
  /path/to/lc_image.png \
  /path/to/rc_image.png \
  --output_dir=/path/to/03_sgm_disp_map \
  --no_display=1 \
  --disp_size=128 --P1=8 --P2=32

---

Available Parameters

Parameter	Default Value	Description
@left-image-format	none	Format string for the path to input left image (e.g., "left/img_%04d.png")
@right-image-format	none	Format string for the path to input right image
--disp_size	256	Maximum possible disparity value
--P1	10	Penalty for disparity change of ±1
--P2	120	Penalty for disparity change > 1
--uniqueness	0.80	Margin ratio for uniqueness constraint
--num_paths	8	Number of scanlines used in cost aggregation (4 or 8)
--min_disp	-160	Minimum disparity value
--LR_max_diff	1	Maximum allowed left-right disparity difference
--census_type	1	Census transform type (0: 5x5, 1: 9x7, 2: 11x9)
--interval	1	Polling interval (in seconds) for checking new stereo image pairs
--output_dir	.	Directory to save disparity.xml and disparity_color.png
--no_display	0	Set to 1 to skip interactive display window (required for pipeline/headless use)
--help or -h		Show help message

Custom Parameters

You can override any parameter through command-line arguments. Below is an example with some customized parameters:

./stereosgm_image data/lc%05d.bmp data/rc%05d.bmp \
  --disp_size=128 --P1=8 --P2=32 --interval=2

libSGM(Orignal)

---

A CUDA implementation performing Semi-Global Matching.

Introduction

---

libSGM is library that implements in CUDA the Semi-Global Matching algorithm.
From a pair of appropriately calibrated input images, we can obtain the disparity map.

Features

---

Because it uses CUDA, we can compute the disparity map at high speed.

Performance

The libSGM performance obtained from benchmark sample

Settings

• image size : 1024 x 440
• disparity size : 128
• sgm path : 4 path
• subpixel : enabled

Results

Device	CUDA version	Processing Time[Milliseconds]	FPS
GTX 1080 Ti	10.1	2.0	495.1
GeForce RTX 3080	11.1	1.5	651.3
Tegra X2	10.0	28.5	35.1
Xavier(MODE_15W)	10.2	17.3	57.7
Xavier(MAXN)	10.2	9.0	110.7

Requirements

Package Name	Minimum Requirements	Note
CMake	version >= 3.18
CUDA Toolkit	compute capability >= 3.5
OpenCV	version >= 3.4.8	for samples
OpenCV CUDA module	version >= 3.4.8	for OpenCV wrapper
ZED SDK	version >= 3.0	for ZED sample

Build Instructions

$ git clone https://github.com/fixstars/libSGM.git
$ cd libSGM
$ git submodule update --init  # It is needed if ENABLE_TESTS option is set to ON
$ mkdir build
$ cd build
$ cmake ../  # Several options available
$ make

Sample Execution

$ pwd
.../libSGM
$ cd build
$ cmake .. -DENABLE_SAMPLES=on
$ make
$ cd sample
$ ./stereosgm_movie <left image path format> <right image path format> <disparity_size>
left image path format: the format used for the file paths to the left input images
right image path format: the format used for the file paths to the right input images
disparity_size: the maximum number of disparities (optional)

"disparity_size" is optional. By default, it is 128.

Next, we explain the meaning of the "left image path format" and "right image path format".
When provided with the following set of files, we should pass the "path formats" given below.

left_image_0000.pgm
left_image_0001.pgm
left_image_0002.pgm
left_image_0003.pgm
...

right_image_0000.pgm
right_image_0001.pgm
right_image_0002.pgm
right_image_0003.pgm

$ ./stereosgm_movie left_image_%04d.pgm right_image_%04d.pgm

The sample images available at Daimler Urban Scene Segmentation Benchmark Dataset 2014 are used to test the software.

Test Execution

libSGM uses Google Test for tests as Git submodule.
So, we need to init submodule by following command firstly.

$ pwd
.../libSGM
$ git submodule update --init

We can run tests after a build.

$ pwd
.../libSGM
$ cd build
$ cd test
$ ./sgm-test

Test code compares our implementation of each functions to naive implementation.

Python pipeline runner dependencies

run_sgm_pipeline.py uses only the Python standard library. Disparity is computed by the compiled stereosgm_new binary.

See requirements.txt in this folder for system build requirements (CUDA, CMake, OpenCV C++).

# No pip packages needed for the Python runner.
# Build the binary first (see above), then:
cd ~/Speckle-Scanner/05_disparity/libsgm
python run_sgm_pipeline.py --project <project> --date <date>

Author

The "adaskit Team"

The adaskit is an open-source project created by Fixstars Corporation and its subsidiary companies including Fixstars Autonomous Technologies, aimed at contributing to the ADAS industry by developing high-performance implementations for algorithms with high computational cost.

License

Apache License 2.0