Metadata-Version: 2.4
Name: rangegeo
Version: 0.1.0
Summary: RANGE (CVPR 2025): multi-resolution geo-embeddings for any location - retrieval-augmented location encoder that outperforms SatCLIP, GeoCLIP, CSP, and SINR
Author: Aayush Dhakal, Srikumar Sastry, Subash Khanal, Eric Xing, Adeel Ahmad, Nathan Jacobs
License: MIT
Project-URL: Homepage, https://github.com/mvrl/RANGE
Project-URL: Repository, https://github.com/mvrl/RANGE
Project-URL: Paper, https://arxiv.org/abs/2502.19781
Project-URL: Models, https://huggingface.co/collections/MVRL/range-67e99fa1dfc6c86a3b872c09
Keywords: geospatial,location-encoder,embeddings,satclip,remote-sensing
Classifier: License :: OSI Approved :: MIT License
Classifier: Programming Language :: Python :: 3
Classifier: Topic :: Scientific/Engineering :: GIS
Classifier: Topic :: Scientific/Engineering :: Artificial Intelligence
Requires-Python: >=3.9
Description-Content-Type: text/markdown
License-File: LICENSE
Requires-Dist: torch>=2.0
Requires-Dist: numpy
Requires-Dist: einops
Requires-Dist: huggingface_hub
Dynamic: license-file

# RANGE 🌎 — Multi-Resolution Geo-Embeddings for Any Location

**Retrieval Augmented Neural Fields for Multi-Resolution Geo-Embeddings (CVPR 2025)**

[📄 Paper (arXiv:2502.19781)](https://arxiv.org/abs/2502.19781) ·
[💻 Code (github.com/mvrl/RANGE)](https://github.com/mvrl/RANGE) ·
[🤗 Models & Database (HuggingFace)](https://huggingface.co/collections/MVRL/range-67e99fa1dfc6c86a3b872c09) ·
[🔬 MVRL Lab](https://mvrl.cse.wustl.edu/)

RANGE turns geographic coordinates (longitude, latitude) into rich, general-purpose
embedding vectors that you can drop into any downstream model — species
distribution, climate, land cover, population, housing prices, or any task where
*where* matters.

![RANGE framework](https://raw.githubusercontent.com/mvrl/RANGE/main/images/framework_cam.jpg)

## How it works

Location encoders like SatCLIP learn a smooth neural field over the globe, which
captures low-frequency spatial patterns but washes out fine detail. RANGE is a
**retrieval-augmented** location encoder: for a query location, it estimates the
**visual features** a satellite image at that location would have, by retrieving
from a pre-built database of (location, SatCLIP embedding, image embedding)
triplets:

- **RANGE** retrieves database entries whose *semantic* (SatCLIP) embeddings are
  similar to the query's, and aggregates their high-resolution image embeddings.
- **RANGE+** additionally retrieves by *geographic* proximity on the sphere and
  blends the two estimates with a weight **β** — moving β trades off between
  smooth, low-frequency embeddings (β→0) and sharp, high-frequency ones (β→1),
  giving you multi-scale control at inference time.

The final embedding concatenates this estimated high-resolution visual feature
(1024-d) with the smooth SatCLIP location feature (256-d) into a **1280-d**
vector. Across 7 downstream benchmarks (biome, ecoregion, country, temperature,
elevation, population, housing), RANGE outperforms state-of-the-art location
encoders such as SatCLIP, GeoCLIP, CSP, and SINR — see the paper for full tables.

## Installation

```bash
pip install rangegeo
```

Dependencies are minimal: `torch`, `numpy`, `einops`, `huggingface_hub`.

## Usage

```python
from rangegeo import RANGE

# downloads the SatCLIP backbone + RANGE database from HuggingFace on first use
model = RANGE("RANGE+", db="large", beta=0.5)   # or "RANGE"

# coordinates are (longitude, latitude) in degrees
embeddings = model.encode([
    [-90.19, 38.63],   # St. Louis
    [ 85.32, 27.72],   # Kathmandu
])
print(embeddings.shape)  # (2, 1280) numpy float32
```

That's it — `encode()` accepts any `(N, 2)` array-like of (lon, lat) degrees,
batches internally (default batch size 10000), and runs on GPU automatically
when available.

**Options:**

| argument | values | meaning |
|---|---|---|
| `model_name` | `"RANGE+"` (default), `"RANGE"` | RANGE+ adds geographic retrieval + β control |
| `db` | `"large"` (default), `"med"` | retrieval database (~0.9 GB / ~0.45 GB, cached after first download) |
| `beta` | 0.0 – 1.0 (default 0.5) | RANGE+ smoothness↔detail trade-off |
| `device` | `"cuda"`, `"cpu"` | default: auto |
| `pretrained_path`, `db_path` | local paths | use a fine-tuned SatCLIP backbone or a custom/regenerated database |

The model is a regular `torch.nn.Module`: inside a torch pipeline you can call
`model(coords_tensor)` directly with an `(N, 2)` double tensor of (lon, lat).

For training code, evaluation benchmarks, database generation
(`generate_db.py`), and baseline encoders, see the
[GitHub repository](https://github.com/mvrl/RANGE).

## Citation

```bibtex
@article{dhakal2025range,
  title={RANGE: Retrieval Augmented Neural Fields for Multi-Resolution Geo-Embeddings},
  author={Dhakal, Aayush and Sastry, Srikumar and Khanal, Subash and Ahmad, Adeel and Xing, Eric and Jacobs, Nathan},
  booktitle={Computer Vision and Pattern Recognition},
  year={2025},
  organization={IEEE/CVF}
}
```

## License

MIT — © the RANGE authors ([MVRL](https://mvrl.cse.wustl.edu/), Washington University in St. Louis).
