Complete model card and gated-access terms

README.md

@@ -7,24 +7,104 @@ tags:
   - image-matching
   - image-registration
   - remote-sensing
+  - geolocalization
+extra_gated_heading: "Acknowledge the DINOv3 License"
+extra_gated_description: "LoRetta's checkpoint incorporates DINOv3 parameters. Access is granted automatically after you sign in and complete the acknowledgments below."
+extra_gated_button_content: "Acknowledge and access"
+extra_gated_prompt: "By requesting access, you confirm that you have read the DINOv3 License and will comply with its restrictions. Hugging Face also shares your username and email address with the model authors."
+extra_gated_fields:
+  I have read and agree to the DINOv3 License: checkbox
+  I will not use the model for activities prohibited by the DINOv3 License: checkbox
 ---
 
 # LoRetta
 
-Official inference checkpoint for the LoRetta localization-and-registration model.
+Official inference checkpoint for **LoRetta: A Localization-and-Registration Foundation Model and Extensive Dataset for Global-Scale Dense Image Matching**.
 
+- Project page: https://www.siweiyu.com/work/loretta/
 - Code: https://github.com/yusiwei77-star/LoRetta
+- Authors: Siwei Yu, Han Guo, Zhenwei Shi, and Zhengxia Zou
+- Institution: LEVIR Lab, Beihang University
 - File: `loretta.pth`
-- Format: canonical tensor-only PyTorch state dict
-- State-dict entries: 807
+- Format: canonical tensor-only PyTorch state dictionary
+- State-dictionary entries: 807
+- File size: 1,294,957,584 bytes
 - SHA-256: `09a502056b671d4e07819f454f96eb385ebe605a186ee1b059ce2447d8fb602e`
 
-The LoRetta demo downloads this checkpoint automatically through `huggingface_hub`. See the code repository for installation, usage, input normalization, and output definitions.
+## Model description
 
-## License
+LoRetta is an inference model for dense image matching in remote-sensing imagery. It follows a localization-and-registration design: a matchability-aware module estimates the overlapping region and an affine prior, then a guided coarse-to-fine registration module predicts residual dense correspondence in the aligned frame. The released package uses a pinned, locally vendored DINOv3 ViT-L/16 backbone architecture and does not fetch executable model code at runtime.
 
-This checkpoint incorporates DINOv3 parameters and is distributed under the [DINOv3 License](DINOV3_LICENSE.md). Use and redistribution must comply with that agreement.
+The public API, installation instructions, input preprocessing, output definitions, and checkpoint-integrity verification are documented in the code repository. The default loader downloads this file from an immutable Hub commit and verifies the complete file against the SHA-256 above.
 
-LoRetta-authored source code is distributed separately under the Apache License 2.0. Third-party source components retain their respective licenses. See the code repository's `THIRD_PARTY_NOTICES.md` for details.
+## Intended use
+
+This research release is intended for remote-sensing image registration, cross-view image matching, geometric alignment experiments, and evaluation on imagery for which the user has appropriate rights and a lawful basis to process. It may also be useful as a research component in astronaut-to-satellite and UAV-to-satellite geolocalization pipelines, subject to independent validation.
+
+The model is not a decision authority. Any output used in safety-critical, legal, surveillance, property, emergency-response, or other high-impact settings requires qualified human review, application-specific testing, and independent corroboration.
+
+## Input and output assumptions
+
+- The reference and sensed images are independently resized to 512 × 512; their original aspect ratios are not preserved.
+- The sensed image is expected to have a ground sampling distance no greater than the reference image and a ground footprint no larger than the reference image.
+- Outputs include a dense warp field and a per-pixel matchability estimate. Optional geometry estimation derives a homography from predicted matches using RANSAC.
+- Very large aspect-ratio changes, weak overlap, severe appearance change, clouds, repetitive texture, or violations of the scale/footprint assumptions can degrade results.
+
+## Data overview
+
+LoRetta was developed with LEVIR-GM, a multi-temporal optical remote-sensing matching benchmark described by the authors as containing 103K aligned pairs and 827K augmented pairs across six continents, five years, and spatial resolutions from 0.5 to 1024 metres. Dataset files, detailed sampling documentation, and training code are not part of this v0.1.0 checkpoint release and remain forthcoming. Users should not infer demographic, geographic, sensor, season, or land-cover coverage beyond the published description.
+
+## Evaluation
+
+The authors report the following results on LEVIR-GM under their unified evaluation protocol:
+
+- AUC: 83.3%.
+- AUC improvement over RoMa v2: 1.6 percentage points.
+- PCK improvement over RoMa v2: 6.5 points at 1 pixel and 8.2 points at 2 pixels.
+- Inference-latency reduction relative to RoMa v2: 47.8%.
+
+Here, PCK is the percentage of evaluated keypoints whose correspondence error falls within the stated pixel threshold. AUC summarizes accuracy across the evaluation error thresholds used by the authors. Latency is implementation- and hardware-dependent and should not be treated as a platform-independent guarantee. The paper and evaluation code are not included in v0.1.0, so these results should be treated as author-reported until the complete evaluation artifacts are released.
+
+## Limitations and risks
+
+- Matchability is a model estimate, not proof that two locations correspond. Repetitive structures, roads, agricultural patterns, shorelines, cloud edges, and texture-poor regions can create plausible but incorrect matches.
+- A wrong match can propagate into an incorrect affine transform, homography, or geolocation. Downstream systems must preserve uncertainty, reject low-confidence cases, and avoid presenting estimated coordinates as verified ground truth.
+- Results may be unreliable outside the stated input assumptions or on sensors, geographies, seasons, atmospheric conditions, and land-cover types underrepresented in development data.
+- Independent resizing to 512 × 512 can distort geometry, especially for extreme aspect ratios.
+- The checkpoint can support dual-use geospatial workflows. Users are responsible for lawful, ethical use, respecting privacy and imagery rights, and assessing downstream harms.
+
+## License and prohibited uses
+
+This checkpoint incorporates DINOv3 parameters and is distributed under the [DINOv3 License](DINOV3_LICENSE.md). Use and redistribution must comply with that agreement. In particular, the license requires compliance with applicable laws, privacy/data-protection rules, and trade controls, and prohibits covered end uses including military or warfare purposes, nuclear applications, espionage, and the development or use of guns or illegal weapons. This summary is informational only; the license text controls.
+
+LoRetta-authored source code is distributed separately under Apache License 2.0. Third-party source components retain their respective licenses. See the code repository's `THIRD_PARTY_NOTICES.md` for provenance and complete notices.
+
+If results produced with this checkpoint are submitted for publication, the DINOv3 License requires acknowledgment of the DINO Materials. Please also cite LoRetta as shown below.
+
+## Access
+
+Access is automatic after signing in to Hugging Face and completing the two license acknowledgments on this page. Command-line downloads also require authentication:
+
+```bash
+hf auth login
+```
+
+No company, country, or intended-use description is requested. Hugging Face's standard gated-model flow shares the requesting account's username and email address with the model authors.
+
+## Citation
+
+```bibtex
+@article{yu2026loretta,
+  title     = {LoRetta: A Localization-and-Registration Foundation Model and
+               Extensive Dataset for Global-Scale Dense Image Matching},
+  author    = {Yu, Siwei and Guo, Han and Shi, Zhenwei and Zou, Zhengxia},
+  journal   = {arXiv preprint},
+  year      = {2026}
+}
+```
+
+## Security contact
+
+Please report suspected vulnerabilities privately to `contact@siweiyu.com`. Do not include access tokens, private imagery, credentials, or other sensitive data in the initial report.
 
 Copyright 2026 LEVIR Lab, Beihang University.