LEVIRDetNet

Paper: LEVIRDet: A Million-Scale 159-Category Dataset and Foundation Model for Universal Remote Sensing Object Detection

Trained detectors and a ready-to-use Docker environment for remote sensing object detection.

This repository mirrors the LEVIRDetNet model downloads provided by the LEVIRDet release project. It provides the 30-class detector, the strict 159-class detector, the Linux GPU environment, a matching source snapshot, and the optional GSD training initialization weight. The model files keep their original names.

Project page · GitHub · Dataset on Hugging Face

Contents

• Available files
• Download
• Run image inference with Docker
• Training and dataset preparation
• Checkpoint details and validation
• Intended use and limitations
• License

Individual detector repositories

• LEVIRDetNet-30: 30-class detector.
• LEVIRDetNet-159: strict 159-class detector.

The checkpoints have identical bytes in both locations. All existing files and download links in this resource repository remain available; Docker and the source snapshot stay here.

Available files

File	Bytes	Purpose
epoch_117.pth	2,377,858,580	Trained 30-class detector
best_coco_weighted_bbox_mAP_epoch_110_159class.pth	1,704,129,664	Trained detector adapted to the strict 159-class release vocabulary
docker/levir-train-cuda121-torch231.tar	10,017,927,168	Docker image archive: Linux x86_64, PyTorch 2.3.1, CUDA 12.1
gsd_fft/best.pt	291,564,399	Optional standalone GSD initialization for training
source/LEVIRDet-release-0e6e41b-source.zip	45,554,511	Source snapshot of GitHub commit 0e6e41b, without browser caches or temporary outputs
SHA256SUMS	—	Download integrity checksums

Use the corresponding configuration from the source snapshot:

Detector	Configuration
epoch_117.pth	configs/levirdetnet/levirdetnet-30class.py
best_coco_weighted_bbox_mAP_epoch_110_159class.pth	configs/levirdetnet/levirdetnet-159class.py

These are PyTorch/MMDetection checkpoints used with the project's inference entry point. They are not Transformers pipeline() model packages.

Download

Install the Hugging Face Hub client on the host used for downloading:

python -m pip install --upgrade huggingface_hub

The following Python example downloads both detectors, the Docker image, the source snapshot, and their checksum file. It works on Windows and Linux; change local_dir to your preferred destination.

from huggingface_hub import snapshot_download

snapshot_download(
    repo_id="yangqinzhe/LEVIRDetNet",
    repo_type="model",
    local_dir="levirdetnet-hf",
    allow_patterns=[
        "epoch_117.pth",
        "best_coco_weighted_bbox_mAP_epoch_110_159class.pth",
        "docker/levir-train-cuda121-torch231.tar",
        "source/LEVIRDet-release-0e6e41b-source.zip",
        "SHA256SUMS",
    ],
)

Alternatively, use the Hugging Face CLI. The commands below use Bash on Linux or a Docker-integrated WSL 2 distribution:

export LEVRUN_ROOT="$HOME/levirdetnet-hf"

hf download yangqinzhe/LEVIRDetNet \
  epoch_117.pth \
  best_coco_weighted_bbox_mAP_epoch_110_159class.pth \
  docker/levir-train-cuda121-torch231.tar \
  source/LEVIRDet-release-0e6e41b-source.zip \
  SHA256SUMS \
  --local-dir "$LEVRUN_ROOT"

Remove either detector filename if you only need the other model. Rerun the same download command after a connection interruption; keep the local download metadata. To pin a mirror version, specify a full Hugging Face commit hash using revision= in Python or --revision in the CLI.

For training initialization, download GSD separately if needed:

hf download yangqinzhe/LEVIRDetNet gsd_fft/best.pt \
  --local-dir "$LEVRUN_ROOT"

On Linux/WSL, verify the files present in your selected download:

cd "$LEVRUN_ROOT"
sha256sum --ignore-missing -c SHA256SUMS

The Docker archive's SHA256 is:

3f673ae0700176eb6f103b8a8946bf893adf9a49fab0f3b25ce2a6a93531203d

Run image inference with Docker

Use a Linux x86_64 host with an NVIDIA GPU, a compatible NVIDIA driver, Docker, and GPU container support. Windows users can use Docker Desktop's WSL 2 backend and a compatible NVIDIA driver. See the official NVIDIA Container Toolkit guide and Docker Desktop GPU guide.

The remaining commands are host-side Bash, including when using WSL 2. Set LEVRUN_ROOT to the absolute, Bash-visible path of your downloads.

Prepare the source and image

export LEVRUN_ROOT="$HOME/levirdetnet-hf"
cd "$LEVRUN_ROOT"
unzip source/LEVIRDet-release-0e6e41b-source.zip
mkdir -p inputs outputs LEVIRDet-release/work_dirs

docker load -i "$LEVRUN_ROOT/docker/levir-train-cuda121-torch231.tar"
docker run --rm --pull never --gpus all \
  levir-train:cuda121-torch231 nvidia-smi

The source ZIP extracts to LEVIRDet-release/. It is pinned to GitHub commit 0e6e41b97d4bd3ca5434154fb63ef1e8e8684afa. The generated fast_demo_outputs/ directory is excluded; all 2,628 retained files match the pinned Git blobs. See source snapshot metadata and the asset manifest. Place your input images in $LEVRUN_ROOT/inputs. Annotations and the full dataset are not required for image inference.

Mount the complete source snapshot at /workspace/levirdetnet. The Docker image contains an older build-time source tree; the mount supplies the updated demo, model code, and matching configurations. Importing the tar alone does not install the updated source or detector checkpoints. No Conda activation or Python dependency installation is needed inside the provided image.

The examples keep model checkpoints at the download root and mount them at /models; there is no need to copy the large checkpoints into the source tree.

30-class inference

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-30class.py \
  --weights /models/epoch_117.pth \
  --out-dir work_dirs/infer_30 --batch-size 1

159-class inference

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

Replace /inputs with /inputs/example.jpg to process a single image.

The same python demo/image_demo.py ... command can be run interactively inside a container started with the same mounts and bash as its command. See the project image prediction instructions for additional examples.

Training and dataset preparation

Download images, annotations, taxonomy, and the matching extraction helpers from LEVIRDet-159-Dataset. It provides an Original-image release and a Lightweight release with JPEG quality 95 images. Use the annotations distributed with the chosen image release.

The 30-class configuration uses annotations/train_30.json and annotations/test_30.json. The hierarchical configuration uses annotations/train_159.json and annotations/test_159.json. Images are under train/images/ and test/images/. The test split is also used for validation in the provided training configuration.

For training, mount the dataset at /data and set LEVIR_DATA_ROOT=/data. The source configurations use these initialization paths relative to the project root:

• dinov3_vits16plus_pretrain_lvd1689m-4057cbaa.pth: DINOv3 initialization; obtain it through the upstream DINOv3 distribution and its terms.
• gsd_fft/best.pt: GSD initialization, available in this repository.

Before training, place the DINOv3 initialization file at $LEVRUN_ROOT/LEVIRDet-release/dinov3_vits16plus_pretrain_lvd1689m-4057cbaa.pth and copy the downloaded GSD file into the source tree:

mkdir -p "$LEVRUN_ROOT/LEVIRDet-release/gsd_fft"
cp "$LEVRUN_ROOT/gsd_fft/best.pt" "$LEVRUN_ROOT/LEVIRDet-release/gsd_fft/best.pt"

Neither separate initialization weight is required for inference with a complete detector checkpoint. Training instructions and configuration details are maintained in the GitHub README. With the project, data, initialization weights, and writable output mount prepared, the standard entry points inside the container are:

# Choose the configuration and GPU count for your run.
bash tools/dist_train.sh configs/levirdetnet/levirdetnet-30class.py 8
# Or:
bash tools/dist_train.sh configs/levirdetnet/levirdetnet-159class.py 8

The dataset has its own release and license status; see its dataset card. Updates and questions can be directed to the project repository.