Interface: ModelManager

Defined in: packages/viewer-core/src/public/managers/ModelManager.ts:101

模型加载与节点级外观控制 manager。

职责域:.fmbv 模型的加载 / 卸载、包围盒与结构树元数据查询 (getNodeInfo / iterateNodes / findNodesByName)、节点与面组的 颜色 / 可见性 / 高亮覆盖。典型入口:load() 加载模型,随后经 getRootNodeId() 遍历结构树,用 setNodesColor() / setNodesVisibility() 调整外观。

Remarks

经 Viewer 实例上的 viewer.model 访问,不要直接构造。

Accessors

isLoaded

Get Signature

get isLoaded(): boolean

Defined in: packages/viewer-core/src/public/managers/ModelManager.ts:130

当前是否已有模型加载完成(骨架就绪即为 true)。

Returns

boolean

---

loadProgress

Get Signature

get loadProgress(): object

Defined in: packages/viewer-core/src/public/managers/ModelManager.ts:136

当前加载进度快照:skeleton 骨架是否就绪、geomReady/geomTotal 几何 LOD 分块的已到达数 / 总数。

Returns

object

geomReady

geomReady: number

geomTotal

geomTotal: number

skeleton

skeleton: boolean

Methods

_advanceAppearanceAnimation()

_advanceAppearanceAnimation(nowMs): boolean

Defined in: packages/viewer-core/src/public/managers/ModelManager.ts:744

RenderLoop 接线：推进外观渐变一帧；finish 时广播一次 animated 事件。 返回本帧过后渐变是否仍未结束（RenderScheduler 的 animating 信号源）。

Parameters

nowMs

number

Returns

boolean

---

animateAppearance()

animateAppearance(target, durationMs?): void

Defined in: packages/viewer-core/src/public/managers/ModelManager.ts:735

视图切换：把外观从当前态渐变到 target（record-free）。

Parameters

target

AppearanceTarget

durationMs?

number

Returns

void

---

applyStructureBlock()

applyStructureBlock(block): void

Defined in: packages/viewer-core/src/public/managers/ModelManager.ts:235

应用持久化结构块(load-time seed / sidecar 回放):覆盖 overlay 状态、 隐藏所有(直接或经祖先)被删的叶子实例、重算整模型总量,并广播一次 structure-changed{change:"apply"}(订阅方全量重建、忽略 affected)。 未加载时静默返回。

Parameters

block

StructureBlock

Returns

void

---

beginAppearanceEdit()

beginAppearanceEdit(ids): void

Defined in: packages/viewer-core/src/public/managers/ModelManager.ts:680

开始一次实时拖拽外观编辑（e.g. 颜色/表面滑块拖动）。 快照 ids 的当前外观作为 before 状态；后续调用 inputAppearance 实时更新（不记录历史）； commitAppearanceEdit 结束时将整次拖拽作为一步压入撤销历史。

Parameters

ids

readonly NodeId[]

Returns

void

---

commitAppearanceEdit()

commitAppearanceEdit(): void

Defined in: packages/viewer-core/src/public/managers/ModelManager.ts:711

提交一次外观拖拽：对比 beginAppearanceEdit 时的快照与当前状态， 将净变化作为一步压入共享撤销历史（整次拖拽合并为一步，一次 undo 回到拖拽前）。 提交后触发一次 appearance-changed 事件供 Inspector 同步最终状态。

Returns

void

---

deleteNodes()

deleteNodes(ids): void

Defined in: packages/viewer-core/src/public/managers/ModelManager.ts:1036

逻辑删除一组节点(含子树):收集有效叶子、静默剪除其序号标签、隐藏几何, 作为一条 doc-level 步压入共享撤销历史(viewId=null,跨视图恒删)。

Parameters

ids

readonly NodeId[]

Returns

void

---

exportStructureBlock()

exportStructureBlock(): StructureBlock

Defined in: packages/viewer-core/src/public/managers/ModelManager.ts:250

导出当前结构编辑(逻辑删除 + 合并)为持久化块;未加载 / 无 overlay → 空块。

Returns

StructureBlock

---

findNodesByName()

findNodesByName(name): readonly NodeId[]

Defined in: packages/viewer-core/src/public/managers/ModelManager.ts:451

按名称精确匹配查找节点(同名节点全部返回);无匹配或未加载返回空数组。

Parameters

name

string

Returns

readonly NodeId[]

---

finishAppearanceAnimation()

finishAppearanceAnimation(): void

Defined in: packages/viewer-core/src/public/managers/ModelManager.ts:753

settle 当前外观渐变到目标（捕快照前调用）。

Returns

void

---

getBoundingBox()

getBoundingBox(): Box3 | null

Defined in: packages/viewer-core/src/public/managers/ModelManager.ts:363

取整个模型的世界坐标轴对齐包围盒;未加载返回 null。

Returns

Box3 | null

---

getBoundingSphere()

getBoundingSphere(): BoundingSphere | null

Defined in: packages/viewer-core/src/public/managers/ModelManager.ts:369

取由包围盒推导的模型包围球(球心 = 盒中心,半径 = 到角点距离);未加载返回 null。

Returns

BoundingSphere | null

---

getFaceGroupAppearance()

getFaceGroupAppearance(id, fg): object

Defined in: packages/viewer-core/src/public/managers/ModelManager.ts:627

取单个面组当前的外观（颜色 / 表面材质 / 预设）；未设置通道返回 null；未加载时返回全 null。

Parameters

id

NodeId

fg

FaceGroupId

Returns

object

color

color: Color | null

presetId

presetId: string | null

surface

surface: SurfaceOverride | null

---

getFaceGroupColor()

getFaceGroupColor(id, fg): Color | null

Defined in: packages/viewer-core/src/public/managers/ModelManager.ts:569

取面组当前的覆盖颜色;未设置过返回 null。

Parameters

id

NodeId

fg

FaceGroupId

Returns

Color | null

---

getFaceGroupCount()

getFaceGroupCount(id): number

Defined in: packages/viewer-core/src/public/managers/ModelManager.ts:575

取节点所在 mesh 的面组数量(可染色的面组索引为 0..count-1);未加载 / 无网格返回 0。

Parameters

id

NodeId

Returns

number

---

getHighlightedNodeIds()

getHighlightedNodeIds(): readonly NodeId[]

Defined in: packages/viewer-core/src/public/managers/ModelManager.ts:863

取当前处于高亮状态的节点 id 列表;未加载返回空数组。

Returns

readonly NodeId[]

---

getInstancesSharingMesh()

getInstancesSharingMesh(nodeId): NodeId[]

Defined in: packages/viewer-core/src/public/managers/ModelManager.ts:460

取与 nodeId 同 meshId 的全部实例 NodeId（含自身），按 nodeIdx 升序排列。 nodeId 无关联 mesh（装配节点）或未加载时返回 [nodeId]。

Parameters

nodeId

NodeId

Returns

NodeId[]

---

getLeafNodeIds()

getLeafNodeIds(): readonly NodeId[]

Defined in: packages/viewer-core/src/public/managers/ModelManager.ts:439

取全部叶子节点(带几何 meshId 的节点)id 列表;未加载返回空数组。

Returns

readonly NodeId[]

---

getMergeLeafCount()

getMergeLeafCount(root): number | null

Defined in: packages/viewer-core/src/public/managers/ModelManager.ts:933

合并根折叠的叶子数;非合并根 / 未加载 → null。

Parameters

root

NodeId

Returns

number | null

---

getModelTotals()

getModelTotals(): ModelTotals | null

Defined in: packages/viewer-core/src/public/managers/ModelManager.ts:224

取整模型全量几何统计(三角/边线总数,含实例倍数);尚未算好 / 未加载返回 null。

Returns

ModelTotals | null

---

getNodeAppearance()

getNodeAppearance(id): NodeAppearance

Defined in: packages/viewer-core/src/public/managers/ModelManager.ts:670

取节点当前的完整外观（颜色 / 表面材质 / 预设）；未设置通道返回 null；未加载时返回全 null。

Parameters

id

NodeId

Returns

NodeAppearance

---

getNodeColor()

getNodeColor(id): Color | null

Defined in: packages/viewer-core/src/public/managers/ModelManager.ts:550

取节点当前的覆盖颜色;未设置过返回 null。

Parameters

id

NodeId

Returns

Color | null

---

getNodeCount()

getNodeCount(): number

Defined in: packages/viewer-core/src/public/managers/ModelManager.ts:445

结构树节点总数(含装配节点);未加载返回 0。与 .fmbview.json 的签名字段同源。

Returns

number

---

getNodeInfo()

getNodeInfo(id): NodeInfo | null

Defined in: packages/viewer-core/src/public/managers/ModelManager.ts:389

取单个节点的结构信息(名称 / 父子关系 / 包围盒 / meshId 等);id 不存在或未加载返回 null。

Parameters

id

NodeId

Returns

NodeInfo | null

---

getNodeMaterial()

getNodeMaterial(id): MaterialInfo | null

Defined in: packages/viewer-core/src/public/managers/ModelManager.ts:395

取节点关联的材质信息(由 materials payload 解析);无材质或未加载返回 null。

Parameters

id

NodeId

Returns

MaterialInfo | null

---

getNodeOpacity()

getNodeOpacity(_id): number

Defined in: packages/viewer-core/src/public/managers/ModelManager.ts:894

取节点透明度 — v2 前恒返回 1(不透明)。

Parameters

_id

NodeId

Returns

number

---

getNodeProperties()

getNodeProperties(id): Promise<readonly NodeProperty[]>

Defined in: packages/viewer-core/src/public/managers/ModelManager.ts:409

取节点业务属性(按需:首次调用按节点 offset 发一次 range 请求,memoize)。 无属性 / 无 ATTRIBUTES chunk / 未加载 → 返回 []。

Parameters

id

NodeId

Returns

Promise<readonly NodeProperty[]>

---

getNodeVisibility()

getNodeVisibility(id): boolean

Defined in: packages/viewer-core/src/public/managers/ModelManager.ts:844

查询节点当前是否可见;未加载时按默认可见返回 true。

Parameters

id

NodeId

Returns

boolean

---

getRootNodeId()

getRootNodeId(): NodeId | null

Defined in: packages/viewer-core/src/public/managers/ModelManager.ts:383

取结构树根节点 id;未加载返回 null。

Returns

NodeId | null

---

getSubtreeTotals()

getSubtreeTotals(root): Promise<ModelTotals | null>

Defined in: packages/viewer-core/src/public/managers/ModelManager.ts:260

合并 Inspector 聚合口径:对 root 子树内的有效叶子(减去已删除子树)建 meshId 实例直方图,复用 computeModelTotals 读各 mesh 的 LOD-0 头汇总三角/边线总数。 未加载 / root 不存在时返回 null。LOD-0 口径,与整模型总量、删除重算口径一致。

Parameters

root

NodeId

Returns

Promise<ModelTotals | null>

---

inputAppearance()

inputAppearance(patch): void

Defined in: packages/viewer-core/src/public/managers/ModelManager.ts:691

实时应用外观 patch 到 beginAppearanceEdit 指定的节点（不记录历史，不影响撤销栈）。 静默更新引擎属性（viewport 经 rAF 渲染循环自动刷新），不触发 appearance-changed 事件。

Parameters

patch

AppearancePatch

Returns

void

---

isAnimatingAppearance()

isAnimatingAppearance(): boolean

Defined in: packages/viewer-core/src/public/managers/ModelManager.ts:760

Returns

boolean

---

isNodeDeleted()

isNodeDeleted(id): boolean

Defined in: packages/viewer-core/src/public/managers/ModelManager.ts:915

节点是否被逻辑删除(自身或任一祖先在删除集内);未加载 / 无 overlay → false。

Parameters

id

NodeId

Returns

boolean

---

isNodeMerged()

isNodeMerged(id): boolean

Defined in: packages/viewer-core/src/public/managers/ModelManager.ts:921

节点是否是一个已合并折叠根;未加载 / 无 overlay → false。

Parameters

id

NodeId

Returns

boolean

---

isolateNodes()

isolateNodes(ids): void

Defined in: packages/viewer-core/src/public/managers/ModelManager.ts:831

Isolate：恰好显示 ids（装配自动展开为子树），其余叶子隐藏；保留集内 先前隐藏的叶子复显。ids 为空数组时静默 no-op。 实际发生变化时触发 visibility-changed 并入撤销历史。

Parameters

ids

readonly NodeId[]

Returns

void

---

iterateNodes()

iterateNodes(visitor): void

Defined in: packages/viewer-core/src/public/managers/ModelManager.ts:433

自根节点深度优先遍历结构树,对每个节点调用 visitor。 visitor 返回 false 时跳过该节点的子树(剪枝),继续遍历其余分支。

Parameters

visitor

(info) => boolean | void

Returns

void

---

load()

load(source, opts?): Promise<void>

Defined in: packages/viewer-core/src/public/managers/ModelManager.ts:153

加载 .fmbv 模型数据(URL / Uint8Array / Blob / 自定义 fetcher)并开始渐进渲染。

触发 model-loading,骨架(结构树 + 索引)就绪并触发 model-skeleton-ready 后本 Promise resolve;几何 LOD 分块在后台继续流式加载,期间触发 model-geom-progress,全部到达后触发 model-loaded。 再次调用会先卸载当前模型(触发 model-disposed)并取消未完成的旧加载。 失败时抛 ViewerError(InvalidModelSource / NetworkFailed / Cancelled 等)。

Parameters

source

ModelSource

opts?

ModelLoadOptions

Returns

Promise<void>

---

mergeNode()

mergeNode(root): void

Defined in: packages/viewer-core/src/public/managers/ModelManager.ts:1048

把装配折叠为单一零件:成员=该根下有效叶子,作为一条 doc-level 步入栈。

Parameters

root

NodeId

Returns

void

---

mergeRootOf()

mergeRootOf(id): NodeId | null

Defined in: packages/viewer-core/src/public/managers/ModelManager.ts:927

返回 id 的最外层当前合并祖先(折叠头);无则 null。

Parameters

id

NodeId

Returns

NodeId | null

---

resetFaceAppearances()

resetFaceAppearances(): void

Defined in: packages/viewer-core/src/public/managers/ModelManager.ts:593

非记录批量还原：清除所有用户面级外观覆盖（颜色/表面/预设），供 applySnapshot 对称还原，不入撤销历史。

Returns

void

---

resetFaceGroupColors()

resetFaceGroupColors(): void

Defined in: packages/viewer-core/src/public/managers/ModelManager.ts:581

清除所有面组级覆盖颜色。

Returns

void

---

resetHighlight()

resetHighlight(): void

Defined in: packages/viewer-core/src/public/managers/ModelManager.ts:857

清除所有节点高亮。

Returns

void

---

resetNodesColor()

resetNodesColor(): void

Defined in: packages/viewer-core/src/public/managers/ModelManager.ts:514

清除所有节点级覆盖颜色。

Returns

void

---

resetNodesOpacity()

resetNodesOpacity(): void

Defined in: packages/viewer-core/src/public/managers/ModelManager.ts:888

重置节点透明度 — v2 才提供,当前调用必抛 ViewerError。

Returns

void

---

resetNodesPreset()

resetNodesPreset(): void

Defined in: packages/viewer-core/src/public/managers/ModelManager.ts:538

非记录批量还原：清除所有节点预设覆盖（供 applySnapshot 对称还原，不入撤销历史）。

Returns

void

---

resetNodesSurface()

resetNodesSurface(): void

Defined in: packages/viewer-core/src/public/managers/ModelManager.ts:526

非记录批量还原：清除所有节点表面覆盖（供 applySnapshot 对称还原，不入撤销历史）。

Returns

void

---

resetNodesVisibility()

resetNodesVisibility(): void

Defined in: packages/viewer-core/src/public/managers/ModelManager.ts:819

重置所有节点可见性（全部恢复显示）；实际发生变化时触发 visibility-changed 并入撤销历史。

Returns

void

---

restoreFaceAppearances()

restoreFaceAppearances(entries): void

Defined in: packages/viewer-core/src/public/managers/ModelManager.ts:602

非记录批量还原：按 entries 还原每个叶子所在 mesh 的面级覆盖，供 applySnapshot 对称还原，不入撤销历史。 每个 entry 经 applyFaceAppearance（clear-then-set）覆盖该 mesh 的全部面级覆盖。

Parameters

entries

readonly object[]

Returns

void

---

setFaceGroupAppearance()

setFaceGroupAppearance(id, fg, patch): void

Defined in: packages/viewer-core/src/public/managers/ModelManager.ts:615

设置单个面组的外观覆盖（颜色 / 表面材质 / 预设）。 面级覆盖按 (mesh, faceGroup) 存储，同 mesh 的实例共享。 patch 中仅设置的字段生效；缺失字段保持现状；null 值显式清除该通道。 净变化作为一步压入共享撤销历史（撤销时整 mesh 的面级覆盖随节点快照一并还原）。

Parameters

id

NodeId

fg

FaceGroupId

patch

AppearancePatch

Returns

void

---

setFaceGroupColor()

setFaceGroupColor(id, fg, color): void

Defined in: packages/viewer-core/src/public/managers/ModelManager.ts:557

给节点内单个面组设置覆盖颜色(粒度细于节点级染色)。

Parameters

id

NodeId

fg

FaceGroupId

color

Color

Returns

void

---

setHighlightColor()

setHighlightColor(color): void

Defined in: packages/viewer-core/src/public/managers/ModelManager.ts:869

设置高亮染色所用的颜色。

Parameters

color

Color

Returns

void

---

setNodesAppearance()

setNodesAppearance(ids, patch): void

Defined in: packages/viewer-core/src/public/managers/ModelManager.ts:644

批量设置节点外观（颜色 / 表面材质 / 预设）。 patch 中仅设置的字段生效；缺失字段保持现状；null 值显式清除该通道。 设置完成后触发 appearance-changed 事件，并将净变化压入共享撤销历史。

Parameters

ids

readonly NodeId[]

patch

AppearancePatch

Returns

void

---

setNodesColor()

setNodesColor(ids, color): void

Defined in: packages/viewer-core/src/public/managers/ModelManager.ts:496

给一组节点设置覆盖颜色(不改原始材质,可经 unset / reset 撤销);未加载抛 ModelNotLoaded。

Parameters

ids

readonly NodeId[]

color

Color

Returns

void

---

setNodesColors()

setNodesColors(map): void

Defined in: packages/viewer-core/src/public/managers/ModelManager.ts:502

按映射批量设置节点覆盖颜色(每节点各自一色)。

Parameters

map

ReadonlyMap<NodeId, Color>

Returns

void

---

setNodesHighlighted()

setNodesHighlighted(ids, on): void

Defined in: packages/viewer-core/src/public/managers/ModelManager.ts:851

程序化设置一组节点的高亮染色(与交互选中走同一外观高亮通道)。

Parameters

ids

readonly NodeId[]

on

boolean

Returns

void

---

setNodesOpacity()

setNodesOpacity(_ids, _opacity): void

Defined in: packages/viewer-core/src/public/managers/ModelManager.ts:876

节点透明度设置 — v2 才提供,当前调用必抛 ViewerError。

Parameters

_ids

readonly NodeId[]

_opacity

number

Returns

void

---

setNodesPresets()

setNodesPresets(map): void

Defined in: packages/viewer-core/src/public/managers/ModelManager.ts:544

非记录批量还原：按映射设置节点预设覆盖（供 applySnapshot 对称还原，不入撤销历史）。

Parameters

map

ReadonlyMap<NodeId, string>

Returns

void

---

setNodesSurfaces()

setNodesSurfaces(map): void

Defined in: packages/viewer-core/src/public/managers/ModelManager.ts:532

非记录批量还原：按映射设置节点表面覆盖（供 applySnapshot 对称还原，不入撤销历史）。

Parameters

map

ReadonlyMap<NodeId, SurfaceOverride>

Returns

void

---

setNodesVisibility()

setNodesVisibility(ids, visible): void

Defined in: packages/viewer-core/src/public/managers/ModelManager.ts:810

设置一组节点的显示 / 隐藏；实际发生变化时触发 visibility-changed 并入撤销历史。

Parameters

ids

readonly NodeId[]

visible

boolean

Returns

void

---

unload()

unload(): void

Defined in: packages/viewer-core/src/public/managers/ModelManager.ts:206

卸载当前模型并清空场景,触发 model-disposed;未加载时静默返回。

Returns

void

---

unmergeNode()

unmergeNode(root): void

Defined in: packages/viewer-core/src/public/managers/ModelManager.ts:1058

取消合并(展开折叠根):作为一条独立 doc-level 步入栈(不是 merge 的 redo)。

Parameters

root

NodeId

Returns

void

---

unsetFaceGroupColor()

unsetFaceGroupColor(id, fg): void

Defined in: packages/viewer-core/src/public/managers/ModelManager.ts:563

撤销单个面组的覆盖颜色。

Parameters

id

NodeId

fg

FaceGroupId

Returns

void

---

unsetNodesAppearance()

unsetNodesAppearance(ids): void

Defined in: packages/viewer-core/src/public/managers/ModelManager.ts:659

清除一组节点的所有外观覆盖（颜色 / 表面材质 / 预设），触发 appearance-changed 事件，并将净变化压入共享撤销历史。

Parameters

ids

readonly NodeId[]

Returns

void

---

unsetNodesColor()

unsetNodesColor(ids): void

Defined in: packages/viewer-core/src/public/managers/ModelManager.ts:508

撤销指定节点的覆盖颜色,恢复原始材质色。

Parameters

ids

readonly NodeId[]

Returns

void

---

unsetNodesOpacity()

unsetNodesOpacity(_ids): void

Defined in: packages/viewer-core/src/public/managers/ModelManager.ts:882

撤销节点透明度 — v2 才提供,当前调用必抛 ViewerError。

Parameters

_ids

readonly NodeId[]

Returns

void

---

visibleTreeChildren()

visibleTreeChildren(parent): readonly NodeId[]

Defined in: packages/viewer-core/src/public/managers/ModelManager.ts:939

结构树可见直接子节点(跳过已删除;合并根返回 []);无 overlay 时回落 NodeInfo.childrenIds。

Parameters

parent

NodeId

Returns

readonly NodeId[]