How tavisshore/spagbol works
Project Type and Purpose
• This is a research-oriented ML pipeline for Cross-View Geo-Localisation (SpaGBOL). It ingests raw map data and imagery, constructs spatial graph datasets, trains a GNN model, and produces evaluation metrics.
File Structure Analysis
• Top level
• run.py – CLI entry point that ties together configuration, data preparation, model training, and evaluation.
• config/ – Configuration loader (config.py) and default settings (standard.yaml).
• cache/ – Local JSON cache of downloaded graph and image metadata.
• requirements.yaml – Conda environment spec.
• src/utils/ – Data-preparation modules:
• data.py – Orchestrates dataset download, graph construction, and “walk” generation.
• image_downloading.py & satellite.py – Download panoramic street-view and satellite tiles.
• guillame.py – Extracts road network graphs (via OSM).
• write_db.py – Writes processed data into persistent storage.
• metric.py – Computes evaluation metrics.
• src/models/
• model.py – Defines the GNN architecture, loss functions, and forward/training logic.
Key Architectural Patterns
• Modular pipeline: clear separation between configuration, data ingestion, graph construction, model definition, and evaluation.
• Data-centric design: cache layer for downloaded assets, write_db for persistence.
• Batch ML training workflow: run.py orchestrates end-to-end steps.
Main Components
a. External Data Sources
• OpenStreetMap (via Guillame)
• Google Street View API (panoramic images)
• Satellite imagery provider
b. Data Pipeline
1. Config Loader (config/config.py + standard.yaml)
2. Graph Constructor (src/utils/guillame.py → constructs node/edge graph)
3. Image Downloaders (image_downloading.py & satellite.py)
4. Cache Store (cache/*.json)
5. Data Writer (src/utils/write_db.py → local file system or DB)
6. Walk Generator (src/utils/data.py → exhaustive/random DFS walks)
c. Model Training
• Model Definition (src/models/model.py)
• Training Loop (invoked by run.py)
• Metrics Computation (src/utils/metric.py)
d. Orchestration
• run.py – CLI front end, argument parsing, pipeline coordination
Relationships and Data Flow
• Graph Constructor & Downloaders → Cache Store → Write_DB → Dataset Store
• Dataset Store → Walk Generator → Training Data Loader
• Training Data Loader → Model → Metrics → Output Reports
Final Checklist
• Components: Config Loader, Graph Builder, Image Downloaders, Cache, DB, Walk Generator, Model, Metrics.
• External APIs: OSM/Guillame, Street View, Satellite.
• Data Stores: cache/*.json, processed dataset folder or DB.
• Orchestration: run.py as the central coordinator.