LEVIRDetNet

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

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

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. Directory inference scans only the selected directory, without recursing into subdirectories. Input images in a run must have unique filename stems so their prediction JSON files do not collide. The demo resizes inputs to 1024 × 1024 and returns boxes in original-image coordinates. Visualizations and prediction JSON files remain in the host's outputs/infer_30 or outputs/infer_159 after the container exits. Use a new output subdirectory for subsequent runs. Add --no-save-vis to save prediction JSON without rendered images.

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

Checkpoint details and validation

The 30-class detector is the released epoch_117.pth. Its coarse vehicle category uses the historical name car.

The strict 159-class checkpoint was prepared from the trained epoch-110 checkpoint with a 160-class head. The other AS output row, which is excluded from the public vocabulary, was removed from the classification tensors and label embedding, in both the regular model state and EMA state. Class metadata was updated to match the 159-class configuration; other model tensors were retained unchanged. The public vocabulary distinguishes the parent vehicle from its fine child car and uses the unified LL label.

The original unsuffixed best_coco_weighted_bbox_mAP_epoch_110.pth has 160 classes and is not interchangeable with the strict 159-class release. The legacy epoch_117_hierarchy_pretrain.pth is a training initializer, not a substitute for the trained 159-class detector.

The strict 159-class file passed a four-image inference check at 1024 × 1024 with EMA weights. Full test-set metrics were not recomputed after the 160-to-159 conversion. This mirror therefore does not claim a newly measured 159-class mAP value. For research context and reported experiments, consult the project documentation; a sample inference check is not a benchmark evaluation.

The image demo handles single-image batch priors using the project's runtime inference handling. Predictions can depend on batch composition. Directory inference with --batch-size 1 should not be treated as a reproduction of the original validation/evaluation pipeline.

Intended use and limitations

LEVIRDetNet is intended for remote sensing object detection research, evaluation, and adaptation to related datasets. It predicts bounding boxes and category scores for the selected vocabulary. Predictions may be incorrect, and performance can vary with image resolution, sensor, scene, and domain. The 30-class and hierarchical 159-class outputs use different category definitions and must be interpreted using their matching configurations.

The Docker archive targets Linux x86_64 and NVIDIA GPU execution. CPU-only, ARM, and alternative accelerator environments are not validated by this release. Downloading the archive requires additional disk space for the imported Docker image and outputs.

License

The license for the LEVIRDetNet model release is pending clarification. The pinned source snapshot includes the project's LICENSE.md notice, which also leaves the release license unspecified. This mirror does not grant a new license or additional usage permissions. Existing licenses and notices for source files, third-party dependencies, pretrained components, and bundled Docker software continue to apply to their respective components. No blanket license has been assigned to this model repository's metadata.

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

Downloads last month: -; Downloads are not tracked for this model. How to track

yangqinzhe
/

LEVIRDetNet