weather/docs/GeoMaskFoundation.md

NavSea Geo Mask Foundation

Version: codex6 Architecture: NavSea V11 Domain: geo-mask Status: implemented-v1

1. Selection Conclusion

NavSea land/sea mask foundation v1 uses Natural Earth 10m land as the default source asset.

Selection result:

• Primary source: Natural Earth 10m land
• Backup direction: GSHHG
• Local refinement direction: GSI coastline / local land assets

Why this was chosen for v1:

• Good enough coastline detail for Japan and nearby waters
• Stable global coverage
• Easy to automate in a server-side pipeline
• Lightweight preprocessing path without adding new geo stack dependencies
• Independent from weather products and reusable by multiple display lines

2. Source Comparison

Natural Earth 10m land

• Japan coastal suitability: good for v1 display masking
• Coastline detail: medium-high
• Island detail: good, but not the highest fidelity
• Licensing: permissive and easy to operationalize
• Coverage: global
• Update cadence: moderate
• Preprocess complexity: low
• Integration difficulty: low

GSHHG

• Japan coastal suitability: very strong
• Coastline detail: higher than Natural Earth in many coastal areas
• Island detail: stronger
• Licensing / operational complexity: acceptable but heavier than Natural Earth for this repo
• Coverage: global
• Preprocess complexity: medium
• Integration difficulty: medium

GSI local assets

• Japan coastal suitability: strongest for Japan-specific refinement
• Coastline detail: potentially best
• Coverage: Japan-focused
• Operational complexity: medium-high because it should be layered as a refinement source, not as the only source
• Integration difficulty: medium-high

3. V1 Asset Model

V1 outputs a reusable raster mask tile asset:

/geo-mask/land-sea/{z}/{x}/{y}.png

Semantics:

• sea: pixel alpha 0
• land: pixel alpha 255
• coastTransition: reserved for v2, not yet emitted

PNG interpretation:

• RGB is white for land pixels
• Alpha carries the effective mask

4. Metadata Model

V1 metadata fields:

• maskId
• version
• source
• classes
• encoding
• coverage
• supportedZoom
• coastTransition
• noDataMode
• displayPolicies

5. Display Integration Boundary

The geo mask layer is product-independent and only answers geography semantics.

Recommended display product policy binding:

• wind: sea normal, land attenuate
• wave: sea normal, land mask
• current: sea normal, land mask
• pressure: sea normal, land normal

These policies are separate from the mask asset itself.

6. Directory Layout

Source asset:

data/geo_mask/source/ne_10m_land.geojson

Generated output:

/home/wwwroot/weather/geo-mask/land-sea/{z}/{x}/{y}.png
/home/wwwroot/weather/geo-mask/metadata/land-sea.json
/home/wwwroot/weather/geo-mask/policies/display-product-policies.json

7. V2 Extension Path

Planned next steps:

• add coastTransition band
• blend-friendly shoreline attenuation
• multi-zoom simplification strategy
• Japan hotspot refinement using higher-resolution local coast assets