SAGE-Map: Inference Code, Model Weights and Evaluation Materials

This repository provides the inference code, frozen model weights and saved evaluation materials accompanying the SAGE-Map manuscript prepared for Remote Sensing. It is a checkpoint-based inference and evaluation release; see verification scope below.

Download the two ZIP archives and the checksum JSON from Files and versions:

• Code and evaluation records
• Model weights
• Package checksums

Files

File	Contents
SAGE_Map_Inference_Code_20261005.zip	Inference and evaluation code, English/Chinese instructions, data partitions, original per-tile evaluation records, aggregate metrics, bootstrap outputs and verification reports.
SAGE_Map_Inference_Weights_20261005.zip	The frozen backbone, baseline and refinement assets, DINOv2 and required calibration references.
SAGE_Map_Inference_Packages_20261005.json	Archive sizes and SHA-256 checksums, asset counts and verification scope.

The code archive is 1,780,779 bytes; the weights archive is 4,199,418,570 bytes. Both archives extract into the same sage-map-reproducibility/ directory. The weights expand to 6,409,516,010 bytes; allow additional disk space for the Python environment, input images, intermediate caches and inference outputs.

Verify and extract

Run these commands from this upload folder on Linux:

python3 - <<'PYVERIFY'
import hashlib
import json
from pathlib import Path
manifest = json.loads(Path('SAGE_Map_Inference_Packages_20261005.json').read_text())
for item in manifest['packages']:
    path = Path(item['file'])
    if path.stat().st_size != item['bytes']:
        raise SystemExit(f'Size mismatch: {path}')
    digest = hashlib.sha256()
    with path.open('rb') as stream:
        for chunk in iter(lambda: stream.read(8 * 1024 * 1024), b''):
            digest.update(chunk)
    if digest.hexdigest() != item['sha256']:
        raise SystemExit(f'SHA-256 mismatch: {path}')
    print(f'PASS: {path}')
PYVERIFY

mkdir -p extracted
unzip -n SAGE_Map_Inference_Code_20261005.zip -d extracted
unzip -n SAGE_Map_Inference_Weights_20261005.zip -d extracted
cd extracted/sage-map-reproducibility

Use a fresh extraction directory for each release. The archives share one identical weights manifest; unzip -n preserves the first extracted copy. The full instructions are in README.md and README_zh.md inside that directory.

Option A: Replay the published experiment records (CPU)

This path uses the supplied records without downloading images or loading model weights. It reconstructs aggregate AP/mIoU and reruns paired bootstrap sampling.

python3.12 -m venv .venv
source .venv/bin/activate
python -m pip install -r requirements.txt
PYTHONPATH=evaluation python -m unittest discover -s evaluation -p 'test_*.py'
OPENBLAS_NUM_THREADS=1 OMP_NUM_THREADS=1 python evaluation/replay_sage_release.py \
  --data results --output runs/replayed

Dataset AP is computed from globally ordered matching records, not by averaging per-tile AP. The replay uses 2000 tile draws and 2000 scene-group draws.

Option B: Run OpenSatMap20 image inference (NVIDIA GPU)

Download the original OpenSatMap20 validation images and annotations separately from https://huggingface.co/datasets/z-hb/OpenSatMap and follow their usage terms. Raw satellite images and official annotations are not redistributed here. Use the unmodified 4096 × 4096 validation PNG images, not OpenSatMap19.

The tested environment used Python 3.12.13 and CUDA 12.6 PyTorch wheels. A single-tile backbone test ran on an RTX 3060 with 12 GB GPU memory. Allow at least 16 GB of free system RAM; full-validation peak memory/runtime are not measured. From the extracted repository, create/activate a Python 3.12 environment and run:

python -m pip install torch==2.11.0 torchvision==0.26.0 --index-url https://download.pytorch.org/whl/cu126
python -m pip install -r requirements-inference.txt
python verification/verify_weights.py

# First run a single-tile functional check.
python inference/run_opensatmap.py \
  --image-root /path/to/OpenSatMap20/picuse20trainvaltest/val \
  --annotation-json /path/to/OpenSatMap20/annotrainval20.json \
  --output runs/smoke --limit 1

# Then evaluate all 393 official validation tiles.
python inference/run_opensatmap.py \
  --image-root /path/to/OpenSatMap20/picuse20trainvaltest/val \
  --annotation-json /path/to/OpenSatMap20/annotrainval20.json \
  --output runs/validation393
python evaluation/compare_paper_metrics.py --run runs/validation393

Replace /path/to/OpenSatMap20 with your dataset location. Annotations are joined for evaluation after predictions are saved. Use a new output directory for each run. Candidate ranking depends on the complete scoring set; do not independently score shards and average their AP.

Verification scope

• The saved full-393-tile evaluation and bootstrap replay was verified.
• The complete single-tile image-to-map workflow passed on ATX_-1_-1_sat (206 candidates); all 19 evaluation tests passed.
• All 29 weight/calibration assets are present; 24 hashes additionally match archived experimental records.
• The new image-inference release has NOT been rerun on all 393 tiles. Full-set numerical equivalence across hardware/software is not established.
• This package supports inference and evaluation with supplied checkpoints; it is not a complete from-scratch training or all-ablation reproduction package.

See verification/inference_status.json and the other reports inside the code archive for the detailed verification record.

License and publication status

No new public reuse license is granted for project-specific code, model weights or derived records in this release; rights remain with the respective rightsholders. Public download availability does not itself grant unrestricted reuse. See the repository LICENSE inside the code ZIP. Third-party code and weights retain their original licenses and notices; these are included in the archives.

The package JSON records verification and Zenodo status at packaging time. A Zenodo publication is not claimed by this Hugging Face release.

中文使用说明

本仓库提供代码、权重和评估材料。下载两个 ZIP 和校验 JSON，再按上文校验并解压。

1. 按上面的校验命令检查两个 ZIP，然后解压到同一个新目录；两者会合并为 sage-map-reproducibility/。详细中文说明在解压后的 README_zh.md。
2. 仅复算已有逐瓦片记录与 bootstrap 时，按 Option A 在 CPU 上运行，不需要影像或权重。
3. 从 OpenSatMap20 影像生成地图时，按 Option B 安装 GPU 环境，单独下载原始数据， 先运行 --limit 1，再运行完整验证集。
4. 已验证已有 393 张记录的评估复算及单瓦片完整影像流程；尚未在此发布环境中 从影像重跑全部 393 张，不能据此宣称全量端到端数值已完全复现。
5. 项目自有材料尚未授予新的公开复用许可；第三方材料遵循包内原始许可。 本 Hugging Face 仓库不表示材料已经在 Zenodo 发布。