| name | minemap-scene-components |
| description | MineMap 三维场景组件体系:SceneModel、SceneTileset、SceneObject(Earth/Skybox/AirLine 等),重点补全 glTF/glb 与 3D Tiles 参数边界。 |
MineMap Scene Components
Quick Start
map.on("load", () => {
map.addSceneComponent({
id: "building-gltf",
type: "3d-model",
data: "https://example.com/building.glb",
position: new minemap.Math.Vector3(116.39, 39.9, 0),
rotation: [90, 0, 0],
scale: [1, 1, 1],
allowPick: true
});
map.addSceneComponent({
id: "city-tiles",
type: "3d-tiles",
urls: [{ url: "https://example.com/tileset.json", name: "city" }],
maximumScreenSpaceError: 8,
maximumMemoryUsage: 512
});
});
Core Concepts
1) 统一入口
map.addSceneComponent() 是三维对象推荐入口,内部按 type 分发:
3d-model -> SceneModel
3d-tiles -> SceneTileset
scene-object -> 场景对象(如 Earth、Skybox、Panorama、AirLine)
2) 迁移规则
addSource(type="3d-model" | "3d-tiles") + addLayer(...) 是历史路径
- 4.22 继续兼容,但源码注释已经明确不推荐继续新增
最近 master 补充的一个重要现实情况是:
- 历史
addSource + addLayer(type='3d-model') 路径在当前版本仍被修复维护
demo/html/GLBAddSourceOfficialStyle.html 就是专门补给这条历史路径的 shipped demo
因此文档应写成:
- 新业务仍优先
addSceneComponent()
- 但如果你在维护旧项目,
addSource + addLayer(type='3d-model') 不是“理论兼容而已”,当前 master 仍在修复其实际加载问题
3) 统一生命周期管理
推荐统一用:
map.addSceneComponent()
map.getSceneComponent()
map.removeSceneComponent()
4) SceneModel 和 SceneTileset 的角色边界
SceneModel:
- 适合 glTF / glb
- 适合单模型和实例化模型
- 适合做模型级动画、线框、局部裁剪、最小像素显示
SceneTileset:
- 适合 3D Tiles
- 适合倾斜摄影、BIM 切片、点云
- 适合做 LOD、内存预算、多数据集组合飞行、TileFeature 级运行时样式
5) 其他公开场景对象与辅助类
source/index.js 还导出了:
- 场景对象:
Sun、Earth、Skybox、Panorama
- 业务对象:
AirLine、BeiDouGrid、GradientLine、GaussianSplatting、AdminDivision
- 模型辅助:
TerrainLeveling、ModelInstance、ModelInstanceCollection
- 裁剪辅助:
ClippingPlane、ClippingPlaneCollection
SceneModel(glTF / glb)详细参数
这一节以 source/style/SceneModel.js 为准。
使用定位
推荐场景:
- 单个 glTF / glb 模型
- 一份 glTF 做大量实例化
- 需要 pick、裁剪、阴影、水面交互、线框、模型自带动画
最核心的输入字段
id
data:glTF JSON、glb URL,或可被内部 loader 解析的数据
map
变换参数优先级
源码和注释都很明确,优先级必须按下面理解:
matrix 存在时,position / rotation / scale / quaternion 都被忽略
- 没有
matrix 时,用 TRS 组合
rotation 和 quaternion 同时给时,优先 rotation
因此推荐:
- 简单业务用
position + rotation + scale
- 精确姿态控制用
matrix
位置与姿态
position:模型锚点位置,顺序 XYZ
scale:XYZ 缩放
rotation:欧拉角旋转,顺序 XYZ
quaternion:四元数旋转
matrix:完整变换矩阵
modelFolder:模型外部贴图、资源文件夹地址
渲染与显示控制
minimumPixelSize:最小屏幕像素尺寸,默认 0
visibility:默认 visible
allowPick:默认 true
minzoom:默认 0
maxzoom
opacity
backCulling
光照、分类、阴影、水面
lightingModel
classificationType
castShadow
receiveShadow
allowWaterRefract
allowWaterReflect
源码实现上的关键点:
- 构造默认
lightingModel 实际取 LightingModelType.PBR
classificationType 默认 ClassificationType.NONE
castShadow 默认 true
receiveShadow 默认 true
classificationType 的重要边界:
- 注释只允许
IGNORECLASSIFICATION 和 NONE
IGNORECLASSIFICATION 用在地形下挖、标绘场景较多
- 开了
IGNORECLASSIFICATION 后,不再接受 layer / primitive 的矢量贴地叠加
glTF 自带动画与包围盒
activeAnimation:是否激活 glTF 自带动画,默认 true
accurateBounding:是否按动画实时刷新精确包围体,默认 false
loaded:加载完成回调
使用建议:
- 模型如果会动,但你只是看,不一定开
accurateBounding
- 只有出现视锥误剔除、动画边界错误时,再考虑打开
裁剪与距离控制
clippingPlanes
distanceDisplayCondition
实例化模式
源码里非常关键的一点:当传入 positions 时,会进入实例化模型路径。
实例化相关字段:
positions
rotations
scales
shows
colors
instanceNames
推荐场景:
不推荐:
- 把 1000 个同款模型写成 1000 个独立
addSceneComponent({type:'3d-model'})
线框相关参数
showEmbeddedWireframe:显示模型内置线框,默认 true
generateWireframe:是否生成折痕线框,默认 false
showGeneratedWireframe:默认跟随 generateWireframe
wireframeCreaseThreshold:默认 0.05235988 弧度
这套参数的意义:
- 有些 glTF 节点名本身就带
_wireframe / _crease_edge
- 没有内置线框时,可以让引擎在装配阶段按折痕阈值生成
最近 master 需要补充的一条行为是:
_crease_edge 已被明确纳入内置线框尾缀识别
- 不只是
_wireframe,带 _crease_edge 的内置数据也会进入这套兼容逻辑
对应 demo:
demo/html/ModelCreaseEdgeWireframeRender.html
因此当前版本更准确的表述是:
- 内置线框命名兼容至少覆盖
_wireframe / _crease_edge
- 如果资产本身已经带好这类内置线框数据,应优先用
showEmbeddedWireframe
- 只有没有内置线框数据时,再考虑
generateWireframe
自定义属性
这不是渲染参数,而是给业务层挂附加信息的容器,常用于点击后弹面板、三维查询结果识别。
推荐写法
map.addSceneComponent({
id: "building-gltf",
type: "3d-model",
data: "https://example.com/building.glb",
modelFolder: "https://example.com/assets/",
position: [116.39, 39.9, 0],
rotation: [90, 0, 0],
scale: [1, 1, 1],
allowPick: true,
castShadow: true,
receiveShadow: true
});
实例化推荐写法
map.addSceneComponent({
id: "tree-instance",
type: "3d-model",
data: "https://example.com/tree.glb",
modelFolder: "https://example.com/assets/",
positions,
rotations,
scales,
shows,
colors,
instanceNames
});
SceneTileset(3D Tiles)详细参数
这一节以 source/style/SceneTileset.js 为准。
使用定位
推荐场景:
- 倾斜摄影
- BIM 切片
- 点云
pnts
- 多份 tileset 组合管理
数据入口
推荐:
- 单份也尽量用
urls 思维理解,因为 MineMap 明确支持多份 tileset 组合
显示与变换
show:默认 true
translation:沿模型局部坐标平移,单位米
minzoom
maxzoom
opacity
backCulling
清晰度与缓存预算
maximumScreenSpaceError
maximumMemoryUsage
源码真实默认值:
maximumScreenSpaceError = 16
maximumMemoryUsage = 256
说明:
- 注释里还有旧文案写 64 MB,但运行时代码已经是 256 MB,文档应以实现为准
maximumScreenSpaceError 越小越清晰,网络和内存开销越大
跨级调度参数
loadSiblings
skipLevelOfDetail
baseScreenSpaceError
skipLevels
skipScreenSpaceErrorFactor
immediatelyLoadDesiredLevelOfDetail
schedulingPolicy
源码默认值:
loadSiblings = false
skipLevelOfDetail = false
baseScreenSpaceError = 1024
skipLevels = 1
skipScreenSpaceErrorFactor = 16
immediatelyLoadDesiredLevelOfDetail = false
schedulingPolicy = BALANCED
使用建议:
- 默认先不用跨级调度
- 只有大数据场景卡在调度阶段时,再逐项尝试
immediatelyLoadDesiredLevelOfDetail 会忽略 skip 相关因素,只拉目标精度 tile,移动相机时常更慢,不是普遍优化开关
点云专属字段
pointSize
customizedColor
说明:
pointSize 只对点云生效,默认 1
customizedColor 目前只对点云生效
- 点云不支持部分普通 mesh 参数,比如 pick / clipping / opacity 这类能力要具体看数据类型
拾取、分类、光照
allowPick:默认 true
classificationType
lightingModel:默认 LightingModelType.NONE
sourceLoaded
sourceLoaded 和 SceneModel.loaded 不同:
sourceLoaded 更偏 source / tileset 加载完成后的回调
- 很适合在 tileset 边界可用后立即
flyTo({ target: tileset })
geoBoundsOptions
这是 MineMap 特有、而且很实用的参数:
- 默认
{ index: 0, combine: false }
作用:
- 用
urls 同时挂了多份 3D Tiles 时,指定飞行对准哪一份
- 或者把多份边界合并后再飞
规则:
- 一旦指定
index,combine 就不会再参与合并逻辑
裁剪、阴影、水面、线框
clippingPlanes
castShadow
receiveShadow
allowWaterRefract
allowWaterReflect
showEmbeddedWireframe
generateWireframe
showGeneratedWireframe
wireframeCreaseThreshold
源码默认值:
castShadow = true
receiveShadow = false
allowWaterRefract = false
allowWaterReflect = true
showEmbeddedWireframe = true
generateWireframe = false
其他运行时参数
subIPs:多服务地址并发方案,不建议常规使用
debugFreezeFrame:调试用,慎用
flowOptions:流动纹理参数
useCompTexMipmapsGenerate:压缩纹理解压后生成 mipmaps,容易吃内存,尤其倾斜摄影慎开
推荐写法
map.addSceneComponent({
id: "city-tiles",
type: "3d-tiles",
urls: [{ url: "https://example.com/tileset.json", name: "city" }],
maximumScreenSpaceError: 8,
maximumMemoryUsage: 512,
allowPick: true,
sourceLoaded: (tileset) => {
map.flyTo({ target: tileset, duration: 1500, range: 0 });
}
});
多份 tileset 推荐写法
map.addSceneComponent({
id: "multi-tiles",
type: "3d-tiles",
urls: [
{ url: "https://example.com/a/tileset.json", name: "A" },
{ url: "https://example.com/b/tileset.json", name: "B" }
],
geoBoundsOptions: { index: 0, combine: false }
});
获取/移除组件
Common Patterns
获取/移除组件
const tileset = map.getSceneComponent("city-tiles");
if (tileset) {
map.flyTo({ target: tileset, duration: 1500 });
}
map.removeSceneComponent("city-tiles");
通过矩阵精确控制模型
复杂姿态建议先算 modelMatrix(Transforms.cartographicToFixedFrame + 自定义旋转缩放),再作为 matrix 传入;这时就不要再同时依赖 position / rotation / scale。
模型/瓦片裁剪面
const clippingPlanes = new minemap.ClippingPlaneCollection({
enabled: true,
planes: [
new minemap.ClippingPlane({
normal: new minemap.Math.Vector3(1, 0, 0),
distance: 0
})
]
});
sceneModel.clippingPlanes = clippingPlanes;
适用对象:
SceneModel
SceneTileset
- 部分地形/拉伸对象
注意:demo 中有直接改内部 _planes 的调试写法,技能库不把它当正式推荐 API。
Do Not Do This
- 不要在新业务里继续扩散
addSource/addLayer 的旧 3D Tiles 路径
- 不要把大量重复对象拆成大量独立
3d-model,优先实例化
- 不要把
extrusion 当 glTF 替代品
- 不要默认对所有 scene component 都开
allowPick
- 不要把
adaptTerrain 和 “贴 3D Tiles / 贴模型”混为一谈
- 不要把
ThreeLayer 融合层和原生 SceneModel / SceneTileset 当成同一套对象体系
Demo-backed References
demo/html/GLBAddSourceOfficialStyle.html
demo/html/ModelCreaseEdgeWireframeRender.html
常见业务 demo 已经普遍采用 scene component 作为主入口,尤其是:
- 3D Tiles 装载
- BIM / glTF 模型
- 航线、北斗网格、高斯泼溅等场景对象
Demo References
demo/html/3DTiles.html
demo/html/3DTilesLoaded.html
demo/html/3DGS-3DTiles.html
demo/html/BeiDouGridSceneObject.html
demo/html/AirLine.html
Performance Tips
- 3D Tiles 优先设置合理
maximumScreenSpaceError(常见 8~16)
maximumMemoryUsage 不要只看注释旧值,要按数据体量实测
- 多份 tileset 优先用
urls 聚合管理
- 非必要关闭
allowPick
- 实例化模型优先代替海量重复 glTF
- 线框、实时精确包围盒、压缩纹理 mipmaps 都是高成本开关
See Also
-
minemap-threejs-integration
-
minemap-2d-3d-overlay-and-classification
-
minemap-transforms
-
minemap-math-foundations
-
minemap-lighting-and-shadows
-
minemap-water-surface-and-refraction
-
minemap-primitives-and-materials
-
minemap-terrain-and-analysis
-
minemap-performance-and-backend