baidu-maps MapV-Three 3D 地图开发指南
MapV-Three 是基于 Three.js 的专业 3D 地图渲染引擎（@baidu/mapv-three），提供从底图加载、天空环境、3DTiles、可视化组件到 GIS 空间分析的完整 3D 地图开发能力。
何时适用
- 使用 MapV-Three 创建 3D 地图应用、数字孪生、城市可视化
- 加载和配置底图（百度、Bing、OSM、天地图、WMS/WMTS 等）
- 使用天空环境和天气系统（物理天空、动态天空、雨雪雷暴等）
- 加载 3DTiles 数据（建筑、高精地图、交通地图）
- 使用可视化组件（点、线、面、热力图、飞线等）
- 加载 3D 模型和设备资产（GLTF、实例化渲染、LOD）
- 使用 LBS 服务（地理编码、路线规划、POI 搜索）
- 进行 GIS 空间分析（通视、视域、淹没、坡度、体积等）
- 使用编辑和测量工具（绘制、编辑、长度/面积测量）
- 管理数据源和动画追踪系统
代码生成原则（必须在查阅参考文档前先读完本节）
生成 mapv-three 代码时必须遵守以下原则：
- 最小改动：只给用户请求的功能代码，不堆砌额外参数。例如用户说"添加动态天空"，只给
engine.add(new mapvthree.DynamicSky())，不要附带cloudsCoverage、affectWorld等高级参数。 - 默认天空冲突：Engine 自带默认天空。添加自定义天空（DynamicSky 等）时，必须在 Engine 配置中设置
rendering: { sky: null }，否则两个天空会叠加。 - 交互确认：涉及多种方案选择时（如安装环境、3DTiles 类型），如果用户已明确说明，直接执行不再询问。否则通过交互确认让用户选择，具体选项见各 reference 文档的「交互判断」章节。
- 路况加载：用户提到"路况"、"高精路况"、"百度路况"时，查阅
vector-tile.md（不是 3dtiles.md）。路况通过矢量瓦片提供者加载，不是 3DTiles。 - 百度底图：用户提到"百度底图"、"百度地图"时，需同时查阅
mapview-bindmap.md（百度栅格影像 Baidu09ImageryTileProvider）和vector-tile.md（百度矢量 BaiduVectorTileProvider），两者都是百度底图，让用户选择栅格还是矢量。 - 参数准确：代码中的 API 名称、参数名、默认值必须与参考文档一致，不要凭记忆猜测。
- AK 不要猜测：使用 LBS 服务（地理编码、搜索、路线规划等）需要
BaiduMapConfig.ak。如果代码中已有BaiduMapConfig.ak的设置，可以直接复用；如果没有，必须提示用户提供，不要从其他服务（如 AssetsScene、TileLightManager 等）的 ak 中复用，因为不同服务的 ak 权限可能不同。 - 自定义瓦片排查：用户反馈自定义 XYZ 瓦片加载不出来时，不要直接修改代码，而是查阅
mapview-bindmap.md中 XYZImageryTileProvider 的「自定义瓦片服务常见问题排查」章节，将排查方案以清单形式列出引导用户确认。对于 startLevel 问题，如果用户不确定最小层级，可让用户提供一个可访问的瓦片地址，AI 通过 WebFetch 逐级访问父瓦片（z-1, x//2, y//2）自动探测出 startLevel。排查清单：(1) 瓦片地址是否可访问 (2) startLevel 是否匹配数据最小层级 (3) Y 坐标方向（{y} vs {reverseY}） (4) CORS 跨域。确认具体原因后再修改代码。 - 版本确认：当用户遇到 API 不存在、参数不生效等问题时，优先让用户确认
@baidu/mapv-three的版本（npm list @baidu/mapv-three）。内网 npm 安装时必须加@latest（npm install -S @baidu/mapv-three@latest），否则可能因 registry 缓存或 lock 文件安装到旧版本。详见project-setup.md的版本注意事项。
快速参考
0. 项目搭建
- 项目搭建指南 — npm安装、离线部署、环境配置、项目结构
1. 引擎核心
- 引擎初始化与地图绑定 — Engine构造函数、配置项、视野控制、生命周期
2. 天空与天气
- 天空环境系统 — EmptySky、DefaultSky、HazeSky、StaticSky、CustomStaticSky、VerticalGradientSky、DynamicSky、PhysicalSky
- 天气系统 — DynamicWeather 雨雪雾雷暴等9种天气效果
3. 底图加载
- MapView底图系统 — MapView、QuadMap、影像瓦片提供者（Bing/OSM/XYZ/百度/天地图/WMS/WMTS）
- 矢量瓦片、路况与地形 — Mapbox矢量、百度矢量、GeoJSON矢量、百度路况（BaiduTrafficTileProvider）、高精路况（HDTrafficTileProvider）、Cesium地形、材质管理器。用户要求加载路况时查阅此文档
4. 3DTiles
- 3DTiles加载与管理 — Default3DTiles、3DTilesGroup、材质管理器、HDMap、TrafficMap、元素管理器
5. 可视化组件
- SimplePoint 简单点 — 基础散点、数据驱动颜色/大小、自定义形状
- Label 标签、IconPoint 图标点、Icon 图标与 Text 文字 — 文本标签、图标点、图文组合、Icon 贴地/跳动/旋转图标、Text 纯文字标注
- EffectPoint 特效、Circle 圆形、Pillar 柱体 — 波纹/雷达/气泡特效、圆形、柱状图
- Polyline 折线与 Wall 墙体 — SimpleLine、Polyline（屏幕/贴地）、飞线效果、Wall 墙体动画
- Polygon 多边形 — 填充/拉伸/边框/贴地/纹理/动画多边形
- Heatmap 热力图与 ClusterPoint 聚合点 — 2D/3D 热力图、点聚合
- EffectModelPoint 效果模型点 — 自定义3D模型点、旋转/跳跃动画、PointGroup组合
6. 模型与资产
- 模型加载 — SimpleModel、AnimationModel、LODModel、GLTFScene、GeoInstancedMesh、InstancedModel、DynamicInstancedMesh
- AssetsScene 资产场景 — 资产平台对接、设备加载/添加/编辑/删除、巡游、设备查询与显隐控制
- 设备状态控制 — 情报板文字、信号灯、路灯、风机、卷帘门、升降杆、防火门等 8 种设备操作
7. LBS 服务
- Geocoder 地理编码 — 地址转坐标、坐标转地址、百度/天地图数据源
- LocalSearch 搜索与 AutoComplete 自动完成 — POI检索、范围搜索、周边搜索、输入提示
- 路线规划 — 驾车/步行/骑行/公交路线规划、策略配置、途经点
- 行政区划 — Boundary边界查询、DistrictLayer聚合图层
8. GIS 分析
- GIS空间分析 — 通视、天际线分析（SkylineAnalysis）、淹没、坡度、视域、体积、缓冲区、瓦片掩膜（TileMask）
9. 编辑与测量
- 编辑与测量工具 — Editor（DrawerType: Spline/Point/Circle/Rect/Polygon）、Measure（MeasureType: Length/Area/Point）
10. 数字孪生与实时数据
- Twin 数字孪生车流 — Twin车辆管理、MockTwin模拟车流、DataProvider数据映射、模型配置、车辆追踪
- TileLightManager 实时信号灯 — 实时信号灯加载、DefaultLampRequest/RegionLampRequest数据源、灯态编码、自定义数据源
11. 数据源
- 数据源 — DataItem、DataSource、GeoJSONDataSource、CSVDataSource、JSONDataSource、属性映射、数据过滤
12. 动画追踪
- 动画追踪器 — PathTracker 路径巡游、OrbitTracker 轨道环绕、ObjectTracker 对象跟随
13. 覆盖物
- 覆盖物与弹窗 — DOMOverlay、Popup、Marker、GroundOverlay、事件系统
如何使用
- 根据你要实现的功能，在上面的「快速参考」中找到对应的章节
- 阅读对应的参考文档，其中包含构造函数、参数表格、方法列表和完整代码示例
- 将代码示例中的参数替换为你的实际数据即可