# 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