AsadUllah/Speckle-Scanner
1
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity

Initial commit: Speckle-Scanner 3D pipeline with setup README

Browse Source
This commit is contained in:
AsadUllah
2026-06-10 03:09:05 +05:00
commit 1765934846
375 changed files with 123081 additions and 0 deletions
Download Patch File Download Diff File Expand all files Collapse all files
05_disparity/libsgm/README.md
+335
View File
@@ -0,0 +1,335 @@
# 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