Skip to content

Quickstart Guide

Get up and running with Cuvis.AI in 5 minutes.

Installation

First, ensure you have Python 3.10+ and uv installed:

# Clone the repository
git clone https://github.com/cubert-hyperspectral/cuvis-ai.git
cd cuvis-ai

# Install dependencies
uv sync

See the Installation Guide for detailed setup instructions.

Download Sample Data

Download the Lentils dataset from Hugging Face:

# Automated download (default: lentils dataset)
uv run download-data

# Or explicitly specify dataset
uv run download-data --dataset lentils

This downloads ~1.0 GB of real hyperspectral data to data/Lentils/.

Quick Demo: Run Pre-Trained Pipeline

Want to see Cuvis.AI in action first? Run inference with a pre-configured pipeline:

# View pipeline structure
uv run restore-pipeline --pipeline-path configs/pipeline/anomaly/rx/rx_statistical.yaml

# Run inference on sample data
uv run restore-pipeline --pipeline-path configs/pipeline/anomaly/rx/rx_statistical.yaml --cu3s-file-path data/Lentils/Demo_000.cu3s

This loads the pipeline configuration and runs anomaly detection on the sample hyperspectral cube.

Train Your Own Pipeline

Train an RX anomaly detector from scratch using the script in the cuvis-ai-cookbook repo:

# Clone the cookbook alongside this repo, then from cuvis-ai-cookbook/main:
uv run python examples/rx_statistical.py

Results are saved to outputs/base_trainrun/.

What Just Happened?

  1. Loaded data - The Lentils hyperspectral dataset
  2. Built pipeline - RX statistical anomaly detector from configs/pipeline/anomaly/rx/rx_statistical.yaml
  3. Trained model - Statistical initialization on training data
  4. Saved results - Pipeline, weights, and metrics to outputs/

Use Your Trained Model

After training, restore and use your model for inference:

# Restore trained pipeline
uv run restore-pipeline --pipeline-path outputs/base_trainrun/trained_models/RX_Statistical.yaml --cu3s-file-path data/Lentils/Lentils_000.cu3s

The pipeline will load your trained weights and run inference on new data.

Next Steps

Learn the fundamentals:

Follow comprehensive tutorials:

Explore how-to guides: