octopath-ai/KRK-Open

Run inference on your slides

Run inference on OpenSlide-compatible slides (.svs, .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.17).

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

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

In your working directory:

uv venv venv --python 3.11.17
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/KRK-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.

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. 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 .czi, .svs, .tif, or .tiff slide	Unsupported file extension.