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.
119 lines
5.0 KiB
Markdown
119 lines
5.0 KiB
Markdown
# Earth High Resolution Basemap Tiles Plan
|
|
|
|
## Summary
|
|
|
|
High-precision borders now expose a separate visual problem: the vector coastline and border data are more accurate than the current raster Earth texture. The next step is a high-resolution basemap tile layer that aligns visually with the high-precision coastline instead of replacing the globe with one huge static image.
|
|
|
|
Do not solve this by committing a larger single world texture. A single 16K/32K raster still wastes memory, loads slowly, and becomes blurry or misaligned when zooming into coastal detail. The target architecture is viewport-based raster tiles with cache control, similar to terrain tiles.
|
|
|
|
## Goals
|
|
|
|
- Render a high-resolution Earth imagery basemap that visually matches the high-precision coastline and country boundary layer.
|
|
- Load imagery by visible bbox / tile key instead of loading a whole-world giant texture.
|
|
- Keep the current global texture only as a low-zoom background, not as the source of truth for coastlines at inspection zoom.
|
|
- Let imagery failures degrade only the imagery layer; high-precision borders and hover must continue working.
|
|
- Keep generated imagery cache out of Git.
|
|
|
|
## Data Sources
|
|
|
|
Candidate sources, in recommended order:
|
|
|
|
- NASA GIBS / Blue Marble / VIIRS style imagery for permissive global coverage and stable tile service behavior.
|
|
- Sentinel-2 cloudless style public imagery if licensing and tile access are acceptable.
|
|
- A self-hosted raster pyramid generated offline from audited global imagery if third-party online tile terms are unsuitable.
|
|
|
|
The selected source must document:
|
|
|
|
- license / attribution
|
|
- max zoom and native resolution
|
|
- tile matrix / projection
|
|
- cache policy
|
|
- whether commercial or public deployment is allowed
|
|
|
|
## Architecture
|
|
|
|
```text
|
|
global low-zoom texture
|
|
→ visible Earth bbox from camera raycast
|
|
→ Web Mercator tile keys by zoom
|
|
→ raster tile fetch/cache
|
|
→ project tile image patches onto Earth surface
|
|
→ high-precision coastline / border layer remains above imagery
|
|
```
|
|
|
|
Implementation should mirror the existing terrain tile discipline:
|
|
|
|
- dedupe in-flight requests
|
|
- LRU cache for decoded images / textures
|
|
- debounce camera movement
|
|
- cancel or ignore stale viewport requests
|
|
- cap max tiles per frame / per view
|
|
- expose loading/error diagnostics
|
|
|
|
## Rendering Rules
|
|
|
|
- The high-resolution imagery layer is visual only. It must not define country hover, coastline, or border geometry.
|
|
- The high-precision coastline remains the visual alignment reference.
|
|
- The border layer render order stays above the basemap imagery.
|
|
- Low zoom may use the current global texture for speed.
|
|
- Mid/high zoom overlays imagery tiles only for the visible region plus a small prefetch ring.
|
|
- Do not draw decorative gradients or fake coastlines to hide mismatch.
|
|
|
|
## Frontend Work
|
|
|
|
- Add a new `basemap-imagery.js` module instead of expanding `country-boundaries.js`.
|
|
- Add config in `constants.js`:
|
|
- source URL template
|
|
- attribution
|
|
- min/max zoom
|
|
- tile cache limit
|
|
- debounce interval
|
|
- opacity
|
|
- enable/disable setting
|
|
- Add Earth settings control:
|
|
- `高清底图`: off / auto / on
|
|
- default `auto`
|
|
- Add debug counters for:
|
|
- active tile count
|
|
- cached tile count
|
|
- failed tile count
|
|
- current imagery zoom
|
|
|
|
## Backend / Ops Work
|
|
|
|
- If using a third-party tile service directly, document attribution and rate-limit behavior.
|
|
- If proxying tiles, add backend cache with request coalescing and timeout limits.
|
|
- If self-hosting, add an offline builder that writes ignored tile artifacts under a dedicated data directory.
|
|
- Update Nginx static serving if self-hosted raster tiles are used.
|
|
|
|
## Performance Budget
|
|
|
|
- Desktop target: keep visible imagery tiles under a configurable cap, initially 64.
|
|
- Mobile target: lower max zoom and tile cap by default.
|
|
- Decode and upload textures incrementally; avoid blocking Earth startup on high-resolution imagery.
|
|
- First Earth paint must still use the existing lightweight global texture.
|
|
|
|
## Verification
|
|
|
|
- Compare high-precision coastline against imagery in coastal areas such as southeast China, Taiwan, Hainan, the Korean peninsula, Japan, and island chains in the South China Sea.
|
|
- Verify zooming / panning does not create visible tile thrash or long blank periods.
|
|
- Verify failed imagery requests do not hide borders or break hover.
|
|
- Verify memory stabilizes after repeated pan/zoom due to LRU eviction.
|
|
- Run `/home/ray/.bun/bin/bun run build`.
|
|
|
|
## User Operation Steps
|
|
|
|
After implementation, the user should be able to:
|
|
|
|
1. Open Earth settings.
|
|
2. Set `高清底图` to `auto` or `on`.
|
|
3. Open Earth and zoom into a coastline.
|
|
4. See imagery tiles refine under the high-precision boundary/coastline layer.
|
|
5. Use diagnostics to confirm which imagery zoom and tile source are active.
|
|
|
|
## Assumptions
|
|
|
|
- The existing high-precision vector coastline is the alignment reference.
|
|
- This plan improves visual texture fidelity; it does not replace the boundary data pipeline.
|
|
- A single larger static Earth texture is rejected as the primary solution.
|