6.1 KiB
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. 目标产物
本任务完成后，应至少形成：
land/sea mask数据来源选型结论mask asset组织方案mask tile或mask data block输出方案coast transition基础定义mask metadata结构- 给 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. 必须定义的数据语义
至少定义：
landseacoastTransition（如实现第二阶段）- 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. 第一阶段最小可交付
必做
- 数据源选型结论
- land/sea mask 数据模型
- mask 资产组织方式
- 基础 land / sea 判定
- 给 Display Product 的对接方式
第二阶段
- coast transition band
- 多 zoom 精度策略
- 日本重点海域精度优化
- 与 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 基础地理资产层。