| name | minemap-threejs-integration |
| description | MineMap 与 threejs 融合规范。覆盖 ThreeLayer、自定义 three 场景接入、OBJ/FBX/IFC/VTK 等多种数据加载，以及 GeoJSON 驱动的道路/围栏/雷达特效。 |
MineMap Threejs Integration
Quick Start
import * as THREE from "three";
import { ThreeLayer } from "../js/minemap-three-plugin/index.js";
map.on("load", () => {
map.addSource("imagery", {
type: "raster",
tiles: ["https://example.com/satellite/{z}/{r}/{c}/{z}_{x}_{y}.jpg"],
tileSize: 512
});
map.addLayer({
id: "imagery",
type: "raster",
source: "imagery",
"depth-test": true
});
const threeLayer = new ThreeLayer({
id: "three-scene",
refCenter: [120.301663, 28.576329]
});
map.addLayer(threeLayer);
const mesh = new THREE.Mesh(new THREE.BoxGeometry(20, 20, 20), new THREE.MeshStandardMaterial({ color: 0x00aaff }));
mesh.position.set(0, 0, 10);
threeLayer.addObject(mesh);
});
Architecture Positioning
1) 这不是 MineMap 核心三维对象体系，而是一条“custom layer + threejs”的融合路径
threejs 插件当前来自：
demo/js/minemap-three-plugin/index.jsdemo/js/minemap-three-plugin/index.d.ts
它的定位要和 SceneModel / SceneTileset 分清：
SceneModel / SceneTileset 属于 MineMap 原生三维对象体系ThreeLayer 属于自定义渲染层，把 threejs 场景挂到 MineMap 地图渲染管线里
因此推荐理解是：
- 需要原生 glTF / 3D Tiles / tileset / terrain 联动的标准三维对象，优先
addSceneComponent()
- 需要程序化特效、three 原生 loader、非 MineMap 原生格式或高度自定义 mesh 时，用
ThreeLayer
2) ThreeLayer 的真实渲染形态
从 index.js 和 index.d.ts 可确认：
ThreeLayer.type = 'custom'ThreeLayer.renderingMode = '3d'- 要通过
map.addLayer(threeLayer) 挂到地图里
也就是说它本质上是：
- 一个 MineMap custom layer
- 内部持有自己的 three
Scene、PerspectiveCamera、WebGLRenderer
- 复用 MineMap 的 canvas 和 WebGL 上下文
3) 当前实现要求 WebGL2
源码里 onAdd(map, gl) 会直接检查：
gl instanceof WebGL2RenderingContext
如果不是 WebGL2：
- 会直接
console.warn
- 当前 threejs 融合层不会正常进入工作状态
所以文档里必须明确写：
- 这条路径当前按 shipped 代码看是 WebGL2-only
4) 坐标不是直接拿经纬度塞 three，而是以 refCenter 为基准做转换
ThreeLayer 的最关键参数是：
作用：
- threejs 场景以内插参考中心为原点
- MineMap 经纬度 / 高程通过 world matrix 转成 three scene position
对外可用方法：
getRefCenter()setRefCenter(center)toScenePosition(position, altitude?)
这决定了 threejs 融合的基本工作流：
- 地理坐标交给 MineMap
- three mesh 坐标放在
refCenter 的局部场景系里
Public Surface Confirmed By Types
ThreeLayer 已确认入口
new ThreeLayer(options)addObject(object)removeObject(object)getScene()getSceneRoot()getCamera()getRenderer()getWebGLRenderer()getMap()findObjectByName(name, root?)toScenePosition(...)
ThreeLayer 参数
从 index.d.ts 当前可确认：
idslot?refCenter?envTexture?envIntensity?createLight?
当前 shipped demo 里最稳定、最明确使用的是：
createLight 在实现里也有明确使用；默认会创建基础光。
对 envTexture / envIntensity：
- 类型里已出现
- 但当前示例对它们的展示不足
- skill 不把它们当 first-choice demo-backed 主能力
Demo-backed Data Support
最近与当前仓库已确认的 threejs 融合 demo 包括：
demo/html/Threejs-Box.htmldemo/html/Threejs-OBJ.htmldemo/html/Threejs-FBX.htmldemo/html/Threejs-FBX-New.htmldemo/html/Threejs-IFC.htmldemo/html/Threejs-VTK.htmldemo/html/Threejs-RoadEffect.html
这说明 threejs 融合路径当前至少覆盖 3 类对象来源。
A. three 原生 Object3D / Mesh
Threejs-Box.html 证明：
- 直接 new
THREE.Mesh(...)
- 设置局部
position
threeLayer.addObject(mesh)
就可以进入 MineMap 场景。
这是最基础、最稳的融合路径。
B. 通过 three loader 加载外部模型格式
当前 demo 已明确展示：
这条能力非常关键，因为它说明 threejs 融合不是只会画程序化几何，而是真的能接更多外部格式。
OBJ + MTL
对应 demo：
demo/html/Threejs-OBJ.html
特点：
MTLLoader 先加载材质OBJLoader 再加载模型- 可做包围盒辅助显示和 GUI 变换调试
FBX
对应 demo：
demo/html/Threejs-FBX.htmldemo/html/Threejs-FBX-New.html
特点：
FBXLoader 加载外部 FBX- 运行时可调材质双面、阴影、缩放、旋转
- 新版 demo 还证明了可以通过 URL 动态追加 FBX 模型，而不只是固定本地路径
IFC
对应 demo：
demo/html/Threejs-IFC.html
特点：
- 使用
web-ifc + web-ifc-three
IFCLoader 加载 IFC- 可关闭
IFCSPACE 等可选类别
这条路径说明：
- threejs 融合对 BIM 交换格式也能形成补充入口
VTK
对应 demo：
demo/html/Threejs-VTK.html
特点：
VTKLoader 加载科学可视化 / 医工类常见几何- geometry 读入后再配 three material
C. GeoJSON 驱动的程序化特效对象
对应 demo：
demo/html/Threejs-RoadEffect.html
这个 demo 很值得单独强调，因为它不是“再加载一个外部模型”，而是：
- 读取 GeoJSON / JSON 数据
- 生成围栏、流动道路 tube、雷达圈等程序化对象
- 让 threejs 成为 MineMap 的视觉增强层
它证明的不是“支持某一种文件格式”，而是：
Built-in Mesh Factories
从 index.d.ts 当前能确认，插件公开了 3 个程序化 mesh 工厂：
createFenceMesh(...)createTubeMesh(...)createCircleMesh(...)
createFenceMesh
适用：
关键参数：
layercoordinatesmaterialcoloropacitynumspeedheight
createTubeMesh
适用：
关键参数：
layercoordinates: Position[][]materialspeedtubeRadius?tubularSegments?radialSegments?radius
这里非常重要的一点是：
coordinates 支持多条线- 这正是
Threejs-RoadEffect.html 能把多份 road GeoJSON 组织进一张 three layer 的原因
createCircleMesh
适用：
已确认材质预设：
关键参数：
layercoordinatesmaterialcoloropacityradiussegmentsnumspeedfollowWidth
Recommended Workflow
模式 1：底图仍由 MineMap 管，three 只做增强层
推荐组织：
map.addSource(...) / map.addLayer(...) 先铺影像或底图- 再
map.addLayer(new ThreeLayer(...))
- 最后把 three object 往
ThreeLayer 里加
这条路径在现有 demo 里非常一致。
模式 2：地理坐标先进 MineMap，再转 scene 坐标
如果对象本身不是直接放在 refCenter 附近局部坐标里，优先用：
threeLayer.toScenePosition(lnglat, altitude?)
不要自己手写一套经纬度转 three world 的逻辑。
模式 3：three loader 负责格式，MineMap 负责地图环境
推荐职责分工：
- three loader：OBJ / FBX / IFC / VTK 等外部格式
- MineMap：底图、地理定位、地图交互、相机环境
ThreeLayer：桥接渲染和坐标转换
模式 4：GeoJSON 做输入，three mesh 做高表现力输出
如果需求是：
优先思路不是把 GeoJSON 直接塞 style layer 里硬做，而是：
- GeoJSON 作为输入
createTubeMesh/createFenceMesh/createCircleMesh 作为可视化输出
Strict Constraints
1) 当前 threejs 融合路径不是 MineMap 原生 feature/layer 体系
这意味着你不能期待它天然拥有：
feature-state- 原生 layer query
- style spec 驱动
- 原生 source/layer 生命周期语义
2) 这条路径当前按 shipped 代码看依赖 WebGL2
不要默认把它当成 WebGL1 兼容能力写进公开文档。
3) threejs 融合不等于替代 SceneModel / SceneTileset
如果你加载的是：
除非你确实需要 three 专属能力，否则仍优先用 MineMap 原生三维对象体系。
4) 多格式支持来自 three loader 生态，不是 MineMap 原生统一 loader
这条边界要写清：
- MineMap 提供的是融合层
- OBJ / FBX / IFC / VTK 的格式解析实际依赖 three 及其扩展 loader
Failure Cases
失败场景 1：把 ThreeLayer 当作普通 MineMap 图层来写
它是 custom layer，不是 style layer。
失败场景 2：直接把 three 场景坐标当经纬度用
没处理 refCenter 和坐标转换时，位置会完全错位。
失败场景 3：用 threejs 融合去替代所有标准图层
这样会丢掉很多 MineMap 原生数据组织、查询和交互优势。
失败场景 4：没开 map.repaint = true，却期待 three 动画持续更新
当前示例基本都显式开了：
对于流动材质、雷达圈、tube 动效，这通常是必要前提。
Demo-backed References
demo/html/Threejs-Box.htmldemo/html/Threejs-OBJ.htmldemo/html/Threejs-FBX.htmldemo/html/Threejs-FBX-New.htmldemo/html/Threejs-IFC.htmldemo/html/Threejs-VTK.htmldemo/html/Threejs-RoadEffect.htmldemo/js/minemap-three-plugin/index.jsdemo/js/minemap-three-plugin/index.d.ts
See Also
minemap-fundamentalsminemap-style-and-dataminemap-2d-3d-overlay-and-classificationminemap-scene-componentsminemap-primitives-and-materialsminemap-plugin-demo-editor
