@idetik/core 0.40.3 → 0.42.0

package/README.md

@@ -16,7 +16,7 @@ Idetik is a high-performance library for exploring multi-dimensional OME-Zarr da
 
 #### Documentation
 
-- Guide: https://chanzuckerberg.github.io/idetik/guide/getting-started
+- User guide: https://chanzuckerberg.github.io/idetik/guide/getting-started
 - API reference: https://chanzuckerberg.github.io/idetik/api/
 
 ## Installation

package/dist/index.d.ts

@@ -160,8 +160,13 @@ type ChunkLoader = {
     loadChunkData(chunk: Chunk, signal: AbortSignal): Promise<void>;
 };
 
-declare const ALL_CATEGORIES: readonly ["fallbackVisible", "prefetchTime", "visibleCurrent", "fallbackBackground", "prefetchSpace"];
-type PriorityCategory = (typeof ALL_CATEGORIES)[number];
+/**
+ * A category of chunk request ordered by a loading policy.
+ */
+type PriorityCategory = "fallbackVisible" | "prefetchTime" | "visibleCurrent" | "fallbackBackground" | "prefetchSpace";
+/**
+ * @hidden
+ */
 type ImageSourcePolicyProps = {
     profile?: string;
     prefetch: {
@@ -177,6 +182,13 @@ type ImageSourcePolicyProps = {
         bias?: number;
     };
 };
+/**
+ * A resolved and frozen loading policy consumed by layers.
+ *
+ * Create instances with {@link createExplorationPolicy},
+ * {@link createPlaybackPolicy}, {@link createNoPrefetchPolicy}, or
+ * {@link createImageSourcePolicy} rather than by hand.
+ */
 type ImageSourcePolicy = Readonly<{
     profile: string;
     prefetch: {
@@ -193,14 +205,42 @@ type ImageSourcePolicy = Readonly<{
         bias: number;
     };
 }>;
-/** @hidden */
-declare function createImageSourcePolicy(config: ImageSourcePolicyProps): ImageSourcePolicy;
-/** @hidden */
+/**
+ * Creates a loading policy tuned for interactively browsing a scene.
+ *
+ * Prefetches one chunk beyond the view along each spatial axis and
+ * fills the visible region before prefetching. This is the default
+ * policy for layers constructed without one.
+ *
+ * @param overrides - Properties merged over.
+ */
 declare function createExplorationPolicy(overrides?: Partial<ImageSourcePolicyProps>): ImageSourcePolicy;
-/** @hidden */
+/**
+ * Creates a loading policy tuned for playing through timepoints.
+ *
+ * Prefetches twenty timepoints ahead, buffering at the current LOD
+ * for smooth playback without reduced quality.
+ *
+ * @param overrides - Properties merged over.
+ */
 declare function createPlaybackPolicy(overrides?: Partial<ImageSourcePolicyProps>): ImageSourcePolicy;
-/** @hidden */
+/**
+ * Creates a loading policy with spatial and temporal prefetching disabled.
+ *
+ * No spatial or temporal prefetching happens, which minimizes memory
+ * use and network traffic for static scenes.
+ *
+ * @param overrides - Properties merged over.
+ */
 declare function createNoPrefetchPolicy(overrides?: Partial<ImageSourcePolicyProps>): ImageSourcePolicy;
+/**
+ * Creates a loading policy from explicit properties, validating and
+ * freezing them. Prefer the profile factories for common cases and use
+ * this to build a policy from scratch.
+ *
+ * @param config - Initialization properties.
+ */
+declare function createImageSourcePolicy(config: ImageSourcePolicyProps): ImageSourcePolicy;
 
 declare class ChunkStore {
     private readonly chunks_;
@@ -1262,6 +1302,14 @@ interface CameraControls {
      */
     onEvent(event: EventContext): void;
 }
+type ScrollZoomMode = "always" | "modifier" | "never";
+/**
+ * Initialization properties for constructing pan and zoom controls.
+ */
+type PanZoomControlsProps = {
+    /** When the scroll wheel zooms. Defaults to `"always"`. */
+    scrollZoom?: ScrollZoomMode;
+};
 /**
  * Camera controls for 2D pan and zoom with an orthographic camera.
  *
@@ -1291,14 +1339,16 @@ interface CameraControls {
  */
 declare class PanZoomControls implements CameraControls {
     private readonly camera_;
+    private readonly scrollZoom_;
     private dragActive_;
     private dragStart_;
     /**
      * Creates pan and zoom controls for the given camera.
      *
      * @param camera - The orthographic camera to control.
+     * @param params - Initialization properties.
      */
-    constructor(camera: OrthographicCamera);
+    constructor(camera: OrthographicCamera, params?: PanZoomControlsProps);
     /** Whether a pan drag is in progress. */
     get isMoving(): boolean;
     /**
@@ -3328,6 +3378,8 @@ type OrbitControlsProps = {
     target?: vec3;
     /** Velocity decay rate between `0` and `1`. Defaults to `0.5`. */
     dampingFactor?: number;
+    /** When the scroll wheel zooms. Defaults to `"always"`. */
+    scrollZoom?: ScrollZoomMode;
 };
 /**
  * Camera controls for orbiting a perspective camera around a target.
@@ -3361,6 +3413,7 @@ declare class OrbitControls implements CameraControls {
     private readonly currPos_;
     private readonly currCenter_;
     private readonly dampingFactor_;
+    private readonly scrollZoom_;
     private currMouseButton_;
     /**
      * Creates orbit controls and moves the camera to the initial pose.
@@ -3405,4 +3458,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, LabelColorMap, LabelColorMapProps, LabelImageRenderableProps, LabelLayerProps, LayerProps, LayerState, MemoryStats, OrbitControlsProps, OrthographicCameraFrame, OrthographicCameraProps, Overlay, PerspectiveCameraProps, PointPickingResult, PointProps, ProjectedLineRenderableProps, QueueStats, SliceCoordinates, SliceOrientation, SourceDimension, SourceDimensionLod, SourceDimensionMap, StateChangeCallback, ViewportProps, VolumeLayerProps, VolumeRenderableProps };
+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 };

package/dist/index.js

@@ -2409,44 +2409,44 @@ class JQ {
     return o === this.currentLOD_ ? !1 : (this.currentLOD_ = o, !0);
   }
   markTimeChunksForPrefetchImage(A, I, B, C) {
-    const Q = this.store_.dimensions.t?.lods[0].size ?? 1, E = Math.min(this.policy_.prefetch.t, Q - 1), i = this.fallbackLOD(), o = this.policy_.priorityMap.prefetchTime, a = this.channelsOfInterest(I);
-    for (let s = 1; s <= E; ++s) {
-      const D = (A + s) % Q;
+    const Q = this.store_.dimensions.t?.lods[0].size ?? 1, E = Math.min(this.policy_.prefetch.t, Q - 1), i = this.policy_.priorityMap.prefetchTime, o = this.channelsOfInterest(I);
+    for (let a = 1; a <= E; ++a) {
+      const s = (A + a) % Q;
       this.iterateChunksInBox(
-        D,
-        i,
-        a,
+        s,
+        this.currentLOD_,
+        o,
         B,
-        (h) => {
-          const t = this.squareDistance2D(
-            h,
+        (D) => {
+          const h = this.squareDistance2D(
+            D,
             C
-          ), y = hA(
-            t / this.sourceMaxSquareDistance2D_,
+          ), t = hA(
+            h / this.sourceMaxSquareDistance2D_,
             0,
             1 - Number.EPSILON
-          ), n = s + y;
-          this.chunkViewStates_.set(h, {
+          ), y = a + t;
+          this.chunkViewStates_.set(D, {
             visible: !1,
             prefetch: !0,
-            priority: o,
-            orderKey: n
+            priority: i,
+            orderKey: y
           });
         }
       );
     }
   }
   markTimeChunksForPrefetchVolume(A, I) {
-    const B = this.store_.dimensions.t?.lods[0].size ?? 1, C = Math.min(this.policy_.prefetch.t, B - 1), Q = this.fallbackLOD(), E = this.policy_.priorityMap.prefetchTime, i = this.channelsOfInterest(I);
-    for (let o = 1; o <= C; ++o) {
-      const a = (A + o) % B;
-      this.iterateAllChunksAtLod(a, Q, i, (s) => {
-        const D = o;
-        this.chunkViewStates_.set(s, {
+    const B = this.store_.dimensions.t?.lods[0].size ?? 1, C = Math.min(this.policy_.prefetch.t, B - 1), Q = this.policy_.priorityMap.prefetchTime, E = this.channelsOfInterest(I);
+    for (let i = 1; i <= C; ++i) {
+      const o = (A + i) % B;
+      this.iterateAllChunksAtLod(o, this.currentLOD_, E, (a) => {
+        const s = i;
+        this.chunkViewStates_.set(a, {
           visible: !1,
           prefetch: !0,
-          priority: E,
-          orderKey: D
+          priority: Q,
+          orderKey: s
         });
       });
     }
@@ -12828,36 +12828,8 @@ const nC = [
   "fallbackBackground",
   "prefetchSpace"
 ];
-function mg(g) {
-  mi(g);
-  const A = {
-    x: g.prefetch.x,
-    y: g.prefetch.y,
-    z: g.prefetch.z ?? 0,
-    t: g.prefetch.t ?? 0
-  }, I = Object.freeze(
-    nC.reduce(
-      (Q, E) => {
-        const i = g.priorityOrder.indexOf(E);
-        return Q[E] = i, Q;
-      },
-      {}
-    )
-  ), B = {
-    min: g.lod?.min ?? 0,
-    max: g.lod?.max ?? Number.MAX_SAFE_INTEGER,
-    bias: g.lod?.bias ?? 0.5
-  }, C = {
-    profile: g.profile ?? "custom",
-    prefetch: A,
-    priorityOrder: Object.freeze([...g.priorityOrder]),
-    priorityMap: I,
-    lod: B
-  };
-  return Object.freeze(C);
-}
-function ug(g = {}) {
-  return mg(Tg({
+function mg(g = {}) {
+  return ug(Tg({
     profile: "exploration",
     prefetch: { x: 1, y: 1, z: 1, t: 0 },
     priorityOrder: [
@@ -12870,20 +12842,20 @@ function ug(g = {}) {
   }, g));
 }
 function No(g = {}) {
-  return mg(Tg({
+  return ug(Tg({
     profile: "playback",
     prefetch: { x: 0, y: 0, z: 0, t: 20 },
     priorityOrder: [
       "fallbackVisible",
-      "prefetchTime",
       "visibleCurrent",
+      "prefetchTime",
       "fallbackBackground",
       "prefetchSpace"
     ]
   }, g));
 }
 function co(g = {}) {
-  return mg(Tg({
+  return ug(Tg({
     profile: "no-prefetch",
     prefetch: { x: 0, y: 0, z: 0, t: 0 },
     priorityOrder: [
@@ -12895,6 +12867,34 @@ function co(g = {}) {
     ]
   }, g));
 }
+function ug(g) {
+  mi(g);
+  const A = {
+    x: g.prefetch.x,
+    y: g.prefetch.y,
+    z: g.prefetch.z ?? 0,
+    t: g.prefetch.t ?? 0
+  }, I = Object.freeze(
+    nC.reduce(
+      (Q, E) => {
+        const i = g.priorityOrder.indexOf(E);
+        return Q[E] = i, Q;
+      },
+      {}
+    )
+  ), B = {
+    min: g.lod?.min ?? 0,
+    max: g.lod?.max ?? Number.MAX_SAFE_INTEGER,
+    bias: g.lod?.bias ?? 0.5
+  }, C = {
+    profile: g.profile ?? "custom",
+    prefetch: A,
+    priorityOrder: Object.freeze([...g.priorityOrder]),
+    priorityMap: I,
+    lod: B
+  };
+  return Object.freeze(C);
+}
 function mi(g) {
   for (const [B, C] of Object.entries(g.prefetch))
     if (C !== void 0 && C < 0)
@@ -13166,7 +13166,7 @@ class rC extends qI {
     onPickValue: E,
     ...i
   }) {
-    super({ blendMode: "additive", occludes: !0, ...i }), this.setState("initialized"), this.source_ = A, this.policy_ = B ?? ug(), this.sliceCoords_ = I, this.orientation_ = C ?? "XY", this.axes_ = MA(this.orientation_), this.planeRotation_ = dA(this.axes_), this.channelProps_ = Q, this.initialChannelProps_ = Q, this.onPickValue_ = E;
+    super({ blendMode: "additive", occludes: !0, ...i }), this.setState("initialized"), this.source_ = A, this.policy_ = B ?? mg(), this.sliceCoords_ = I, this.orientation_ = C ?? "XY", this.axes_ = MA(this.orientation_), this.planeRotation_ = dA(this.axes_), this.channelProps_ = Q, this.initialChannelProps_ = Q, this.onPickValue_ = E;
   }
   /** @hidden */
   attach(A) {
@@ -13748,7 +13748,7 @@ class Uo extends qI {
    * @param props - Initialization properties.
    */
   constructor({ source: A, sliceCoords: I, policy: B, channelProps: C }) {
-    super({ blendMode: "premultipliedOver" }), this.source_ = A, this.sliceCoords_ = I, this.policy_ = B ?? ug(), this.initialChannelProps_ = C, this.channelProps_ = C, this.setState("initialized");
+    super({ blendMode: "premultipliedOver" }), this.source_ = A, this.sliceCoords_ = I, this.policy_ = B ?? mg(), this.initialChannelProps_ = C, this.channelProps_ = C, this.setState("initialized");
   }
   getOrCreateVolume(A, I) {
     const B = this.currentVolumes_.get(A);
@@ -14036,7 +14036,7 @@ class RC extends qI {
     outlineSelected: i = !1,
     ...o
   }) {
-    super(o), this.setState("initialized"), this.source_ = A, this.policy_ = B ?? ug(), this.sliceCoords_ = I, this.orientation_ = C ?? "XY", this.axes_ = MA(this.orientation_), this.planeRotation_ = dA(this.axes_), this.colorMap_ = JI(Q), this.onPickValue_ = E, this.outlineSelected_ = i;
+    super(o), this.setState("initialized"), this.source_ = A, this.policy_ = B ?? mg(), this.sliceCoords_ = I, this.orientation_ = C ?? "XY", this.axes_ = MA(this.orientation_), this.planeRotation_ = dA(this.axes_), this.colorMap_ = JI(Q), this.onPickValue_ = E, this.outlineSelected_ = i;
   }
   /** @hidden */
   attach(A) {
@@ -14537,6 +14537,7 @@ class Lo {
   currPos_;
   currCenter_ = d();
   dampingFactor_;
+  scrollZoom_;
   currMouseButton_ = vI;
   /**
    * Creates orbit controls and moves the camera to the initial pose.
@@ -14553,7 +14554,7 @@ class Lo {
       I?.dampingFactor ?? so,
       0,
       1
-    ), this.updateCamera();
+    ), this.scrollZoom_ = I?.scrollZoom ?? "always", this.updateCamera();
   }
   /** The current distance from the target in world units. */
   get radius() {
@@ -14624,6 +14625,7 @@ class Lo {
   }
   onWheel(A) {
     const I = A.event;
+    if (this.scrollZoom_ === "never" || this.scrollZoom_ === "modifier" && !(I.ctrlKey || I.metaKey)) return;
     I.preventDefault();
     const B = I.deltaY ?? 0;
     this.zoom(B);
@@ -14771,15 +14773,17 @@ class Jo extends cC {
 const PB = 0;
 class Yo {
   camera_;
+  scrollZoom_;
   dragActive_ = !1;
   dragStart_ = d();
   /**
    * Creates pan and zoom controls for the given camera.
    *
    * @param camera - The orthographic camera to control.
+   * @param params - Initialization properties.
    */
-  constructor(A) {
-    this.camera_ = A;
+  constructor(A, I) {
+    this.camera_ = A, this.scrollZoom_ = I?.scrollZoom ?? "always";
   }
   /** Whether a pan drag is in progress. */
   get isMoving() {
@@ -14818,6 +14822,7 @@ class Yo {
   onWheel(A) {
     if (!A.worldPos || !A.clipPos) return;
     const I = A.event;
+    if (this.scrollZoom_ === "never" || this.scrollZoom_ === "modifier" && !(I.ctrlKey || I.metaKey)) return;
     I.preventDefault();
     const B = EA(A.worldPos), C = I.deltaY < 0 ? 1.05 : 0.95;
     this.camera_.zoom(C);
@@ -14930,8 +14935,8 @@ export {
   uQ as Viewport,
   Uo as VolumeLayer,
   bi as VolumeRenderable,
-  ug as createExplorationPolicy,
-  mg as createImageSourcePolicy,
+  mg as createExplorationPolicy,
+  ug as createImageSourcePolicy,
   co as createNoPrefetchPolicy,
   No as createPlaybackPolicy,
   wo as loadOmeZarrPlate,