octopath-ai/Nemo-Open

Run inference on your slides

Run inference on OpenSlide-compatible slides (.svs, .ndpi, .mrxs, .tif, .tiff) or BGR24 CZI mosaics (.czi) using Python 3.11 and an NVIDIA GPU on Linux. The requirements use PyTorch with CUDA 12.8.

We recommend the uv package manager, which sets up the exact environment we tested with (Python 3.11.7).

1. Install uv and Python 3.11.7, and create an environment

curl -LsSf https://astral.sh/uv/install.sh | sh
source $HOME/.local/bin/env
uv python install 3.11.7

In your working directory:

uv venv venv --python 3.11.7
source venv/bin/activate

Note that uv venv does not include pip. Use uv pip ... for all package commands below, not pip or python -m pip.

2. Download the model files

uvx --from huggingface_hub hf download octopath-ai/Nemo-Open best_ema.pth config.json run_rfdetr.py requirements.txt --local-dir model

3. Install the dependencies

uv pip install -r model/requirements.txt

On Ubuntu, install OpenCV's system libraries if they are missing:

sudo apt update
sudo apt install -y libgl1 libglib2.0-0

Check GPU access:

python -c "import cv2, torch; print('CUDA available:', torch.cuda.is_available())"

4. Run inference

python model/run_rfdetr.py \
  --slide "/path/to/your_slide.svs" \
  --checkpoint model/best_ema.pth

Results are saved to results/<slide filename without extension>. To choose another location, add --output-dir /path/to/new_output. The output folder must not already exist. To continue an interrupted run, add --resume.

Outputs

• scene_0_detections.geojson: detection points with class, confidence and bounding box properties.
• detections.csv: the same detections as a table.
• scene_0_overview_conf025.jpg: overview of detections with confidence of at least 0.25.
• summary.json: detection counts and completion status.

Coordinates are in full-resolution pixels, relative to each scene. Multi-scene CZI files produce one set of scene_N_... files per scene; detections.csv combines all scenes, with a scene column, and czi_x/czi_y give global positions. A finished run shows "status": "complete" in summary.json.

Troubleshooting

Error	Cause and fix
No module named pip	uv environments have no pip. Use uv pip instead.
mmap can only be used with files saved with ...	best_ema.pth is a Git LFS pointer, not the weights. Re-download with hf download.
config.json not found	Download config.json into the same folder as best_ema.pth.
Expected a slide with extension ...	Unsupported file extension.
... already exists	Choose another --output-dir, or add --resume to continue an interrupted run.
Slide pixel size is missing or invalid	The slide has no usable resolution, or it is outside 0.1–2 µm/pixel. Set "mpp" or "distance_pixels" under deduplication in config.json.