u-space 0.0.26 → 0.0.28

package/dist/plugins/u-manager/instances/SemanticInstanceObject.d.ts

@@ -0,0 +1,37 @@
+import { Box3, Color, Object3D, type ColorRepresentation } from 'three/webgpu';
+import { BaseGroup } from 'u-space';
+export interface SemanticInstanceStyle {
+    color: Color | null;
+    colorMode: number;
+    opacity: number;
+}
+export interface SemanticInstanceObjectOptions {
+    boundsName?: string;
+}
+export declare const SEMANTIC_COLOR_MODE_NONE = 0;
+export declare const SEMANTIC_COLOR_MODE_OVERRIDE = 1;
+export declare const SEMANTIC_COLOR_MODE_TINT = 2;
+export declare class SemanticInstanceObject extends BaseGroup {
+    #private;
+    isSemanticInstanceObject: boolean;
+    type: string;
+    constructor(options?: SemanticInstanceObjectOptions);
+    setSemanticBounds(bounds: Box3): this;
+    setSemanticRenderObject(object: Object3D | null): this;
+    getSemanticRenderObject(): Object3D<import("three").Object3DEventMap> | null;
+    getSemanticBoundingBox(target?: Box3, world?: boolean): Box3;
+    setSemanticVisible(visible: boolean): this;
+    setSemanticColor(color: ColorRepresentation): this;
+    resetSemanticColor(): this;
+    setSemanticOpacity(opacity: number): this;
+    getSemanticColor(target?: Color): Color;
+    hasSemanticColor(): boolean;
+    getSemanticOpacity(): number;
+    setSemanticHighlight(color: ColorRepresentation, opacity: number, overwrite?: boolean): this;
+    clearSemanticHighlight(): this;
+    getSemanticColorMode(): number;
+    onSemanticRenderDirty(callback: () => void): () => boolean;
+    markSemanticRenderDirty(): this;
+    updateMatrixWorld(force?: boolean): void;
+}
+export declare function isSemanticInstanceObject(object: Object3D): object is SemanticInstanceObject;

package/dist/plugins/u-manager/instances/SemanticModelInstancedLayer.d.ts

@@ -0,0 +1,33 @@
+import { Object3D } from 'three/webgpu';
+import { BaseGroup } from 'u-space';
+import { SemanticInstanceObject } from './SemanticInstanceObject';
+export interface SemanticInstanceCullingOptions {
+    enabled?: boolean;
+    frustum?: boolean;
+    minScreenRadius?: number;
+}
+export interface SemanticModelInstancedLayerOptions<T extends SemanticInstanceObject> {
+    name?: string;
+    getBatchUserData?: (url: string, instances: T[]) => Record<string, unknown>;
+    getHitUserData?: (instance: T, renderIndex: number) => Record<string, unknown>;
+}
+export declare class SemanticModelInstancedLayer<T extends SemanticInstanceObject = SemanticInstanceObject> extends BaseGroup {
+    #private;
+    isSemanticModelInstancedLayer: boolean;
+    type: string;
+    constructor(options?: SemanticModelInstancedLayerOptions<T>);
+    getSemanticInstances(): T[];
+    getInstanceCulling(): {
+        enabled: boolean;
+        frustum: boolean;
+        minScreenRadius: number;
+    };
+    setInstanceCulling(options?: SemanticInstanceCullingOptions): this;
+    setSemanticVisible(visible: boolean): this;
+    setSemanticColor(color: Parameters<SemanticInstanceObject['setSemanticColor']>[0]): this;
+    resetSemanticColor(): this;
+    setSemanticOpacity(opacity: number): this;
+    setSemanticHighlight(color: Parameters<SemanticInstanceObject['setSemanticHighlight']>[0], opacity: number, overwrite?: boolean): this;
+    clearSemanticHighlight(): this;
+    addSemanticBatch(url: string, template: Object3D, instances: T[]): boolean;
+}

package/dist/plugins/u-manager/instances/index.d.ts

@@ -0,0 +1,2 @@
+export * from './SemanticInstanceObject';
+export * from './SemanticModelInstancedLayer';

package/dist/plugins/u-manager/loaders/SceneInstancedLayer.d.ts

@@ -0,0 +1,13 @@
+import type { Object3D } from 'three/webgpu';
+import { SemanticInstanceObject, SemanticModelInstancedLayer } from '../instances';
+export declare class SceneInstanceObject extends SemanticInstanceObject {
+    isSceneInstanceObject: boolean;
+    type: string;
+    constructor();
+}
+export declare class SceneInstancedLayer extends SemanticModelInstancedLayer<SceneInstanceObject> {
+    isSceneInstancedLayer: boolean;
+    type: string;
+    constructor();
+}
+export type SceneInstanceReference = SceneInstanceObject | Object3D;

package/dist/plugins/u-manager/loaders/SceneLoader.d.ts

@@ -1,9 +1,7 @@
 import { Group, Loader } from 'three/webgpu';
-import { type Viewer } from 'u-space';
+import { Model, type Viewer } from 'u-space';
 import type { ITreeData } from '../types';
-export interface SceneLoaderOptions {
-}
-export declare class SceneLoader extends Loader<unknown, SceneLoaderOptions> {
+export declare class SceneLoader extends Loader {
     #private;
     viewer: Viewer;
     key: string;
@@ -12,13 +10,15 @@ export declare class SceneLoader extends Loader<unknown, SceneLoaderOptions> {
     protected _treeData: ITreeData[];
     constructor(viewer: Viewer);
     setKey(key: string): this;
+    protected loadModel(url: string): Promise<Model>;
     protected _preareTreeData(): Promise<void>;
+    protected _prepareSemanticIds(): Promise<ReadonlySet<string>>;
     /**
      * 加载场景
      * @param options
      * @returns
      */
-    loadAsync(options?: SceneLoaderOptions): Promise<Group>;
+    loadAsync(): Promise<Group>;
     clearCache(): void;
     dispose(): void;
 }

package/dist/plugins/u-manager/loaders/UManagerLoader.d.ts

@@ -0,0 +1,24 @@
+import { Loader, type Group } from 'three/webgpu';
+import { BaseGroup, type Viewer } from 'u-space';
+import { SceneLoader } from './SceneLoader';
+import { SemanticLoader } from '../semantics/SemanticLoader';
+import type { SemanticGroup } from '../semantics';
+export declare class UManagerSceneGroup extends BaseGroup {
+    isUManagerSceneGroup: boolean;
+    type: string;
+    semanticGroup: SemanticGroup;
+    sceneGroup: Group;
+    constructor(semanticGroup: SemanticGroup, sceneGroup: Group);
+}
+export declare class UManagerLoader extends Loader {
+    #private;
+    viewer: Viewer;
+    key: string;
+    sceneLoader: SceneLoader;
+    semanticLoader: SemanticLoader;
+    constructor(viewer: Viewer);
+    setKey(key: string): this;
+    loadAsync(): Promise<UManagerSceneGroup>;
+    clearCache(): void;
+    dispose(): void;
+}

package/dist/plugins/u-manager/semantics/SemanticLoader.d.ts

@@ -1,6 +1,6 @@
 import { Loader } from 'three/webgpu';
 import type { Viewer } from 'u-space';
-import { SemanticSceneGroup } from './objects/SemanticSceneGroup';
+import { SemanticGroup } from './objects/SemanticGroup';
 export declare class SemanticLoader extends Loader {
     #private;
     viewer: Viewer;
@@ -8,7 +8,7 @@ export declare class SemanticLoader extends Loader {
     cachedIds: Set<string>;
     constructor(viewer: Viewer);
     setKey(key: string): this;
-    loadAsync(): Promise<SemanticSceneGroup>;
+    loadAsync(): Promise<SemanticGroup>;
     clearCache(): void;
     dispose(): void;
 }

package/dist/plugins/u-manager/semantics/SemanticParser.d.ts

@@ -1,5 +1,5 @@
 import { type LoadingManager, type Object3D } from 'three/webgpu';
-import { SemanticSceneGroup } from './objects/SemanticSceneGroup';
+import { SemanticGroup } from './objects/SemanticGroup';
 import type { SemanticObject } from './semantic.types';
 import type { ITreeData } from '../types';
 export interface SemanticParserOptions {
@@ -10,6 +10,6 @@ export interface SemanticParserOptions {
 }
 export declare class SemanticParser {
     #private;
-    parse(semanticData: SemanticObject): SemanticSceneGroup;
-    parseAsync(semanticData: SemanticObject, options?: SemanticParserOptions): Promise<SemanticSceneGroup>;
+    parse(semanticData: SemanticObject): SemanticGroup;
+    parseAsync(semanticData: SemanticObject, options?: SemanticParserOptions): Promise<SemanticGroup>;
 }

package/dist/plugins/u-manager/semantics/index.d.ts

@@ -5,7 +5,7 @@ export * from './objects/VerticalShaftMesh';
 export * from './objects/ElevatorMesh';
 export * from './objects/VentMesh';
 export * from './objects/BuildingGroup';
-export * from './objects/SemanticSceneGroup';
+export * from './objects/SemanticGroup';
 export * from './objects/FacilityInstancedLayer';
 export * from './SemanticParser';
 export * from './SemanticLoader';

package/dist/plugins/u-manager/semantics/objects/BuildingGroup.d.ts

@@ -1,10 +1,10 @@
-import type { ColorRepresentation, Object3D } from 'three/webgpu';
 import { BaseGroup } from 'u-space';
 import type { ElevatorMesh } from './ElevatorMesh';
 import type { FloorMesh, FloorSemanticKind } from './FloorMesh';
 import type { VentMesh } from './VentMesh';
+import type { SemanticInstanceObject } from '../../instances';
 export type BuildingFloorReference = FloorMesh | number;
-export type BuildingFacilityReference = Object3D | string;
+export type BuildingFacilityReference = SemanticInstanceObject | string;
 export declare class BuildingGroup extends BaseGroup {
     #private;
     isBuildingGroup: boolean;
@@ -31,17 +31,11 @@ export declare class BuildingGroup extends BaseGroup {
     showAllFloors(): this;
     showAllFacilities(): this;
     hideAllFacilities(): this;
-    getFacilityById(id: string): Object3D<import("three").Object3DEventMap> | undefined;
-    setFacilityVisible(facility: BuildingFacilityReference, visible: boolean): this;
-    showFacility(facility: BuildingFacilityReference): this;
-    hideFacility(facility: BuildingFacilityReference): this;
-    setFacilityColor(facility: BuildingFacilityReference, color: ColorRepresentation): this;
-    resetFacilityColor(facility: BuildingFacilityReference): this;
-    setFacilityOpacity(facility: BuildingFacilityReference, opacity: number): this;
+    getFacilityById(id: string): SemanticInstanceObject | undefined;
     syncFacilityIndexes(): this;
     get facilityIndexVersion(): number;
     getFacilityIndexIds(): MapIterator<string>;
-    getFacilityIndexObjects(): MapIterator<Object3D<import("three").Object3DEventMap>>;
+    getFacilityIndexObjects(): MapIterator<SemanticInstanceObject>;
     planishFloors(kind?: FloorSemanticKind): this;
     unplanishFloors(kind?: FloorSemanticKind): this;
 }

package/dist/plugins/u-manager/semantics/objects/FacilityInstancedLayer.d.ts

@@ -1,31 +1,12 @@
-import { Box3, Color, Group, Object3D, type ColorRepresentation } from 'three/webgpu';
-import { BaseGroup } from 'u-space';
-export declare class FacilityInstanceObject extends Group {
-    #private;
+import { SemanticInstanceObject, SemanticModelInstancedLayer, type SemanticInstanceCullingOptions } from '../../instances';
+export declare class FacilityInstanceObject extends SemanticInstanceObject {
     isFacilityInstanceObject: boolean;
     type: string;
-    setLocalBounds(bounds: Box3): this;
-    getFacilityBoundingBox(target?: Box3, world?: boolean): Box3;
-    setFacilityVisible(visible: boolean): this;
-    setFacilityColor(color: ColorRepresentation): this;
-    resetFacilityColor(): this;
-    setFacilityOpacity(opacity: number): this;
-    getFacilityColor(target?: Color): Color;
-    hasFacilityColor(): boolean;
-    getFacilityOpacity(): number;
+    constructor();
 }
-export declare class FacilityInstancedLayer extends BaseGroup {
-    #private;
+export declare class FacilityInstancedLayer extends SemanticModelInstancedLayer<FacilityInstanceObject> {
     isFacilityInstancedLayer: boolean;
     type: string;
-    /** @deprecated No effect; facility culling uses per-instance bounding-box frustum tests only. */
-    cameraDistanceCulling: boolean;
-    /** @deprecated No effect; facility culling uses per-instance bounding-box frustum tests only. */
-    cameraCullDistance: number;
-    /** @deprecated No effect; facility culling uses per-instance bounding-box frustum tests only. */
-    cameraCullOverviewFactor: number;
-    /** @deprecated No effect; facility culling uses per-instance bounding-box frustum tests only. */
-    cameraCullPlanViewThreshold: number;
     constructor();
-    addFacilityBatch(url: string, template: Object3D, facilities: FacilityInstanceObject[]): boolean;
 }
+export type FacilityInstanceCullingOptions = SemanticInstanceCullingOptions;

package/dist/plugins/u-manager/semantics/objects/FloorMesh.d.ts

@@ -1,7 +1,8 @@
 import { Box3, BufferGeometry, Matrix4, MeshStandardNodeMaterial, Sphere, Vector3, Vector4, type ColorRepresentation, type Intersection, type Object3D, type Raycaster } from 'three/webgpu';
 import { BaseMesh, type InteractionEvent, type InteractionEventMap } from 'u-space';
 import type { SemanticColor, SemanticGeometryEntry, SemanticKind } from '../types';
-type FacilityReference = Object3D | string;
+import { SemanticInstanceObject } from '../../instances';
+type FacilityReference = SemanticInstanceObject | string;
 type FacilitySemanticKind = 'Facilities';
 type FloorMeshMaterial = MeshStandardNodeMaterial | MeshStandardNodeMaterial[];
 export type FloorSemanticKind = SemanticKind | FacilitySemanticKind;
@@ -11,6 +12,7 @@ export interface FloorGeometrySemanticEntity {
     id: string;
     name?: string;
     index: number;
+    object: FloorSemanticInstanceObject;
 }
 export interface FloorFacilitySemanticEntity {
     type: 'object';
@@ -18,7 +20,7 @@ export interface FloorFacilitySemanticEntity {
     id: string;
     name?: string;
     index: number;
-    object: Object3D;
+    object: SemanticInstanceObject;
     aliases: string[];
 }
 export type FloorSemanticEntity = FloorGeometrySemanticEntity | FloorFacilitySemanticEntity;
@@ -33,7 +35,8 @@ export interface FloorMeshIntersection extends Intersection<Object3D> {
     semanticName?: string;
     semanticIndex: number;
     instanceId: number;
-    facility?: Object3D;
+    semanticObject?: SemanticInstanceObject;
+    facility?: SemanticInstanceObject;
     facilityId?: string;
 }
 export type FloorMeshInteractionEvent = Omit<InteractionEvent, 'target' | 'currentTarget' | 'intersect'> & {
@@ -44,6 +47,22 @@ export type FloorMeshInteractionEvent = Omit<InteractionEvent, 'target' | 'curre
 export type FloorMeshEventMap = {
     [K in keyof InteractionEventMap]: FloorMeshEventPayload<InteractionEventMap[K]>;
 };
+export declare class FloorSemanticInstanceObject extends SemanticInstanceObject {
+    #private;
+    isFloorSemanticInstanceObject: boolean;
+    type: string;
+    readonly floorMesh: FloorMesh;
+    readonly semanticIndex: number;
+    constructor(floorMesh: FloorMesh, semanticIndex: number);
+    setSemanticVisible(visible: boolean): this;
+    setSemanticColor(color: ColorRepresentation): this;
+    resetSemanticColor(): this;
+    setSemanticOpacity(opacity: number): this;
+    getSemanticOpacity(): number;
+    setSemanticHighlight(color: ColorRepresentation, opacity: number, overwrite?: boolean): this;
+    clearSemanticHighlight(): this;
+    getSemanticBoundingBox(target?: Box3, world?: boolean): Box3;
+}
 export declare class FloorMesh extends BaseMesh<BufferGeometry, FloorMeshMaterial, FloorMeshEventMap> {
     #private;
     isFloorMergedSemanticMesh: boolean;
@@ -59,8 +78,8 @@ export declare class FloorMesh extends BaseMesh<BufferGeometry, FloorMeshMateria
     staircasesInstances: Map<string, number>;
     semanticInstances: Map<string, number>;
     semanticEntities: Map<string, FloorSemanticEntity>;
-    facilityObjectsById: Map<string, Object3D>;
-    facilityObjects: Object3D[];
+    facilityObjectsById: Map<string, SemanticInstanceObject>;
+    facilityObjects: SemanticInstanceObject[];
     facilityIndexVersion: number;
     constructor(entries: SemanticGeometryEntry[]);
     planish(kind?: FloorSemanticKind): this;
@@ -74,20 +93,16 @@ export declare class FloorMesh extends BaseMesh<BufferGeometry, FloorMeshMateria
     getSemanticIdAt(index: number): string;
     getSemanticKindAt(index: number): SemanticKind;
     getSemanticNameAt(index: number): string | undefined;
+    getSemanticObjectAt(index: number): FloorSemanticInstanceObject;
     showAllFacilities(): this;
     hideAllFacilities(): this;
-    addFacility(object: Object3D, ids?: string | string[]): this;
-    getFacilityById(id: string): Object3D<import("three").Object3DEventMap> | undefined;
-    getFacilityAt(index: number): Object3D<import("three").Object3DEventMap>;
-    getFacilities(): Object3D<import("three").Object3DEventMap>[];
-    setFacilityVisible(facility: FacilityReference, visible: boolean): this;
-    showFacility(facility: FacilityReference): this;
-    hideFacility(facility: FacilityReference): this;
-    setFacilityColor(facility: FacilityReference, color: ColorRepresentation): this;
-    resetFacilityColor(facility: FacilityReference): this;
-    setFacilityOpacity(facility: FacilityReference, opacity: number): this;
+    addFacility(object: SemanticInstanceObject, ids?: string | string[]): this;
+    getFacilityById(id: string): SemanticInstanceObject | undefined;
+    getFacilityAt(index: number): SemanticInstanceObject;
+    getFacilities(): SemanticInstanceObject[];
     removeFacility(facility: FacilityReference): this;
     setColorAt(index: number, color: SemanticColor): this;
+    resetColorAt(index: number): this;
     getColorAt(index: number, target?: Vector4): Vector4;
     setOpacityAt(index: number, opacity: number): this;
     getOpacityAt(index: number): number;

package/dist/plugins/u-manager/semantics/objects/SemanticGroup.d.ts

@@ -0,0 +1,26 @@
+import { type Object3D } from 'three/webgpu';
+import { BaseGroup } from 'u-space';
+import type { BuildingGroup } from './BuildingGroup';
+import type { FloorMesh, FloorSemanticKind } from './FloorMesh';
+import type { SemanticInstanceObject } from '../../instances';
+export declare class SemanticGroup extends BaseGroup {
+    #private;
+    isSemanticGroup: boolean;
+    type: string;
+    buildings: BuildingGroup[];
+    facilityLayer: Object3D | null;
+    constructor();
+    addBuilding(group: BuildingGroup): this;
+    getBuildingAt(index: number): BuildingGroup;
+    getBuildingById(id: string): BuildingGroup | undefined;
+    getBuildings(): BuildingGroup[];
+    removeBuilding(group: BuildingGroup): this;
+    get floorMeshes(): FloorMesh[];
+    setFacilityLayer(layer: Object3D | null): this;
+    showAllFacilities(): this;
+    hideAllFacilities(): this;
+    getFacilityById(id: string): SemanticInstanceObject | undefined;
+    showAllFloors(): this;
+    planishFloors(kind?: FloorSemanticKind): this;
+    unplanishFloors(kind?: FloorSemanticKind): this;
+}

package/dist/plugins/u-manager/semantics/types.d.ts

@@ -19,6 +19,7 @@ export interface SemanticObjectState {
     matrix: Matrix4;
     finalMatrix: Matrix4;
     geometry: BufferGeometry;
+    initialColor: Vector4;
     color: Vector4;
     visible: boolean;
 }

package/dist/src/effects/MaterialEffects.d.ts

@@ -4,6 +4,7 @@ export interface HighlightColorOptions {
     color?: ColorRepresentation;
     overwrite?: boolean;
     depthWrite?: boolean;
+    multiplyOpacity?: boolean;
 }
 export interface BreatheColorOptions {
     color?: ColorRepresentation;

package/dist/src/tools/AnnotationManager.d.ts

@@ -1,4 +1,7 @@
 import { Line, type Scene, type ColorRepresentation, Group } from 'three/webgpu';
+export type AnnotationLabelStyle = {
+    [K in keyof CSSStyleDeclaration as CSSStyleDeclaration[K] extends string ? K : never]?: CSSStyleDeclaration[K];
+};
 export interface AnnotationOptions {
     /** Position of the annotation anchor in 3D space */
     position: {
@@ -19,7 +22,7 @@ export interface AnnotationOptions {
     /** Leader line color */
     lineColor?: ColorRepresentation;
     /** CSS styles for the label element */
-    labelStyle?: Partial<CSSStyleDeclaration>;
+    labelStyle?: AnnotationLabelStyle;
 }
 export interface Annotation {
     id: string;

package/dist/src/viewers/RenderPipeline.d.ts

@@ -12,8 +12,9 @@ export interface SSGIConfig {
     radius?: number;
     thickness?: number;
 }
-export type OutputNodeComposer = (scenePass: PassNode) => Node;
-export type OutputNodeEffect = ((scenePass: PassNode, inputNode: Node) => Node) & {
+export type ColorOutputNode = Node<'vec4'>;
+export type OutputNodeComposer = (scenePass: PassNode) => ColorOutputNode;
+export type OutputNodeEffect = ((scenePass: PassNode, inputNode: ColorOutputNode) => ColorOutputNode) & {
     includesTemporalAntialias?: boolean;
     includesOutputTransform?: boolean;
 };
@@ -27,11 +28,11 @@ export declare class RenderPipeline extends RenderPipelineBase {
     constructor(...args: Args);
     /** @deprecated Use `scenePass` instead */
     get currentOutputNode(): PassNode;
-    addOverlayPass(pass: Node): void;
-    removeOverlayPass(pass: Node): void;
+    addOverlayPass(pass: ColorOutputNode): void;
+    removeOverlayPass(pass: ColorOutputNode): void;
     setCamera(camera: Camera): void;
     /** @deprecated Use `setOutputComposer` instead */
-    setCurrentOutputNode(node: Node): void;
+    setCurrentOutputNode(node: ColorOutputNode): void;
     /** @deprecated Use `setOutputComposer(null)` instead */
     resetCurrentOutputNode(): void;
     setOutputComposer(composer: OutputNodeComposer | null): void;

package/docs/api-effects.md

@@ -5,6 +5,8 @@
 ## `MaterialEffects`
 
 静态工具类，将基于 TSL 的视觉特效直接应用于对象的材质。适用于任何 `Object3D`（支持单个或数组），会自动遍历所有子网格。
+当对象是 `SemanticInstanceObject`（例如 `SceneInstanceObject`、`FacilityInstanceObject` 或楼层里的 `FloorSemanticInstanceObject`）时，`highlightColor()` / `removeHighlightColor()` 会通过 `setSemanticHighlight()` / `clearSemanticHighlight()` 改写该语义实例的颜色和透明度，而不是改动共享 batch 材质。
+`SemanticInstanceObject` 支持 `overwrite` 的替换/染色语义；`depthWrite` 属于共享 batch 材质状态，不能按单个实例设置，因此对该类对象不会生效。
 
 特性：
 - **效果可叠加**：高亮和呼吸效果可同时作用于同一对象，呼吸在高亮结果之上混合
@@ -48,6 +50,7 @@ MaterialEffects.highlightColor([model1, model2], { color: 0x00ff00 });
 | `opacity`    | `number`              | `0.5`       | 高亮时材质的透明度。                                                         |
 | `overwrite`  | `boolean`             | `false`     | `false` = 与原始颜色相乘（叠加）；`true` = 完全替换颜色。                    |
 | `depthWrite` | `boolean`             | —           | 可选。设为 `false` 可产生 X 光透视效果。不设置时保持原始值。                  |
+| `multiplyOpacity` | `boolean`       | `false`     | 可选。设为 `true` 时高亮透明度会与材质原始透明度相乘，主要用于语义 fallback 模型内部。 |
 
 ### `MaterialEffects.removeHighlightColor(object)`
 

package/docs/api-interactions.md

@@ -16,6 +16,7 @@ viewer.interactionManager.pointerMoveEventsEnabled = true;
 ### 目标对象
 
 可以限制射线检测所针对的对象范围。默认值为 `scene.children`（即整个场景的直接子级，含递归嵌套）。
+`BaseMesh` / `BaseGroup` 默认会在自身 `visible === false` 时让 `raycast()` 返回 `false`，从而阻止自身和子级继续参与递归射线检测；如需隐藏但仍可交互，可将对象的 `ignoreInvisibleWhenRaycast` 设为 `false`。`setInteractable(object, false)` / `addIgnore(object)` 会在命中后过滤该对象及其子对象。
 
 ```typescript
 // 仅检测指定对象

package/docs/api-managers.md

@@ -129,7 +129,7 @@ viewer.objectManager.showAll();
 
 #### `setOpacity(id: string, opacity: number)`
 
-设置指定对象所有材质的透明度。
+设置指定对象所有材质的透明度。对于 `SemanticInstanceObject`（例如 `SceneInstanceObject`、`FacilityInstanceObject` 或 `FloorSemanticInstanceObject`），会调用 `setSemanticOpacity()` 写入该实例的透明度，而不会影响同一模型 path 或同一楼层内的其他实例。
 
 ```typescript
 viewer.objectManager.setOpacity('building-01', 0.3);