Model card in : 🤗
src/geotagflow_train/
training.py canonical library: flow maths, target standardiser, models, samplers, loops
evaluation/ full predictive distributions, particle-cloud statistics, HF test-set runner, maps
scripts/
run_flowtime.py record particle error distributions at 11 flow times over the test set
infer_legacy.py original quick check against a raw training checkpoint
notebooks/ training (geotag_flow_dino) and analysis notebooks, outputs stripped
tests/ weight-free tests: coordinate maths, standardiser, loss, samplers, checkpoints,
and the parity tests against the inference repository
Test set, 137,173 images. Each image gets a 32-particle cloud (10 Heun steps) and the error is the great-circle distance from the cloud's mean to the true location.
| Metric | Value |
|---|---|
| Median error | 0.40 km |
| Mean error | 1.05 km |
| P90 / P95 error | 2.34 km / 4.81 km |
| Within 100 m / 250 m / 500 m | 7 % / 30 % / 59 % |
| Within 1 km / 2.5 km / 5 km | 79 % / 91 % / 95 % |
The distribution has a long tail: most images land within a few hundred metres, and about
5 % are off by more than 5 km (the spike in the last bin). The numbers come from
results/flowtime_errors.csv (the t = 1.0 rows), written by scripts/run_flowtime.py.
nadh0708/JKTSV-primary on the
Hugging Face Hub: Google Street View images along Jakarta's motorway and primary roads
(OpenStreetMap), with panoramas sampled about every 50 m.
| Panoramas | 85,744 (captured 2023-02 to 2025-07) |
| Views per panorama | 8 perspective crops, headings 0° to 315° in 45° steps |
| Images | 685,848: train 548,675, test 137,173 (80 / 20) |
| Format | WebDataset .tar shards (train/, test/) + train.gpkg / test.gpkg (pano_id, lat, lon, date) |
| Area | 106.69° to 106.97° E, 6.37° to 6.10° S |
- The split is per image, not per panorama: a location usually has some of its headings in train and others in test, so the test set measures new views of known places, not unseen streets.
- During training, validation ran on a random 20 % of the test split, and the released checkpoint is the one with the best validation RMSE.
- Images are resized to 256 × 256. Training augmentation is a random resized crop (scale 0.8 to 1.0) and colour jitter. There is no horizontal flip, because mirroring swaps east and west in the scene.
- Encoder: DINOv3 ViT-L/16 (LVD-1689M pretrain). Its CLS token (1024-d) is the condition.
- Velocity head (
VelocityMLP):[cond, yₜ]→ Linear(1026 → 512) → 8 residual blocks → LayerNorm → Linear(512 → 2). Flow timetis a 128-d sinusoidal embedding that enters every block through AdaLN (scale and shift), with SiLU activations. - Target: lon/lat projected to metres around central Jakarta (106.828° E, 6.227° S), then
z-scored by
RunningStandardizer. - Training: conditional flow matching on a skewed-sigmoid path from
y₀ ~ N(0, I)to the target, with a Huber loss on the velocity. Stages A and B train the head with the backbone frozen, stage C unfreezes the last 4 backbone blocks, and stage D fine-tunes the whole backbone (8-block head, gradient checkpointing, layer-wise LR decay 0.75). - Inference: N noise particles are integrated from
t = 0tot = 1with Heun steps. The cloud's mean is the prediction and its spread is the uncertainty.
- The library:
src/geotagflow_train/training.py. The model (DinoV3CFMRegressor,VelocityMLP), the target standardiser (RunningStandardizer), the flow interpolation and loss (skewed_interpolate,cfm_velocity_loss,CFMTrainConfig), the optimiser and schedule (build_optimizer,build_warmup_cosine_scheduler), the loops (train_one_epoch_cfm,train_stage), the samplers (sample_cfm_euler,sample_cfm_heun) and checkpoint I/O (save_checkpoint,load_checkpoint). - The original runs:
notebooks/geotag_flow_dino.ipynb, a Colab notebook.
pip install -e . # library + evaluation
pip install -e ".[analysis]" # + matplotlib, scipy, folium, plotly, jupyter
pip install -e ".[dev]" # + pytestFor a CUDA build of PyTorch, install it from the PyTorch index first, or let uv do it: this
repository's pyproject.toml pins the CUDA 12.4 wheels on Windows and Linux
(uv sync --extra dev). uv sync is exact: it removes packages that are not in the lock.
data/ (checkpoints, parquet and gpkg tables), results/, hf_cache/ and an optional
dinov3/ clone are not in git and sit in the work folder: the folder above this
checkout by default, or wherever $GEOTAGFLOW_WORKDIR points. run_flowtime.py and
infer_legacy.py look there. The notebooks were written for Colab (Drive paths); only
flowtime_full.ipynb is repository-aware.
notebooks/geotag_flow_dino.ipynbtrains the model in stages A to D.- The maths in
training.pymust not change without retraining: it has to match the checkpoints exactly. The inference repository'smodeling.pyrepeats the parts needed to sample from a trained model, andtests/test_contract_inference.pycompares the two. - A checkpoint is a plain
torch.savedict (model_state_dict,target_std,stage,epoch,best_metric, ...) written bysave_checkpoint. To release one, run the inference repository'sscripts/export_to_hf.py/build_hf_release.py.
Created by claude
pip install -e ".[dev]" && pytestThe tests run on CPU around a tiny stand-in backbone (no weights, no downloads): coordinate
conversion, the running standardiser, the flow interpolation and loss, a few real
optimisation steps, the Heun sampler against its closed form, checkpoint save/load and
PredictionDistribution statistics.
tests/test_contract_inference.py also checks that this library and the inference
repository's copy of the maths agree and that a training checkpoint exports into a model that
predicts the same thing. It needs the inference repository next to this one and is skipped
otherwise (pytest prints why):
pip install -e ../geotagflow-inference # or set GEOTAGFLOW_INFERENCE_REPO to its folder
pytestApache-2.0 (see LICENSE).


