@niivue/niivue 0.67.1-dev.1 → 0.67.1-dev.2

package/build/{nvdocument-B64_4nuJ.d.ts → nvdocument-DrX6RoEG.d.ts}

@@ -448,6 +448,8 @@ type ImageFromUrlOptions = {
     zarrChannel?: number;
     /** Convert OME spatial units to millimeters for NIfTI compatibility (default: true) */
     zarrConvertUnits?: boolean;
+    /** World-space center [x, y, z] in mm where the zarr volume center should be positioned */
+    zarrCenterMM?: [number, number, number];
 };
 type ImageFromFileOptions = {
     file: File | File[];
@@ -747,6 +749,7 @@ declare class NVZarrHelper {
     private voxelTranslations;
     private hasTranslations;
     private convertUnitsToMm;
+    private worldOffsetMM;
     private centerX;
     private centerY;
     private centerZ;
@@ -757,6 +760,7 @@ declare class NVZarrHelper {
     private currentAbortController;
     private runningMin;
     private runningMax;
+    private calibrationDone;
     private updateDebounceTimer;
     private readonly UPDATE_DEBOUNCE_MS;
     private pendingChunkCount;
@@ -814,6 +818,13 @@ declare class NVZarrHelper {
         height: number;
         depth: number;
     };
+    getWorldOffset(): [number, number, number];
+    /**
+     * Set the world-space offset so the full level's center maps to targetMM in world space.
+     * Computes the native physical center of the zarr level, then sets worldOffsetMM
+     * so that center aligns with targetMM. Also centers the viewport on the level center.
+     */
+    setWorldCenter(targetMM: [number, number, number]): void;
     /**
      * Convert physical (mm) coordinates back to real zarr level pixel coordinates.
      * Inverts the affine: levelPixel = (mm - OME_translation) / scale
@@ -953,6 +964,7 @@ declare class NVImage {
     onColormapChange: (img: NVImage) => void;
     onOpacityChange: (img: NVImage) => void;
     zarrHelper: NVZarrHelper | null;
+    _hasExplicitZarrCenter: boolean;
     mm000?: vec3;
     mm100?: vec3;
     mm010?: vec3;
@@ -1056,7 +1068,7 @@ declare class NVImage {
     /**
      * factory function to load and return a new NVImage instance from a given URL
      */
-    static loadFromUrl({ url, urlImgData, headers, name, colormap, opacity, cal_min, cal_max, trustCalMinMax, percentileFrac, ignoreZeroVoxels, useQFormNotSForm, colormapNegative, frame4D, isManifest, limitFrames4D, imageType, colorbarVisible, buffer, zarrLevel, zarrMaxVolumeSize, zarrChannel, zarrConvertUnits }?: Partial<Omit<ImageFromUrlOptions, 'url'>> & {
+    static loadFromUrl({ url, urlImgData, headers, name, colormap, opacity, cal_min, cal_max, trustCalMinMax, percentileFrac, ignoreZeroVoxels, useQFormNotSForm, colormapNegative, frame4D, isManifest, limitFrames4D, imageType, colorbarVisible, buffer, zarrLevel, zarrMaxVolumeSize, zarrChannel, zarrConvertUnits, zarrCenterMM }?: Partial<Omit<ImageFromUrlOptions, 'url'>> & {
         url?: string | Uint8Array | ArrayBuffer;
     }): Promise<NVImage>;
     /**
@@ -1071,6 +1083,7 @@ declare class NVImage {
         convertUnitsToMm?: boolean;
         colormap?: string;
         opacity?: number;
+        zarrCenterMM?: [number, number, number];
     }): Promise<NVImage>;
     static readFileAsync(file: File, bytesToLoad?: number): Promise<ArrayBuffer>;
     /**

package/build/utils/index.d.ts

@@ -1,4 +1,4 @@
-import { ar as Volume, x as NiftiHeader } from '../nvdocument-B64_4nuJ.js';
+import { ar as Volume, x as NiftiHeader } from '../nvdocument-DrX6RoEG.js';
 import { vec3, mat4, vec4 } from 'gl-matrix';
 import 'nifti-reader-js';
 

package/dist/index.d.ts

@@ -245,6 +245,8 @@ type ImageFromUrlOptions = {
     zarrChannel?: number;
     /** Convert OME spatial units to millimeters for NIfTI compatibility (default: true) */
     zarrConvertUnits?: boolean;
+    /** World-space center [x, y, z] in mm where the zarr volume center should be positioned */
+    zarrCenterMM?: [number, number, number];
 };
 type ImageFromFileOptions = {
     file: File | File[];
@@ -544,6 +546,7 @@ declare class NVZarrHelper {
     private voxelTranslations;
     private hasTranslations;
     private convertUnitsToMm;
+    private worldOffsetMM;
     private centerX;
     private centerY;
     private centerZ;
@@ -554,6 +557,7 @@ declare class NVZarrHelper {
     private currentAbortController;
     private runningMin;
     private runningMax;
+    private calibrationDone;
     private updateDebounceTimer;
     private readonly UPDATE_DEBOUNCE_MS;
     private pendingChunkCount;
@@ -611,6 +615,13 @@ declare class NVZarrHelper {
         height: number;
         depth: number;
     };
+    getWorldOffset(): [number, number, number];
+    /**
+     * Set the world-space offset so the full level's center maps to targetMM in world space.
+     * Computes the native physical center of the zarr level, then sets worldOffsetMM
+     * so that center aligns with targetMM. Also centers the viewport on the level center.
+     */
+    setWorldCenter(targetMM: [number, number, number]): void;
     /**
      * Convert physical (mm) coordinates back to real zarr level pixel coordinates.
      * Inverts the affine: levelPixel = (mm - OME_translation) / scale
@@ -750,6 +761,7 @@ declare class NVImage {
     onColormapChange: (img: NVImage) => void;
     onOpacityChange: (img: NVImage) => void;
     zarrHelper: NVZarrHelper | null;
+    _hasExplicitZarrCenter: boolean;
     mm000?: vec3;
     mm100?: vec3;
     mm010?: vec3;
@@ -853,7 +865,7 @@ declare class NVImage {
     /**
      * factory function to load and return a new NVImage instance from a given URL
      */
-    static loadFromUrl({ url, urlImgData, headers, name, colormap, opacity, cal_min, cal_max, trustCalMinMax, percentileFrac, ignoreZeroVoxels, useQFormNotSForm, colormapNegative, frame4D, isManifest, limitFrames4D, imageType, colorbarVisible, buffer, zarrLevel, zarrMaxVolumeSize, zarrChannel, zarrConvertUnits }?: Partial<Omit<ImageFromUrlOptions, 'url'>> & {
+    static loadFromUrl({ url, urlImgData, headers, name, colormap, opacity, cal_min, cal_max, trustCalMinMax, percentileFrac, ignoreZeroVoxels, useQFormNotSForm, colormapNegative, frame4D, isManifest, limitFrames4D, imageType, colorbarVisible, buffer, zarrLevel, zarrMaxVolumeSize, zarrChannel, zarrConvertUnits, zarrCenterMM }?: Partial<Omit<ImageFromUrlOptions, 'url'>> & {
         url?: string | Uint8Array | ArrayBuffer;
     }): Promise<NVImage>;
     /**
@@ -868,6 +880,7 @@ declare class NVImage {
         convertUnitsToMm?: boolean;
         colormap?: string;
         opacity?: number;
+        zarrCenterMM?: [number, number, number];
     }): Promise<NVImage>;
     static readFileAsync(file: File, bytesToLoad?: number): Promise<ArrayBuffer>;
     /**

package/dist/index.js

@@ -5249,7 +5249,7 @@ var forEach3 = (function() {
 // package.json
 var package_default = {
   name: "@niivue/niivue",
-  version: "0.67.1-dev.0",
+  version: "0.67.1-dev.2",
   description: "minimal webgl2 nifti image viewer",
   types: "./build/niivue/index.d.ts",
   main: "./build/niivue/index.js",
@@ -31283,6 +31283,7 @@ var NVZarrHelper = class _NVZarrHelper {
     __publicField(this, "voxelTranslations");
     __publicField(this, "hasTranslations");
     __publicField(this, "convertUnitsToMm");
+    __publicField(this, "worldOffsetMM", [0, 0, 0]);
     __publicField(this, "centerX");
     __publicField(this, "centerY");
     __publicField(this, "centerZ");
@@ -31293,6 +31294,7 @@ var NVZarrHelper = class _NVZarrHelper {
     __publicField(this, "currentAbortController", null);
     __publicField(this, "runningMin", Infinity);
     __publicField(this, "runningMax", -Infinity);
+    __publicField(this, "calibrationDone", false);
     // Debounce state for batching chunk updates
     __publicField(this, "updateDebounceTimer", null);
     __publicField(this, "UPDATE_DEBOUNCE_MS", 50);
@@ -31355,9 +31357,9 @@ var NVZarrHelper = class _NVZarrHelper {
     const level = Math.max(0, Math.min(options.level, helper.pyramidInfo.levels.length - 1));
     helper.pyramidLevel = level;
     helper.updateLevelInfo();
-    helper.centerX = helper.volumeDims.width / 2;
-    helper.centerY = helper.volumeDims.height / 2;
-    helper.centerZ = helper.volumeDims.depth / 2;
+    helper.centerX = helper.levelDims.width / 2;
+    helper.centerY = helper.levelDims.height / 2;
+    helper.centerZ = helper.levelDims.depth / 2;
     helper.configureHostImage();
     return helper;
   }
@@ -31520,6 +31522,9 @@ var NVZarrHelper = class _NVZarrHelper {
         affine[row][col] = niftiCols[col].scale;
         affine[row][3] = niftiCols[col].trans;
       }
+      affine[0][3] += this.worldOffsetMM[0];
+      affine[1][3] += this.worldOffsetMM[1];
+      affine[2][3] += this.worldOffsetMM[2];
       hdr.affine = affine;
     } else {
       const { scaleW, scaleH, scaleD } = this.getConvertedScales();
@@ -31543,12 +31548,15 @@ var NVZarrHelper = class _NVZarrHelper {
           affine[row][col] = niftiCols[col].scale;
           affine[row][3] = niftiCols[col].trans;
         }
+        affine[0][3] += this.worldOffsetMM[0];
+        affine[1][3] += this.worldOffsetMM[1];
+        affine[2][3] += this.worldOffsetMM[2];
         hdr.affine = affine;
       } else {
         hdr.affine = [
-          [scaleW, 0, 0, volStartW * scaleW],
-          [0, -scaleH, 0, volStartH * scaleH],
-          [0, 0, -scaleD, volStartD * scaleD],
+          [scaleW, 0, 0, volStartW * scaleW + this.worldOffsetMM[0]],
+          [0, -scaleH, 0, volStartH * scaleH + this.worldOffsetMM[1]],
+          [0, 0, -scaleD, volStartD * scaleD + this.worldOffsetMM[2]],
           [0, 0, 0, 1]
         ];
       }
@@ -31622,11 +31630,46 @@ var NVZarrHelper = class _NVZarrHelper {
   getVolumeDims() {
     return { ...this.volumeDims };
   }
+  getWorldOffset() {
+    return [...this.worldOffsetMM];
+  }
+  /**
+   * Set the world-space offset so the full level's center maps to targetMM in world space.
+   * Computes the native physical center of the zarr level, then sets worldOffsetMM
+   * so that center aligns with targetMM. Also centers the viewport on the level center.
+   */
+  setWorldCenter(targetMM) {
+    const { scaleW, scaleH, scaleD } = this.getConvertedScales();
+    const { transW, transH, transD } = this.getConvertedTranslations();
+    const axisNames = this.pyramidInfo.axisMapping.spatialAxisNames;
+    const physW = this.levelDims.width / 2 * scaleW + transW;
+    const physH = this.levelDims.height / 2 * scaleH + transH;
+    const physD = this.levelDims.depth / 2 * scaleD + transD;
+    const nativeCenter = [0, 0, 0];
+    const dims = [
+      { name: axisNames[axisNames.length - 1], phys: physW },
+      { name: axisNames[axisNames.length - 2], phys: physH },
+      { name: axisNames.length >= 3 ? axisNames[axisNames.length - 3] : "z", phys: physD }
+    ];
+    for (const d of dims) {
+      const row = d.name === "x" ? 0 : d.name === "y" ? 1 : 2;
+      nativeCenter[row] = d.phys;
+    }
+    this.worldOffsetMM = [targetMM[0] - nativeCenter[0], targetMM[1] - nativeCenter[1], targetMM[2] - nativeCenter[2]];
+    this.centerX = this.levelDims.width / 2;
+    this.centerY = this.levelDims.height / 2;
+    this.centerZ = this.levelDims.depth / 2;
+    this.clampCenter();
+    this.updateAffine();
+  }
   /**
    * Convert physical (mm) coordinates back to real zarr level pixel coordinates.
    * Inverts the affine: levelPixel = (mm - OME_translation) / scale
    */
   mmToLevelCoords(mmX, mmY, mmZ) {
+    mmX -= this.worldOffsetMM[0];
+    mmY -= this.worldOffsetMM[1];
+    mmZ -= this.worldOffsetMM[2];
     const { scaleW, scaleH, scaleD } = this.getConvertedScales();
     const axisNames = this.pyramidInfo.axisMapping.spatialAxisNames;
     const mmByAxis = { x: mmX, y: mmY, z: mmZ };
@@ -31738,8 +31781,6 @@ var NVZarrHelper = class _NVZarrHelper {
         this.currentAbortController?.abort();
         const abortController = new AbortController();
         this.currentAbortController = abortController;
-        this.runningMin = Infinity;
-        this.runningMax = -Infinity;
         await new Promise((resolve2) => {
           requestAnimationFrame(() => resolve2());
         });
@@ -31852,14 +31893,16 @@ var NVZarrHelper = class _NVZarrHelper {
     if (actualChunkW <= 0 || actualChunkH <= 0 || actualChunkD <= 0) {
       return;
     }
-    const step = Math.max(1, Math.floor(data.length / 2e3));
-    for (let i = 0; i < data.length; i += step) {
-      const val = data[i];
-      if (val < this.runningMin) {
-        this.runningMin = val;
-      }
-      if (val > this.runningMax) {
-        this.runningMax = val;
+    if (!this.calibrationDone) {
+      const step = Math.max(1, Math.floor(data.length / 2e3));
+      for (let i = 0; i < data.length; i += step) {
+        const val = data[i];
+        if (val < this.runningMin) {
+          this.runningMin = val;
+        }
+        if (val > this.runningMax) {
+          this.runningMax = val;
+        }
       }
     }
     const fullChunkVol = this.chunkSize.width * this.chunkSize.height * this.chunkSize.depth;
@@ -31890,6 +31933,9 @@ var NVZarrHelper = class _NVZarrHelper {
     }
   }
   updateCalibration() {
+    if (this.calibrationDone) {
+      return;
+    }
     if (this.runningMin < Infinity && this.runningMax > -Infinity) {
       this.hostImage.cal_min = this.runningMin;
       this.hostImage.cal_max = this.runningMax;
@@ -31897,6 +31943,7 @@ var NVZarrHelper = class _NVZarrHelper {
       this.hostImage.robust_max = this.runningMax;
       this.hostImage.global_min = this.runningMin;
       this.hostImage.global_max = this.runningMax;
+      this.calibrationDone = true;
     }
   }
   /**
@@ -31990,6 +32037,7 @@ var NVImage = class _NVImage {
     __publicField(this, "onOpacityChange", () => {
     });
     __publicField(this, "zarrHelper", null);
+    __publicField(this, "_hasExplicitZarrCenter", false);
     __publicField(this, "mm000");
     __publicField(this, "mm100");
     __publicField(this, "mm010");
@@ -32626,7 +32674,8 @@ var NVImage = class _NVImage {
     zarrLevel,
     zarrMaxVolumeSize,
     zarrChannel,
-    zarrConvertUnits
+    zarrConvertUnits,
+    zarrCenterMM
   } = {}) {
     if (url === "") {
       throw Error("url must not be empty");
@@ -32679,7 +32728,8 @@ var NVImage = class _NVImage {
           channel: zarrChannel,
           convertUnitsToMm: zarrConvertUnits,
           colormap,
-          opacity
+          opacity,
+          zarrCenterMM
         });
       }
       const zarrResult = await loadZarrData(url);
@@ -32758,6 +32808,10 @@ var NVImage = class _NVImage {
       cacheSize: options.cacheSize,
       convertUnitsToMm: options.convertUnitsToMm
     });
+    if (options.zarrCenterMM) {
+      nvimage.zarrHelper.setWorldCenter(options.zarrCenterMM);
+      nvimage._hasExplicitZarrCenter = true;
+    }
     if (options.colormap) {
       nvimage._colormap = options.colormap;
     }
@@ -45355,7 +45409,8 @@ var Niivue = class {
         zarrLevel: imageItem.zarrLevel,
         zarrMaxVolumeSize: imageItem.zarrMaxVolumeSize,
         zarrChannel: imageItem.zarrChannel,
-        zarrConvertUnits: imageItem.zarrConvertUnits
+        zarrConvertUnits: imageItem.zarrConvertUnits,
+        zarrCenterMM: imageItem.zarrCenterMM
       };
       const volume = await NVImage.loadFromUrl(imageOptions);
       this.document.addImageOptions(volume, imageOptions);
@@ -45935,6 +45990,20 @@ var Niivue = class {
     this.setVolume(volume, result.index);
     this.onImageLoaded(volume);
     if (volume.zarrHelper) {
+      if (!volume._hasExplicitZarrCenter && this.back && this.back !== volume && this.back.hdr?.dims) {
+        const bg = this.back;
+        const dims = bg.hdr.dims;
+        const affine = bg.hdr.affine;
+        const ci = (dims[1] - 1) / 2;
+        const cj = (dims[2] - 1) / 2;
+        const ck = (dims[3] - 1) / 2;
+        const bgCenter = [
+          affine[0][0] * ci + affine[0][1] * cj + affine[0][2] * ck + affine[0][3],
+          affine[1][0] * ci + affine[1][1] * cj + affine[1][2] * ck + affine[1][3],
+          affine[2][0] * ci + affine[2][1] * cj + affine[2][2] * ck + affine[2][3]
+        ];
+        volume.zarrHelper.setWorldCenter(bgCenter);
+      }
       volume.zarrHelper.onChunksUpdated = () => {
         this.updateGLVolume();
         this._skipDragInDraw = true;