# 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 基础地理资产层。** ---