@idetik/core 0.44.0 → 0.45.0

package/dist/index.d.ts

@@ -242,34 +242,6 @@ declare function createNoPrefetchPolicy(overrides?: Partial<ImageSourcePolicyPro
  */
 declare function createImageSourcePolicy(config: ImageSourcePolicyProps): ImageSourcePolicy;
 
-declare class ChunkStore {
-    private readonly chunks_;
-    private readonly lowestResLOD_;
-    private readonly dimensions_;
-    private readonly views_;
-    private hasHadViews_;
-    private readonly resident_;
-    constructor(dimensions: SourceDimensionMap);
-    getChunkGrid(lod: number, t: number, c: number): Chunk[][][] | undefined;
-    hasChunksAtTime(timeIndex: number): boolean;
-    get lodCount(): number;
-    get channelCount(): number;
-    get dimensions(): SourceDimensionMap;
-    getLowestResLOD(): number;
-    addView(policy: ImageSourcePolicy, axes?: SliceAxes): ChunkStoreView;
-    get views(): ReadonlyArray<ChunkStoreView>;
-    get residentChunks(): ReadonlySet<Chunk>;
-    setChunkTexture(chunk: Chunk, texture: Texture): void;
-    clearChunkTexture(chunk: Chunk): Texture | undefined;
-    canDispose(): boolean;
-    updateAndCollectChunkChanges(): Set<Chunk>;
-    private removeDisposedViews;
-    private aggregateChunkViewStates;
-    private validateXYScaleRatios;
-    private getAndValidateTimeDimension;
-    private getAndValidateChannelDimension;
-}
-
 /**
  * Axis-aligned bounding box defined by minimum and maximum corners.
  *
@@ -377,6 +349,94 @@ declare class ChunkStoreView {
     private squareDistance2D;
 }
 
+declare class ChunkStore {
+    private readonly chunks_;
+    private readonly lowestResLOD_;
+    private readonly dimensions_;
+    private readonly views_;
+    private hasHadViews_;
+    private readonly resident_;
+    constructor(dimensions: SourceDimensionMap);
+    getChunkGrid(lod: number, t: number, c: number): Chunk[][][] | undefined;
+    hasChunksAtTime(timeIndex: number): boolean;
+    get lodCount(): number;
+    get channelCount(): number;
+    get dimensions(): SourceDimensionMap;
+    getLowestResLOD(): number;
+    addView(policy: ImageSourcePolicy, axes?: SliceAxes): ChunkStoreView;
+    get views(): ReadonlyArray<ChunkStoreView>;
+    get residentChunks(): ReadonlySet<Chunk>;
+    setChunkTexture(chunk: Chunk, texture: Texture): void;
+    clearChunkTexture(chunk: Chunk): Texture | undefined;
+    canDispose(): boolean;
+    updateAndCollectChunkChanges(): Set<Chunk>;
+    private removeDisposedViews;
+    private aggregateChunkViewStates;
+    private validateXYScaleRatios;
+    private getAndValidateTimeDimension;
+    private getAndValidateChannelDimension;
+}
+
+/**
+ * A snapshot of chunk demand and GPU residency.
+ *
+ * Requested counts include prefetch. When the memory limit cannot hold every
+ * requested chunk, some are never fetched and `resident` stays below
+ * `requested`.
+ */
+type ChunkStats = {
+    /** Cache state per source. */
+    sources: readonly SourceChunkStats[];
+    /** Loading progress per viewport. Viewports without chunked layers are omitted. */
+    viewports: readonly ViewportChunkStats[];
+};
+/** Cache state for one source, combined across all of its views. */
+type SourceChunkStats = {
+    /** The source the counts describe. */
+    source: ChunkSource;
+    /**
+     * Chunks requested by any view, visible or prefetch, at any LOD. A chunk
+     * requested by several views counts once. The budget may defer fetching.
+     */
+    requested: number;
+    /** How many of `requested` are on the GPU and drawable. */
+    resident: number;
+    /**
+     * The same counts by timepoint index, the position along the source's time
+     * axis rather than the world `t` coordinate. A timepoint is fully loaded for
+     * every view of the source when its two counts are equal.
+     */
+    timepoints: {
+        /** `requested[t]` is the chunks requested at timepoint index `t`. */
+        requested: Uint32Array;
+        /** `resident[t]` is how many of `requested[t]` are on the GPU. */
+        resident: Uint32Array;
+    };
+};
+/** Loading progress for one viewport, summed across its chunked layers. */
+type ViewportChunkStats = {
+    /** The viewport the counts describe. */
+    viewportId: string;
+    /**
+     * Visible and prefetch chunks at any LOD, including the fallback LOD
+     * drawn while the current one loads.
+     */
+    requested: number;
+    /** How many of `requested` are on the GPU. */
+    resident: number;
+    /**
+     * The same counts excluding fallback and prefetch: chunks visible at each
+     * layer's current LOD and timepoint. The viewport is fully drawn at its
+     * selected LOD when these are equal.
+     */
+    current: {
+        /** Chunks visible at each layer's current LOD and timepoint. */
+        requested: number;
+        /** How many of `requested` are on the GPU. */
+        resident: number;
+    };
+};
+
 /**
  * A snapshot of the chunk request queue.
  */
@@ -402,6 +462,7 @@ declare class ChunkManager {
         cpuChunkBytes: number;
         cpuChunkCount: number;
     };
+    get sourceChunkStats(): SourceChunkStats[];
     addView(source: ChunkSource, policy: ImageSourcePolicy, axes?: SliceAxes): ChunkStoreView;
     update(): void;
     private releaseChunk;
@@ -1614,6 +1675,12 @@ declare class Idetik {
     constructor(params: IdetikProps);
     /** Counts of queued and in-flight chunk requests. */
     get chunkQueueStats(): QueueStats;
+    /**
+     * Chunk demand and GPU residency per source, by timepoint, and loading
+     * progress per viewport. Each read walks every view's chunk states and returns a
+     * new snapshot, so poll it at the rate you need rather than every frame.
+     */
+    get chunkStats(): ChunkStats;
     /** A snapshot of current CPU/GPU/JS heap memory usage. */
     get memoryStats(): MemoryStats;
     /** The number of objects drawn in the last rendered frame. */
@@ -1740,24 +1807,24 @@ declare const Image: z.ZodObject<{
                 active: z.ZodOptional<z.ZodBoolean>;
             }, "strip", z.ZodTypeAny, {
                 color?: string | undefined;
+                label?: string | undefined;
                 window?: {
                     min: number;
                     max: number;
                     end: number;
                     start: number;
                 } | undefined;
-                label?: string | undefined;
                 family?: string | undefined;
                 active?: boolean | undefined;
             }, {
                 color?: string | undefined;
+                label?: string | undefined;
                 window?: {
                     min: number;
                     max: number;
                     end: number;
                     start: number;
                 } | undefined;
-                label?: string | undefined;
                 family?: string | undefined;
                 active?: boolean | undefined;
             }>, "many">;
@@ -1780,13 +1847,13 @@ declare const Image: z.ZodObject<{
         }, "strip", z.ZodTypeAny, {
             channels: {
                 color?: string | undefined;
+                label?: string | undefined;
                 window?: {
                     min: number;
                     max: number;
                     end: number;
                     start: number;
                 } | undefined;
-                label?: string | undefined;
                 family?: string | undefined;
                 active?: boolean | undefined;
             }[];
@@ -1799,13 +1866,13 @@ declare const Image: z.ZodObject<{
         }, {
             channels: {
                 color?: string | undefined;
+                label?: string | undefined;
                 window?: {
                     min: number;
                     max: number;
                     end: number;
                     start: number;
                 } | undefined;
-                label?: string | undefined;
                 family?: string | undefined;
                 active?: boolean | undefined;
             }[];
@@ -1832,13 +1899,13 @@ declare const Image: z.ZodObject<{
         omero?: {
             channels: {
                 color?: string | undefined;
+                label?: string | undefined;
                 window?: {
                     min: number;
                     max: number;
                     end: number;
                     start: number;
                 } | undefined;
-                label?: string | undefined;
                 family?: string | undefined;
                 active?: boolean | undefined;
             }[];
@@ -1863,13 +1930,13 @@ declare const Image: z.ZodObject<{
         omero?: {
             channels: {
                 color?: string | undefined;
+                label?: string | undefined;
                 window?: {
                     min: number;
                     max: number;
                     end: number;
                     start: number;
                 } | undefined;
-                label?: string | undefined;
                 family?: string | undefined;
                 active?: boolean | undefined;
             }[];
@@ -1896,13 +1963,13 @@ declare const Image: z.ZodObject<{
         omero?: {
             channels: {
                 color?: string | undefined;
+                label?: string | undefined;
                 window?: {
                     min: number;
                     max: number;
                     end: number;
                     start: number;
                 } | undefined;
-                label?: string | undefined;
                 family?: string | undefined;
                 active?: boolean | undefined;
             }[];
@@ -1929,13 +1996,13 @@ declare const Image: z.ZodObject<{
         omero?: {
             channels: {
                 color?: string | undefined;
+                label?: string | undefined;
                 window?: {
                     min: number;
                     max: number;
                     end: number;
                     start: number;
                 } | undefined;
-                label?: string | undefined;
                 family?: string | undefined;
                 active?: boolean | undefined;
             }[];
@@ -2564,7 +2631,7 @@ declare class ImageLayer extends Layer implements ChannelsEnabled {
      */
     onEvent(event: EventContext): void;
     private pickAtRay;
-    /** The layer's chunk store view for diagnostic overlays. */
+    /** @hidden */
     get chunkStoreView(): ChunkStoreView | undefined;
     /**
      * The slice coordinates the layer displays. This is the object passed
@@ -2753,6 +2820,8 @@ declare class VolumeLayer extends Layer implements ChannelsEnabled {
      */
     update(viewport?: Viewport): void;
     private rebuildObjects;
+    /** @hidden */
+    get chunkStoreView(): ChunkStoreView | undefined;
     /** Returns the ray marching uniforms for this layer. */
     getUniforms(): Record<string, unknown>;
 }
@@ -2999,7 +3068,7 @@ declare class LabelLayer extends Layer {
     get imageSourcePolicy(): Readonly<ImageSourcePolicy>;
     /** @param newPolicy - The policy to apply. */
     set imageSourcePolicy(newPolicy: ImageSourcePolicy);
-    /** The layer's chunk store view for diagnostic overlays. */
+    /** @hidden */
     get chunkStoreView(): ChunkStoreView | undefined;
     /** The `t` coordinate of the most recently presented slice. */
     get lastPresentationTimeCoord(): number | undefined;
@@ -3463,4 +3532,4 @@ declare class OrbitControls implements CameraControls {
 }
 
 export { AxesLayer, Box2, Box3, Camera, Color, Frustum, Idetik, ImageLayer, ImageRenderable, LabelImageRenderable, LabelLayer, Layer, OmeZarrImageSource, OrbitControls, OrthographicCamera, PanZoomControls, PerspectiveCamera, PointsRenderable, ProjectedLineRenderable, RenderableObject, TrsTransform, Viewport, VolumeLayer, VolumeRenderable, createExplorationPolicy, createImageSourcePolicy, createNoPrefetchPolicy, createPlaybackPolicy, loadOmeZarrPlate, loadOmeZarrWell, loadOmeroChannels, loadOmeroDefaults };
-export type { AxesLayerProps, BlendMode, CameraControls, CameraType, ChannelProps, ColorLike, FileSystemOmeZarrImageSourceProps, HttpOmeZarrImageSourceProps, IdetikProps, ImageLayerProps, ImageRenderableProps, ImageSourcePolicy, ImageSourcePolicyProps, LabelColorMap, LabelColorMapProps, LabelImageRenderableProps, LabelLayerProps, LayerProps, LayerState, MemoryStats, OrbitControlsProps, OrthographicCameraFrame, OrthographicCameraProps, Overlay, PanZoomControlsProps, PerspectiveCameraProps, PointPickingResult, PointProps, PriorityCategory, ProjectedLineRenderableProps, QueueStats, SliceCoordinates, SliceOrientation, SourceDimension, SourceDimensionLod, SourceDimensionMap, StateChangeCallback, ViewportProps, VolumeLayerProps, VolumeRenderableProps };
+export type { AxesLayerProps, BlendMode, CameraControls, CameraType, ChannelProps, ChunkStats, ColorLike, FileSystemOmeZarrImageSourceProps, HttpOmeZarrImageSourceProps, IdetikProps, ImageLayerProps, ImageRenderableProps, ImageSourcePolicy, ImageSourcePolicyProps, LabelColorMap, LabelColorMapProps, LabelImageRenderableProps, LabelLayerProps, LayerProps, LayerState, MemoryStats, OrbitControlsProps, OrthographicCameraFrame, OrthographicCameraProps, Overlay, PanZoomControlsProps, PerspectiveCameraProps, PointPickingResult, PointProps, PriorityCategory, ProjectedLineRenderableProps, QueueStats, SliceCoordinates, SliceOrientation, SourceChunkStats, SourceDimension, SourceDimensionLod, SourceDimensionMap, StateChangeCallback, ViewportChunkStats, ViewportProps, VolumeLayerProps, VolumeRenderableProps };