planet/docs/plans/earth-high-resolution-basemap-tiles-plan.md

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

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.