# 互联网底图叠加（高德 / 天地图）

> 文档：`vjcad/doc/tutorial/web-map-overlay.md`
> 示例：`vjcad/example/tile/06webmapoverlay.js`

让 CAD 图纸下方铺一张高德 / 天地图，用作"现实参考"。**与 `tile/webmap-overlay.md`** 内容衔接，但本页聚焦 **常规矢量编辑模式** 下的叠加，不依赖瓦片模式。

## 1. 一行启用（自动 EPSG）

```js
Engine.enableWebMap({
    tileCrs: 'gcj02',                              // 瓦片坐标系：gcj02 / wgs84
    tileUrl: [
        'https://webst0{s}.is.autonavi.com/appmaptile?lang=zh_cn&size=1&scale=1&style=6&x={x}&y={y}&z={z}',
        'https://webst0{s}.is.autonavi.com/appmaptile?lang=zh_cn&size=1&scale=1&style=8&x={x}&y={y}&z={z}'
    ],
    tileShards: '1,2,3,4',
    mapbounds: 'minX,minY,maxX,maxY',              // TS 类型必填；1.0.16 不发送、不参与对齐
    srs:       'EPSG:4509'                          // CAD 图纸坐标系 EPSG（对齐靠它）
});
```

`tileUrl` 数组中按顺序融合（一般 6=影像、8=道路注记）。

## 2. 手动叠加（自定义坐标系，四参数）

```js
Engine.enableWebMap({
    tileCrs: 'gcj02',
    tileUrl: ['https://webst0{s}.is.autonavi.com/appmaptile?...&x={x}&y={y}&z={z}'],
    tileShards: '1,2,3,4',
    mapbounds: 'minX,minY,maxX,maxY',
    // dx, dy, scale, rotation
    fourParameterBefore: '12727039.383545,3579066.6894800006,1,0'
});
```

什么时候用四参数？

- CAD 图纸坐标 **不是** 国家标准 EPSG（自定义本地坐标 / 老图）
- 已知精确的"图坐标→Web Mercator"线性变换

详细计算见 [coords-bridge.md](coords-bridge.md)。

## 3. 操作 API

```js
Engine.enableWebMap(config);          // 启用
Engine.disableWebMap();               // 移除

Engine.setWebMapAlpha(0.5);           // 0~1
Engine.pcanvas.redraw();              // 必须 redraw 才会生效

if (Engine.isWebMapEnabled()) { /* ... */ }
```

## 4. 命令式（可视化面板）

```js
await Engine.editor.executerWithOp('WEBMAPOVERLAY');
```

面板提供的功能：

- **地图类型**：高德影像 / 高德道路 / 天地图影像 / 天地图道路
- **自动模式**：选坐标系类型 → 自动推算 EPSG
- **手动模式**：拾取对应点 / 直接填四参数（对应点的经纬度一律按 **WGS84** 处理；从高德等 GCJ02 底图取的坐标要先转成 WGS84）
- **透明度滑条**：实时调
- **配置记忆**：自动保存到 localStorage

适合做 demo 和"由用户配置"的场景。

## 5. 内置坐标系类型与 EPSG 推算

面板"自动模式"可选 4 种坐标系（**没有 WGS84 选项**），按带号算 EPSG（源码 `getEpsgParam`，`service/geo/transform/epsg.ts`）：

| 坐标系 | 带号 | EPSG |
|---|---|---|
| CGCS2000 3° | 25–45 | 4513–4533 |
| CGCS2000 6° | 13–23 | 4491–4501 |
| 西安 80 3° | 25–45 | 2349–2369 |
| 西安 80 6° | 13–23 | 2327–2337 |
| 北京 54 3° | 25–45 | 2401–2421 |
| 北京 54 6° | 13–23 | 21413–21423 |
| 新北京 54 3° | 25–29 / 30–45 | 4652–4656 / 4766–4781 |
| 新北京 54 6° | 13–23 | 4568–4578 |

推算原理：取 **当前视图中心** 的 WCS X（不是实体坐标）——X 为 8 位时前两位即带号；X 只有 6~7 位（无带号前缀）时需在面板里手填带号。带号 13–23 走 6° 带、25–45 走 3° 带，再按所选坐标系查上表。表中都是"带号前缀"版 EPSG；4502–4512、4534–4554 这类按中央经线编号（无带号前缀）的 EPSG 面板不会推出，需要时自己填进 `srs`。

## 6. 常用瓦片源（合规 / 申请要求自查）

```js
// 高德影像 (GCJ02)
'https://webst0{s}.is.autonavi.com/appmaptile?lang=zh_cn&size=1&scale=1&style=6&x={x}&y={y}&z={z}'
// 高德道路 (GCJ02)
'https://webst0{s}.is.autonavi.com/appmaptile?lang=zh_cn&size=1&scale=1&style=8&x={x}&y={y}&z={z}'
// 天地图（需要 token）
'http://t{s}.tianditu.gov.cn/img_w/wmts?...&TILEMATRIX={z}&TILEROW={y}&TILECOL={x}&tk=YOUR_TOKEN'
// 自定义 XYZ
'https://your-server.com/tiles/{z}/{x}/{y}.png'
```

`{s}` 是 shard，从 `tileShards` 中循环替换；不带 shard 的源把 `tileShards` 设为 `''`。

## 7. 透明度建议

- 现场定位 / 设计 → `0.6 ~ 0.8`，地图作为"暗淡背景"
- 测量验证 → `0.4 ~ 0.5`，CAD 与底图都看得清
- 数据叠加 / 复核 → `0.3` 以下，主要看底图，CAD 作为"细节修正"

## 8. 与瓦片模式 (tile mode) 的关系

| | 普通矢量模式 | tile mode |
|---|---|---|
| CAD 数据 | 全部下载到前端绘制 | 服务端 WMS 切片 |
| 内存 / 性能 | 适合中小图（<10 万实体） | 适合大图 |
| `enableWebMap` | ✅ 可用 | ✅ 可用（同样调用） |
| 透明度 | `setWebMapAlpha` | `setWmsTileAlpha` + `setWebMapAlpha` 各管一层 |
| 坐标对齐 | `srs` / `fourParameterBefore`（`mapbounds` 不参与） | 同 |

> 详见 `tile/webmap-overlay.md`。

## 红旗

- `mapbounds` 类型是字符串 "minX,minY,maxX,maxY"（TS 必填），但 1.0.16 不发送给服务端、不参与对齐；对齐只看 `srs`（优先）或 `fourParameterBefore`，两者都不给则底图空白
- 高德 / 天地图等地图源在生产环境需要 **API key / 合规许可**；示例中的 URL 仅用于演示
- `setWebMapAlpha` 不立即生效，必须 `Engine.pcanvas.redraw()`
- 如果图纸是 GCJ02 而 `tileCrs: 'wgs84'`（或反之），地图与 CAD 会"差几十米"
- `fourParameterBefore` 的角度单位是 **弧度**（与 `enableWebMap` 内部接口一致），不是度
- 多次调 `enableWebMap` 会替换上一次配置；想叠多层底图请用 `tileUrl` 数组而不是连续调用
- 移动端 / 切换主题后必须 `pcanvas.redraw()` 才会重新分块拉瓦片

## 参考（官方文档 MCP）

- 文档：`vjcad/doc/tutorial/web-map-overlay.md`
- 示例：`vjcad/example/tile/06webmapoverlay.js`