目前平台将量算、日照、可视域等空间分析、模型相关分析、地形相关分析、相机的管理类 等所有功能都统一封装为thing对象。

1. Thing类型清单

Thing均是继承自BaseThing类的子类对象。

目前有以下类型：

功能	类名	功能示例
图上量算	mars3d.thing.Measure	查看
通视分析	mars3d.thing.Sightline	查看
地表透明	mars3d.thing.Underground	查看
日照分析	mars3d.thing.Shadows	查看
天际线描边	mars3d.thing.Skyline	查看
地形开挖	mars3d.thing.TerrainClip	查看
地形开挖(planes方式)	mars3d.thing.TerrainPlanClip	查看
地形压平	mars3d.thing.TerrainFlat	查看
地形抬升	mars3d.thing.TerrainUplift	查看
等高线	mars3d.thing.ContourLine	查看
坡度坡向分析	mars3d.thing.Slope	查看
淹没分析(地球材质)	mars3d.thing.FloodByMaterial	查看
淹没分析(矢量面)	mars3d.thing.FloodByGraphic	查看
模型平面剖切	mars3d.thing.TilesetPlanClip	查看
模型盒子裁剪	mars3d.thing.TilesetBoxClip	查看
模型压平	mars3d.thing.TilesetFlat	查看
模型裁剪	mars3d.thing.TilesetClip	查看
模型淹没分析	mars3d.thing.TilesetFlood	查看
限高分析	mars3d.thing.LimitHeight	查看
地震模拟	mars3d.thing.TilesetShake	查看
模型颜色校正	mars3d.thing.TilesetColorCorrection	查看
绕点环绕飞行	mars3d.thing.RotatePoint	查看
原地四周旋转	mars3d.thing.RotateOut	查看
第一人称贴地漫游	mars3d.thing.FirstPersonRoam	查看
视角历史记录	mars3d.thing.CameraHistory	查看
街景视角模式	mars3d.thing.StreetView	查看

2. thing的使用

平台的所有管理及分析功能类都继承于BaseThing类 ，管理及分析功能类均在mars3d.thing.*命名空间下面。 下面我们演示创建一个thing对象 ，并调用map.addThing添加到地图上。

const measure = new mars3d.thing.Measure({ 
  label: { // 可设置文本样式
    color: '#ffffff',
    font_family: '楷体',
    font_size: 20,
    background: false,
  },
})
map.addThing(measure)

// 测量长度
measure.distance()

2.1. 运行效果

新窗口查看

3. Thing的通用用法

thing对象都继承于BaseThing类，因此用法都是统一的：构造 → map.addThing 添加 → 配置参数/调用方法 → map.removeThing 移除。

成员	说明
map.addThing(thing)	将 thing 添加到地图（必须，之后才能使用）
map.removeThing(thing)	从地图上移除 thing
map.getThingById(id)	按 id 获取地图上已添加的 thing
thing.id、thing.name	对象标识与名称
thing.enabled	是否启用该功能（部分对象为 show）
thing.on(type, fn) / thing.off(type, fn)	事件监听/解绑，常用 start（开始分析）、end（分析完成）、change（参数变化）
thing.clear()	清除分析结果（区域、线、面等）
thing.destroy()	销毁对象，释放内部资源

// 通用写法
const skyline = new mars3d.thing.Skyline({
  color: "#ffff00",
  width: 2
})
map.addThing(skyline)

skyline.on(mars3d.EventType.change, (event) => {
  console.log("参数发生变化", event)
})

// 不再使用时
map.removeThing(skyline)

分析类的 thing 内部都有一个 graphicLayer（分析结果所在图层），例如 measure.graphicLayer，可以像普通矢量图层一样遍历、导出、清空结果。

4. 空间量算（Measure）

图上量算是使用频率最高的分析功能，平台封装为mars3d.thing.Measure，支持"交互绘制量算"与"已有坐标直接量算"两种用法。

4.1 构造与通用参数

const measure = new mars3d.thing.Measure({
  label: { // 量算结果文本样式
    color: "#ffffff",
    font_family: "楷体",
    font_size: 20,
    background: false
  },
  isAutoEditing: false // 绘制完成后是否自动激活编辑
  // drawEndEventType: mars3d.EventType.rightClick, // 自定义结束绘制的鼠标事件
  // drawDelEventType: mars3d.EventType.middleClick // 自定义删除点的鼠标事件
})
map.addThing(measure)

// 开始/结束 异步分析事件，可用于显示 loading
measure.on(mars3d.EventType.start, (e) => {
  console.log("开始异步分析", e)
})
measure.on(mars3d.EventType.end, (e) => {
  console.log("完成异步分析", e)
})

另外可以通过 mars3d.DrawUtil.setAllEditPointStyle({ pixelSize: 14 }) 统一修改绘制过程中编辑点的样式。

4.2 常用量算方法

方法	功能	说明
measure.distance()	空间距离	返回 DistanceMeasure 图形对象
measure.distanceSurface()	贴地距离	支持 exact 精确计算、minDistance 最小采样距离
measure.area()	空间面积	返回 AreaMeasure 图形对象
measure.areaSurface()	贴地面积	同上
measure.height()	高度差	两点间垂直高差
measure.point()	坐标测量	拾取点位并展示经纬度、高程等
measure.angle()	方位角/夹角	方位角量算

完整方法列表见 Measure API 文档。所有方法都是异步的，可用 await 等待标绘完成。

4.3 交互量算与结果获取

// 空间距离（交互式：在地图上依次点击，右键结束）
const graphic = await measure.distance({
  showAddText: true, // 是否显示结果文本
  style: {
    width: 3,
    color: "#ffff00"
  }
})
console.log("标绘完成", graphic.toJSON())

// 贴地距离
await measure.distanceSurface({
  showAddText: true,
  minDistance: 10,
  exact: true // true 精确计算；false 为快速概略计算，精度低但速度快
})

量算结果也是矢量对象，可以直接用已有的坐标构造（用于"后端计算好的结果直接上图"）：

const graphic = new mars3d.graphic.DistanceMeasure({
  positions: [
    [116.193794, 30.994415, 654.8],
    [116.236077, 30.925154, 506.2],
    [116.314569, 30.864239, 408.7]
  ],
  style: { width: 5, color: "#3388ff" },
  showAddText: true,
  attr: { remark: "示例" }
})
measure.graphicLayer.addGraphic(graphic)

4.4 结果保存与清空

// 保存为 json 文件（坐标测量、距离、面积结果均可）
const geojson = measure.graphicLayer.toJSON()
mars3d.Util.downloadFile("测量结果.json", JSON.stringify(geojson))

// 从 json 文件加载
measure.graphicLayer.loadJSON(json, { flyTo: true, clear: true })

// 清空全部量算结果
measure.clear()

运行效果

新窗口查看

5. 常见问题

5.1 创建了 thing 却没有效果？

按下面顺序排查：

1. 是否调用了 map.addThing(thing)：只 new 不添加是不会生效的，这与"图层必须 map.addLayer"是同一个道理。
2. 是否已加载对应依赖：地形类分析（开挖、压平、抬升、等高线、坡度、淹没）必须已加载地形服务；通视分析在无地形时结果不真实。
3. 是否已启用：大部分 thing 有 enabled 属性，默认可能为 false（例如天际线、地表透明）。
4. 是否有分析范围：多数分析需要先 addArea() / add() 传入区域，或先在地图上绘制。
5. 深度检测与视域：通视分析需要"分析点都在视域内"，并且分析前后需要正确设置 map.scene.globe.depthTestAgainstTerrain。
6. 模型类分析的模型是否加载完成：模型未加载完就分析，可能按包围盒得到错误结果，建议在 TilesetLayer 的 load 事件后再操作。

5.2 thing、layer、graphic 三者的关系

概念	作用	举例
layer（图层）	管理一批数据的容器，负责加载、组织、显隐	GraphicLayer、TilesetLayer、XyzLayer
graphic（矢量对象）	地图上的一个具体对象，负责样式与交互	PolygonEntity、ModelEntity
thing（功能对象）	一个"功能模块"，内部通常自带图层与交互逻辑	Measure、TerrainClip、Shadows

所以"分析类 thing"的绘制结果其实都在它自己的 graphicLayer 里，需要保存/导出结果时直接操作 thing.graphicLayer 即可。

5.3 多个分析功能同时开启会卡吗？

会。分析类功能（尤其是开挖、裁剪、坡度、淹没、等高线）都要在地形/模型的渲染管线上做额外计算。建议：

1. 同一时刻只保留 1-2 个"重分析"功能开启，其余按需 enabled = false 或 clear() 清除；
2. 分析完成后及时清理临时绘制对象（map.graphicLayer.clear()）；
3. 区域范围尽量小、splitNum 等精度参数不要盲目放大。

贡献者: wanghao

上一页场景特效