# 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