01 私有化地图加载绘制

目标：把私有化交付的海图数据（亿海蓝 SQLite 库表文件）发布为瓦片服务，在离线环境中用 Leaflet 加载出与在线平台 ShipxyAPI.Map 等效的海图底图，并复刻图源切换、自定义瓦片叠加、常用控件等能力。

1. 海图数据使用说明（SQLite 库表）

私有化交付的海图数据为 SQLite 库表文件，本章完整说明其数据结构、网格规则与提取方式，是后续服务搭建与前端加载的依据。

1.1 数据库解压

先解压数据包（若有解压密码请联系商务人员）。解压缩后共 19 个数据文件，其中名为 sglcolor 的为单色图数据，其他为 1～18 级海图数据库表文件，每个库表文件一张同名表。

1.2 库表说明

表名	说明
na_b_01	1级全球海图
na_b_02	2级全球海图
na_b_03	3级全球海图
na_b_04	4级全球海图
na_b_05	5级全球海图
na_b_06	6级全球海图
na_b_07	7级全球海图
na_b_08	8级全球海图
na_f_09	9级指定区域海图
na_f_10	10级指定区域海图
na_f_11	11级指定区域海图
na_f_12	12级指定区域海图
na_f_13	13级指定区域海图
na_f_14	14级指定区域海图
na_f_15	15级指定区域海图
na_f_16	16级指定区域海图
na_f_17	17级指定区域海图
na_f_18	18级指定区域海图
sglcolor	单色图

即：1～8 级表名前缀为 na_b_，9～18 级表名前缀为 na_f_，编号与缩放级别 z 一一对应（z=10 对应 na_f_10）。

1.3 库表字段说明

瓦片数据表（1～8 级表名前缀为 na_b_，9～18 级表名前缀为 na_f_）：

字段名	说明
r	行
c	列
version	图片版本，可忽略
pic	瓦片图的二进制数据，JFIF(JPEG) 格式，256×256 像素，24 位深，投影模式为 EPSG:3395。注意：当该字段长度为 3 字节时，为单色图 RGB 信息，请按 1.6 节从单色图表中提取图片数据

单色图表（sglcolor）：

字段名	说明
color	RGB 色值
pic	单色图二进制数据

1.4 网格行列值说明

海图完整图幅的经度范围为 -180°～180°，纬度范围约为 -80°～80°；

行列原点 (0, 0) 在左上角，向右、向下为正向；

1 级全球海图总共 4 张，row[0,1]，col[0,1]：

(0,0)	(0,1)
(1,0)	(1,1)

2 级全球海图总共 16 张，row[0,3]，col[0,3]；依此类推，每级瓦片数为 2^z × 2^z，级别范围 z = 1～18（无 0 级）。

寻址关系与前端 XYZ 瓦片三要素一一对应：x = 列 c，y = 行 r，z = 级别，可直接寻址。

1.5 提取海图

方式一：读库表提取

假设要提取 10 级、行为 512、列为 513 的海图图片，执行 SQL 语句：

若返回的 pic 长度为 3 字节，再按 1.6 节从单色图表二次提取。

方式二：调接口提取

若附带了接口服务，可直接访问 HTTP 接口来获取瓦片。请求格式：

http://服务器IP:端口/tile?x={x}&y={y}&z={z}&l=na&m=q

其中 x、y、z 分别为列、行、缩放级别（1～18）。例如请求 10 级、行 512、列 513 的海图图片：

http://127.0.0.1:8080/tile?x=513&y=512&z=10&l=na&m=q

注意：全球海图在低级别基本全球覆盖，但在高级别时并不是全球无缝覆盖，某些船舶罕至的区域可能无海图，所以在查表时需要处理结果为 null 的情况（服务端与前端均须做缺瓦片兜底，见第 2、3 章）。

1.6 提取单色图

当从表中查询 pic 数据的长度为 3 字节时，其为 RGB 数据，依次为 b、g、r 值。

先计算 colorValue：

colorValue = r*65536 + g*256 + b

再从 sglcolor 表中取单色图：

例如：r=255，g=250，b=190

colorValue = 255*65536 + 250*256 + 190 = 16775870

2. 服务搭建：发布 `/tile?x={x}&y={y}&z={z}&l=na&m=q`

2.1 服务接口约定

私有化瓦片服务对外暴露 1.5 节所述的 HTTP 接口：

http://服务器IP:端口/tile?x={x}&y={y}&z={z}&l=na&m=q

x、y、z 分别为列、行、缩放级别（1～18）；

例如请求 10 级、行 512、列 513 的海图：http://127.0.0.1:8080/tile?x=513&y=512&z=10&l=na&m=q。

若交付中已附带接口服务，可直接使用该服务地址，跳过 2.2 的自建实现；自建实现用于自行托管 SQLite 数据的场景。

2.2 瓦片服务：Node.js + better-sqlite3（完整可运行）

服务职责：按 z 路由到对应库表文件 → 按 (r, c) 查 pic → 3 字节时自动按 1.6 节回退 sglcolor 单色图 → 缺瓦片返回透明占位图。

tiles-server/package.json：

{
  "name": "private-chart-server",
  "version": "1.0.0",
  "main": "server.js",
  "dependencies": {
    "better-sqlite3": "^11.0.0"
  }
}

tiles-server/server.js：

启动：

浏览器访问 http://localhost:8080/tile?x=513&y=512&z=10&l=na&m=q 能看到一张海图瓦片，即服务正常。

2.3 部署要点

数据即服务：无需导入/转换，服务直接只读打开 19 个库表文件，随数据版本整包替换即可；

null 是正常态：高级别存在无海图区域，服务对查不到的瓦片返回透明占位图（HTTP 200），避免前端控制台刷 404；若希望严格区分，也可改返回 404 并配合前端 errorTileUrl；

性能：better-sqlite3 同步预编译查询在单核上即可支撑内网并发；Cache-Control 让浏览器/网关长缓存瓦片；

多源扩展：第 4 节的地图/卫星图源可用同一服务以不同 l 参数或不同端口扩展，海图固定 l=na。

3. 前端加载：Leaflet 版"ShipxyAPI.Map"

3.1 投影配置：EPSG:3395 自定义 CRS

海图瓦片投影为 EPSG:3395（WGS 84 / World Mercator，椭球墨卡托），与 Leaflet 默认的 Web 墨卡托 EPSG:3857（球面墨卡托）不同——高纬度地区两者 y 方向差异随纬度增大（±80° 处约差 0.3%），直接用默认 CRS 会导致高级别下瓦片错位、船舶位置漂移。需引入 proj4.js + proj4leaflet 定义自定义 CRS：

落地验证建议：CRS 配置完成后，叠加一条已知 WGS84 岸线或几艘 AIS 船位核对——若出现系统性南北偏移，说明该批瓦片实际按球面墨卡托切割，此时把地图 crs 配置移除（使用 Leaflet 默认 CRS）即可，其余代码不变。

3.2 与官方初始化的对应关系

官方在线写法（7.1/7.2）：

私有化等价写法（centerPoint: [32.1, 122.11] 是 [lat, lng]，与 Leaflet setView 一致，可直接平移）：

3.3 完整 HTML（可直接保存为 `index.html` 运行）

容器要求完全沿用官方 7.1 第 5 节（必须显式宽高、UTF-8、底色 #A3CCFF——官方海图海洋区域底色）：

3.4 复刻官方内置控件

官方 7.2 的控件清单（zoomControlElane/zoomviewControl/scaleCtrl/mousePostionCtrl/measureCtrl/miniMapControl）在 Leaflet 生态全部有对应实现：

官方控件	options 默认位置	Leaflet 私有化实现
zoomControlElane 缩放	topright	`L.control.zoom({position:"topright"})`
zoomviewControl 级别数字	topleft	监听 `zoomend` 自绘（下方代码）
scaleCtrl 比例尺	bottomleft	`L.control.scale({position:"bottomleft", metric:true})`
mousePostionCtrl 鼠标经纬度	bottomright	监听 `mousemove` 自绘（下方代码）
measureCtrl 测距	topleft	`L.control.polylineMeasure`（leaflet-polylined measure 插件，内网部署）
miniMapControl 鹰眼	默认关	`L.control.minimap`（leaflet-minimap 插件）

测距控件对应的插件调用（leaflet-polylemeasure 系列插件，以内网方式引入后）：

4. 图源切换（对应 basemapsControl / MT_SEA / MT_GOOGLE / MT_SATELLITE）

官方在线切换：_map.basemapsControl.changeMap("MT_SEA")。私有化环境为每个图源建一个 L.tileLayer，用 L.control.layers 提供切换（也支持代码切换）：

注意：海图瓦片为 EPSG:3395，若地图/卫星图源为 EPSG:3857，二者不能挂在同一个 CRS 的地图上——需统一投影（重切瓦片或在服务端转投影），或为不同图源分别配置匹配的 CRS。混合图源切换前先用岸线叠加验证。

卫星图高级别分段加载：官方 tileLayer.satellite.url 是按层级分段的（12 级用船讯瓦片、18 级用谷歌卫星），私有化同样可用多个不同 maxZoom 的图层叠加，或用 L.TileLayer.multi（官方月更新海图同款方案）。

5. 自定义瓦片叠加（对应 customeTileLayerService）

官方 7.5 的自定义瓦片图层服务：map.customeTileLayerService.addLayer(options)，内部就是把瓦片模板地址挂成一个瓦片图层。私有化直接用 L.tileLayer 叠加：

6. 坐标系注意事项（海图模式）

海图瓦片投影为 EPSG:3395：椭球墨卡托，需按 3.1 节配置自定义 CRS；与默认 EPSG:3857 的差异在高纬度放大，不可忽略。

网格直接寻址：原点左上、向右向下为正，x=列、y=行，与前端 XYZ 三要素一一对应；级别从 1 开始（无 0 级），minZoom 必须 ≥1。

GCJ02 偏移：在线平台海图模式下，中国沿岸陆地基面存在 GCJ02 加偏处理；私有化数据如果直接用 WGS84（AIS 数据即 WGS84），与离线矢量海图叠加时通常无需处理；但若客户的其它瓦片由互联网图源导出（带 GCJ02 偏移），需要在业务坐标进入绘制前做偏移纠正，否则船舶会"开到岸上"。

[lat, lng] 顺序：官方 centerPoint: [32.1, 122.11] 与 Leaflet L.latLng 均为纬度在前，从官方代码平移时无需调换；但调用自建后端接口时注意官方 Getmanyship 等接口是经度在前（lon/lat，且 ×10⁶ 定点），见文档 02。

完成本章后，底图链路已通，继续文档 02：在底图上绘制船舶与轨迹。

01 私有化地图加载绘制

1. 海图数据使用说明（SQLite 库表）#

1.1 数据库解压#

1.2 库表说明#

1.3 库表字段说明#

1.4 网格行列值说明#

1.5 提取海图#

1.6 提取单色图#

2. 服务搭建：发布 /tile?x={x}&y={y}&z={z}&l=na&m=q#

2.1 服务接口约定#

2.2 瓦片服务：Node.js + better-sqlite3（完整可运行）#

2.3 部署要点#

3. 前端加载：Leaflet 版"ShipxyAPI.Map"#

3.1 投影配置：EPSG:3395 自定义 CRS#

3.2 与官方初始化的对应关系#

3.3 完整 HTML（可直接保存为 index.html 运行）#

3.4 复刻官方内置控件#

4. 图源切换（对应 basemapsControl / MT_SEA / MT_GOOGLE / MT_SATELLITE）#

5. 自定义瓦片叠加（对应 customeTileLayerService）#

6. 坐标系注意事项（海图模式）#