Mapping-test-V1

Mapping-test-V1 is a local-first desktop geospatial fusion playground.

It combines aircraft, vessel, and weather sources into one interactive map so you can iterate on ingest, normalization, persistence, and visualization without standing up external services.

This is a prototype system intended for exploration and architecture learning, not a production deployment.

Project Overview

The project explores practical multi-source fusion workflows:

• ingest source payloads (aircraft, marine, weather)
• normalize into internal models
• persist snapshots/history in local SQLite
• enrich vessel identity using MMSI lookup fallback providers
• render live state and selected trails in a desktop map UI

Key Features

• Aircraft tracking from OpenSky (/api/states/all)
• Vessel tracking from public AIS snapshot feed
• Weather-at-map-center integration via Open-Meteo
• Multi-source vessel metadata enrichment (MMSI fallback chain)
• Local SQLite persistence and cache reuse across sessions
• Startup retention cleanup driven by config
• Selected-unit trails (aircraft + vessels) from SQLite history
• Config system (config/app_settings.yaml)
• Display-aware startup window sizing with persisted geometry

Architecture Overview

High-level flow:

ingest -> normalize -> store -> (history/query) -> visualize

• ingest/* handles external APIs/files and source-specific failures.
• core/normalizer.py converts raw payloads to internal dataclasses.
• core/storage.py is the persistence boundary:
  • SQLite schema/init
  • writes (snapshots, metadata, logs)
  • reads (history, metadata cache, app state)
  • retention cleanup
  • in-memory runtime stores for responsive UI
• app/ui/main_window.py orchestrates refresh workers, selection logic, enrichment, trail loading, and panel updates.
• app/web/map.js handles Leaflet-side rendering/interactions.

SQLite is used as local prototype storage (history + cache), while the UI still relies on in-memory snapshots for smooth interaction.

Project Structure

• app/ - desktop entrypoint and UI code.
  • app/ui/ - main window orchestration and embedded map widget.
  • app/web/ - local Leaflet assets (map.html, map.js, map.css).
• core/ - shared models, normalization, config loading, storage boundary.
• ingest/ - source adapters (OpenSky, marine feed, weather, vessel lookup).
• config/ - app settings (app_settings.yaml).
• data/ - local runtime artifacts, including SQLite database file.

Running the Project

Python requirement: 3.9+

1. Create and activate virtual environment (PowerShell):
   • python -m venv .venv
   • .venv\Scripts\Activate.ps1
2. Install dependencies:
   • pip install -r requirements.txt
3. Run app:
   • python -m app.main

Also supported:

• python app/main.py

Recommended PowerShell workflow

powershell -ExecutionPolicy Bypass -File .\setup.ps1
powershell -ExecutionPolicy Bypass -File .\run.ps1

Debug:

powershell -ExecutionPolicy Bypass -File .\run_debug.ps1

Logs are written to logs/app.log.

Configuration

Primary config file:

• config/app_settings.yaml

Main sections:

• database
  • path: SQLite location (default data/mapping_test_v1.db)
• retention
  • per-table retention windows (days)
  • vacuum_after_cleanup
• trails
  • selected-unit trail windows and max points
• window
  • startup mode (remember / configured / maximized)
  • size defaults
  • centering/clamping behavior

Missing config keys are auto-filled from defaults at startup.

Database

SQLite file location:

• data/mapping_test_v1.db

Current persisted tables:

• aircraft_positions
• vessel_positions
• weather_snapshots
• vessel_metadata
• metadata_lookup_log
• app_state

Stored content includes:

• aircraft position history
• vessel position history
• weather snapshots
• vessel metadata cache
• metadata lookup diagnostics
• app/window state key-values

This is local-only prototype storage (no server database).

Current Limitations

• Polling-based refresh, not continuous streaming ingestion yet.
• Query capabilities are currently focused on selected trails and cache lookups.
• Vessel metadata coverage is incomplete and source-dependent.
• Trails are selected-unit only (not global/all-entity rendering).
• No playback/timeline UI yet.
• Weather is point-based at map center (no full weather overlay layer yet).

Roadmap (Near-Term)

• continuous ingestion and improved scheduling/retry behavior
• broader query layer for replay/trails/fusion exploration
• initial fusion/event rules across sources
• better filter/search controls in UI
• optional 3D visualization exploration after 2D workflow stabilizes