93eb41a9f7
Release 0.58.0 includes the Earth high-precision boundary PMTiles/MVT pipeline, standardized Earth boundary source collectors, China POV boundary configuration templates, and removal of the legacy low-precision GeoJSON fallback. It also adds Earth news target-location queueing/archive support, fixes datasource task status visibility, documents the Earth surface depth-spacing rules that prevent far-zoom z-fighting snow/black blocks, and updates bilingual operations/developer docs.
68 lines
5.0 KiB
Markdown
68 lines
5.0 KiB
Markdown
# Earth High Precision Boundary PMTiles Plan
|
|
|
|
## Status
|
|
|
|
Current implementation:
|
|
|
|
- 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 must serve a single PMTiles artifact through static hosting and HTTP range requests. Missing PMTiles is a hard boundary-layer error, not a silent low-precision fallback.
|
|
|
|
## Key Implementation Rules
|
|
|
|
- Source inputs must be auditable. OSM admin boundaries, coastline packages, and claim-line endpoints are configured through Collector Settings using the `earth_boundary_source` target schema; `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 the boundary manifest:
|
|
- `tileProvider: "pmtiles-mvt"` reads the PMTiles artifact.
|
|
- Any other provider, missing manifest, or missing PMTiles artifact is treated as an error.
|
|
- 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, source collection, artifact build/deploy, page verification, and fallback troubleshooting.
|
|
|
|
## Verification
|
|
|
|
- The PMTiles builder fails as not ready when any of `earth_admin0_boundaries`, `earth_coastline`, or `earth_claim_lines` has not produced a current artifact record.
|
|
- 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 boundary-layer error; the frontend must not draw low-precision legacy 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 removed repository seed file cannot be used as a runtime fallback for country boundaries.
|