336 lines
11 KiB
Markdown
336 lines
11 KiB
Markdown
# 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**
|
|
|
|
```bash
|
|
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):
|
|
|
|
```bash
|
|
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:
|
|
|
|
```bash
|
|
./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](http://www.6d-vision.com/scene-labeling) are used to test the software.
|
|
|
|
## Test Execution
|
|
libSGM uses [Google Test](https://github.com/google/googletest) 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++).
|
|
|
|
```bash
|
|
# 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](https://www.fixstars.com/) and its subsidiary companies including [Fixstars Autonomous Technologies](https://at.fixstars.com/), aimed at contributing to the ADAS industry by developing high-performance implementations for algorithms with high computational cost.
|
|
|
|
## License
|
|
Apache License 2.0
|
|
|
|
|
|
|
|
|