# map-integration / 与地图融合总览

> 文档：
> - `vjcad/doc/tutorial/map-overlay.md`
> - `vjcad/doc/tutorial/web-map-overlay.md`
> 示例：
> - `vjcad/example/basic/05mapoverlay.js` — `CadMapOverlay`
> - `vjcad/example/tile/06webmapoverlay.js` — 互联网地图叠加

## 1. 三种"CAD + 地图"组合

vjcad 与地图集成的方式不只一种，按"谁是底、谁是顶"区分：

| 组合 | API / 场景 | 适用 |
|---|---|---|
| **CAD 上叠地图** | `Engine.enableWebMap(...)` 把高德 / 天地图 / 自定义 XYZ 当 **底图** | 设计图与现实位置对照 |
| **地图上叠 CAD** | `CadMapOverlay` 把整个 vjcad 视图当 **图层** 叠到 vjmap 地图 | GIS 系统中嵌入图纸 |
| **瓦片渲染** | `enableWmsTileLayer` + 服务端 WMS 瓦片 | 大图纸 / 多端访问 |

本目录聚焦前两种"融合"。瓦片渲染见 `tile/`。

## 2. 子文档结构

| 主题 | 文档 |
|---|---|
| CadMapOverlay 实战 | [cad-map-overlay.md](cad-map-overlay.md) |
| 互联网底图叠加 | [web-map-overlay.md](web-map-overlay.md) |
| 坐标系桥接（EPSG / 四参数 / 经纬度） | [coords-bridge.md](coords-bridge.md) |

## 3. 心智模型

```mermaid
flowchart LR
    subgraph CAD 上叠地图
        DWG1[(CAD 图)] -->|底图| WebMap[高德/天地图<br/>XYZ 瓦片]
    end

    subgraph 地图上叠 CAD
        Map[(vjmap 地图)] -->|图层| CadOL[CadMapOverlay<br/>vjcad 全功能视图]
    end
```

## 4. 共同的红旗

- **坐标系是核心** — 三种坐标会同时存在：CAD 内部坐标、CAD 投影坐标（如 CGCS2000）、Web Mercator (3857)、地理经纬度（4326 / GCJ02）。集成前先想清楚转换路径
- **GCJ02 偏移** — 高德坐标是 GCJ02（"火星坐标"），与 WGS84 有 100~500m 偏移；混用国家平台 / Google 时差异更明显
- **对齐依据**：`CadMapOverlay` 的位置由 vjmap `map.attach(svc, prj)` 的投影决定（`cadToLngLat` 即 `map.toLngLat`），`bounds` 只影响缩放比取样和 `zoomToExtents()`；`enableWebMap` 的对齐只看 `srs` / `fourParameterBefore`，`mapbounds` 不参与
- **token / appkey** 集成阶段要分清楚 vjcad token、vjmap token、地图供应商 key（高德 / 天地图）三者
- **加载顺序** —— 必须 `await map.onLoad()` 后再 `cadOverlay.addTo(map)`；必须 `await cadView.onLoad()` 后再 `Engine.enableWebMap(...)`

## 参考（官方文档 MCP）

- 文档：
- `vjcad/doc/tutorial/map-overlay.md`
- `vjcad/doc/tutorial/web-map-overlay.md`
- 示例：
- `vjcad/example/basic/05mapoverlay.js` — `CadMapOverlay`
- `vjcad/example/tile/06webmapoverlay.js` — 互联网地图叠加