README.md

---
license: apache-2.0
tags:
  - location-encoder
  - geospatial
  - remote-sensing
  - siren
  - implicit-neural-representation
library_name: pytorch
---

# HydroLoc

A **ReSIREN location encoder** that maps a geographic coordinate `(lat, lon)` to a 512-d
embedding. It is a MIND-style model (residual [SIREN](https://arxiv.org/abs/2006.09661) trunk
over an Equal-Earth projection of the coordinate) trained by **distilling two frozen image
foundation models** evaluated over ~106k global Sentinel-2 water patches from the
[Hydro dataset](https://huggingface.co/datasets/isaaccorley/hydro):

- **DINOv3 ViT-L/16** (`vit_large_patch16_dinov3`, timm) on the RGB quicklooks → 1024-d
- **OlmoEarth v1.2 Base** on the 12-band multispectral tiles → 768-d

The trunk is supervised with a **Matryoshka** objective (nested prefixes 64/128/256/512),
so any leading slice `embedding[:, :m]` is itself a usable, compact location embedding — the
signal is front-loaded into the earliest dimensions.

## Usage

```python
import torch
from hydroloc import HydroLoc

model = HydroLoc.from_pretrained("isaaccorley/hydroloc").eval()

latlon = torch.tensor([[37.77, -122.42],   # (lat, lon) in degrees
                       [-8.70, 45.00]])
with torch.no_grad():
    emb = model(latlon)        # [2, 512]
    emb64 = emb[:, :64]        # compact 64-d Matryoshka prefix
```

`hydroloc.py` is self-contained and depends only on `torch` (plus `huggingface_hub` and
`safetensors` for `from_pretrained`).

## Coordinate convention

Input is `(..., 2)` with **column 0 = latitude, column 1 = longitude**, in degrees. Internally
the coordinate is mapped through the Equal-Earth projection before the SIREN trunk.

## Files

- `hydroloc.py` — standalone model definition + loader
- `model.safetensors` — trunk weights
- `config.json` — architecture config

## Architecture

| | |
|---|---|
| Trunk | residual SIREN, `embed_dim=512`, `depth=4`, `w0_first=30` |
| Input | Equal-Earth-projected `(lat, lon)` |
| Output | 512-d embedding; Matryoshka prefixes `[64, 128, 256, 512]` |
| Objective | cosine + MSE distillation of L2-normalized teacher embeddings |
| Teachers | DINOv3 ViT-L/16 (RGB), OlmoEarth v1.2 Base (multispectral) |

The per-teacher distillation heads are training-only and not included; the released artifact is
the coordinate → embedding trunk.

## Notes

- Trained on water locations, so embeddings are most meaningful over oceans/coasts/inland water.
- The embedding is spatially smooth (nearby coordinates → similar embeddings) and, under PCA,
  recovers global coastline structure.