Skip to content

About

Img2LocJakarta in Conditional Flow Matching

Resources

Stars

0 stars

Watchers

0 watching

Forks

Latest commit

 

History

4 Commits

Folders and files

Repository files navigation

geotagflow-train: training and evaluation for GeotagFlow

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

Model performance

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.

Test-set error histogram and CDF

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.

Dataset

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.

Panorama locations in JKTSV-primary

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.

Architecture

GeotagFlow architecture

  • 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 time t is 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 = 0 to t = 1 with Heun steps. The cloud's mean is the prediction and its spread is the uncertainty.

Where the training code is

  • 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.

Install

pip install -e .                 # library + evaluation
pip install -e ".[analysis]"     # + matplotlib, scipy, folium, plotly, jupyter
pip install -e ".[dev]"          # + pytest

For 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.

Where data lives

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.

Training

  • notebooks/geotag_flow_dino.ipynb trains the model in stages A to D.
  • The maths in training.py must not change without retraining: it has to match the checkpoints exactly. The inference repository's modeling.py repeats the parts needed to sample from a trained model, and tests/test_contract_inference.py compares the two.
  • A checkpoint is a plain torch.save dict (model_state_dict, target_std, stage, epoch, best_metric, ...) written by save_checkpoint. To release one, run the inference repository's scripts/export_to_hf.py / build_hf_release.py.

Tests

Created by claude

pip install -e ".[dev]" && pytest

The 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
pytest

License

Apache-2.0 (see LICENSE).

About

Img2LocJakarta in Conditional Flow Matching

Resources

Stars

0 stars

Watchers

0 watching

Forks

Releases

Packages

Contributors

Languages