# Task: NavSea_LandSeaMaskFoundation
Version: codex6
Architecture: NavSea V11
Domain: geo-mask
Status: planned

---

## 1. 任务名称

`NavSea_LandSeaMaskFoundation`

---

## 2. 任务目标

建立 NavSea 的 `land/sea mask` 基础能力，作为天气 Display Product 服务端生成链的独立地理基础层。

该任务的目标不是生成天气数据，而是建立一个可复用的海陆判定资产，使后续天气显示产品能够支持：

- 海域正常显示
- 陆地弱化或屏蔽
- 海岸过渡带处理
- 不同天气产品按海陆语义应用不同 compositing 规则
- 不同 zoom 下稳定一致的海陆判定

本任务必须明确：

- land/sea mask 是独立基础地理资产
- 不从天气 pbf 中反推海陆边界
- mask 需服务于 Display Product，但不依附于某个天气产品
- mask 后续也可复用于其它海图/航海场景

---

## 3. 问题定义

当前 NavSea 天气显示层需要区分海域与陆地，否则会出现：

- 陆地区域被整体染色
- 底图地名和地形被压脏
- 海岸线附近视觉边界不干净
- wave/current 等本应海域专属的产品错误显示到陆地
- wind 等产品缺少“海域优先、陆地弱化”的语义控制

这些问题无法通过天气数据本身稳定解决。

因此必须建立独立 land/sea mask 基础层。

---

## 4. 核心原则

### 4.1 Mask 必须独立于天气产品
land/sea mask 不得从 weather pbf、weather raster、weather contour 结果中推断。

### 4.2 Mask 是基础地理资产
它应来源于独立海岸线、陆地面、水域面或底图地理数据。

### 4.3 Mask 必须可复用
同一套 mask 应可服务于：
- wind display
- wave display
- current display
- pressure display
- 后续其它海图叠加产品

### 4.4 产品规则独立于 mask 数据本身
mask 只回答“哪里是 land / sea / coast transition”，
具体如何使用由各 weather product policy 决定。

---

## 5. 推荐数据来源方向

本任务允许并建议调研与选型以下来源：

### 5.1 日本本地官方方向
- 国土地理院（GSI）相关地理数据 / 地理院瓦片体系 / 可复用海岸线或陆地区域数据

### 5.2 全球通用基础源
- Natural Earth
- GSHHG
- OpenStreetMap 派生 coastline / land polygons / water polygons

### 5.3 复用现有底图数据
若 NavSea 当前底图体系已经具备：
- land polygon
- water polygon
- coastline vector data

则优先复用，不重复建设平行数据链。


建议按 OSM land polygons → GSHHG → GSI 来尝试模型。
---

## 6. 任务范围

本任务关注：

- land/sea mask 数据源选型
- mask 数据模型
- mask 生成规则
- mask tile / mask asset 组织方式
- coastline transition 基础能力
- mask 元数据定义
- 与 Display Product 的服务端对接边界

本任务不包括：

- 天气 raster 生成
- palette 生成
- Analysis Product 查询
- Offline Package 打包
- 前端 layer 实现
- 航线规划算法

---

## 7. 目标产物

本任务完成后，应至少形成：

1. `land/sea mask` 数据来源选型结论
2. `mask asset` 组织方案
3. `mask tile` 或 `mask data block` 输出方案
4. `coast transition` 基础定义
5. `mask metadata` 结构
6. 给 Display Product 复用的服务端接口或内部资产规范

---

## 8. 推荐实现方向

### 8.1 最小可行版本
先建立基础二值判定：

- land
- sea

并支持：
- land attenuate
- land mask out

### 8.2 第二阶段增强
增加海岸过渡带：

- coast transition band
- 渐变衰减
- 防止海岸线处硬切边

### 8.3 输出形式建议
推荐至少评估以下两种输出之一：

#### A. Raster mask tiles
例如：
`/geo-mask/land-sea/{z}/{x}/{y}.png`

适合快速接入服务端 display compositing。

#### B. Vector / polygon asset
例如：
- 预处理 land polygons
- 预处理 coastline bands
- 服务端生成 tile 时内部引用

适合更高质量生成链。

---

## 9. 必须定义的数据语义

至少定义：

- `land`
- `sea`
- `coastTransition`（如实现第二阶段）
- no-data / out-of-coverage 行为
- 不同 zoom 下精度与简化策略
- mask 版本号
- 源数据来源标识

---

## 10. Display Product 对接要求

本任务必须为后续天气显示产品提供可复用能力，使不同产品可采用不同策略，例如：

### wind
- sea: normal
- land: attenuate

### wave
- sea: normal
- land: mask

### current
- sea: normal
- land: mask

### pressure
- sea: normal
- land: normal

因此本任务输出的不是某个固定产品规则，而是支持这些规则的统一 mask 基础层。

---

## 11. 选型评估要求

执行任务时，必须对候选数据源至少从以下维度进行比较：

- 日本沿岸适用性
- 海岸线精度
- 岛屿细节表现
- 许可与使用约束
- 全球/区域覆盖能力
- 数据更新便利性
- 预处理复杂度
- 与当前底图体系兼容性
- 服务端 tile 生成链接入难度

---

## 12. 第一阶段最小可交付

### 必做
1. 数据源选型结论
2. land/sea mask 数据模型
3. mask 资产组织方式
4. 基础 land / sea 判定
5. 给 Display Product 的对接方式

### 第二阶段
1. coast transition band
2. 多 zoom 精度策略
3. 日本重点海域精度优化
4. 与 Offline Package 的复用关系定义

---

## 13. 接受标准

任务完成时，必须满足：

- land/sea mask 被正式定义为独立基础层
- 不再从天气 pbf 推断海陆边界
- 已有明确数据源选型结论
- 已定义 mask 资产和输出组织方式
- 已能支撑 Display Product 的海陆差异化显示
- 已为 coastline transition 预留扩展空间
- 符合 NavSea V11 非破坏式扩展要求

---

## 14. Codex 执行要求

执行此任务时：

- 优先产出选型文档、mask 类型定义、mask asset 组织规则
- 若修改已有文件，必须等待用户提供原文件
- 若新建 `.ts/.tsx` 文件，必须包含 NavSea logger 初始化
- 不引入未知依赖
- 不把天气产品逻辑混入 mask 基础层
- 不把 mask 简化成前端临时判断逻辑

---

## 15. 一句话定义

本任务的本质是：

**为 NavSea 建立一个独立、可复用、可服务于天气显示产品的 land/sea mask 基础地理资产层。**

---
