本文档独立记录 MinBIMEffects 公开 API，与 MinBIM 主引擎文档分开维护、分开版本化。以下划线
_开头的属性和方法不属于稳定公开接口。
1 概述
独立于主引擎的特效包，产物 dist/minbim-effect.min.js（UMD，挂 window.MinBIMEffects）/ dist/minbim-effect.module.min.js（ESM）。
公开出口包括 VERSION（当前为 '1.0'）、attach、detach、EffectManager、Effect 以及下述 18 个特效类。
引入约定：UMD 必须在 minbim.min.js 之后加载（复用主包的 THREE，不重复打包）；浏览器直接 import effects/ 源码调试时，页面需在 module script 之前配置 import map：{ "imports": { "three": "./libs/three/three.module.js" } }。
2 管理器与生命周期
const mgr = MinBIMEffects.attach(viewer); // 注入（幂等），返回 EffectManager
const id = mgr.add(effect); // 添加特效，返回 id
mgr.remove(id); // 移除单个，返回 Boolean
mgr.get(id); // 按 id 取特效实例
mgr.clear(); // 清空全部
mgr.size; // 当前特效数
MinBIMEffects.detach(viewer); // 解除注入并释放全部特效
mgr.pause(); mgr.resume(); mgr.paused; // 暂停/恢复全部动画（暂停即停止逐帧渲染，GPU 回落）
mgr.setVisible(false); mgr.visible; // 整体显隐（隐藏同样零成本）
mgr.dispose(); // 直接销毁管理器；与 detach 等效
通用约定：所有特效对象不参与 AO；都受 pause()/setVisible() 总开关控制；shader 类特效的参数可在运行时通过 effect.object3d 下的 material.uniforms 调整。基类 Effect 暴露 id、enabled（单独开关动画）、animated、object3d、setVisible() 和 dispose()；update(time) 由管理器驱动，自定义特效不应另建 RAF 循环。
3 特效清单（18 个）
3.1 FlowLine — 流动线
彗尾条纹沿路径滚动（管线流向、车流等）。
| 参数 | 默认 | 说明 |
|---|---|---|
| points | 必填 | 路径点 [[x,y,z],...]（≥2） |
| color | '#00ffff' |
颜色 |
| radius | 0.15 |
管径 |
| speed | 1 |
条纹滚动速度（周/秒） |
| density | 按长度约每 3 单位一条 | 条纹重复条数 |
| segments | 按长度自适应 | 路径分段数 |
| closed | false |
闭合路径 |
mgr.add(new MinBIMEffects.FlowLine({ points: [[0,0,0],[20,0,0],[20,0,20]], color: '#00ff00' }));
3.2 PulseRing — 放射波/脉冲圈
圆环由中心向外扩散淡出，多层错峰。
| 参数 | 默认 | 说明 |
|---|---|---|
| position | [0,0,0] |
中心点 |
| color | '#00aaff' |
颜色 |
| radius | 5 |
最大半径 |
| duration | 2 |
单层扩散周期（秒） |
| rings | 2 |
层数（1~4） |
| width | 0.12 |
环带宽度（占半径比） |
mgr.add(new MinBIMEffects.PulseRing({ position: [10, 0.1, 10], radius: 18, rings: 3, color: '#ff6600' }));
3.3 PoiMarker — 点位标记（POI）
canvas 圆点 + 文字标牌（Sprite 始终面向相机），上下浮动。
| 参数 | 默认 | 说明 |
|---|---|---|
| position | [0,0,0] |
位置 |
| text | 无 | 标注文字（不传则只有圆点） |
| color | '#ff3333' |
圆点颜色 |
| size | 2 |
标牌高度（世界单位） |
| bob | 0.3 |
浮动幅度（0 = 纯静态） |
| speed | 2 |
浮动速度 |
mgr.add(new MinBIMEffects.PoiMarker({ position: [0, 2, 20], text: '1# 摄像头', color: '#ff3333' }));
3.4 CloudLine — 云线标注
沿圆/矩形区域生成修订云线，圈出重点区域。默认纯静态（不触发逐帧渲染）。
| 参数 | 默认 | 说明 |
|---|---|---|
| shape | 'circle' |
'circle' | 'rect' |
| center | [0,0,0] |
中心 |
| radius | 5 |
圆半径（circle） |
| width / height | 10 / 8 |
矩形宽/高（rect） |
| scallop | 0.4 |
凸弧高度 |
| arcLength | 2 |
单个凸弧长度 |
| color | '#ffcc00' |
颜色 |
| pulse | false |
呼吸闪烁 |
mgr.add(new MinBIMEffects.CloudLine({ shape: 'rect', center: [10, 0.2, 10], width: 26, height: 18 }));
3.5 RadarScan — 雷达扫描
旋转扇形拖尾扫描。
| 参数 | 默认 | 说明 |
|---|---|---|
| position | [0,0,0] |
中心 |
| color | '#00aaff' |
颜色 |
| radius | 8 |
半径 |
| speed | 1.5 |
旋转速度（弧度/秒） |
mgr.add(new MinBIMEffects.RadarScan({ position: [0, 0.1, 0], radius: 8 }));
3.6 ElectronicFence — 电子围栏
沿多边形路径升起的半透明围墙，能量带向上流动。
| 参数 | 默认 | 说明 |
|---|---|---|
| points | 必填 | 路径点 [[x,y,z],...]（≥2，y 为墙底高度） |
| height | 3 |
墙高 |
| color | '#00ff88' |
颜色 |
| speed | 0.5 |
能量带流动速度 |
| opacity | 0.6 |
不透明度（0~1） |
| closed | true |
闭合 |
mgr.add(new MinBIMEffects.ElectronicFence({ points: [[-4,0,-4],[24,0,-4],[24,0,24],[-4,0,24]], height: 3 }));
3.7 RouteFly — 路线飞行（巡检漫游）
相机沿路径飞行，视线朝向前方路径点。纯相机动画（无场景对象）。
| 参数 | 默认 | 说明 |
|---|---|---|
| points | 必填 | 路径点 [[x,y,z],...]（≥2） |
| speed | 10 |
飞行速度（单位/秒） |
| lookAhead | = speed | 视线前视距离 |
| loop | false |
循环飞行 |
| closed | false |
路径闭合（loop 时建议 true） |
| interruptible | true |
飞行中点击/滚轮即打断并接管视角 |
| onComplete | 无 | 飞到终点回调（loop 不触发） |
方法：play() 开始/继续（manager 全局暂停时会自动恢复）；pause() 暂停（恢复交互）；stop() 停止回起点。
const fly = new MinBIMEffects.RouteFly({ points: [[35,15,35],[0,10,35],[-20,8,0]], speed: 8, loop: true, closed: true });
mgr.add(fly);
fly.play(); // 飞行中用户点击/滚轮可打断接管
3.8 LightPillar — 光柱
点位直冲向上的光束（竖直渐隐 + 能量带上流 + 菲涅尔软边）。
| 参数 | 默认 | 说明 |
|---|---|---|
| position | [0,0,0] |
底部中心 |
| color | '#00e5ff' |
颜色 |
| radius | 1 |
半径 |
| height | 10 |
高度 |
| speed | 0.8 |
能量带上流速度 |
mgr.add(new MinBIMEffects.LightPillar({ position: [0, 0, 0], height: 15 }));
3.9 HeightScan — 楼体升层扫描
发光水平切面自下而上循环扫过建筑（巡检/分层展示）。
| 参数 | 默认 | 说明 |
|---|---|---|
| center | [0,0,0] |
扫描中心（y 为起点高度） |
| width / depth | 20 / 20 |
切面宽/深 |
| height | 15 |
扫描行程（向上） |
| color | '#00ffff' |
颜色 |
| speed | 3 |
上升速度（单位/秒） |
mgr.add(new MinBIMEffects.HeightScan({ center: [10, 0, 10], width: 30, depth: 25, height: 20 }));
3.10 ArrowFlow — 流向箭头
锥体串沿路径等距行进、朝向切线（比 FlowLine 更强调方向）。
| 参数 | 默认 | 说明 |
|---|---|---|
| points | 必填 | 路径点 [[x,y,z],...]（≥2） |
| color | '#ffaa00' |
颜色 |
| count | 约每 5 单位一个 | 箭头个数 |
| size | 1 |
箭头尺寸（锥体高度） |
| speed | 3 |
行进速度（单位/秒） |
| closed | false |
闭合路径 |
mgr.add(new MinBIMEffects.ArrowFlow({ points: [[0,0.5,0],[20,0.5,0],[20,0.5,20]] }));
3.11 SpinRing — 旋转光环
倾斜光环绕点位旋转（常套在 PulseRing/LightPillar 外做组合标记）。
| 参数 | 默认 | 说明 |
|---|---|---|
| position | [0,0,0] |
中心 |
| color | '#00ffff' |
颜色 |
| radius | 3 |
半径 |
| tube | 0.08 |
环管粗细 |
| tilt | 0.4 |
倾斜角（弧度） |
| speed | 1 |
旋转速度（弧度/秒） |
mgr.add(new MinBIMEffects.SpinRing({ position: [10, 0.3, 10], radius: 4 }));
3.12 RegionPulse — 区域告警闪烁
多边形区域填充呼吸 + 描边（告警区域/重点地块圈定）。
| 参数 | 默认 | 说明 |
|---|---|---|
| points | 必填 | 多边形顶点 [[x,z],...]（≥3） |
| y | 0.05 |
高度（略高于地面防闪面） |
| color | '#ff3333' |
颜色 |
| speed | 2.5 |
闪烁速度 |
| min / max | 0.15 / 0.55 |
不透明度范围 |
| border | true |
描边 |
mgr.add(new MinBIMEffects.RegionPulse({ points: [[-4,-4],[24,-4],[24,24],[-4,24]] }));
3.13 FireEffect — 着火
单张火焰贴图（fire.png，base64 内嵌无需资源目录）+ 交叉面片 + 噪声 UV 扭曲。根部稳定、尖部摆动且顶端不规则破碎，纵向伸缩 + 亮度闪烁。
| 参数 | 默认 | 说明 |
|---|---|---|
| position | [0,0,0] |
火焰底部中心 |
| height | 3 |
火焰高度 |
| width | height × 0.7 | 火焰宽度 |
| planes | 3 |
面片数：1 = billboard 单面（始终面向相机）；≥2 = 静态交叉面（夹角 180°/planes） |
| speed | 1 |
扭曲/闪烁速度 |
mgr.add(new MinBIMEffects.FireEffect({ position: [5, 0, 5], height: 4 }));
// 换图：替换 effects/fire/fire.png 后运行 python embed-textures.py，再重新打包
3.14 SmokeEffect — 烟雾
粒子烟柱：上升中尺寸渐大、颜色渐浅、透明度渐散。常叠在 FireEffect 上方。
| 参数 | 默认 | 说明 |
|---|---|---|
| position | [0,0,0] |
烟柱底部中心 |
| height | 6 |
烟柱高度 |
| radius | 0.6 |
底部半径 |
| count | 40 |
粒子数 |
| size | 3 |
粒子尺寸 |
| speed | 0.5 |
上升速度 |
| color | '#666666' |
烟颜色 |
| opacity | 0.5 |
最大不透明度 |
mgr.add(new MinBIMEffects.SmokeEffect({ position: [5, 3, 5], height: 8, opacity: 0.4 }));
3.15 Rainfall — 下雨天
全屏雨幕（屏幕空间 shader，单三角形）——覆盖整个画面、不随相机/缩放变化，三层雨丝视差。无深度遮挡（雨画在模型上方，大屏氛围通用做法）。
| 参数 | 默认 | 说明 |
|---|---|---|
| speed | 1 |
下落速度 |
| slant | 0.15 |
风斜率（雨丝倾斜度） |
| intensity | 1 |
密度（0~2） |
| color | '#aecbe8' |
颜色 |
| opacity | 0.4 |
不透明度 |
mgr.add(new MinBIMEffects.Rainfall({ speed: 1.2, slant: 0.2, intensity: 1.2 }));
3.16 Snowfall — 下雪天
全屏飘雪（屏幕空间 shader，单三角形）——三层雪花视差（近大快、远小慢）+ 摇摆。同样无深度遮挡。
| 参数 | 默认 | 说明 |
|---|---|---|
| speed | 1 |
飘落速度 |
| size | 1 |
雪花尺寸倍数 |
| intensity | 1 |
密度（0~2） |
| color | '#ffffff' |
颜色 |
| opacity | 0.85 |
不透明度 |
mgr.add(new MinBIMEffects.Snowfall({ speed: 0.8, size: 1.2 }));
3.17 GlowEffect — 辉光
让构件（如路灯）发光，或在纯定位点放光晕。两种形态可叠加：
- shell — 克隆构件几何 + 菲涅尔边缘发光（贴合轮廓，支持 InstancedMesh），需要构件
- halo — 径向渐变光晕精灵（点光源发光感），只需要位置
| 参数 | 默认 | 说明 |
|---|---|---|
| target | — | 目标 Object3D（优先） |
| name | — | 构件名字（viewer.models 中查找） |
| position | — | 定位点 [x,y,z]（无构件时的 halo 位置） |
| size | 2 |
halo 半径（世界单位，仅纯点位模式） |
| mode | 按入参推断 | 'shell' | 'halo' | 'both'；有构件默认 shell，纯点位默认 halo |
| color | '#ffcc66' |
颜色 |
| intensity | 1.2 |
发光强度 |
| power | 2.5 |
菲涅尔锐度（越大光越收向轮廓） |
| haloScale | 2.5 |
halo 尺寸倍数（包围球半径 × haloScale，仅构件模式） |
| pulse | true |
呼吸闪烁 |
mgr.add(new MinBIMEffects.GlowEffect({ name: '路灯', mode: 'both', color: '#ffcc66' })); // 构件
mgr.add(new MinBIMEffects.GlowEffect({ position: [10, 5, 10], size: 3 })); // 纯定位点
注意：shell 按世界矩阵快照定位，构件之后再做 explode/位移辉光不跟随（重建即可）。
3.18 HeatMap — 空间热力图
水平面上渲染热力分布（人流密度/温度/设备热度等），高斯衰减累加 + 色带映射。默认纯静态（不触发逐帧渲染）。
| 参数 | 默认 | 说明 |
|---|---|---|
| points | [] |
热力点 {x,y,z,value} 或 [x,y,z,value]，value 为强度（上限 64 个，超出截断） |
| width / depth | 按点云包围盒 + 2×radius 边距 | 平面宽/深 |
| radius | max(width,depth)/8 | 每个点的影响半径 |
| maxValue | 自动取最大 value | 归一化上限 |
| height | 点 y 平均值 | 平面离地高度 |
| opacity | 1 |
不透明度 |
| gradient | 蓝→青→绿→黄→红 | 色带颜色数组（2~8 个） |
| pulse | false |
呼吸闪烁 |
方法：setPoints(points) 运行期更新热力点（不改平面尺寸，自动重算 maxValue 并补渲一帧）。
const hm = new MinBIMEffects.HeatMap({
points: [[0,0,0,10], [15,0,8,25], { x:-10, y:0, z:12, value:40 }],
radius: 8, opacity: 0.9,
});
mgr.add(hm);
hm.setPoints([[5,0,5,80], [20,0,0,15]]); // 运行期更新
4 组合建议
- 重点点位标记：
PulseRing+SpinRing+LightPillar叠加（同 position） - 火灾告警：
FireEffect+SmokeEffect（烟的 position 抬高到火焰顶部）+RegionPulse（地面红区） - 巡检：
RouteFly飞行 + 沿途PoiMarker
5 版本历史
v1.0（2026年10月18日）
- 整理首个独立接口文档版本，覆盖特效管理器、基类及 18 个特效类。
6 版权声明
本文档及其中内容为 魔兜（济南）数字科技有限公司 所有，公开用于产品评估及授权项目开发，未经许可不得转载或用于其他商业用途。