Skip to content

Installation

Install Cuvis.AI and its dependencies.

Requirements

Component Recommended
Python 3.11 (3.10 minimum, tested up to 3.13)
RAM 32 GB (16 GB minimum; hyperspectral cubes are memory-hungry)
GPU NVIDIA + CUDA 12.8 (optional but strongly recommended)
OS Windows or Linux — macOS works for pure-Python use but has no Cuvis SDK build, so .cu3s / .cu3 I/O is unavailable

Why so much disk?

A single hyperspectral cube at 1000 × 1000 × 61 is 115 MB in F16 and 230 MB in F32. At 15 FPS, one minute of video is on the order of 100–200 GB. Plan dataset and output storage accordingly.

1. Install uv

curl -LsSf https://astral.sh/uv/install.sh | sh

curl -LsSf https://astral.sh/uv/install.sh | sh

irm https://astral.sh/uv/install.ps1 | iex

2. Clone and install (all extras)

git clone https://github.com/cubert-hyperspectral/cuvis-ai.git
cd cuvis-ai

uv sync --all-extras

Cuvis SDK (only for cu3s/cu3 I/O)

Reading .cu3s / .cu3 files needs the system-wide C++ Cuvis SDK plus the cuvis Python binding. Neither ships with cuvis-ai: cu3s/cu3 support lives in the cuvis-ai-dataloader plugin, which owns the cuvis pin and the full setup steps. Pipelines that only use numpy, TIFF, or video input don't need it.

See the cuvis-ai-dataloader README for the SDK download, OS support, and verification.

FFmpeg (required for video pipelines)

uv sync installs the Python video deps but not FFmpeg itself — both the reader (torchcodec shared-lib link) and writer (ToVideoNode subprocess) need it at runtime.

sudo apt install ffmpeg

brew install ffmpeg

Use the shared build so torchcodec can find the DLLs, then put it on PATH:

scoop install ffmpeg-shared
$env:Path = "$env:USERPROFILE\scoop\apps\ffmpeg-shared\current\bin;$env:Path"

Verify both paths:

ffmpeg -version                # writer-side binary
python -c "import torchcodec"  # reader-side shared libs

Graphviz (required for pipeline graph rendering)

The Python graphviz wrapper shells out to the system dot binary, so pipeline.visualize(format="render_graphviz", output_path=...) (alias format="render") needs it on PATH. Pure DOT/Mermaid string output (format="dot_string" / "mermaid") doesn't.

sudo apt install graphviz

brew install graphviz

scoop install graphviz

Verify with dot -V.

GPU support (optional)

Check CUDA availability:

import torch
print(torch.cuda.is_available(), torch.version.cuda, torch.cuda.device_count())

Verify

Quick smoke test — imports the package and prints its version:

uv run python -c "import cuvis_ai; print(f'cuvis_ai {cuvis_ai.__version__} ready')"

Run the test suite (optional)

If you want stronger confidence, run the tests with fast, and CPU-only filter:

uv run python -m pytest tests/ -v --tb=line -m "not slow and not gpu"

Next steps