Mini Map Macau 🚈🚌✈️🛥️

• 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
• Cyberpunk-styled menu — Hamburger menu with Orbitron-font title and gradient branding
• Responsive mobile UI — Hamburger menu for map controls, compact legend buttons (LRT/Bus), optimized touch layout with safe-area support
• Lazy loading — Code-split panels (VehicleInfoPanel, StationInfoPanel, FlightInfoPanel) for fast initial load
• Automated flight data — GitHub Actions workflow syncs MFM flight schedules from the AviationStack API daily

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 so stale data is easy to spot
• Outputs public/data/ferry-schedules.json

Automated via GitHub Actions (.github/workflows/update-ferry-schedules.yml), which runs on the 1st of each month at 00:00 UTC (08:00 Macau) and commits updates if changed.

mini-macau/
├── src/
│   ├── components/
│   │   ├── MapView.tsx           # Main map + hamburger menu
│   │   ├── ControlPanel.tsx      # Playback speed controls
│   │   ├── TimeDisplay.tsx       # Clock + DateTimePicker trigger
│   │   ├── DateTimePicker.tsx    # Date/time selection overlay
│   │   ├── LineLegend.tsx        # LRT/Bus/Flight legend (desktop + mobile)
│   │   ├── VehicleInfoPanel.tsx  # Vehicle detail + ETA
│   │   ├── StationInfoPanel.tsx  # Station detail + next arrivals
│   │   ├── FlightInfoPanel.tsx   # Flight detail panel
│   │   └── FerryInfoPanel.tsx    # Ferry detail panel
│   ├── engines/
│   │   └── simulationEngine.ts   # Timetable-driven vehicle + flight position computation
│   ├── hooks/
│   │   ├── useSimulationClock.ts # RAF-based clock with speed/pause
│   │   └── useTransitData.ts     # JSON data loader
│   ├── layers/
│   │   ├── Bus3DLayer.ts         # 3D bus model (fill-extrusion)
│   │   ├── LRT3DLayer.ts         # 3D LRT model (fill-extrusion)
│   │   ├── Flight3DLayer.ts      # 3D airplane model (fill-extrusion)
│   │   ├── Ferry3DLayer.ts       # 3D jetfoil model (fill-extrusion, 8 layers)
│   │   └── VehicleLayer.ts       # 2D vehicle circles + labels
│   ├── App.tsx                   # Root layout + state management
│   ├── main.tsx                  # React entry point with I18nProvider
│   ├── routeGroups.ts            # Bus route grouping logic
│   ├── i18n.tsx                  # Internationalization (EN / 繁中 / PT)
│   ├── types.ts                  # TypeScript interfaces
│   └── index.css                 # Tailwind + MapLibre control overrides
├── public/
│   ├── data/
│   │   ├── lrt-lines.json
│   │   ├── stations.json
│   │   ├── trips.json
│   │   ├── bus-routes.json
│   │   ├── bus-stops.json
│   │   ├── flights.json          # MFM flight schedules (with localized names)
│   │   └── ferry-schedules.json  # TurboJET + CotaiJet monthly timetables
│   ├── favicon.svg
│   ├── icons.svg
│   ├── og-image.png
│   ├── sitemap.xml
│   └── robots.txt
├── data/
│   ├── scripts/
│   │   ├── extract_lrt_osm.py
│   │   ├── extract_bus_data.py
│   │   ├── fetch_bus_data.py
│   │   ├── fetch_bridge_geometry.py
│   │   ├── fetch_flights.py      # AviationStack flight data sync (MFM)
│   │   ├── fetch_ferry_schedules.py # TurboJET + CotaiJet monthly scraper
│   │   ├── osrm_route.py
│   │   ├── patch_bus_bridges.py
│   │   └── generate_timetable.py
│   ├── bus_reference/
│   ├── output/
│   └── main.py
├── .github/workflows/
│   ├── deploy.yml                  # Cloudflare Pages CI/CD
│   ├── docker-release.yml          # Docker image release on new tag
│   ├── service-status.yml          # Upstream service availability check
│   ├── update-flights.yml          # Daily flight data update
│   └── update-ferry-schedules.yml  # Monthly ferry data update
└── index.html

The simulation asks the same question once per vehicle per tick: given a route and a progress ∈ [0, 1], where on the polyline is the vehicle, and which way is it facing?

The original implementation used Turf's along twice per vehicle (once for position, once for a 1-metre-ahead lookahead to derive bearing). along walks the coordinate array from index 0 and sums haversine distances until it reaches the target km — O(n) haversines per call. At ~400 vehicles × 2 calls × 20 Hz × 100-point routes, that worked out to roughly 12 000 full-route scans per second, all on the main thread.

Key observation: each route's geometry is immutable, so the per-segment work only needs to happen once. On first touch we cache:

• cumKm[i] — cumulative kilometres from coords[0] to coords[i] (Float64Array)
• segBearing[i] — heading of segment coords[i] → coords[i+1] (Float64Array)

Per-call cost then collapses to a binary search on cumKm (≈ 8 comparisons for a 150-point route), a linear interpolation between two lat/lng pairs, and a table lookup for bearing. No trig in the hot loop, and no second along call since the segment index already tells us the heading.

We deliberately don't cache a per-line "last index" hint: multiple vehicles share the same polyline at different progress values, so a shared hint would thrash. O(log n) is cheap enough that per-vehicle state isn't worth it. See simulationEngine.ts (getLineCache / interpolateOnLine).

MapLibre GeoJSON sources are tiled in a web worker: the worker clips each source's features to tile boundaries, tessellates lines into triangle strips, and ships vertex buffers back to the main thread. Originally each of the 92 bus routes was its own addSource + addLayer, meaning every zoom level change forced 92 separate postMessage round-trips and 92 independent tile-index rebuilds.

Consolidating into a single bus-routes source (one tile index, one round-trip per reindex) drastically cut worker chatter during zoom. Per-route dimming — previously setPaintProperty('bus-route-${id}', 'line-opacity', …) against 92 layers — became setFeatureState({ source: 'bus-routes', id }, { inService }) on one layer, with opacity driven by a ['case', ['==', ['feature-state', 'inService'], false], DIM, FULL] paint expression. setFeatureState doesn't recompile paint; setPaintProperty does.

Moving 300+ buses as 3D fill-extrusion polygons is heavy (each bus is 8 quads × lat/lng math). Moving them as 2D circles is almost free (just a setData on a Point FeatureCollection).

The animate loop splits them: simulation + 2D circle updates run every 50 ms unconditionally, while 3D polygon rebuilds throttle to 160 ms whenever the map is actively moving (movestart / moveend set a mapBusy flag). During zoom gestures the 2D layer keeps vehicles visibly moving at full cadence while the expensive 3D rebuild backs off, leaving MapLibre's own render pipeline more time to finish zoom frames.

The zoom indicator in the HUD used to be a useState, so every map.on('zoom', …) event caused <MapView> to re-render — which is a huge component with map refs, ETA panels, and layer toggles. Now zoom lives in an external store read via useSyncExternalStore, and only a tiny <ZoomText> leaf subscribes. The rest of <MapView> stays stable during pinch/scroll zoom.

• Mini Tokyo 3D — Original inspiration for the concept
• Mini Taiwan — Sister project inspiration

• OpenStreetMap — LRT track geometry, bus routes, and stop locations
• MLM 澳門輕軌股份有限公司 — Official per-station LRT timetables (used to hand-transcribe data/scripts/generate_timetable.py for the Taipa / Seac Pai Van / Hengqin lines)
• MoTransport Info — Curated Macau bus stop reference data
• DSAT 巴士資訊 — Official Macau bus realtime feed (live bus positions in RT mode)
• AviationStack — MFM flight schedule data (arrivals + departures)
• TurboJET — Ferry timetable (Hong Kong, HKIA, Shenzhen Airport, Shekou routes)
• CotaiJet — Ferry timetable (Hong Kong ↔ Macau Taipa route)

• MapLibre GL JS — Open-source map rendering
• CARTO — Basemap tiles (Dark Matter / Positron)
• OpenFreeMap — 3D building tiles
• OSRM — Road routing engine
• Turf.js — Geospatial analysis
• Google Fonts — Orbitron, JetBrains Mono, Noto Sans HK