Mini Map Macau 🚈🚌✈️🛥️

mini-map-macau.app

3D visualization of Macau's public transit, ferry, and aviation system, inspired by Mini Tokyo 3D and Mini Taiwan.

Visualizes the Macau Light Rapid Transit (LRT), bus network, HK–Macau ferry routes, and MFM airport flights on an interactive 3D map. Vehicles move along actual geometry in a timetable-driven simulation, with an opt-in RT mode that replaces simulated bus positions with live DSAT realtime data.

How "live" is this? See Data freshness & update strategy for a per-layer breakdown — LRT / buses / flights / ferries each sit at a different point on the simulated-to-live spectrum.

Contents

• Features
• Architecture
• Tech Stack
• Getting Started
• Data Pipeline
• Data Sources
• Data freshness & update strategy
• Project Structure
• Performance Notes
• Acknowledgements
• License
• Developer Docs 開發筆記 (繁中)

Features

• 3D LRT vehicles — 3 lines, 15 stations, real track geometry and elevated viaducts
• 3D Bus fleet — 92 routes, road-snapped via OSRM, with accurate cross-harbour bridge geometry
• 3D Aircraft — 176 real MFM flights (87 dep + 89 arr) with detailed airplane models, apron stands, and taxi paths
• 3D Ferries — 6 HK/Shenzhen ↔ Macau sea routes (TurboJET + CotaiJet) with jetfoil-shaped hull, red belly belt, and multi-deck cabin
• Timetable-driven simulation — Schedule-synced playback with ETAs, service status, and trilingual labels (EN / 繁中 / PT)
• RT mode (opt-in) — Toggle replaces simulated bus positions with the DSAT live feed; simulation stays active for LRT / flights / ferries
• Time controls — Play/pause, 1×–60× speed, jump-to-now, free date/time picker
• Vehicle tracking — Click-to-follow with smooth camera and free zoom/pan

• 3D LRT vehicles — All 3 lines (Taipa, Seac Pai Van, Hengqin) with 15 stations, rendered as 3D models with real track geometry and elevated viaducts
• 3D Bus fleet — 92 routes with road-snapped paths via OSRM, including accurate bridge geometry (Macau–Taipa bridges)
• 3D Aircraft — 176 real MFM airport flights (87 departures + 89 arrivals) with detailed airplane models (fuselage, swept wings, vertical tail in airline colors, engine nacelles, window rows, cockpit windshield); aircraft park at 12 apron stands before departure and taxi along waypoint paths before takeoff
• Landing & holding patterns — Aircraft approach from North or South with multi-waypoint landing routes; when the runway is occupied, arriving flights enter a realistic circular holding pattern above the airport and smoothly transition back to the landing route when clear
• 3D Ferries — 6 sea routes (Hong Kong Outer Harbour / Taipa / Sheung Wan, HKIA, Shenzhen Airport, Shekou) served by TurboJET and CotaiJet, rendered as jetfoil models (pontoon hull, red belt, white TurboJET band, cabin, windows, wheelhouse, roof) following great-circle paths with wake-aware headings
• Real-time simulation — Vehicles move along routes based on timetables, service frequencies, and schedule types (Mon–Thu / Friday / Sat–Sun)
• ETA & vehicle info — Click any vehicle or station to see live ETAs, next arrivals, route details, and service status
• Flight info — Click any aircraft to see flight number, airline, destination/origin (with localized names), scheduled time, aircraft type, and live/sim status
• Ferry info — Click any ferry to see operator, route, origin/destination port (localized), scheduled departure, crossing time, and live progress
• Automated ferry data — GitHub Actions workflow scrapes TurboJET and CotaiJet timetables monthly and commits updated schedules if changed
• Time controls — Play, pause (spacebar), speed up (1×–60×), jump to current time, or pick any date/time with the DateTimePicker; Esc toggles the sidebar menu
• Vehicle tracking — Click a vehicle to follow it with smooth camera animation; freely zoom/pan while tracking
• Route visibility — Toggle individual bus routes by group (Peninsula, Cross-Harbour, Taipa/Cotai, Night, Special); auto-mode shows only routes currently in service
• 3D/2D toggle — Switch between perspective and top-down views
• Dark/Light mode — Two map styles (CARTO Dark Matter / Positron)
• Trilingual UI — English / 繁體中文 / Português — flight destinations, station names, and all labels switch with the language

Architecture

Three clean stages: upstream sources get normalized by Python into versioned static JSON, which the browser runtime replays on a simulated clock. RT mode adds a parallel live-feed path for buses only.

flowchart LR
  subgraph Sources["External sources"]
    OSM[OpenStreetMap]
    MLM[MLM LRT timetables]
    DSATFreq[DSAT bus frequencies]
    AS[AviationStack API]
    TJ[TurboJET · CotaiJet]
    DSATrt[DSAT realtime feed]
  end

  subgraph Pipeline["Python pipeline · GitHub Actions"]
    Scripts["data/scripts/*.py<br/>(manual regen)"]
    CronF["update-flights.yml<br/>(daily)"]
    CronFerry["update-ferry-schedules.yml<br/>(monthly)"]
  end

  subgraph Static["Bundled static JSON (public/data/)"]
    J1[lrt-lines · stations · trips]
    J2[bus-routes · bus-stops]
    J3[flights.json]
    J4[ferry-schedules.json]
  end

  subgraph Runtime["Browser runtime"]
    Sim["Simulation engine<br/>timetable-driven playback"]
    RT["RT client<br/>/api/dsat/batch · 8s cache"]
    UI[MapLibre layers + React UI]
  end

  OSM --> Scripts
  MLM --> Scripts
  DSATFreq --> Scripts
  AS --> CronF
  TJ --> CronFerry

  Scripts --> J1
  Scripts --> J2
  CronF --> J3
  CronFerry --> J4

  J1 --> Sim
  J2 --> Sim
  J3 --> Sim
  J4 --> Sim

  DSATrt -.->|opt-in RT toggle| RT
  Sim --> UI
  RT --> UI

Tech Stack

Layer	Technology
Frontend	React 19, TypeScript 6, Vite 8
3D Map	MapLibre GL JS, custom WebGL fill-extrusion layers
Geo utilities	Turf.js (nearest-point-on-line) + custom precomputed-polyline cache
Styling	Tailwind CSS v4
Fonts	Orbitron, JetBrains Mono, Noto Sans HK (Google Fonts)
Data pipeline	Python 3.13+, uv, OpenStreetMap Overpass API, OSRM
Flight data	AviationStack API (daily sync)
Ferry data	TurboJET + CotaiJet timetables (monthly web scraper)
Deployment	Cloudflare Pages (via GitHub Actions)
Analytics	Google Analytics (gtag.js)

Getting Started

Prerequisites

• Node.js 20+
• npm
• uv (for data pipeline only)

Install & Run

npm install
npm run dev

The app will be available at http://localhost:5173.

Build for Production

npm run build
npm run preview

Data Pipeline

Transit data is pre-generated and included in public/data/.

cd data

# Set up Python environment
uv sync

# Run all data extraction scripts
uv run python main.py

This will:

1. Extract LRT track geometry from OpenStreetMap (railway=light_rail ways)
2. Extract bus routes and stops from OpenStreetMap + motransportinfo.com reference data
3. Fetch bridge approach geometry for accurate cross-harbour routing
4. Snap bus routes to roads via OSRM with custom bridge geometry patching
5. Generate timetables based on published service frequencies
6. Output JSON files to data/output/

Then copy the output to public/data/.

Flight schedules are fetched from the AviationStack API and stored as a static JSON file:

cd data

# Fetch today's MFM flights (requires API key)
AVIATIONSTACK_API_KEY=your_key uv run python scripts/fetch_flights.py

# Fetch a specific date
AVIATIONSTACK_API_KEY=your_key uv run python scripts/fetch_flights.py 2026-04-19

The sync:

• Pulls arrivals and departures for MFM (IATA: MFM) from the AviationStack flights endpoint
• Filters by the target date's active schedule
• Validates aircraft type codes (ICAO format like A320, B738)
• Outputs public/data/flights.json with times in Macau local (UTC+8)

This is also automated via GitHub Actions (.github/workflows/update-flights.yml), which runs daily at 04:00 Macau time (UTC+8) and commits updated flight data if changed.

Ferry timetables are scraped from the operator sites and stored as a single static JSON file with 6 routes across two operators (TurboJET and CotaiJet):

cd data

# Scrape the current month's schedules for all routes
uv run python scripts/fetch_ferry_schedules.py

The scraper:

• Pulls TurboJET schedules for Hong Kong (Outer Harbour), Hong Kong (Taipa), HKIA, Shenzhen Airport, and Shekou
• Pulls CotaiJet schedule for Hong Kong (Sheung Wan) ↔ Macau Taipa
• Records fetchedAtUtc and effectiveAs metadata