互联网地图叠加（WebMap Overlay）

文档：vjcad/doc/tile/tile-mode.md 示例：vjcad/example/tile/06webmapoverlay.js

把 高德 / 天地图 / 自定义瓦片源 作为 CAD 的底图叠加显示，常用于做 GIS / BIM 的位置对照、外业核对。

1. 启用 / 关闭

Engine.enableWebMap(config) 只接收 一个 WebMapTileConfig 对象——没有 ('gaode', {type}) 这样的供应商名参数：

// 高德卫星图（WebMapOverlayPanel 内置预设同款配置）
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',           // {s} 占位符的取值列表
    tileSize: 256,
    tileMaxZoom: 18,
    mapbounds: '0,0,100000,100000',  // TS 类型必填，但 1.0.16 不发送、不参与对齐
    srs: 'EPSG:4509',                // 自动对齐模式：CAD 图的 EPSG 码（对齐靠它）
});

// 调整透明度
Engine.setWebMapAlpha(0.6);

// 状态查询 / 关闭
Engine.isWebMapEnabled();            // → boolean
Engine.disableWebMap();

2. WebMapTileConfig 字段

3. 常用源配置

WebMapOverlayPanel 内置预设（源码 MAP_PRESETS）照抄即可：

高德

// 卫星 + 路网叠加（gcj02）
Engine.enableWebMap({
    tileCrs: 'gcj02',
    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', tileSize: 256, tileMaxZoom: 18,
    mapbounds: boundsStr,
    srs: 'EPSG:4509',
});

// 路网（gcj02）
Engine.enableWebMap({
    tileCrs: 'gcj02',
    tileUrl: 'https://webrd0{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: boundsStr, srs: 'EPSG:4509',
});

天地图（需 token）

// 天地图矢量 + 注记（wgs84），{t} 占位符由 tileToken 填充
Engine.enableWebMap({
    tileCrs: 'wgs84',
    tileUrl: [
        'https://t{s}.tianditu.gov.cn/DataServer?T=vec_w&X={x}&Y={y}&L={z}&tk={t}',
        'https://t{s}.tianditu.gov.cn/DataServer?T=cva_w&X={x}&Y={y}&L={z}&tk={t}',
    ],
    tileShards: '1,2,3,4,5,6',
    tileToken: ['TOKEN_A', 'TOKEN_B'],   // token 池（不是每层一个）：服务端用当前 token 填 {t}，遇 429 换下一个
    mapbounds: boundsStr,
    srs: 'EPSG:4509',                    // 填 CAD 图自身的 EPSG，与底图是天地图还是高德无关
});
// 卫星图把 T=vec_w/cva_w 换成 T=img_w/cia_w

自定义 XYZ 瓦片

Engine.enableWebMap({
    tileCrs: 'gcj02',
    tileUrl: 'https://tile.example.com/{z}/{x}/{y}.png',
    tileMaxZoom: 18,
    mapbounds: boundsStr,
    fourParameterBefore: '0,0,1,0',      // 无 EPSG 时用四参数对齐（CAD→EPSG:3857；此值表示 CAD 坐标本身就是 3857 米）
});

4. 坐标对齐

对齐完全由服务端 /map/tile/webmap 完成：前端每块瓦片只发送自己的 CAD WCS bbox，服务端把 bbox 两角点换算成 WGS84，再按 tileCrs 抓取并拼接互联网瓦片。CAD 坐标 → 经纬度的换算二选一：

• srs（推荐）：图是标准投影坐标，给出 EPSG 码，服务端 proj4 转 WGS84（两者都给时 srs 优先）
• fourParameterBefore：图是任意本地坐标，用四参数（平移 dx,dy + 缩放 + 旋转弧度）把 CAD 坐标直接换到 EPSG:3857，再反算经纬度

两者都不给，服务端一律返回空白瓦片；mapbounds 不发送、不参与对齐。

5. 透明度联动

// 给互联网地图加 50% 透明
Engine.setWebMapAlpha(0.5);

setWebMapAlpha 与 setWmsTileAlpha / setReadOnlyAlpha 是 三个独立通道。常见组合：

6. 与瓦片模式叠加示意

flowchart TB
    W[互联网地图] --> C[Canvas 底层]
    T[CAD 瓦片] --> C
    M[编辑区遮罩] --> C
    V[矢量层] --> C
    C --> Out[最终画面]

每一层都有自己的透明度。enableWebMap 不会进入只读，纯粹是显示层。

红旗

• 天地图 token 需要后端代理，否则会暴露在前端代码
• 互联网地图按公司或项目可能有合规要求，部署前确认是否被允许
• tileUrl 的 {z}/{x}/{y}/{s}/{t} 占位符可出现在 URL 任意位置（如天地图 ?X={x}&Y={y}&L={z}）；瓦片由 vjmap 服务端代为抓取，浏览器不直连瓦片源
• enableWebMap 之后必须保证 pcanvas 仍然存在（页面 destroy 时记得 disableWebMap）
• srs/fourParameterBefore 配错 = 地图叠到错误位置，都不给 = 空白；先小范围验证再铺开
• 内置 UI 面板 WebMapOverlayPanel 走的也是同一套 enableWebMapTileLayer——手动开启后再用面板操作会互相覆盖

参考（官方文档 MCP）

• 文档：vjcad/doc/tile/tile-mode.md
• 示例：vjcad/example/tile/06webmapoverlay.js