Quickstart

This step-by-step guide walks you from a fresh checkout to a successful run of VISWIR. Follow the steps in order; optional paths (container/HPC) are clearly marked.

Prerequisites

  • OS: Linux (recommended) or Windows (developed on), not tested on macOS

  • Python: 3.10+ installed and on PATH

  • Git: installed

  • Disk space: ~3-5 GB (datasets + container optional)

  • Optional: Singularity/Apptainer (for container), SLURM (for HPC)

Note

If you plan to use TIFF images, you’ll need the Python package imagecodecs.

Step 1 - Get the source

  1. Clone the repository:

    git clone https://github.com/comsee-research/viswir.git
cd viswir

  2. Inspect the layout (optional):

    ls -1
# README.md, HELP.md, src/, config/, data/, tools/, results/, requirements.txt ...

Step 2 - Choose your environment

A. Local Python (virtualenv)

  1. Install packages (script provided):

    chmod +x install_packages_venv.sh
./install_packages_venv.sh

  2. If you use TIFF images:

    pip install imagecodecs

Note

You can also install manually with pip install -r requirements.txt. In this case, first create a virtualenv and activate it:

python -m venv .venv
source .venv/bin/activate

B. Container (Singularity/Apptainer)

  1. Build the container (CPU-only example):

    cd tools
sudo singularity build VISWIR.sif Singularity

    The Singularity build file is available in the tools folder.

Important

To use Singularity, you must be running Linux or WSL2 for Windows (tested via WSL2 with Debian). See the Singularity user guide.

  1. Confirm it runs:

    singularity exec VISWIR.sif python -V

Tip

Full container instructions are available in Help for Singularity and Running VISWIR on HPC with SLURM.

Step 3 - Prepare your data

  1. Create a minimal dataset structure:

    mkdir -p data/visible data/swir results
cp path/to/your/visible_images/*.png data/visible/
cp path/to/your/swir_images/*.png data/swir/

  2. Ensure filenames are paired consistently:

    • Example: data/visible/img_001.png matches data/swir/img_001.png.

  3. Optional detection annotations:

    • Add XML files in data/ground_truth/ if you plan to run detection.

Warning

Misaligned pairs produce invalid fusion. Always verify filenames match across visible/ and swir/.

Step 4 - Configure the run

  1. Edit config/config_viswir.yaml: - Paths: visible_folder, swir_folder, output_folder - Mode: sql (recommended), optuna, or fixed (legacy) - Optional: ref_image_path, ground_truth_path, run_detection, save_output

  2. Fusion parameters: - parameters.json (SQL/fixed modes) - fast_config.yaml (fast mode)

  3. Detection (optional): - yolo_config.json (weights, thresholds, classes, device)

Tip

Start simple—disable detection and enable save_output to validate the pipeline first.

Step 5 - First execution

Fast mode (quick smoke test)

python src/VISWIR_vQuasar.py --fast \
    --visible ./data/visible/img_001.png \
    --swir ./data/swir/img_001.png \
    --out ./results/fused_img_001.png

Note

Fast mode skips metric computation. Use it for rapid prototyping, not for final evaluation.

Optuna mode (hyperparameter optimization)

# In config_viswir.yaml: mode: "optuna"
python src/VISWIR_vQuasar.py

Tip

Start with fewer trials (10-20) to validate everything, then scale up.

Step 6 - Running with container

Fast test inside container:

singularity run VISWIR.sif --fast \
    --visible /VISWIR/data/visible/img_001.png \
    --swir /VISWIR/data/swir/img_001.png \
    --out /VISWIR/results/fused_img_001.png

Bind host directories:

singularity run \
    -B $(pwd)/results:/VISWIR/results \
    -B $(pwd)/src/logs:/VISWIR/src/logs \
    -B $(pwd)/config:/VISWIR/config \
    -B $(pwd)/data:/VISWIR/data \
    VISWIR.sif

Step 7 - Optional: HPC (SLURM) submission

  1. Pick a script in tools/: - job_viswir_test.slurm (quick test) - job_viswir.slurm (standard) - job_viswir_ex.slurm (custom resources)

  2. Submit:

    sbatch tools/job_viswir.slurm

  3. Monitor:

    squeue -u $USER
scontrol show job <job_id>
seff <job_id>

Important

Adjust --mem, --cpus-per-task, and --time to match your quota and dataset size.

Step 8 - Verify outputs and logs

  • Images: check results/ for fused outputs.

  • Database: inspect results/results.db with tools/sql_explorer.py.

  • Logs: review src/logs/ for warnings or errors.

Note

Any errors related to input data (different sizes, unequal number of visible and SWIR images, etc.) will cause a fatal error in code execution. Errors that cause the code to crash will be displayed in your terminal.

Step 9 - Common issues and quick fixes

  • Missing TIFF support → pip install imagecodecs

  • No fused image in fast mode → check --out path

  • SQL run persists but no metrics → confirm save_output and dataset paths

  • Detection crashes → check yolo_config.json and try device: "cpu"

  • Container path issues → verify -B bindings and internal paths

Step 10 - Next steps

Tip

Once your pipeline is stable in SQL mode, move to Optuna to tune parameters and maximize metric performance for your dataset.