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

package/package.json

@@ -1,114 +1,114 @@
 {
-  "name": "@niivue/niivue",
-  "version": "0.67.1-dev.1",
-  "description": "minimal webgl2 nifti image viewer",
-  "types": "./build/niivue/index.d.ts",
-  "main": "./build/niivue/index.js",
-  "type": "module",
-  "unpkg": "./dist/index.min.js",
-  "module": "./build/niivue/index.js",
-  "exports": {
-    ".": {
-      "import": "./build/niivue/index.js",
-      "types": "./build/niivue/index.d.ts"
+    "name": "@niivue/niivue",
+    "version": "0.67.1-dev.2",
+    "description": "minimal webgl2 nifti image viewer",
+    "types": "./build/niivue/index.d.ts",
+    "main": "./build/niivue/index.js",
+    "type": "module",
+    "unpkg": "./dist/index.min.js",
+    "module": "./build/niivue/index.js",
+    "exports": {
+        ".": {
+            "import": "./build/niivue/index.js",
+            "types": "./build/niivue/index.d.ts"
+        },
+        "./drawing": {
+            "import": "./build/drawing/index.js",
+            "types": "./build/drawing/index.d.ts"
+        },
+        "./utils": {
+            "import": "./build/utils/index.js",
+            "types": "./build/utils/index.d.ts"
+        },
+        "./min": {
+            "import": "./build/index.min.js"
+        }
     },
-    "./drawing": {
-      "import": "./build/drawing/index.js",
-      "types": "./build/drawing/index.d.ts"
+    "scripts": {
+        "dev": "vite",
+        "build:umd": "vite build --config vite.config.js --base=./ && vite build --config vite.config_inject.js --base=./",
+        "build": "tsup --config tsup.config.ts && npm run build:forTests && npm run build:min && npm run build:umd",
+        "build:forTests": "tsup --config tsup.config.tests.ts && npm run build:mindemos",
+        "build:min": "node bundle.js",
+        "build:mindemos": "node bundleForDemos.js",
+        "demo": "npm run build:forTests && rm -rf demos/dist && cp -r dist demos/dist && npx http-server demos/ --cors",
+        "demo-win": "npm run build && npx http-server demos/",
+        "test": "npm run build:forTests && npm run test:unit && jest --maxWorkers=1",
+        "test-win": "npm run build-win && jest",
+        "test-playwright": "npx playwright test --grep-invert \"niivue demo file:\"",
+        "test-demos": "npx playwright test playwright/e2e/test.demos.spec.ts",
+        "docs": "typedoc && rm -rf ../docs/docs/api && cp -r devdocs ../docs/docs/api",
+        "test:unit": "vitest --run --coverage",
+        "serve-docs": "npx http-server devdocs",
+        "pub": "npm run build && npm publish --access public",
+        "lint": "eslint . --ext .ts",
+        "lint:ts": "tsc --noEmit",
+        "lint:fix": "eslint --fix . --ext .ts",
+        "lint:debug": "DEBUG=eslint:cli-engine eslint . --ext .ts",
+        "pretest-playwright": "npm run build:forTests && node preplaywrighttest.cjs && tsc --incremental -p playwright/e2e/tsconfig.json",
+        "pretest-demos": "npm run build:forTests && node preplaywrighttest.cjs && tsc --incremental -p playwright/e2e/tsconfig.json"
     },
-    "./utils": {
-      "import": "./build/utils/index.js",
-      "types": "./build/utils/index.d.ts"
+    "files": [
+        "src",
+        "build",
+        "dist"
+    ],
+    "repository": {
+        "type": "git",
+        "url": "git+https://github.com/niivue/niivue.git"
     },
-    "./min": {
-      "import": "./build/index.min.js"
+    "keywords": [
+        "niivue",
+        "webgl2",
+        "nifti",
+        "image",
+        "viewer"
+    ],
+    "author": "niivue authors",
+    "license": "BSD-2-Clause",
+    "bugs": {
+        "url": "https://github.com/niivue/niivue/issues"
+    },
+    "homepage": "https://github.com/niivue/niivue#readme",
+    "dependencies": {
+        "@lukeed/uuid": "^2.0.1",
+        "@ungap/structured-clone": "^1.2.0",
+        "array-equal": "^1.0.2",
+        "fflate": "^0.8.2",
+        "gl-matrix": "^3.4.3",
+        "nifti-reader-js": "^0.8.0",
+        "zarrita": "^0.5.0"
+    },
+    "devDependencies": {
+        "@playwright/test": "^1.45.2",
+        "@rollup/plugin-commonjs": "^26.0.1",
+        "@types/array-equal": "^1.0.2",
+        "@types/node": "^20.14.11",
+        "@types/ungap__structured-clone": "^1.2.0",
+        "@typescript-eslint/eslint-plugin": "^7.16.1",
+        "@typescript-eslint/parser": "^7.16.1",
+        "@vitest/coverage-v8": "^3.1.3",
+        "esbuild": "^0.25.12",
+        "eslint": "^8.57.0",
+        "eslint-config-prettier": "^9.1.0",
+        "eslint-config-standard": "^17.1.0",
+        "eslint-plugin-prettier": "^5.2.1",
+        "eslint-plugin-tsdoc": "^0.3.0",
+        "express": "^4.19.2",
+        "happy-dom": "^20.0.11",
+        "http-server": "^14.1.1",
+        "prettier": "^3.3.3",
+        "regenerator-runtime": "^0.14.1",
+        "terser": "^5.31.3",
+        "tsup": "^8.1.2",
+        "typedoc": "^0.28.5",
+        "typedoc-docusaurus-theme": "^1.4.0",
+        "typedoc-plugin-markdown": "^4.7.0",
+        "typescript": "^5.5.3",
+        "vite": "^7.2.7",
+        "vitest": "^3.1.3"
+    },
+    "optionalDependencies": {
+        "@rollup/rollup-linux-x64-gnu": "^4.18.1"
     }
-  },
-  "scripts": {
-    "dev": "vite",
-    "build:umd": "vite build --config vite.config.js --base=./ && vite build --config vite.config_inject.js --base=./",
-    "build": "tsup --config tsup.config.ts && npm run build:forTests && npm run build:min && npm run build:umd",
-    "build:forTests": "tsup --config tsup.config.tests.ts && npm run build:mindemos",
-    "build:min": "node bundle.js",
-    "build:mindemos": "node bundleForDemos.js",
-    "demo": "npm run build:forTests && rm -rf demos/dist && cp -r dist demos/dist && npx http-server demos/ --cors",
-    "demo-win": "npm run build && npx http-server demos/",
-    "test": "npm run build:forTests && npm run test:unit && jest --maxWorkers=1",
-    "test-win": "npm run build-win && jest",
-    "test-playwright": "npx playwright test --grep-invert \"niivue demo file:\"",
-    "test-demos": "npx playwright test playwright/e2e/test.demos.spec.ts",
-    "docs": "typedoc && rm -rf ../docs/docs/api && cp -r devdocs ../docs/docs/api",
-    "test:unit": "vitest --run --coverage",
-    "serve-docs": "npx http-server devdocs",
-    "pub": "npm run build && npm publish --access public",
-    "lint": "eslint . --ext .ts",
-    "lint:ts": "tsc --noEmit",
-    "lint:fix": "eslint --fix . --ext .ts",
-    "lint:debug": "DEBUG=eslint:cli-engine eslint . --ext .ts",
-    "pretest-playwright": "npm run build:forTests && node preplaywrighttest.cjs && tsc --incremental -p playwright/e2e/tsconfig.json",
-    "pretest-demos": "npm run build:forTests && node preplaywrighttest.cjs && tsc --incremental -p playwright/e2e/tsconfig.json"
-  },
-  "files": [
-    "src",
-    "build",
-    "dist"
-  ],
-  "repository": {
-    "type": "git",
-    "url": "git+https://github.com/niivue/niivue.git"
-  },
-  "keywords": [
-    "niivue",
-    "webgl2",
-    "nifti",
-    "image",
-    "viewer"
-  ],
-  "author": "niivue authors",
-  "license": "BSD-2-Clause",
-  "bugs": {
-    "url": "https://github.com/niivue/niivue/issues"
-  },
-  "homepage": "https://github.com/niivue/niivue#readme",
-  "dependencies": {
-    "@lukeed/uuid": "^2.0.1",
-    "@ungap/structured-clone": "^1.2.0",
-    "array-equal": "^1.0.2",
-    "fflate": "^0.8.2",
-    "gl-matrix": "^3.4.3",
-    "nifti-reader-js": "^0.8.0",
-    "zarrita": "^0.5.0"
-  },
-  "devDependencies": {
-    "@playwright/test": "^1.45.2",
-    "@rollup/plugin-commonjs": "^26.0.1",
-    "@types/array-equal": "^1.0.2",
-    "@types/node": "^20.14.11",
-    "@types/ungap__structured-clone": "^1.2.0",
-    "@typescript-eslint/eslint-plugin": "^7.16.1",
-    "@typescript-eslint/parser": "^7.16.1",
-    "@vitest/coverage-v8": "^3.1.3",
-    "esbuild": "^0.25.12",
-    "eslint": "^8.57.0",
-    "eslint-config-prettier": "^9.1.0",
-    "eslint-config-standard": "^17.1.0",
-    "eslint-plugin-prettier": "^5.2.1",
-    "eslint-plugin-tsdoc": "^0.3.0",
-    "express": "^4.19.2",
-    "happy-dom": "^20.0.11",
-    "http-server": "^14.1.1",
-    "prettier": "^3.3.3",
-    "regenerator-runtime": "^0.14.1",
-    "terser": "^5.31.3",
-    "tsup": "^8.1.2",
-    "typedoc": "^0.28.5",
-    "typedoc-docusaurus-theme": "^1.4.0",
-    "typedoc-plugin-markdown": "^4.7.0",
-    "typescript": "^5.5.3",
-    "vite": "^7.2.7",
-    "vitest": "^3.1.3"
-  },
-  "optionalDependencies": {
-    "@rollup/rollup-linux-x64-gnu": "^4.18.1"
-  }
-}
+}

package/src/niivue/index.ts

@@ -2508,7 +2508,8 @@ export class Niivue {
                 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)
@@ -3165,6 +3166,22 @@ export class Niivue {
         // Register the callback BEFORE loading initial chunks so the first
         // batch of data triggers a proper GPU upload and render.
         if (volume.zarrHelper) {
+            // Auto-center zarr overlay on background volume if no explicit position was given
+            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: [number, number, number] = [
+                    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 = (): void => {
                 this.updateGLVolume()
                 this._skipDragInDraw = true

package/src/nvimage/index.ts

@@ -89,6 +89,7 @@ export class NVImage {
     onOpacityChange: (img: NVImage) => void = () => {}
 
     zarrHelper: NVZarrHelper | null = null
+    _hasExplicitZarrCenter = false
 
     mm000?: vec3
     mm100?: vec3
@@ -865,7 +866,8 @@ export class NVImage {
         zarrLevel,
         zarrMaxVolumeSize,
         zarrChannel,
-        zarrConvertUnits
+        zarrConvertUnits,
+        zarrCenterMM
     }: Partial<Omit<ImageFromUrlOptions, 'url'>> & { url?: string | Uint8Array | ArrayBuffer } = {}): Promise<NVImage> {
         if (url === '') {
             throw Error('url must not be empty')
@@ -924,7 +926,8 @@ export class NVImage {
                     channel: zarrChannel,
                     convertUnitsToMm: zarrConvertUnits,
                     colormap,
-                    opacity
+                    opacity,
+                    zarrCenterMM
                 })
             }
             // Light path: load entire array (unchanged)
@@ -1014,6 +1017,7 @@ export class NVImage {
             convertUnitsToMm?: boolean
             colormap?: string
             opacity?: number
+            zarrCenterMM?: [number, number, number]
         }
     ): Promise<NVImage> {
         const nvimage = new NVImage()
@@ -1026,6 +1030,10 @@ export 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
         }

package/src/nvimage/utils.ts

@@ -210,6 +210,8 @@ export 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]
 }
 
 // TODO centralize shared options

package/src/nvimage/zarr/NVZarrHelper.ts

@@ -158,6 +158,7 @@ export class NVZarrHelper {
     private voxelTranslations: { width: number; height: number; depth: number }
     private hasTranslations: boolean
     private convertUnitsToMm: boolean
+    private worldOffsetMM: [number, number, number] = [0, 0, 0]
 
     private centerX: number
     private centerY: number
@@ -171,6 +172,7 @@ export class NVZarrHelper {
     private currentAbortController: AbortController | null = null
     private runningMin = Infinity
     private runningMax = -Infinity
+    private calibrationDone = false
 
     // Debounce state for batching chunk updates
     private updateDebounceTimer: ReturnType<typeof setTimeout> | null = null
@@ -250,10 +252,10 @@ export class NVZarrHelper {
         helper.pyramidLevel = level
         helper.updateLevelInfo()
 
-        // Center on the level
-        helper.centerX = helper.volumeDims.width / 2
-        helper.centerY = helper.volumeDims.height / 2
-        helper.centerZ = helper.volumeDims.depth / 2
+        // Center on the level (use levelDims so initial view shows the center of the zarr)
+        helper.centerX = helper.levelDims.width / 2
+        helper.centerY = helper.levelDims.height / 2
+        helper.centerZ = helper.levelDims.depth / 2
 
         // Configure the host NVImage
         helper.configureHostImage()
@@ -457,6 +459,9 @@ export 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 {
             // No OME translations — calculate offset based on pan position
@@ -487,13 +492,16 @@ export 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 {
                 // Fallback: simple diagonal affine with pan position
                 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]
                 ]
             }
@@ -591,6 +599,48 @@ export class NVZarrHelper {
         return { ...this.volumeDims }
     }
 
+    getWorldOffset(): [number, number, number] {
+        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: [number, number, number]): void {
+        const { scaleW, scaleH, scaleD } = this.getConvertedScales()
+        const { transW, transH, transD } = this.getConvertedTranslations()
+        const axisNames = this.pyramidInfo.axisMapping.spatialAxisNames
+
+        // Native physical center per OME dim (width=last, height=2nd-to-last, depth=3rd-to-last)
+        const physW = (this.levelDims.width / 2) * scaleW + transW
+        const physH = (this.levelDims.height / 2) * scaleH + transH
+        const physD = (this.levelDims.depth / 2) * scaleD + transD
+
+        // Map OME dims to x/y/z rows using axis names
+        const nativeCenter: [number, number, number] = [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]]
+
+        // Center viewport on level center so visible region is at the target
+        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
@@ -606,6 +656,11 @@ export class NVZarrHelper {
         level: number
         levelDims: { width: number; height: number; depth: number }
     } {
+        // Subtract world offset to convert from offset world-space back to native zarr space
+        mmX -= this.worldOffsetMM[0]
+        mmY -= this.worldOffsetMM[1]
+        mmZ -= this.worldOffsetMM[2]
+
         const { scaleW, scaleH, scaleD } = this.getConvertedScales()
         const axisNames = this.pyramidInfo.axisMapping.spatialAxisNames
 
@@ -742,9 +797,6 @@ export class NVZarrHelper {
                 const abortController = new AbortController()
                 this.currentAbortController = abortController
 
-                this.runningMin = Infinity
-                this.runningMax = -Infinity
-
                 await new Promise<void>((resolve) => {
                     requestAnimationFrame(() => resolve())
                 })
@@ -891,15 +943,17 @@ export class NVZarrHelper {
             return
         }
 
-        // Track min/max for calibration
-        const step = Math.max(1, Math.floor(data.length / 2000))
-        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
+        // Track min/max for initial calibration (skipped once calibration is done)
+        if (!this.calibrationDone) {
+            const step = Math.max(1, Math.floor(data.length / 2000))
+            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
+                }
             }
         }
 
@@ -940,6 +994,9 @@ export class NVZarrHelper {
     }
 
     private updateCalibration(): void {
+        if (this.calibrationDone) {
+            return
+        }
         if (this.runningMin < Infinity && this.runningMax > -Infinity) {
             this.hostImage.cal_min = this.runningMin
             this.hostImage.cal_max = this.runningMax
@@ -947,6 +1004,7 @@ export class NVZarrHelper {
             this.hostImage.robust_max = this.runningMax
             this.hostImage.global_min = this.runningMin
             this.hostImage.global_max = this.runningMax
+            this.calibrationDone = true
         }
     }