ROOTS

Repository Structure

ROOTS/
├── configs/
│   └── inference.yaml                 # Local inference configuration
├── data/
│   ├── dataset/
│   │   ├── train/
│   │   ├── val/
│   │   └── test/                      # 100 released test images after download
│   ├── generated/                     # Superclass-generation outputs
│   ├── runtime/
│   │   └── corpus/                    # Runtime corpus for the released samples
│   └── samples.jsonl                  # Released test-sample manifest
├── roots/
│   ├── superclass_generation/         # Superclass and corpus generation code
│   └── *.py                           # Local inference pipeline
├── scripts/
│   ├── generate_superclasses.sh
│   ├── run_inference.sh
│   └── validate_assets.py
├── tests/
├── weights/
│   ├── superclass/
│   │   └── model.safetensors
│   └── inference/
│       ├── visual/
│       │   └── model.safetensors
│       └── vl/                        # Vision-language model and processor files
├── pyproject.toml
└── run_roots.py

Environment Setup

git clone https://github.com/OBI-Future/ROOTS.git
cd ROOTS

conda create --name roots python=3.10 -y
conda activate roots
python -m pip install --upgrade pip
python -m pip install -e '.[hf]'

Download Weights and Data from Hugging Face

The public release is hosted at Aaron0915/ROOTS. Download the pinned revision so that the weights, labels, test samples, and runtime corpus remain compatible.

hf download Aaron0915/ROOTS \
  --repo-type model \
  --revision 1bebc0a114d027112b300d56b962f32439fb41e6 \
  --local-dir ../ROOTS-hf-assets

(cd ../ROOTS-hf-assets && sha256sum --check checksums.sha256)

mkdir -p weights/superclass \
  weights/inference/visual \
  weights/inference/vl \
  data/dataset \
  data/runtime

cp -a ../ROOTS-hf-assets/weights/superclass/. weights/superclass/
cp -a ../ROOTS-hf-assets/weights/visual/. weights/inference/visual/
cp -a ../ROOTS-hf-assets/weights/vl/. weights/inference/vl/
cp -a ../ROOTS-hf-assets/data/dataset/. data/dataset/
cp -a ../ROOTS-hf-assets/data/runtime/. data/runtime/
cp ../ROOTS-hf-assets/data/samples.jsonl data/samples.jsonl

Run Inference

Validate the downloaded assets:

python scripts/validate_assets.py --config configs/inference.yaml

The released runtime corpus is scoped to the 100 images listed in data/samples.jsonl. Run full local inference on one of those images:

python run_roots.py \
  --config configs/inference.yaml \
  --device cuda:0 \
  --image data/dataset/test/*/roots_tail_001.png \
  --output outputs/roots_tail_001.json

Run only the visual classifier and corpus retrieval stage:

python run_roots.py \
  --config configs/inference.yaml \
  --device cuda:0 \
  --image data/dataset/test/*/roots_tail_001.png \
  --visual-only \
  --output outputs/roots_tail_001_visual.json