@cognite/reveal 4.29.3 → 4.30.0

package/dist/packages/360-images/index.d.ts

@@ -15,7 +15,9 @@ export { Image360AnnotationIntersection } from './src/annotation/Image360Annotat
 export { Image360Annotation } from './src/annotation/Image360Annotation';
 export { DefaultImage360Collection } from './src/collection/DefaultImage360Collection';
 export { IconsOptions } from './src/icons/IconCollection';
-export { Image360CollectionSourceType, Image360IconIntersectionData } from './src/types';
+export { ClusteredIconData } from './src/icons/clustering/ClusterRenderingStrategy';
+export { HtmlClusterRendererOptions } from './src/icons/clustering/HtmlClusterRenderer';
+export { Image360ClusterIntersectionData, Image360CollectionSourceType, Image360IconIntersectionData } from './src/types';
 export { Image360AnnotationFilter } from './src/annotation/Image360AnnotationFilter';
 export { DEFAULT_IMAGE_360_OPACITY } from './src/entity/Image360VisualizationBox';
 export { Image360Action } from './src/Image360Action';

package/dist/packages/360-images/src/Image360Facade.d.ts

@@ -9,7 +9,7 @@ import { IconCullingScheme } from './icons/IconCollection';
 import { Image360RevisionEntity } from './entity/Image360RevisionEntity';
 import { Image360AnnotationFilterOptions } from './annotation/types';
 import { DataSourceType } from '../../data-providers';
-import { Image360IconIntersectionData } from './types';
+import { Image360ClusterIntersectionData, Image360IconIntersectionData } from './types';
 export declare class Image360Facade<T extends DataSourceType> {
     private readonly _entityFactory;
     private readonly _image360Collections;
@@ -29,5 +29,29 @@ export declare class Image360Facade<T extends DataSourceType> {
     preload(entity: Image360Entity<T>, revision: Image360RevisionEntity<T>, lockDownload?: boolean): Promise<void>;
     getCollectionContainingEntity(entity: Image360Entity<T>): DefaultImage360Collection<T>;
     intersect(coords: Vector2, camera: Camera): Image360IconIntersectionData<T> | undefined;
+    /**
+     * Intersect with cluster icons. Returns cluster data if a cluster is hit.
+     * Also updates hover state to highlight only the closest cluster.
+     * @param coords - Normalized screen coordinates (-1 to 1)
+     * @param camera - The camera used for the intersection
+     * @returns Cluster intersection data if a cluster is hit, undefined otherwise
+     */
+    intersectCluster(coords: Vector2, camera: Camera): Image360ClusterIntersectionData<T> | undefined;
+    /**
+     * Finds the closest cluster candidate.
+     * @param coords - Normalized screen coordinates (-1 to 1)
+     * @param camera - The camera used for the intersection
+     * @returns The closest cluster candidate, undefined if no cluster is hit
+     */
+    private findClosestCluster;
+    /**
+     * Applies cluster hover on the given candidate's collection.
+     * @param candidate - The cluster candidate to apply hover to
+     */
+    private applyClusterHover;
+    /**
+     * Clear hovered cluster state for all collections.
+     */
+    clearHoveredClusters(): void;
     dispose(): void;
 }

package/dist/packages/360-images/src/collection/DefaultImage360Collection.d.ts

@@ -5,11 +5,12 @@ import { EventTrigger } from '../../../utilities';
 import { AssetAnnotationImage360Info, AssetHybridAnnotationImage360Info, Image360AnnotationAssetFilter, Image360AnnotationAssetQueryResult, Image360Collection } from './Image360Collection';
 import { Image360Entity } from '../entity/Image360Entity';
 import { Image360EnteredDelegate, Image360ExitedDelegate } from '../types';
-import { IconCollection, IconCullingScheme } from '../icons/IconCollection';
+import { ClusterIntersectionData, IconCollection, IconCullingScheme } from '../icons/IconCollection';
+import { Overlay3DIcon } from '../../../3d-overlays';
 import { Image360AnnotationAppearance } from '../annotation/types';
 import { ClassicDataSourceType, DataSourceType, DMDataSourceType, Image360FileDescriptor, Image360Provider } from '../../../data-providers';
 import { Image360AnnotationFilter } from '../annotation/Image360AnnotationFilter';
-import { Matrix4 } from 'three';
+import { Matrix4, Ray } from 'three';
 import { InstanceReference } from '../../../data-providers/src/types';
 /**
  * Default implementation of {@link Image360Collection}. Used for events when entering
@@ -31,6 +32,10 @@ export declare class DefaultImage360Collection<T extends DataSourceType> impleme
     private readonly _annotationFilter;
     private readonly _events;
     private readonly _icons;
+    /**
+     * A map containing the image360Entities by their icon.
+     */
+    private readonly _image360EntitiesMap;
     private _isCollectionVisible;
     private readonly _sourceId;
     private readonly _collectionLabel;
@@ -90,6 +95,40 @@ export declare class DefaultImage360Collection<T extends DataSourceType> impleme
     setSelectedForAll(selected: boolean): void;
     setSelectedVisibility(visible: boolean): boolean;
     setCullingScheme(scheme: IconCullingScheme): void;
+    /**
+     * Get the current cluster distance threshold.
+     * @returns The current distance threshold for clustering
+     */
+    getClusterDistanceThreshold(): number;
+    /**
+     * Set the cluster distance threshold.
+     * @param threshold - The new distance threshold (default: 100)
+     */
+    setClusterDistanceThreshold(threshold: number): void;
+    /**
+     * Get the current maximum octree depth for clustering.
+     * @returns The current max depth, or undefined if no limit
+     */
+    getMaxOctreeDepth(): number | undefined;
+    /**
+     * Set the maximum octree depth for clustering.
+     * @param depth - The new max depth
+     */
+    setMaxOctreeDepth(depth: number | undefined): void;
+    /**
+     * Check if HTML cluster rendering is enabled.
+     * @returns true if HTML clusters are enabled
+     */
+    isHtmlClustersEnabled(): boolean;
+    intersectCluster(ray: Ray): ClusterIntersectionData | undefined;
+    /**
+     * Get entities corresponding to the given icons using map lookups.
+     * @param icons - Array of Overlay3DIcon to look up
+     * @returns Array of Image360Entity corresponding to the icons
+     */
+    getEntitiesFromIcons(icons: Overlay3DIcon[]): Image360Entity<T>[];
+    clearHoveredCluster(): void;
+    setHoveredClusterIcon(icon: Overlay3DIcon | undefined): void;
     remove(entity: Image360Entity<T>): void;
     dispose(): void;
     get needsRedraw(): boolean;

package/dist/packages/360-images/src/collection/Image360Collection.d.ts

@@ -158,6 +158,31 @@ export interface Image360Collection<T extends DataSourceType = ClassicDataSource
      * @param opacity The opacity of the icons
      */
     setIconsOpacity(opacity: number): void;
+    /**
+     * Get the current cluster distance threshold.
+     * @returns The current distance threshold for clustering
+     */
+    getClusterDistanceThreshold(): number;
+    /**
+     * Set the cluster distance threshold.
+     * @param threshold - The new distance threshold
+     */
+    setClusterDistanceThreshold(threshold: number): void;
+    /**
+     * Get the current maximum octree depth for clustering.
+     * @returns The current max depth, or undefined if no limit
+     */
+    getMaxOctreeDepth(): number | undefined;
+    /**
+     * Set the maximum octree depth for clustering.
+     * @param depth - The new max depth
+     */
+    setMaxOctreeDepth(depth: number | undefined): void;
+    /**
+     * Check if HTML cluster rendering is enabled.
+     * @returns true if HTML clusters are enabled
+     */
+    isHtmlClustersEnabled(): boolean;
     /**
      * Subscribes to events on 360 Image datasets. There are several event types:
      * 'image360Entered' - Subscribes to a event for entering 360 image mode.

package/dist/packages/360-images/src/icons/IconCollection.d.ts

@@ -1,16 +1,42 @@
 /*!
  * Copyright 2023 Cognite AS
  */
-import { Matrix4, Vector3 } from 'three';
+import { Matrix4, Ray, Vector3 } from 'three';
 import { BeforeSceneRenderedDelegate, EventTrigger, SceneHandler } from '../../../utilities';
-import { Overlay3DIcon } from '../../../3d-overlays';
+import { DefaultOverlay3DContentType, IconOctree, Overlay3DIcon } from '../../../3d-overlays';
+import { PointOctant } from 'sparse-octree';
+import { HtmlClusterRendererOptions } from './clustering/HtmlClusterRenderer';
 export type IconCullingScheme = 'clustered' | 'proximity';
 export type IconsOptions = {
     platformMaxPointsSize?: number;
+    htmlClusterOptions?: HtmlClusterRendererOptions;
+    clusterDistanceThreshold?: number;
+    maxOctreeDepth?: number;
+    enableHtmlClusters?: boolean;
+};
+export type ClusteredIcon = {
+    icon: Overlay3DIcon;
+    isCluster: boolean;
+    clusterSize: number;
+    clusterPosition: Vector3;
+    sizeScale: number;
+    clusterIcons?: Overlay3DIcon[];
+};
+export type ClusterIntersectionData = {
+    clusterPosition: Vector3;
+    clusterSize: number;
+    clusterIcons: Overlay3DIcon[];
+    representativeIcon: Overlay3DIcon;
 };
 export declare class IconCollection {
     private static readonly MinPixelSize;
     private static readonly DefaultMaxPixelSize;
+    private static readonly DefaultProjectionMatrixElement;
+    private static readonly DefaultRenderHeight;
+    private static readonly DefaultProximityPointLimit;
+    private static readonly DefaultProximityRadius;
+    private static readonly DefaultClusterDistanceThreshold;
+    private static readonly DefaultMaxOctreeDepth;
     private readonly _maxPixelSize;
     private readonly _sceneHandler;
     private readonly _sharedTexture;
@@ -21,18 +47,100 @@ export declare class IconCollection {
     private readonly _computeProximityPointsEventHandler;
     private readonly _onBeforeSceneRenderedEvent;
     private readonly _iconRadius;
-    private _activeCullingSchemeEventHandeler;
-    private _iconCullingScheme;
+    private readonly _renderPositions;
+    private readonly _renderColors;
+    private readonly _setNeedsRedraw;
+    private readonly _lastLODCameraPosition;
+    private readonly _minClusterPixelSize;
+    private readonly _htmlRenderer;
+    private readonly _enableHtmlClusters;
+    private _lastProjectionMatrixElement;
+    private _lastRenderHeight;
     private _proximityRadius;
     private _proximityPointLimit;
+    private _clusterDistanceThreshold;
+    private _maxOctreeDepth;
+    private _activeCullingSchemeEventHandeler;
+    private _iconCullingScheme;
+    private _visibleClusteredIcons;
+    private _hoveredClusterIcon;
+    private _cachedClusteredIcons;
     get icons(): Overlay3DIcon[];
     set hoverSpriteVisibility(value: boolean);
     setCullingScheme(scheme: IconCullingScheme): void;
     set360IconCullingRestrictions(radius: number, pointLimit: number): void;
-    constructor(points: Vector3[], sceneHandler: SceneHandler, onBeforeSceneRendered: EventTrigger<BeforeSceneRenderedDelegate>, iconOptions?: IconsOptions);
+    getClusterDistanceThreshold(): number;
+    setClusterDistanceThreshold(threshold: number): void;
+    getMaxOctreeDepth(): number | undefined;
+    isHtmlClustersEnabled(): boolean;
+    setMaxOctreeDepth(depth: number | undefined): void;
+    constructor(points: Vector3[], sceneHandler: SceneHandler, onBeforeSceneRendered: EventTrigger<BeforeSceneRenderedDelegate>, iconOptions?: IconsOptions, setNeedsRedraw?: () => void);
     setTransform(transform: Matrix4): void;
     getTransform(out?: Matrix4): Matrix4;
-    private setIconClustersByLOD;
+    /**
+     * Intersect a ray with visible clusters. Returns cluster data if a cluster is hit.
+     * Only works when HTML clusters are enabled.
+     * @param ray - Ray in model space (ray.origin is camera position in model space)
+     * @returns ClusterIntersectionData if a cluster is hit, undefined otherwise
+     */
+    intersectCluster(ray: Ray): ClusterIntersectionData | undefined;
+    setHoveredClusterIcon(icon: Overlay3DIcon | undefined): void;
+    clearHoveredCluster(): void;
+    /**
+     * Get the currently visible clustered icons (for external intersection handling).
+     */
+    getVisibleClusteredIcons(): readonly ClusteredIcon[];
+    /**
+     * LOD-based icon filtering with cluster visualization.
+     * Shows clusters based on distance/LOD and visualizes them with a count texture.
+     * @param octree - The octree to use for clustering
+     * @param iconSprites - The icon sprites to use for rendering
+     * @returns A BeforeSceneRenderedDelegate function that sets the icons by LOD with cluster visualization
+     */
+    private setIconsByLODWithClustering;
+    /**
+     * LOD-based icon filtering
+     * Shows individual icons based on distance/LOD without pure cluster icons visualization.
+     * @param octree - The octree to use for clustering
+     * @param iconSprites - The icon sprites to use for rendering
+     * @returns A BeforeSceneRenderedDelegate function that sets the icons by LOD without cluster visualization
+     */
+    private setIconsByLOD;
+    /**
+     * Update the cluster rendering.
+     * @param visibleClusters - The visible clustered icons
+     * @param iconSprites - The icon sprites to use for rendering
+     * @param params - The parameters for the rendering
+     * @param params.renderer - The WebGL renderer
+     * @param params.camera - The perspective camera
+     * @param params.modelTransform - The model transform matrix
+     */
+    private updateClusterRendering;
+    private calculateCentroid;
+    /**
+     * Build clustered icons from octree LOD nodes.
+     * Processes each node to determine if it should be shown as a cluster or individual icons.
+     * @param octree - The octree to use for clustering
+     * @param nodes - The nodes to process
+     * @param clusterIconSizeMultiplier - The size multiplier for the cluster icons
+     * @returns The clustered icons
+     */
+    buildClusteredIconsFromNodes(octree: IconOctree, nodes: PointOctant<Overlay3DIcon<DefaultOverlay3DContentType>>[], clusterIconSizeMultiplier: number): ClusteredIcon[];
+    /**
+     * Filter clustered icons by frustum visibility and update culled state.
+     * Returns only the visible icons that pass frustum culling and visibility checks.
+     * @param frustum - The frustum to use for culling
+     * @param clusteredIcons - The clustered icons to filter
+     * @returns The visible clustered icons
+     */
+    private filterVisibleClusteredIcons;
+    /**
+     * Build render data arrays from visible icons and update the icon sprites.
+     * Only renders individual icons (non-clusters)
+     * @param visibleIcons - The visible icons to render
+     * @param iconSprites - The icon sprites to use for rendering
+     */
+    private updateIconSpritesRenderData;
     private computeProximityPoints;
     private initializeImage360Icons;
     dispose(): void;

package/dist/packages/360-images/src/icons/clustering/ClusterRenderingStrategy.d.ts

@@ -0,0 +1,18 @@
+/*!
+ * Copyright 2026 Cognite AS
+ */
+import { Matrix4, PerspectiveCamera, Vector3, WebGLRenderer } from 'three';
+import { Overlay3DIcon } from '../../../../3d-overlays';
+export type ClusteredIconData = {
+    icon: Overlay3DIcon;
+    isCluster: boolean;
+    clusterSize: number;
+    clusterPosition: Vector3;
+    sizeScale: number;
+    clusterIcons?: Overlay3DIcon[];
+};
+export type ClusterRenderParams = {
+    renderer: WebGLRenderer;
+    camera: PerspectiveCamera;
+    modelTransform: Matrix4;
+};

package/dist/packages/360-images/src/icons/clustering/HtmlClusterRenderer.d.ts

@@ -0,0 +1,47 @@
+/*!
+ * Copyright 2026 Cognite AS
+ */
+import { Overlay3DIcon } from '../../../../3d-overlays';
+import { ClusteredIconData, ClusterRenderParams } from './ClusterRenderingStrategy';
+export type HtmlClusterRendererOptions = {
+    maxPoolSize?: number;
+    classPrefix?: string;
+    enableHoverAnimations?: boolean;
+    zIndex?: number;
+};
+/** HTML-based cluster rendering for high-definition text display */
+export declare class HtmlClusterRenderer {
+    private readonly _container;
+    private readonly _elementPool;
+    private readonly _activeElements;
+    private readonly _maxPoolSize;
+    private readonly _classPrefix;
+    private readonly _enableHoverAnimations;
+    private readonly _zIndex;
+    private readonly _countSpanName;
+    private readonly _baseSize;
+    private readonly _minSize;
+    private readonly _maxSize;
+    private readonly _pendingReleaseTimeouts;
+    private _hoveredClusterIcon;
+    private _isVisible;
+    private _isAttached;
+    private _domElement;
+    private readonly _tempPosition;
+    private readonly _tempProjectedPosition;
+    constructor(options?: HtmlClusterRendererOptions);
+    updateClusters(visibleClusters: ClusteredIconData[], params: ClusterRenderParams): void;
+    setHoveredCluster(icon: Overlay3DIcon | undefined): void;
+    getHoveredCluster(): Overlay3DIcon | undefined;
+    setVisible(visible: boolean): void;
+    dispose(): void;
+    private createContainer;
+    private injectStyles;
+    private ensureAttached;
+    private updateContainerSize;
+    private acquireElement;
+    private releaseElement;
+    private createClusterElement;
+    private updateClusterElement;
+    private setElementHovered;
+}

package/dist/packages/360-images/src/icons/clustering/htmlClusterStyles.d.ts

@@ -0,0 +1,9 @@
+/*!
+ * Copyright 2026 Cognite AS
+ */
+/**
+ * Generates CSS styles for HTML cluster icons.
+ * @param classPrefix - The CSS class prefix for cluster elements
+ * @returns The complete CSS stylesheet as a string
+ */
+export declare function generateClusterStyles(classPrefix: string): string;

package/dist/packages/360-images/src/icons/clustering/index.d.ts

@@ -0,0 +1,5 @@
+/*!
+ * Copyright 2026 Cognite AS
+ */
+export { ClusteredIconData, ClusterRenderParams } from './ClusterRenderingStrategy';
+export { HtmlClusterRenderer, HtmlClusterRendererOptions } from './HtmlClusterRenderer';

package/dist/packages/360-images/src/types.d.ts

@@ -25,3 +25,13 @@ export type Image360IconIntersectionData<T extends DataSourceType = DataSourceTy
     point: Vector3;
     distanceToCamera: number;
 };
+/**
+ * Data for a cluster intersection result
+ */
+export type Image360ClusterIntersectionData<T extends DataSourceType = DataSourceType> = {
+    image360Collection: DefaultImage360Collection<T>;
+    clusterPosition: Vector3;
+    clusterSize: number;
+    clusterIcons: Image360Entity<T>[];
+    distanceToCamera: number;
+};

package/dist/packages/3d-overlays/src/IconOctree.d.ts

@@ -37,17 +37,24 @@ export declare class IconOctree<ContentType = DefaultOverlay3DContentType> exten
     /**
      * Get LOD nodes based purely on camera distance.
      * This provides consistent behavior regardless of view angle.
-     *
      * @param cameraPosition - Camera position in model space
      * @param distanceThreshold - Distance from camera within which all icons are shown (no clustering)
      * @param clusteringLevel - The octree level at which to cluster far icons (higher = finer clusters)
      * @returns Set of PointOctant nodes selected for LOD based on distance
      */
     getLODByDistance(cameraPosition: Vector3 | undefined, distanceThreshold: number, clusteringLevel?: number): Set<PointOctant<Overlay3DIcon>>;
+    /**
+     * Get LOD nodes based on camera distance with enhanced clustering for pure cluster visualization.
+     * Uses node size awareness and max depth control for better cluster granularity.
+     * @param cameraPosition - Camera position for distance calculation
+     * @param distanceThreshold - Distance threshold for "close" icons
+     * @param maxOctreeDepth - Maximum octree depth to expand to (controls cluster granularity)
+     * @returns Set of PointOctant nodes selected for LOD based on camera distance
+     */
+    getLODByDistanceWithClustering(cameraPosition: Vector3 | undefined, distanceThreshold: number, maxOctreeDepth?: number): Set<PointOctant<Overlay3DIcon>>;
     /**
      * Get all icons from a node's subtree that are within the given distance from a point.
      * Also returns the representative icon if no close icons are found (for clustering).
-     *
      * @param node - The octree node to get icons from
      * @param cameraPosition - Camera position for distance calculation
      * @param distanceThreshold - Distance threshold for "close" icons

package/dist/packages/api/src/api-helpers/Image360ApiHelper.d.ts

@@ -3,7 +3,7 @@
  */
 import { type Matrix4 } from 'three';
 import { CogniteClient, Metadata } from '@cognite/sdk';
-import { Image360Collection, Image360Entity, Image360, IconsOptions, Image360RevisionEntity, Image360AnnotationIntersection, Image360AnnotationFilterOptions, Image360IconIntersectionData, Image360Action } from '../../../360-images';
+import { Image360Collection, Image360Entity, Image360, IconsOptions, Image360RevisionEntity, Image360AnnotationIntersection, Image360AnnotationFilterOptions, Image360IconIntersectionData, Image360ClusterIntersectionData, Image360Action } from '../../../360-images';
 import { DataSourceType, Image360DataModelIdentifier } from '../../../data-providers';
 import { BeforeSceneRenderedDelegate, EventTrigger, InputHandler, PointerEventData, SceneHandler } from '../../../utilities';
 import { ProxyCameraManager } from '../../../camera-manager';
@@ -49,6 +49,21 @@ export declare class Image360ApiHelper<DataSourceT extends DataSourceType> {
     private findRevisionIdToEnter;
     private enter360ImageOnIntersect;
     intersect360ImageIcons(offsetX: number, offsetY: number): Image360IconIntersectionData<DataSourceT> | undefined;
+    /**
+     * Intersect with cluster icons at the given screen position.
+     * @param offsetX - X offset in pixels from the DOM element
+     * @param offsetY - Y offset in pixels from the DOM element
+     * @returns Cluster intersection data if a cluster is hit, undefined otherwise
+     */
+    intersect360ImageClusters(offsetX: number, offsetY: number): Image360ClusterIntersectionData<DataSourceT> | undefined;
+    /**
+     * Zoom the camera toward a cluster position.
+     * The camera moves to a position nearby the cluster centroid (not exactly at it)
+     * so that the cluster icons become visible and expand.
+     * @param clusterData - The cluster intersection data
+     * @returns Promise that resolves to true when the zoom is complete
+     */
+    zoomToCluster(clusterData: Image360ClusterIntersectionData<DataSourceT>): Promise<boolean>;
     intersect360ImageAnnotations(offsetX: number, offsetY: number): Image360AnnotationIntersection<DataSourceT> | undefined;
     private setHoverIconOnIntersect;
     private exit360ImageByTween;

package/dist/packages/api/src/public/migration/Cognite3DViewer.d.ts

@@ -704,6 +704,7 @@ export declare class Cognite3DViewer<DataSourceT extends DataSourceType = Classi
      */
     onHover360Images(event: PointerEvent): boolean;
     private intersect360Icons;
+    private intersect360Clusters;
     /**
      * Check for intersections with 360 annotations through the given pixel.
      * Similar to {@link Cognite3DViewer.getIntersectionFromPixel}, but checks 360 image annotations

package/dist/packages/api/src/public/migration/types.d.ts

@@ -158,6 +158,12 @@ export interface Cognite3DViewerOptions {
      * @beta
      */
     hasEventListeners?: boolean;
+    /**
+     * Enable HTML-based cluster rendering for 360 image icons.
+     * When enabled, nearby 360 icons are grouped into clusters with a count display.
+     * @default false
+     */
+    enableHtmlClusters?: boolean;
 }
 /**
  * @module @cognite/reveal
@@ -264,12 +270,43 @@ export type Image360IconIntersection<T extends DataSourceType = DataSourceType>
      */
     distanceToCamera: number;
 };
+/**
+ * Represents the result from a 360 cluster intersection test.
+ * @module @cognite/reveal
+ * @beta
+ */
+export type Image360ClusterIntersection<T extends DataSourceType = DataSourceType> = {
+    /**
+     * The intersection type.
+     */
+    type: 'image360Cluster';
+    /**
+     * The image360 collection containing the cluster.
+     */
+    image360Collection: Image360Collection<T>;
+    /**
+     * The world position of the cluster centroid.
+     */
+    clusterPosition: Vector3;
+    /**
+     * The number of icons in the cluster.
+     */
+    clusterSize: number;
+    /**
+     * The image360 entities in the cluster.
+     */
+    clusterIcons: Image360<T>[];
+    /**
+     * Distance from the camera to the cluster.
+     */
+    distanceToCamera: number;
+};
 /**
  * Represents the result from {@link Cognite3DViewer.getAnyIntersectionFromPixel}.
  * @module @cognite/reveal
  * @beta
  */
-export type AnyIntersection<T extends DataSourceType = DataSourceType> = CadIntersection | PointCloudIntersection<T> | Image360IconIntersection<T> | CustomObjectIntersection;
+export type AnyIntersection<T extends DataSourceType = DataSourceType> = CadIntersection | PointCloudIntersection<T> | Image360IconIntersection<T> | Image360ClusterIntersection<T> | CustomObjectIntersection;
 /**
  * @module @cognite/reveal
  */

package/dist/packages/camera-manager/src/DefaultCameraManager.d.ts

@@ -103,7 +103,13 @@ export declare class DefaultCameraManager implements CameraManager {
     setCameraControlsOptions(controlsOptions: CameraControlsOptions): void;
     update(deltaTime: number, boundingBox: THREE.Box3): void;
     dispose(): void;
-    private moveCameraTo;
+    /**
+     * Animates the camera to the given position and target.
+     * @param position Desired camera position in world space.
+     * @param target Desired look-at target in world space.
+     * @param duration Duration of the animation in milliseconds. If omitted, a default is derived from distance.
+     */
+    moveCameraTo(position: THREE.Vector3, target: THREE.Vector3, duration?: number, keyboardNavigationEnabled?: boolean): void;
     private moveCameraTargetTo;
     private updateCameraNearAndFar;
     private calculateAnimationStartTarget;

package/dist/packages/data-providers/index.d.ts

@@ -32,5 +32,6 @@ export { Image360ProviderCombiner } from './src/Image360ProviderCombiner';
 export { BinaryFileProvider, JsonFileProvider, File3dFormat, BlobOutputMetadata, Image360Descriptor, Image360FileProvider, Image360Face, Image360Texture, Image360FileDescriptor, ImageAssetLinkAnnotationInfo, ImageInstanceLinkAnnotationInfo, InstanceReference, Image360Id, Image360RevisionId } from './src/types';
 export { fetchDMModelIdFromRevisionId } from './src/requests/fetchDMModelIdFromRevisionId';
 export { isDMPointCloudVolumeObject, isClassicPointCloudVolumeObject, isDMPointCloudVolume, isClassicPointCloudVolume } from './src/utilities/utils';
+export { getExternalIdFromDescriptor } from './src/utilities/getExternalIdFromDescriptor';
 export { DataSourceType, ClassicDataSourceType, DMDataSourceType, ClassicModelIdentifierType, DMModelIdentifierType, isClassicIdentifier, isDMIdentifier, InternalDataSourceType, LocalDataSourceType, LocalModelIdentifierType, isLocalIdentifier, GenericDataSourceType } from './src/DataSourceType';
 export { LocalAddModelOptions, CommonModelOptions, InternalAddModelOptions, AddModelOptionsWithModelRevisionId } from './src/utilities/internalAddModelOptions';

package/dist/packages/data-providers/src/Image360ProviderCombiner.d.ts

@@ -15,6 +15,7 @@ export declare class Image360ProviderCombiner<T extends DataSourceType> implemen
     get360ImageFiles(image360FaceDescriptors: Image360FileDescriptor[], abortSignal?: AbortSignal): Promise<Image360Face[]>;
     getLowResolution360ImageFiles(image360FaceDescriptors: Image360FileDescriptor[], abortSignal?: AbortSignal): Promise<Image360Face[]>;
     getRelevant360ImageAnnotations(annotationSpecifier: Image360AnnotationSpecifier<T>): Promise<T['image360AnnotationType'][]>;
+    resolveFileIdToExternalIdMapping(annotations: T['image360AnnotationType'][], descriptors: Image360FileDescriptor[]): Promise<Map<number, string>>;
     findImageAnnotationsForInstance(instanceFilter: Image360AnnotationInstanceReference<T>, collection: DefaultImage360Collection<T>): Promise<Image360AnnotationAssetQueryResult<T>[]>;
     getAllImage360AnnotationInfos(source: 'assets', collection: DefaultImage360Collection<T>, annotationFilter: Image360AnnotationFilterDelegate<T>): Promise<AssetAnnotationImage360Info<ClassicDataSourceType>[]>;
     getAllImage360AnnotationInfos(source: 'hybrid', collection: DefaultImage360Collection<T>, annotationFilter: Image360AnnotationFilterDelegate<T>): Promise<AssetHybridAnnotationImage360Info[]>;

package/dist/packages/data-providers/src/image-360-data-providers/Cdf360ImageAnnotationProvider.d.ts

@@ -1,23 +1,47 @@
 /*!
  * Copyright 2022 Cognite AS
  */
-import { CogniteClient } from '@cognite/sdk';
-import { Image360AnnotationFilterDelegate, Image360AnnotationProvider, Image360AnnotationSpecifier, InstanceReference } from '../types';
+import { AnnotationModel, CogniteClient } from '@cognite/sdk';
+import { Image360AnnotationFilterDelegate, Image360AnnotationProvider, Image360AnnotationSpecifier, Image360FileDescriptor, InstanceReference } from '../types';
 import { ClassicDataSourceType, DataSourceType, DMDataSourceType } from '../DataSourceType';
 import { AssetAnnotationImage360Info, AssetHybridAnnotationImage360Info, DefaultImage360Collection, Image360AnnotationAssetQueryResult } from '../../../360-images';
 export declare class Cdf360ImageAnnotationProvider implements Image360AnnotationProvider<ClassicDataSourceType> {
     private readonly _client;
     private readonly _collectionToInstanceReferenceToAnnotationMap;
+    private readonly _collectionAnnotationsCache;
+    private readonly _collectionFileIdMapCache;
     constructor(client: CogniteClient);
     findImageAnnotationsForInstance(asset: InstanceReference<DataSourceType>, collection: DefaultImage360Collection<ClassicDataSourceType>): Promise<Image360AnnotationAssetQueryResult<ClassicDataSourceType>[]>;
     private fetchImageAnnotationsForInstance;
+    /**
+     * Gets all annotations for a collection
+     */
+    private getAllAnnotationsForCollection;
+    /**
+     * Gets the fileId to entity/revision mapping
+     */
+    private getFileIdToEntityRevisionMap;
     private cacheResult;
     getRelevant360ImageAnnotations(annotationSpecifier: Image360AnnotationSpecifier<ClassicDataSourceType>): Promise<ClassicDataSourceType['image360AnnotationType'][]>;
+    /**
+     * Fetches file info for the given IDs and returns a map of fileId -> externalId.
+     */
+    private fetchFileIdToExternalIdMapping;
+    /**
+     * Resolves the mapping from internal file IDs to external IDs.
+     * This is needed to match annotations (which have annotatedResourceId) to descriptors (which may have externalId).
+     */
+    resolveFileIdToExternalIdMapping(annotations: AnnotationModel[], descriptors: Image360FileDescriptor[]): Promise<Map<number, string>>;
     getAllImage360AnnotationInfos(source: 'assets', collection: DefaultImage360Collection<ClassicDataSourceType>, annotationFilter: Image360AnnotationFilterDelegate<ClassicDataSourceType>): Promise<AssetAnnotationImage360Info<ClassicDataSourceType>[]>;
     getAllImage360AnnotationInfos(source: 'hybrid', collection: DefaultImage360Collection<ClassicDataSourceType>, annotationFilter: Image360AnnotationFilterDelegate<ClassicDataSourceType>): Promise<AssetHybridAnnotationImage360Info[]>;
     getAllImage360AnnotationInfos(source: 'cdm', collection: DefaultImage360Collection<ClassicDataSourceType>, annotationFilter: Image360AnnotationFilterDelegate<ClassicDataSourceType>): Promise<AssetAnnotationImage360Info<DMDataSourceType>[]>;
     getAllImage360AnnotationInfos(source: 'all', collection: DefaultImage360Collection<ClassicDataSourceType>, annotationFilter: Image360AnnotationFilterDelegate<ClassicDataSourceType>): Promise<AssetAnnotationImage360Info<DataSourceType>[]>;
-    private createFileIdToEntityRevisionMap;
+    /**
+     * Builds a mapping from annotatedResourceId (internal file ID) to entity/revision.
+     * For legacy descriptors with fileId, uses the fileId directly.
+     * For new descriptors with externalId, resolves the mapping via one batched API call.
+     */
+    private buildFileIdToEntityRevisionMap;
     private fetchAllAnnotations;
     private listFileAnnotations;
 }

package/dist/packages/data-providers/src/types.d.ts

@@ -32,6 +32,12 @@ export type Image360AnnotationSpecifier<T extends DataSourceType> = {
 export type InstanceReference<T extends DataSourceType> = T extends ClassicDataSourceType ? IdEither : DMInstanceRef;
 export interface Image360AnnotationProvider<T extends DataSourceType> {
     getRelevant360ImageAnnotations(annotationSpecifier: Image360AnnotationSpecifier<T>): Promise<T['image360AnnotationType'][]>;
+    /**
+     * Resolves the mapping from internal file IDs (annotatedResourceId) to external IDs.
+     * This is needed to match annotations to face descriptors when descriptors use externalId.
+     * Optional - if not implemented, the caller should build mapping from descriptors only.
+     */
+    resolveFileIdToExternalIdMapping?(annotations: T['image360AnnotationType'][], descriptors: Image360FileDescriptor[]): Promise<Map<number, string>>;
     findImageAnnotationsForInstance(instanceFilter: Image360AnnotationInstanceReference<T>, collection: DefaultImage360Collection<T>): Promise<Image360AnnotationAssetQueryResult<T>[]>;
     getAllImage360AnnotationInfos(source: 'assets', collection: DefaultImage360Collection<T>, annotationFilter: Image360AnnotationFilterDelegate<T>): Promise<AssetAnnotationImage360Info<ClassicDataSourceType>[]>;
     getAllImage360AnnotationInfos(source: 'hybrid', collection: DefaultImage360Collection<T>, annotationFilter: Image360AnnotationFilterDelegate<T>): Promise<AssetHybridAnnotationImage360Info[]>;

package/dist/packages/data-providers/src/utilities/getExternalIdFromDescriptor.d.ts

@@ -0,0 +1,9 @@
+/*!
+ * Copyright 2025 Cognite AS
+ */
+import { Image360FileDescriptor } from '../types';
+/**
+ * Gets the externalId from a file descriptor, if available.
+ * Works with both direct externalId and instanceId.externalId.
+ */
+export declare function getExternalIdFromDescriptor(desc: Image360FileDescriptor): string | undefined;