yangqinzhe/LEVIRDetNet-159

LEVIRDetNet · 159-class detector

Trained remote sensing object detector from LEVIRDet: A Million-Scale 159-Category Dataset and Foundation Model for Universal Remote Sensing Object Detection.

Project · Dataset · All resources and Docker · Other detector

This repository contains one detector, its exact class order, and matching configuration. The checkpoint keeps the same filename and bytes as the original model repository. Existing download links remain available. The detector uses the project's PyTorch / MMDetection code; it is not a Transformers pipeline() package.

Item	Value
Checkpoint	best_coco_weighted_bbox_mAP_epoch_110_159class.pth
Size	1,704,129,664 bytes
Model	DEIMV2GSDGuided, DINOv3 ViT-S/16+ backbone, HierarchicalDEIMV2Head
Configuration	configs/levirdetnet/levirdetnet-159class.py
Class definitions	classes.json, 159 outputs in model order
Source revision	0e6e41b
Environment	Linux x86_64, NVIDIA GPU, PyTorch 2.3.1 / CUDA 12.1

Download and run

Use the desktop launcher for a graphical setup and inference workflow. For command-line use, install huggingface_hub in the downloading environment and run:

hf download yangqinzhe/LEVIRDetNet-159 \
  best_coco_weighted_bbox_mAP_epoch_110_159class.pth meta.yaml classes.json SHA256SUMS \
  configs/levirdetnet/levirdetnet-159class.py configs/_base_/levirdetnet.py \
  --local-dir levirdetnet-hf
hf download yangqinzhe/LEVIRDetNet docker/levir-train-cuda121-torch231.tar source/LEVIRDet-release-0e6e41b-source.zip --local-dir levirdetnet-hf

The detector download includes its real model metadata, ordered class list, task configuration and shared base. Keep these files together: meta.yaml identifies the checkpoint, class count, configuration and expected SHA256; classes.json defines the model output order. When keeping both detector packages, use separate download directories for their metadata.

The following commands use Bash on Linux or a Docker-integrated WSL 2 distribution. Set the path to your actual download directory. The host needs Docker, a working NVIDIA driver, and GPU container support.

export LEVRUN_ROOT="$PWD/levirdetnet-hf"
cd "$LEVRUN_ROOT"
sha256sum --ignore-missing -c SHA256SUMS
unzip source/LEVIRDet-release-0e6e41b-source.zip
mkdir -p inputs outputs LEVIRDet-release/work_dirs
docker load -i docker/levir-train-cuda121-torch231.tar

Optional metadata check (requires Python on the host): after extraction, verify the metadata and configuration pairing from $LEVRUN_ROOT. The sha256sum command above verifies the downloaded checkpoint and supporting files. This additional check confirms the selected vocabulary and that the downloaded configs match the source snapshot used for inference:

python - <<'PY'
import json
from pathlib import Path

# This release stores meta.yaml using JSON-compatible YAML syntax.
meta = json.loads(Path("meta.yaml").read_text(encoding="utf-8"))
labels = json.loads(Path(meta["classes_file"]).read_text(encoding="utf-8"))
assert meta["model_id"] == "yangqinzhe/LEVIRDetNet-159"
assert meta["checkpoint"]["filename"] == "best_coco_weighted_bbox_mAP_epoch_110_159class.pth"
assert meta["num_classes"] == labels["num_classes"] == len(labels["classes"]) == 159
assert [c["model_index"] for c in labels["classes"]] == list(range(159))
for key in ("config", "config_base"):
    path = Path(meta[key])
    assert path.read_text(encoding="utf-8") == (Path("LEVIRDet-release") / path).read_text(encoding="utf-8")
print("Verified:", meta["model_id"], meta["num_classes"], "classes;", meta["config"])
PY

Put input images in inputs/, then run:

docker run --rm --init --pull never --gpus all --shm-size=4g \
  --workdir /workspace/levirdetnet \
  -e PYTHONPATH=/workspace/levirdetnet -e NO_ALBUMENTATIONS_UPDATE=1 \
  --mount "type=bind,source=$LEVRUN_ROOT/LEVIRDet-release,target=/workspace/levirdetnet,readonly" \
  --mount "type=bind,source=$LEVRUN_ROOT,target=/models,readonly" \
  --mount "type=bind,source=$LEVRUN_ROOT/inputs,target=/inputs,readonly" \
  --mount "type=bind,source=$LEVRUN_ROOT/outputs,target=/workspace/levirdetnet/work_dirs" \
  levir-train:cuda121-torch231 \
  python demo/image_demo.py /inputs \
  configs/levirdetnet/levirdetnet-159class.py \
  --weights /models/best_coco_weighted_bbox_mAP_epoch_110_159class.pth \
  --out-dir work_dirs/infer_159 --batch-size 1

Always mount the complete matching project at /workspace/levirdetnet; the configs alone are not a standalone implementation. The Docker archive contains an older build-time source tree. No conda activate is required in the provided container. A complete detector checkpoint supplies the inference weights, so separate DINOv3 and GSD initialization files are not required.

The same python demo/image_demo.py ... command works in an appropriately configured Linux Conda environment. See the complete environment and training instructions. The model configs and their shared base in this repository are byte-identical to the pinned source revision; use the full project for runtime dependencies.

Inputs are resized to 1024 × 1024. Output boxes use original-image coordinates. Visualizations and JSON predictions are saved in outputs/infer_159/. Directory inference is non-recursive and requires unique input filename stems. Use a fresh output directory for each run, or add --no-save-vis for JSON only.

Classes and checkpoint provenance

This vocabulary has exactly 159 outputs, including parent and child categories.

classes.json records zero-based model output indices, exact labels and parent relationships. These indices are not COCO category IDs. Historical label spellings are preserved. The full dataset taxonomy and annotation semantics remain in the dataset release.

Integrity and reproducibility

Checkpoint SHA256:

e59ac416702ec464f10683fae6da18faaa92d91e832d1f058b6ff1a05111b968

SHA256SUMS also covers the supporting files in this repository. meta.yaml records the configuration, source revision, environment and original file provenance.