MineMap 地形设置（setTerrain）、DEM 高程查询、地形分析、TerrainLeveling、相机碰撞高度与 terrain 相关约束。
MineMap 地形设置（setTerrain）、DEM 高程查询、地形分析、TerrainLeveling、相机碰撞高度与 terrain 相关约束。
npx skills add https://github.com/ming1zhou88/minemap-skills --skill minemap-terrain-and-analysis이 명령을 Claude Code에 복사하여 붙여넣어 스킬을 설치하세요
MineMap 二三维叠加规范。覆盖矢量贴地、贴模型、对象接受/拒绝贴合、symbol 自动赋高、以及 raster 深度测试与图层顺序控制。
MineMap 全局配置、key/solution、域名地址、sprite/fonts、minemapCDN 与启动前配置顺序。用于指导用户正确完成地图初始化前的配置，不再把 accessToken 作为主推荐路径。
MineMap 的 Marker 与 Popup 规范。涵盖 DOM 覆盖物、三维高度、distanceDisplayCondition、拖拽、内容 API、地形场景与常见失败场景。
MineMap 模型运行时调试规范。用于爆炸视图、材质/纹理更新、线框显示、属性外挂、运行时查看与距离可见性控制。
MineMap 三维场景组件体系：SceneModel、SceneTileset、SceneObject（Earth/Skybox/AirLine 等），重点补全 glTF/glb 与 3D Tiles 参数边界。
MineMap 样式规范（style v8）、source/layer 管理、图标资源、GeoJSON 更新与数据源组织，重点补全 VectorTileSource 参数与约束。
| name | minemap-terrain-and-analysis |
| description | MineMap 地形设置（setTerrain）、DEM 高程查询、地形分析、TerrainLeveling、相机碰撞高度与 terrain 相关约束。 |
const map = new minemap.Map({
container: "map",
style,
position: [89.11, 27.4, 15000],
pitch: 55,
projection: minemap.ProjectionType.MERCATOR,
minHeightToDemSurface: 5,
terrainSkirtHeight: -1
});
map.on("load", () => {
map.setTerrain({
tiles: ["https://example.com/dem/{z}/{r}/{c}/{z}_{x}_{y}.terrain"],
availabilities: ["https://example.com/dem/layer.json"],
tileSize: 512,
maxzoom: 14,
extensions: {
requestVertexNormals: false,
requestWaterMask: false,
requestHeightFieldNormals: false
}
});
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"
});
const height = map.queryDEMHeightByLngLat([89.11316, 27.40665]);
console.log(height.z);
});
map.setTerrain(...) 的本质不是“再叠一层 DEM 图层”。
它做的是：
所以要记住：
raster source/layermap.setTerrain() 管这就是为什么 MineMap 4.x 已不推荐继续用旧式 terrainTiles + renderWithTerrain 那套 source/layer 写法。
setTerrain() 背后实际做了什么map.setTerrain(options) 是 MineMap 4.x 推荐 DEM 接口。
源码里能确认的实际行为有：
symbolHeightExtraction 缓存style.rasterSourceCache.setTerrain(options) 切换 terrain sourceproxySourceCache 的 layer order，保证矢量贴地缓存状态刷新所以正确理解是：
setTerrain() 是一个全局场景切换动作TerrainTileSource 是内部 terrain 数据源。
从源码可确认：
quantizedheightmap_terrainTiles_tempTerrainTiles，用来减轻切换时闪烁maxzoom 时，不再继续请求更细 DEM，而是走上采样 upsample这决定了两个开发结论：
maxzoom 不是越大越好，取决于你实际 DEM 精度只开 setTerrain() 还不够，它只负责地表几何。
通常你还需要再加一个普通影像或栅格底图：
典型组合：
map.setTerrain(...)map.addSource("imagery", { type: "raster", ... })map.addLayer({ type: "raster", source: "imagery" })地形开启后，只是让地图有真实起伏。
要不要贴地，还要看对象本身：
adaptTerrainMarker / Popup 要看 setAltitude() 与 terrain pick不要把“开启 terrain”误解成“所有对象自动贴地完成”。
setTerrain() Parameter Surfacetiles: string[] | nulltileSize: numbermaxzoom: numberavailabilities: string[] | nullextensionstilesterrain 瓦片 URL 模板。
常见形式是 .terrain 文件：
tiles: ["https://example.com/dem/{z}/{r}/{c}/{z}_{x}_{y}.terrain"];
语义：
tiles: null 表示回退到平面/椭球地表源码实现上，传 falsy 也会退回 ellipsoid；但稳定文档写法仍建议显式用：
map.setTerrain({ tiles: null });
tileSizeDEM 瓦片大小。
MineMap 4.x terrain 相关示例和源码默认使用：
512建议：
512 组织maxzoomDEM 数据的最高请求层级。
源码注释明确给出了经验值：
1416注意：
availabilities，源码注释说明 maxzoom 不再是最高精度遍历的主要依据availabilities地形索引文件列表，常见是 layer.json。
它的价值很大：
queryAccurateDEMHeightByPoint() 想拿到“最高精度”结果时，推荐配置它maxzoom推荐：
layer.json，就加上extensionsterrain 扩展对象，源码里可确认的 3 个字段：
requestVertexNormalsrequestWaterMaskrequestHeightFieldNormals默认都为 false。
requestVertexNormals请求顶点法线扩展。
适用：
requestWaterMask请求水面掩膜扩展。
适用：
requestHeightFieldNormals请求区域场法线扩展。
这个在地形分析里尤其有意义。源码和 demo 都表明：
zeroTileRequestUrl这是一个非常值得写进 skill 的“半隐藏参数”。
虽然 map.setTerrain() 的当前类型注释里没有完整展开，但：
queryAccurateDEMHeightByPoint() 的示例里出现了它TerrainTileSource 构造函数里也明确支持它作用：
适合：
terrainSkirtHeight地图构造参数和运行时属性都支持它。
语义：
规则：
< 0：按级别动态计算>= 0：固定值源码里动态值的实际逻辑是：
getLevelMaximumGeometricError(z) * 5.0建议：
-1运行时也可直接改：
map.terrainSkirtHeight = 80;
改完会重新按当前 terrain 配置刷新 terrain source。
minHeightToDemSurface这个参数非常关键，但经常被忽略。
语义：
默认值：
5适用：
运行时可直接调：
map.minHeightToDemSurface = 5;
enableUnderGround这不是 terrain 参数本身，但和 terrain 强相关。
开启后：
源码注释同时提醒：
logDepthrequestInterval地图构造参数中的请求重试/等待间隔，源码注释明确写了：
60适用：
常见查询：
queryDEMHeightByPoint(...)queryAccurateDEMHeightByPoint(...)queryDEMHeightByLngLat(...)queryDEMSourceHeightByPoint(...)使用建议：地图稳定后（idle）再做高频批量查询。
queryDEMHeightByPoint(queryGeometry)输入：
过程：
sampleTerrain(...) 采样高程返回：
Vector3特点：
适合：
queryAccurateDEMHeightByPoint(queryGeometry)输入仍然是屏幕像素坐标，但内部会调用：
sampleTerrainMostDetailed(...)特点：
availabilities适合：
queryDEMHeightByLngLat(lnglat)输入：
输出：
Vector3适合：
queryDEMSourceHeightByPoint(e, source)这是更低层的“指定 DEM source”查询入口。
当前项目里更常用的还是前三个方法；只有你明确在做 DEM source 级控制时再使用它。
map.on("load", () => {
map.setTerrain({
tiles: [terrainUrl],
tileSize: 512,
maxzoom: 14
});
map.addSource("imagery", {
type: "raster",
tiles: [imageryUrl],
tileSize: 512
});
map.addLayer({
id: "imagery",
type: "raster",
source: "imagery"
});
});
这是最标准的 terrain 起图模式。
map.on("click", async (e) => {
const point = await map.queryAccurateDEMHeightByPoint(e.point);
console.log(point.z);
});
前提：
availabilitiesconst point = map.queryDEMHeightByLngLat([116.39, 39.9]);
const z = point.z;
适合在放模型、marker、分析点之前先拿地表高度。
terrain 打开后，Marker 拖拽会走 terrain pick。
这意味着：
适合：
terrain 开启后，如果 primitive 本身支持：
adaptTerrain: true就可以让线面对象沿地表起伏。
但这依赖对象本身的 geometry/material 支持，不是 terrain 自动替你完成的。
map.setTerrainAnalysis(options) 是 terrain 栅格分析入口。
当前源码可确认：
property 支持 SLOPE、ASPECT、ELEVATIONtype 支持 EXPONENTIAL、INTERVAL、CATEGORICALbasestopsdefaultregionhasArrowproperty决定分析的地形属性：
SLOPE：坡度ASPECT：坡向ELEVATION：高程带type颜色插值方式：
EXPONENTIALINTERVALCATEGORICAL如果用 EXPONENTIAL，可再配：
base默认 base = 1.0，也就是线性插值感。
stops分析值到颜色的映射表。
要求：
Color 名称default不命中 stops 时的默认颜色。
region区域分析时的掩膜区域。
不传时：
传入时：
hasArrow是否显示方向箭头。
源码注释写的是“目前仅有坡度分析有效”，而 demo 用它表达坡向指示，所以更稳妥的理解是：
map.setTerrainAnalysis({
type: minemap.InterpolationType.EXPONENTIAL,
property: minemap.TerrainAnalysisType.SLOPE,
stops: [
[0, "#00FF00"],
[30, "#FFFF66"],
[60, "#FF8000"],
[90, "#FF0000"]
],
default: "rgba(0,0,255,1)",
region: region,
hasArrow: true
});
TerrainLeveling：地形平整TerrainLeveling 不是简单的“盖一个面”。
从源码看，它会：
region 和平整深度 depthonAdd(map) 时找出与区域相交的 terrain tilecartographicListreferenceHeight也就是说，它本质是：
region: number[]：[lng, lat, lng, lat, ...]depth: number它是 scene object，不是 layer，也不是普通 analysis API。
推荐写法：
const leveling = new minemap.TerrainLeveling({
region: [89.1, 27.4, 89.2, 27.4, 89.2, 27.3, 89.1, 27.3],
depth: 50
});
map.addSceneComponent(leveling);
运行时可调：
leveling.setDepth(80);
console.warn 并禁用map.analysis 下默认挂载：
cutFillCollectionexcavationCollectionhighlightCollectionsightlineCollectionviewDomeCollectionviewshed3DCollectioninterferenceCollectionshadowAnalysisCollectionfloodAnalysisCollectionfloodAnalysisOfflineCollectionindex.js 已导出的其他分析类除了可视域、通视、淹没、阴影，公开导出里还包括：
HighlightCutFillExcavationViewDomeInterferenceInterferenceConjoinedProfilePlayer当前空间分析相关能力已按职责拆成 4 个 skill，不再只放在一个总包里：
minemap-terrain-and-analysis
map.analysis 容器入口minemap-business-visibility-analysis
Viewshed3DSightlineminemap-business-flood-and-shadow
FloodAnalysisFloodAnalysisOfflineShadowAnalysisminemap-business-measurement
Measurement3Dminemap-business-spatial-analysis-suite
setTerrainAnalysis(...)CutFillExcavationLimitHeightViewDomeInterferenceInterferenceConjoinedProfile文档策略：
Viewshed3D、Sightline、FloodAnalysis）切换项目/场景时统一 removeAll()，避免分析对象残留。
Highlight / CutFill / Excavation 更偏地形或对象表达修饰ViewDome / Interference / InterferenceConjoined 更偏视场与干扰表达Profile / Player 更偏剖切、播放或过程辅助推荐做法：按业务模块维护自己的分析对象引用，并同步挂入 map.analysis.*Collection，不要创建后失去控制句柄。
if (map.isTerrain()) {
console.log("terrain enabled");
}
map.setTerrain({ tiles: null });
虽然实现层面对 falsy 也有兼容，但文档化写法推荐保持显式。
queryDEMHeightByPoint() 而不是总是走 queryAccurateDEMHeightByPoint()availabilities 能配就配，尤其是高精度查询和大范围分析terrainSkirtHeight 优先保留动态值，除非你明确在调接缝问题TerrainLeveling 依赖 WebGL2，不要把它当成所有终端都能稳定开启的通用效果terrain 相关资料建议交叉看：
https://minedata.cn/https://minedata.cn/nce-support/guide-3D-Ultrahttps://minedata.cn/nce-support/api-3D-Ultrahttps://minedata.cn/nce-support/demoCenter-3D-Ultra本地 demo 里和 terrain 强相关的证据源包括：
demo/html/QueryDEMHeight.htmldemo/html/DemAnalysis.htmldemo/html/TerrainLeveling.htmldemo/html/MarkerDraggableOnTerrain.htmldemo/html/RasterTerrainChange.html查 terrain 时推荐顺序：
source/api/map.js、source/data-source/source-cache/TerrainTileSource.js 看真实行为minemap-official-resources-and-onboardingminemap-fundamentalsminemap-2d-3d-overlay-and-classificationminemap-marker-and-popupminemap-primitives-and-materialsminemap-business-visibility-analysisminemap-business-flood-and-shadowminemap-business-measurementminemap-business-spatial-analysis-suiteminemap-performance-and-backend