Initial import

2026-03-17 19:52:51 +08:00
commit c957fef15b
39 changed files with 7108 additions and 0 deletions
--- a/docs/GeoMaskFoundation.md
+++ b/docs/GeoMaskFoundation.md
@@ -0,0 +1,127 @@
+# 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:
+
+```text
+/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:
+
+```text
+data/geo_mask/source/ne_10m_land.geojson
+```
+
+Generated output:
+
+```text
+/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