name	minemap-billboard
description	MineMap 3D 公告板（Billboard）专题。覆盖 BillboardMaterial / BillboardGeometry / BillboardInstance 动画、拾取高亮、动态纹理更新与轨迹对象联动；不与 DOM 覆盖物 Marker 混淆。

MineMap Billboard（3D 公告板）

概述

MineMap 的 Billboard 是面向 3D 场景的 Primitive 体系下的公告板，不是 DOM 覆盖物。

DOM 标注用 minemap.Marker / minemap.Popup（见 minemap-marker-and-popup）
3D 公告板用 minemap.BillboardMaterial + minemap.Geometries.BillboardGeometry + new minemap.Primitive({...})
大量同形态公告板用 BillboardInstance 场景组件

它和 sprite 图层（addLayer({ type: "sprite" })，见 minemap-layer-system）也不是同一回事：sprite 是 style-layer 路径，billboard 是 Primitive 路径。

Quick Start：单公告板

对应 demo：demo/html/Billboard.html

const material = new minemap.BillboardMaterial({
	position: [116.245, 40.063, 0],
	scale: [1000, 140, 1], // X 宽 / Y 高 / Z 缩放
	center: new minemap.Math.Vector2(0.5, 1), // 锚点 [0..1, 0..1]
	rotation: 0, // 弧度
	image: canvasElement // 或 imageUrl
});

const primitive = new minemap.Primitive({
	id: "billboard-1",
	geometry: new minemap.Geometries.BillboardGeometry({}),
	material
});

map.addPrimitive(primitive);

// 动态更新纹理
setInterval(() => {
	material.image = updateCanvas();
}, 100);

// 移除
map.removePrimitive(primitive);

Quick Start：BillboardInstance 动画

对应 demo：demo/html/BillboardInstanceAnimation.html

BillboardInstance 是同一形状下"成百上千个公告板"的高效形式（共享几何 + 实例化），典型场景是车辆 / 人员 / 设备实时位置。

const material = new minemap.BillboardMaterial({
	position: [119.447, 32.176, 0],
	scale: [800, 200, 1],
	center: new minemap.Math.Vector2(0.5, 1),
	rotation: 0,
	image: carIconImage
});

const geometry = new minemap.Geometries.BillboardGeometry({});

const billboardInstance = new minemap.BillboardInstance({
	name: "vehicles",
	geometry,
	material
});

// 通过 addInstance / setInstances 注入每个公告板的位置 / 状态
billboardInstance.addInstance({
	id: "car-1",
	position: [119.45, 32.18, 0],
	color: minemap.Color.WHITE.clone()
});

map.addPrimitive(billboardInstance);

`BillboardMaterial` 公开参数

参数	说明
`position`	经纬度+高度 `[lng, lat, alt]`
`scale`	`[X, Y, Z]`，X / Y 是世界米，Z 是缩放
`center`	`Vector2`，锚点 [0..1, 0..1]
`rotation`	弧度
`image`	`HTMLCanvasElement` / `HTMLImageElement`
`imageUrl`	与 `image` 二选一；URL 形式
`flipY`	翻转纹理 Y（参考 WebGL 纹理属性）
`color`	`Vector4` (r, g, b, a) 颜色板

image 是元素，imageUrl 是路径。material.image = newCanvas 可以热替换纹理。

`BillboardGeometry`

new minemap.Geometries.BillboardGeometry({}) 不需要参数，公告板形状由 BillboardMaterial.scale / center 决定。

`BillboardInstance` 关键行为

来源：demo BillboardInstanceAnimation.html 注释

拾取高亮：

billboardInstance.color = new minemap.Color(1.0, 0.0, 0.0, 0.3);

动画回调：

billboardInstance.animationCallbackFunction = (instance) => {
	// 每帧拿 instance.position / instance.color 等
};

记录动画位置（用于绘制实时轨迹）：

billboardInstance.recordAnimationPositions = true;
const track = billboardInstance.animationPositions; // 数组

取消高亮 / 复位：

selectedBillboard.color = originalColor;
selectedBillboard.animationCallbackFunction = null;
selectedBillboard.recordAnimationPositions = false;

Architecture Positioning

单公告板 = BillboardMaterial + BillboardGeometry + Primitive（最小单元）
实例化公告板 = BillboardInstance（场景组件，复用 BillboardMaterial + BillboardGeometry）
DOM 标注 = Marker / Popup（不在 Primitive 体系内，不参与 3D 深度）
sprite style-layer = addLayer({ type: "sprite" })（贴地线 / 流动线，业务上不冲突）

Common Patterns

模式 1：实时数据画板（数字 / 面积 / 评分）

对应 demo：Billboard.html

Canvas 画板按需重画
material.image = canvas 热替换
不重建 Primitive，不重建 Material，性能可控

模式 2：车辆 / 人员实时位置

对应 demo：BillboardInstanceAnimation.html

用 BillboardInstance 一次性放成百上千个图标
animationCallbackFunction 拿当前位置画圆形波纹 / 轨迹 / popup
recordAnimationPositions = true 开轨迹记录

模式 3：拾取 + 高亮

map.on("click", (e) => {
	const picked = map.pickPrimitive(e.point);
	if (picked && picked.primitive === billboardInstance) {
		const instance = picked.detail; // instance 句柄
		// 高亮 / 弹窗
	}
});

Strict Constraints

1. 别把 Billboard 当成 Marker

BillboardMaterial 是 3D Primitive，会参与 depth-test，会被遮挡
Marker 是 DOM，永远在最上层
业务上要"在 3D 场景里被建筑挡住"用 Billboard；"始终显示"用 Marker

2. `image` vs `imageUrl` 二选一

两者都传会冲突，源码会优先 image。

3. `scale` 是世界米

不要把它当作像素。scale: [800, 200, 1] 表示宽 800 米、高 200 米；缩放级别变化时看起来会更近 / 更远，这是正常的。

4. `recordAnimationPositions` 会持续累积

长时间开动画会越积越多，业务上要么在合适时机 recordAnimationPositions = false，要么定期清。

5. `BillboardInstance` 拾取粒度

拾取到的是整个实例集合，再 picked.detail 拿具体 instance；不要在每个 instance 上挂 onClick。

Failure Cases

公告板不显示 → image / imageUrl 没加载完；或 position 高度低于地形被裁
公告板太大 / 太小 → scale 单位是米，不是像素
公告板永远在前面 → 误用了 Marker / Popup 路径
实例化公告板全部是同一个色 → 高亮 color 设错了字段（要在 instance 上而不是 material 上）
动画位置空 → 没设 recordAnimationPositions = true 或 animationCallbackFunction 之前就已经访问 animationPositions

Demo References

demo/html/Billboard.html：单公告板 + Canvas 实时画板
demo/html/BillboardInstanceAnimation.html：车辆 / 设备级 BillboardInstance 动画 + 拾取 + 轨迹

minemap-billboard

同仓库更多 Skills