Siapy command line tool

This repository provides a command line interface (CLI) for the siapy library, designed to streamline the segmentation of spectral images for further analysis.

With this CLI, you can:

Display images from two cameras.
Co-register cameras and compute the transformation from one camera's space to another.
Select regions in images for training machine learning (ML) models.
Perform image segmentation using a pre-trained ML model.
Convert radiance images to reflectance by utilizing a reference panel.
Display spectral signatures for in-depth analysis.

🏃‍♀️ Installation

Clone the Repository and Install Dependencies

Start by cloning the repository and running the installation script:

git clone https://github.com/siapy/siapy-cli.git
cd siapy-cli
./scripts/install-dev.sh

Configure Environment Variables

Create .env file in the root of the project directory (inside siapy-cli folder) and define the necessary environment variables:

# -------------------------------------------------------------
# .env file located in the root of the project repository

# Set the project name, e.g.:
PROJECT_NAME=example_project

# Specify the directory where spectral images are stored, e.g.:
IMAGES_DIR=/path/to/your/spectral_images
# -------------------------------------------------------------

❗ Note for WSL (Windows Subsystem for Linux) users:

Make sure that images are also located within the WSL file system, e.g. in /home/$USER/data/ directory

To easily access your WSL file system from Windows, open explorer.exe and type \\wsl$\Ubuntu into the address bar to navigate your WSL files.

Verify the Installation

Run one of the following commands to verify the installation and check if everything is working:

siapy-cli --version
# or
pdm run main.py --version
# or
python main.py --version
# ...

🚀 Usage

$ siapy-cli --help

Usage: siapy-cli [OPTIONS] COMMAND [ARGS]...

Options:
  --install-completion    Install completion for the current shell.
  --show-completion       Show completion for the current shell, to copy it or customize the installation.
  --help                  Show this message and exit.

Commands:
  calculate-transformation
  check-images
  convert-to-reflectance
  create-signatures
  display-image
  display-settings
  segment-images
  select-areas
  train-model

📖 Cookbook

This guide provides a step-by-step workflow to segment relevant areas of spectral images.

Image Naming Convention

Before you begin, ensure that the images are correctly named according to the following convention:

Image file: L1_L2_L3__*.img
Header file: L1_L2_L3__*.hdr (corresponding to the image file)

Where:

L1, L2, L3, etc., represent labels for objects in the spectral image.
The number of labels (L) can vary depending on the number of objects in the image.
Labels are separated by an underscore (_)
Double underscore (__) separates the label section from the rest of the filename.

Workflow

Check images

Run the following command to check the images:

siapy-cli check-images

The number of images and unique labels should be the same for both cameras.
The duplicated labels space should be empty.

Calculate transformation between cameras

Calculate the transformation between the two cameras using the label L:

siapy-cli calculate-transformation L

L is the label on one image where the corresponding points will be selected first on camera one and then on camera two.
Select at least 6 points, but preferably more than 9.
Try to select the same positions on matching images as accurately as possible.

Select areas for ML model training

Run the following commands to select approximately balanced areas for each category (object or background):

# For label e.g. object
siapy-cli select-areas L object
# For label e.g. background
siapy-cli select-areas L background

Train model based on selected areas

siapy-cli train-model

Segment images

If all the steps were executed successfully, you can proceed to segment the images:

# Start from the beginning
siapy-cli segment-images
# Start from label L
siapy-cli segment-images L

First, select the reference panel.
Then, select all the objects and press enter.
The segmentation masks are drawn; press save to save the segmented image, repeat to repeat the process, and skip to proceed to the next one without saving.

Convert to reflectance

Convert images based on reference panel reflectance values:

siapy-cli convert-to-reflectance VALUE
# e.g. for reflectance value of 0.2
siapy-cli convert-to-reflectance 0.2

Convert to spectral signatures

Convert the segmented images to a tabular format for further analysis:

siapy-cli create-signatures

This step will create one row for each object. Therefore, one object in the image will be described by one spectral signature.

Output

Upon execution, images and a Parquet file will be created. All artifacts are saved in siapy-cli/artifacts directory.

The columns of the Parquet file represent the following:

filename: 📄 The name of the image file from which the pixel originates.
label: 🏷️ The label assigned to the image.
image_idx: 🔢 The index of the image in the dataset.
object_idx: 🔢 The index of the object within the image.
signature: 📈 The spectral values associated with the object.

Example row:

{
  "filename": "L1_L2_L3",
  "label": "L1",
  "image_idx": "0",
  "object_idx": "1",
  "signature": [...]
  }