@thatopen/components 3.2.6 → 3.3.0

package/dist/index.d.ts

@@ -1,7 +1,9 @@
 import CameraControls from 'camera-controls';
 import { DataMap as DataMap_2 } from '@thatopen/fragments';
+import { DataSet as DataSet_2 } from '@thatopen/fragments';
 import * as FRAGS from '@thatopen/fragments';
 import * as THREE from 'three';
+import { TransformControls } from 'three/examples/jsm/controls/TransformControls.js';
 import { Vector2 } from 'three';
 import * as WEBIFC from 'web-ifc';
 import { XMLBuilder } from 'fast-xml-parser';
@@ -289,8 +291,8 @@ export declare class BCFTopics extends Component implements Disposable_2, Config
     static xmlParser: XMLParser;
     protected _defaultConfig: Required<BCFTopicsConfig>;
     config: BCFTopicsConfigManager;
-    readonly list: DataMap<string, Topic>;
-    readonly documents: DataMap<string, InternalDocumentReference | ExternalDocumentReference>;
+    readonly list: DataMap_2<string, Topic>;
+    readonly documents: DataMap_2<string, InternalDocumentReference | ExternalDocumentReference>;
     readonly onSetup: Event_2<unknown>;
     isSetup: boolean;
     setup(config?: Partial<BCFTopicsConfig>): void;
@@ -904,6 +906,7 @@ export declare class Clipper extends Component implements Createable, Disposable
     private _size;
     private _enabled;
     private _visible;
+    readonly onStateChanged: Event_2<("material" | "enabled" | "size" | "visibility")[]>;
     /** {@link Component.enabled} */
     get enabled(): boolean;
     /** {@link Component.enabled} */
@@ -1142,7 +1145,7 @@ export declare class ConfigManager extends Component {
     /**
      * The list of all configurations of this app.
      */
-    list: DataMap<string, Configurator<any, any>>;
+    list: DataMap_2<string, Configurator<any, any>>;
     /** {@link Component.enabled} */
     enabled: boolean;
     /**
@@ -1631,10 +1634,174 @@ export declare interface ExternalDocumentReference extends DocumentReference {
     url: string;
 }
 
+/**
+ * A fast model picker that uses color coding to identify fragment models under the mouse cursor.
+ * This is much faster than raycasting for simple model identification.
+ */
+export declare class FastModelPicker implements Disposable_2 {
+    /** {@link Component.enabled} */
+    enabled: boolean;
+    /** The components instance to which this FastModelPicker belongs. */
+    components: Components;
+    /** {@link Disposable.onDisposed} */
+    readonly onDisposed: Event_2<unknown>;
+    /** The position of the mouse in the screen. */
+    readonly mouse: Mouse;
+    /**
+     * A reference to the world instance to which this FastModelPicker belongs.
+     * This is used to access the camera and scene.
+     */
+    world: World;
+    /**
+     * Whether debug mode is enabled. When enabled, shows the color-coded canvas.
+     */
+    debugMode: boolean;
+    /**
+     * Map from color (as RGB number) to model ID.
+     * Color is encoded as: (r << 16) | (g << 8) | b
+     */
+    private colorToModelId;
+    /**
+     * Map from model ID to color.
+     */
+    private modelIdToColor;
+    /**
+     * Render target for the color-coded scene.
+     */
+    private renderTarget?;
+    /**
+     * Size of the render target (stored separately since getSize doesn't exist).
+     */
+    private renderTargetSize;
+    /**
+     * Debug canvas element (shown when debugMode is true).
+     */
+    private debugCanvas?;
+    /**
+     * Debug container element.
+     */
+    private debugContainer?;
+    /**
+     * Material used for color-coding models.
+     */
+    private colorMaterials;
+    /**
+     * Original materials cache (to restore after picking).
+     */
+    private originalMaterials;
+    private originalLodColors;
+    /**
+     * Whether colors need to be reassigned (when models change).
+     */
+    private colorsNeedUpdate;
+    constructor(components: Components, world: World);
+    /**
+     * Sets up listeners for fragment model changes.
+     */
+    private setupFragmentListeners;
+    /**
+     * Sets up the render target for color-coded picking.
+     */
+    private setupRenderTarget;
+    /**
+     * Sets up the debug canvas for visualization.
+     */
+    private setupDebugCanvas;
+    /**
+     * Generates a deterministic color for a model based on its ID.
+     * This ensures the same model always gets the same color.
+     */
+    private generateColorForModel;
+    /**
+     * Converts a color to a numeric ID.
+     */
+    private colorToId;
+    /**
+     * Assigns unique colors to all fragment models.
+     * Colors are deterministic based on model ID, so the same model always gets the same color.
+     */
+    private assignColors;
+    /**
+     * Applies color materials to fragment models.
+     */
+    private applyColorMaterials;
+    /**
+     * Restores original materials to fragment models.
+     */
+    private restoreOriginalMaterials;
+    /**
+     * Renders the scene with color-coded models.
+     */
+    private renderColorCoded;
+    /**
+     * Updates the debug canvas with the color-coded render.
+     */
+    private updateDebugCanvas;
+    /**
+     * Gets the model ID at the given screen position.
+     *
+     * @param position - Optional screen position. If not provided, uses current mouse position.
+     * @returns The model ID at the position, or null if no model is found.
+     */
+    getModelAt(position?: THREE.Vector2): Promise<string | null>;
+    /**
+     * Enables or disables debug mode.
+     * When enabled, shows a canvas with the color-coded render.
+     */
+    setDebugMode(enabled: boolean): void;
+    /**
+     * Removes the debug canvas.
+     */
+    private removeDebugCanvas;
+    /** {@link Disposable.dispose} */
+    dispose(): void;
+}
+
+/**
+ * A component that manages a FastModelPicker for each world and automatically disposes it when its corresponding world is disposed.
+ */
+export declare class FastModelPickers extends Component implements Disposable_2 {
+    /**
+     * A unique identifier for the component.
+     * This UUID is used to register the component within the Components system.
+     */
+    static readonly uuid: "4a82430c-7ff2-49ea-9401-60807502dad6";
+    /** {@link Component.enabled} */
+    enabled: boolean;
+    /**
+     * A Map that stores FastModelPicker instances for each world.
+     * The key is the world's UUID, and the value is the corresponding FastModelPicker instance.
+     */
+    list: Map<string, FastModelPicker>;
+    /** {@link Disposable.onDisposed} */
+    onDisposed: Event_2<unknown>;
+    constructor(components: Components);
+    /**
+     * Retrieves a FastModelPicker instance for the given world.
+     * If a FastModelPicker instance already exists for the world, it will be returned.
+     * Otherwise, a new FastModelPicker instance will be created and added to the list.
+     *
+     * @param world - The world for which to retrieve or create a FastModelPicker instance.
+     * @returns The FastModelPicker instance for the given world.
+     */
+    get(world: World): FastModelPicker;
+    /**
+     * Deletes the FastModelPicker instance associated with the given world.
+     * If a FastModelPicker instance exists for the given world, it will be disposed and removed from the list.
+     *
+     * @param world - The world for which to delete the FastModelPicker instance.
+     * @returns {void}
+     */
+    delete(world: World): void;
+    /** {@link Disposable.dispose} */
+    dispose(): void;
+}
+
 /**
  * Represents a finder query for retrieving items based on specified parameters. This class encapsulates the query logic, caching mechanism, and result management.
  */
 export declare class FinderQuery {
+    name: string;
     customData: Record<string, any>;
     private _components;
     private _queries;
@@ -1689,7 +1856,7 @@ export declare class FinderQuery {
      * @param data - A `SerializedFinderQuery` object representing the serialized query.
      * @returns A `FinderQuery` instance.
      */
-    fromJSON(data: Omit<SerializedFinderQuery, "name">): this;
+    fromJSON(data: SerializedFinderQuery): this;
 }
 
 /**
@@ -2155,7 +2322,7 @@ export declare class IDSSpecifications extends Component {
     static xmlParser: XMLParser;
     IDSInfo?: IDSInfo;
     constructor(components: Components);
-    readonly list: DataMap<string, IDSSpecification>;
+    readonly list: DataMap_2<string, IDSSpecification>;
     /**
      * Processes the results of an IDS check and categorizes the items into passing and failing.
      *
@@ -2373,6 +2540,7 @@ export declare class ItemsFinder extends Component implements Serializable<Seria
     getItems(queries: FRAGS.ItemsQueryParams[], config?: {
         modelIds?: RegExp[];
         aggregation?: QueryResultAggregation;
+        items?: ModelIdMap;
     }): Promise<ModelIdMap>;
     /**
      * Creates a new FinderQuery instance and adds it to the list of queries.
@@ -2648,7 +2816,7 @@ export declare class OrthoPerspectiveCamera extends SimpleCamera {
     readonly threePersp: THREE.PerspectiveCamera;
     protected readonly _userInputButtons: any;
     protected readonly _frustumSize = 50;
-    protected readonly _navigationModes: Map<NavModeID, NavigationMode>;
+    protected readonly _navigationModes: Map<string, NavigationMode>;
     protected _mode: NavigationMode | null;
     private previousSize;
     /**
@@ -2668,7 +2836,7 @@ export declare class OrthoPerspectiveCamera extends SimpleCamera {
      *
      * @param mode - The {@link NavigationMode} to set.
      */
-    set(mode: NavModeID): void;
+    set(mode: string): void;
     /**
      * Make the camera view fit all the specified meshes.
      *
@@ -2683,6 +2851,12 @@ export declare class OrthoPerspectiveCamera extends SimpleCamera {
      * @param active - whether to enable or disable user inputs.
      */
     setUserInput(active: boolean): void;
+    /**
+     * Adds a custom {@link NavigationMode} to the camera that can be used using the {@link OrthoPerspectiveCamera.set} method.
+     *
+     * @param mode - The custom {@link NavigationMode} to add.
+     */
+    addCustomNavigationMode(mode: NavigationMode): void;
     private disableUserInput;
     private enableUserInput;
     private newOrthoCamera;
@@ -2880,6 +3054,10 @@ export declare interface SerializationResult<D extends Record<string, any> = Rec
  * Represents a serialized query for an item finder.
  */
 export declare interface SerializedFinderQuery {
+    /**
+     * The ID of the query.
+     */
+    guid: string;
     /**
      * The name of the query.
      */
@@ -3277,6 +3455,13 @@ export declare class SimplePlane implements Disposable_2, Hideable {
      * @returns {THREE.Object3D} The helper object of the clipping plane.
      */
     get helper(): THREE.Object3D<THREE.Object3DEventMap>;
+    /**
+     * Getter for the transform controls of the clipping plane.
+     * The controls allow interactive manipulation (translation, rotation, etc.) of the clipping plane.
+     *
+     * @returns {TransformControls} The transform controls of the clipping plane.
+     */
+    get controls(): TransformControls;
     constructor(components: Components, world: World, origin: THREE.Vector3, normal: THREE.Vector3, material: THREE.Material, size?: number, activateControls?: boolean);
     private notifyManager;
     /**
@@ -3328,6 +3513,13 @@ export declare class SimpleRaycaster implements Disposable_2 {
      * This is used to access the camera and meshes.
      */
     world: World;
+    /**
+     * Whether to use fast model picking to optimize raycasting.
+     * When enabled, the raycaster will first use FastModelPicker to identify
+     * which model is under the mouse, then only raycast that specific model.
+     * This can significantly improve performance when there are many models.
+     */
+    useFastModelPicking: boolean;
     constructor(components: Components, world: World);
     /** {@link Disposable.dispose} */
     dispose(): void;
@@ -3597,10 +3789,10 @@ export declare class Topic implements BCFTopic {
     title: string;
     creationDate: Date;
     creationAuthor: string;
-    readonly viewpoints: DataSet<string>;
-    readonly relatedTopics: DataSet<string>;
-    readonly comments: DataMap<string, Comment_2>;
-    readonly documentReferences: DataSet<string>;
+    readonly viewpoints: DataSet_2<string>;
+    readonly relatedTopics: DataSet_2<string>;
+    readonly comments: DataMap_2<string, Comment_2>;
+    readonly documentReferences: DataSet_2<string>;
     customData: Record<string, any>;
     description?: string;
     serverAssignedId?: string;
@@ -3900,6 +4092,7 @@ export declare class Viewpoint {
      */
     readonly clippingPlanes: FRAGS.DataSet<string>;
     camera: ViewpointPerspectiveCamera | ViewpointOrthogonalCamera;
+    customData: Record<string, any>;
     /**
      * A list of components GUIDs to hide when defaultVisibility = true or to show when defaultVisibility = false
      */
@@ -4537,7 +4730,7 @@ export declare class Worlds extends Component implements Updateable, Disposable_
      * A collection of worlds managed by this component.
      * The key is the unique identifier (UUID) of the world, and the value is the World instance.
      */
-    list: DataMap<string, World>;
+    list: DataMap_2<string, World>;
     /** {@link Component.enabled} */
     enabled: boolean;
     constructor(components: Components);