Managers API

u-space 使用专用管理器来处理特定领域的逻辑，例如用于缓存和注册 3D 对象的 ObjectManager。

ObjectManager

ObjectManager 提供了一个集中式字典/映射层，让你无需递归遍历 Three.js 场景图，就能通过字符串 ID 或字符串名称轻松检索复杂模型或特定网格。

默认实例可通过 viewer.objectManager 访问。

添加对象

向管理器添加对象时，必须提供唯一标识符。

const myModel = new Model();
// ... 加载逻辑

// 用指定的唯一 ID 添加
viewer.objectManager.add('my-unique-car-id', myModel);

// 一个对象可以注册多个 ID
viewer.objectManager.add('player-vehicle', myModel);

检索对象

管理器提供快速访问对象的方法。

getById(id: string)

精确检索与指定 ID 匹配的一个对象（或 undefined）。

const car = viewer.objectManager.getById('my-unique-car-id');

getByName(name: string)

由于 Three.js 对象可以共享同一个 .name 属性，此方法返回一个 Set<Object3D>，包含所有与指定名称匹配的已注册对象。

// 假设 myModel.name = 'sedan'
const sedans = viewer.objectManager.getByName('sedan');

sedans.forEach((vehicle) => {
  vehicle.position.y += 10;
});

getByType(type: string)

返回一个 Set<Object3D>，包含所有 object.type 与指定类型匹配的已注册对象。

const models = viewer.objectManager.getByType('Model');

getObjectIds(object: Object3D)

返回给定对象已注册的所有 ID 的 Set<string>。

const ids = viewer.objectManager.getObjectIds(myModel);

移除对象

remove(object: Object3D)

从所有内部映射中移除该对象及其所有关联 ID。

viewer.objectManager.remove(myModel);

removeById(id: string)

移除注册在指定 ID 下的对象。

viewer.objectManager.removeById('my-unique-car-id');

removeByName(name: string)

移除所有具有指定 .name 的对象。

viewer.objectManager.removeByName('sedan');

removeByType(type: string)

移除所有具有指定 .type 的对象。

viewer.objectManager.removeByType('Model');

显隐控制

show(id: string) / hide(id: string)

控制对象的可见性。

viewer.objectManager.hide('car-01');
viewer.objectManager.show('car-01');

isolate(ids: string[])

孤立显示：仅显示指定 ID 的对象，隐藏其余所有。

viewer.objectManager.isolate(['car-01', 'car-02']);

showAll()

恢复显示所有已管理对象。

viewer.objectManager.showAll();

材质操作

setOpacity(id: string, opacity: number)

设置指定对象所有材质的透明度。对于 InstanceObject（例如 SceneInstanceObject、FacilityInstanceObject 或 FloorSemanticInstanceObject），会调用 setInstanceOpacity() 写入该实例的透明度，而不会影响同一模型 path 或同一楼层内的其他实例。

viewer.objectManager.setOpacity('building-01', 0.3);
viewer.objectManager.setOpacity('building-01', 1.0); // 恢复不透明

空间查询

getBoundingBox(id?: string)

获取指定对象的包围盒，不传 id 则返回所有已管理对象的包围盒。

const box = viewer.objectManager.getBoundingBox('car-01');
const allBox = viewer.objectManager.getBoundingBox(); // 全部对象

遍历与过滤

forEach(callback)

遍历所有已管理对象。

viewer.objectManager.forEach((object, ids) => {
  console.log(`对象: ${object.name}, IDs: ${Array.from(ids).join(', ')}`);
});

filter(predicate)

按条件过滤对象，返回匹配的数组。

const cars = viewer.objectManager.filter((obj) => obj.name.startsWith('car'));

工具方法

• getAll()：返回所有已跟踪对象的 Set<Object3D>。
• clear()：从所有内部映射中移除所有对象。
• size：返回当前管理器跟踪的唯一对象总数。

---

SceneManager

SceneManager 用于管理多个场景的创建、注册、切换和序列化。

import { SceneManager } from 'u-space';

const sceneManager = new SceneManager();

方法

create(key, options?)

创建并注册一个新场景。

const scene = sceneManager.create('indoor', { background: 0x333333 });

add(key, scene) / get(key) / remove(key)

手动注册、获取或移除场景。

sceneManager.add('outdoor', existingScene);
const scene = sceneManager.get('outdoor');
sceneManager.remove('outdoor');

serialize(key)

将场景元数据序列化为 JSON 快照。

const snapshot = sceneManager.serialize('indoor');
// { name, background, environmentRotation, children }

keys() / size / clear()

列出所有场景 key、获取场景数量或清空。

---

LightManager

LightManager 提供灯光的便捷创建、预设和 Helper 可视化。

import { LightManager } from 'u-space';

const lightManager = new LightManager(viewer.scene);

灯光创建

lightManager.addAmbient('ambient', { color: 0xffffff, intensity: 0.5 });
lightManager.addDirectional('sun', { position: { x: 5, y: 10, z: 5 }, castShadow: true });
lightManager.addPoint('bulb', { position: { x: 0, y: 3, z: 0 }, intensity: 2 });
lightManager.addSpot('spot', { position: { x: 0, y: 10, z: 0 }, angle: Math.PI / 6 });
lightManager.addHemisphere('hemi', { skyColor: 0x87ceeb, groundColor: 0x362907 });

灯光预设

一键应用常见场景的灯光配置：

lightManager.applyPreset('indoor');     // 室内：环境光 + 顶部点光源
lightManager.applyPreset('outdoor');    // 室外：半球光 + 方向光（阳光）
lightManager.applyPreset('studio');     // 摄影棚：三点布光
lightManager.applyPreset('warehouse');  // 仓库：多点光源照明

预设	配置
indoor	环境光 + 2 个点光源
outdoor	半球光 + 方向光（带阴影）
studio	环境光 + 主光 + 补光 + 轮廓光
warehouse	环境光 + 4 个点光源（四角分布）

Helper 可视化

lightManager.showHelper('sun');              // 显示单个灯光 Helper（默认 size=5, color=0xff0000）
lightManager.showHelper('sun', 2, 0x00ff00); // 自定义尺寸和颜色
lightManager.showAllHelpers();               // 显示所有灯光 Helper
lightManager.hideHelper('sun');              // 隐藏单个
lightManager.hideAllHelpers();               // 隐藏所有

showHelper(id, size?, color?)

参数	类型	默认值	说明
id	string	—	灯光 ID。
size	number	5	Helper 尺寸。
color	ColorRepresentation	0xff0000	Helper 颜色。

管理

lightManager.get('sun');     // 获取灯光
lightManager.remove('sun');  // 移除灯光
lightManager.removeAll();    // 移除所有
lightManager.dispose();      // 清理