72 lines
5.6 KiB
Markdown
72 lines
5.6 KiB
Markdown
# Earth High Precision Boundary PMTiles Plan
|
|
|
|
## Status
|
|
|
|
Superseded status:
|
|
|
|
This plan originally treated boundaries as collector-managed source records. The current implementation has moved country boundaries out of the datasource / collector lifecycle. Boundaries are now Earth static rendering assets managed by `Operations and Configuration -> Earth Content -> Boundary Precision` and `/api/v1/earth/boundaries/*`. The bundled low-precision GeoJSON is the default fallback, and high precision is an opt-in local PMTiles build.
|
|
|
|
Historical implementation notes below are retained only as context and must not be used as the current architecture:
|
|
|
|
- Three standard source collectors now handle real source ingestion: `earth_admin0_boundaries`, `earth_coastline`, and `earth_claim_lines`.
|
|
- Each source collector reads endpoint / headers / auth / `target_schema=earth_boundary_source` from Collector Settings, downloads the configured payload, stores the full artifact under `data/earth-boundary-sources/<collector>/<sha256>.*`, and writes a hash / feature-count / artifact-path record to `CollectedData`.
|
|
- The backend `earth_boundary_tiles` item is now a downstream PMTiles builder. It refuses to run until the three source records exist, then skips rebuilds when source / POV policy / build config are unchanged.
|
|
- The frontend boundary layer now requires the production `pmtiles-mvt` provider and no longer falls back to legacy low-precision GeoJSON.
|
|
- Generated loose boundary data is ignored by Git and is not the production deployment format.
|
|
- Production PMTiles builds require external `tippecanoe` and `pmtiles` CLIs; missing tools fail the builder clearly instead of registering fake tile records.
|
|
|
|
Still required before claiming true one-to-one high precision:
|
|
|
|
- Replace the repository seed GeoJSON with audited high-precision admin boundary, coastline, and claim-line source packages.
|
|
- Run a real geometry preparation step that applies the China POV policy through union / subtract / validity repair before PMTiles creation.
|
|
- Build and publish `earth-boundaries-china-pov-v1.pmtiles` plus its manifest.
|
|
|
|
## Summary
|
|
|
|
The Earth boundary layer should use one static PMTiles archive containing MVT tiles instead of thousands of loose GeoJSON files. The artifact is POV-specific: `earth-boundaries-china-pov-v1.pmtiles` has China POV baked in during offline source preparation, and the browser never patches political boundaries at runtime.
|
|
|
|
Production should serve a single PMTiles artifact through static hosting and HTTP range requests. In development or on machines that have not opted into high precision, missing PMTiles falls back to the bundled low-precision GeoJSON so the Earth base remains usable.
|
|
|
|
## Key Implementation Rules
|
|
|
|
- Source inputs must be auditable. OSM admin boundaries, coastline packages, and claim-line endpoints are configured through Earth Content boundary precision settings; `config/earth-boundary-sources.example.json` remains the versioned example template.
|
|
- China POV geometry is applied before tiling:
|
|
- Zangnan and Aksai Chin are unioned into China and subtracted from India.
|
|
- Taiwan/Penghu, Diaoyu Dao and affiliated islands, Chiwei Yu, and South China Sea islands are China hover/country features.
|
|
- The South China Sea dashed line is a claim-line layer only; it never consumes Malaysian, Philippine, Vietnamese, or other land polygons.
|
|
- Kosovo is not an independent country surface in this profile; Gaza is a Palestine region.
|
|
- PMTiles/MVT layer names are fixed for the frontend:
|
|
- `boundary_admin0`
|
|
- `boundary_disputed_internal`
|
|
- `coastline`
|
|
- `claim_line`
|
|
- The frontend provider is selected from local high-precision preference plus the boundary manifest:
|
|
- `tileProvider: "pmtiles-mvt"` reads the PMTiles artifact.
|
|
- Missing high-precision preference, missing manifest, or missing PMTiles artifact falls back to low-precision GeoJSON.
|
|
- Redis is not part of v1. Static PMTiles plus browser/CDN range caching is the default performance model.
|
|
|
|
## Cleanup And Documentation
|
|
|
|
- Do not commit generated loose tiles under `frontend/public/earth/data/boundaries/` or source downloads under `data/earth-boundary-sources/`.
|
|
- Remove stale generated debug data before production builds; regenerate it only when smoke testing the debug path.
|
|
- Keep the high-level plan, backend collector docs, layer style docs, and ops runbook aligned whenever the provider contract changes.
|
|
- After implementation changes, provide user-facing operation steps covering source configuration, artifact build/deploy, page verification, and fallback troubleshooting.
|
|
|
|
## Verification
|
|
|
|
- The Earth boundary build API reports missing source configuration or missing tools clearly, without creating datasource collection records.
|
|
- The PMTiles builder fails as not ready when source artifacts exist but `tippecanoe` / `pmtiles` are missing.
|
|
- Running the PMTiles builder twice returns `unchanged` on the second run when inputs are stable.
|
|
- `git add . --dry-run` does not include generated loose boundary tiles or source downloads.
|
|
- `/home/ray/.bun/bin/bun run build` passes in `frontend`.
|
|
- Manual Earth checks confirm:
|
|
- PMTiles range requests are issued only for visible tiles.
|
|
- Boundary toggle, hover tooltip, and country highlight still work.
|
|
- PMTiles failure reports a high-precision boundary error; machines without high-precision enabled continue drawing low-precision fallback boundaries.
|
|
|
|
## Assumptions
|
|
|
|
- "One-to-one" means source-faithful to the selected audited vector source, not hand-tuned to a screenshot.
|
|
- The China POV artifact is static and versioned; no runtime region-based POV switching is planned.
|
|
- The repository low-precision seed file is retained as the runtime fallback for country boundaries.
|