@niivue/nvreact 0.1.0 → 0.1.2

package/LICENSE

@@ -0,0 +1,24 @@
+BSD 2-Clause License
+
+Copyright (c) 2026, hanayik
+
+Redistribution and use in source and binary forms, with or without
+modification, are permitted provided that the following conditions are met:
+
+1. Redistributions of source code must retain the above copyright notice, this
+   list of conditions and the following disclaimer.
+
+2. Redistributions in binary form must reproduce the above copyright notice,
+   this list of conditions and the following disclaimer in the documentation
+   and/or other materials provided with the distribution.
+
+THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS "AS IS"
+AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE
+IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE ARE
+DISCLAIMED. IN NO EVENT SHALL THE COPYRIGHT HOLDER OR CONTRIBUTORS BE LIABLE
+FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL
+DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR
+SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER
+CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY,
+OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE
+OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE.

package/README.md

@@ -95,6 +95,10 @@ useSceneEvent(scene, "viewerCreated", (nv, index) => {
 useSceneEvent(scene, "imageLoaded", (viewerIndex, volume) => {
   console.log(`loaded ${volume.name} in viewer ${viewerIndex}`);
 });
+
+useSceneEvent(scene, "locationChange", (viewerIndex, data) => {
+  console.log(`viewer ${viewerIndex}: ${data.string}`);
+});
 ```
 
 #### Events

package/dist/lib.js

@@ -324,21 +324,43 @@ class NvSceneController {
   forEachNiivue(callback) {
     this.viewers.forEach((viewer, i) => callback(viewer.niivue, i));
   }
+  hasSyncableContent(nv) {
+    return nv.volumes.length > 0 || nv.meshes.length > 0;
+  }
+  safeBroadcastTo(index, targets) {
+    const viewer = this.viewers[index];
+    if (!viewer)
+      return;
+    try {
+      viewer.niivue.broadcastTo(targets, this.broadcastOptions);
+    } catch (err) {
+      this.addError(viewer.id, err);
+      this.emit("error", index, err);
+    }
+  }
+  rewireBroadcasting() {
+    if (!this.broadcasting) {
+      this.viewers.forEach((_viewer, index) => {
+        this.safeBroadcastTo(index, []);
+      });
+      return;
+    }
+    const syncableViewers = this.viewers.filter((viewer) => this.hasSyncableContent(viewer.niivue));
+    this.viewers.forEach((viewer, index) => {
+      if (!this.hasSyncableContent(viewer.niivue)) {
+        this.safeBroadcastTo(index, []);
+        return;
+      }
+      const others = syncableViewers.filter((v) => v.id !== viewer.id).map((v) => v.niivue);
+      this.safeBroadcastTo(index, others);
+    });
+  }
   setBroadcasting(enabled, options) {
     this.broadcasting = enabled;
     if (options) {
       this.broadcastOptions = { ...this.broadcastOptions, ...options };
     }
-    if (enabled) {
-      this.viewers.forEach((viewer) => {
-        const others = this.viewers.filter((v) => v.id !== viewer.id).map((v) => v.niivue);
-        viewer.niivue.broadcastTo(others, this.broadcastOptions);
-      });
-    } else {
-      this.viewers.forEach((viewer) => {
-        viewer.niivue.broadcastTo([], this.broadcastOptions);
-      });
-    }
+    this.rewireBroadcasting();
     this.notify();
   }
   isBroadcasting() {
@@ -381,6 +403,9 @@ class NvSceneController {
     try {
       const image = await viewer.niivue.addVolumeFromUrl(opts);
       this.emit("volumeAdded", index, opts, image);
+      if (this.broadcasting) {
+        this.rewireBroadcasting();
+      }
       return image;
     } catch (err) {
       this.addError(viewer.id, err);
@@ -406,9 +431,49 @@ class NvSceneController {
     if (vol) {
       nv.removeVolume(vol);
       this.emit("volumeRemoved", index, url);
+      if (this.broadcasting) {
+        this.rewireBroadcasting();
+      }
       this.notify();
     }
   }
+  findVolume(viewerIndex, volumeIndex) {
+    const viewer = this.viewers[viewerIndex];
+    if (!viewer)
+      return;
+    const nv = viewer.niivue;
+    const vol = nv.volumes[volumeIndex];
+    if (!vol)
+      return;
+    return { nv, vol, volumeIndex };
+  }
+  setColormap(viewerIndex, volumeIndex, colormap) {
+    const found = this.findVolume(viewerIndex, volumeIndex);
+    if (!found)
+      return;
+    found.vol.colormap = colormap;
+    found.nv.updateGLVolume();
+    this.emit("colormapChanged", viewerIndex, volumeIndex, colormap);
+    this.notify();
+  }
+  setCalMinMax(viewerIndex, volumeIndex, cal_min, cal_max) {
+    const found = this.findVolume(viewerIndex, volumeIndex);
+    if (!found)
+      return;
+    found.vol.cal_min = cal_min;
+    found.vol.cal_max = cal_max;
+    found.nv.updateGLVolume();
+    this.emit("intensityChanged", viewerIndex, volumeIndex, cal_min, cal_max);
+    this.notify();
+  }
+  setOpacity(viewerIndex, volumeIndex, opacity) {
+    const found = this.findVolume(viewerIndex, volumeIndex);
+    if (!found)
+      return;
+    found.nv.setOpacity(volumeIndex, opacity);
+    this.emit("opacityChanged", viewerIndex, volumeIndex, opacity);
+    this.notify();
+  }
   incrementLoading(id) {
     this.loadingCounts.set(id, (this.loadingCounts.get(id) ?? 0) + 1);
     this.notify();
@@ -464,6 +529,14 @@ class NvSceneController {
     };
     niivue.onImageLoaded = (vol) => {
       this.emit("imageLoaded", index, vol);
+      if (this.broadcasting) {
+        this.rewireBroadcasting();
+      }
+    };
+    niivue.onMeshLoaded = (_mesh) => {
+      if (this.broadcasting) {
+        this.rewireBroadcasting();
+      }
     };
     if (this.broadcasting) {
       this.setBroadcasting(true);
@@ -530,6 +603,14 @@ class NvSceneController {
 
 // src/nvviewer.tsx
 import { jsxDEV as jsxDEV2 } from "react/jsx-dev-runtime";
+function extractVisualProps(opts) {
+  return {
+    colormap: opts.colormap ?? opts.colorMap,
+    cal_min: opts.cal_min,
+    cal_max: opts.cal_max,
+    opacity: opts.opacity
+  };
+}
 var NvViewer = ({
   volumes,
   options,
@@ -542,7 +623,7 @@ var NvViewer = ({
 }) => {
   const containerRef = useRef2(null);
   const nvRef = useRef2(null);
-  const loadedUrlsRef = useRef2(new Set);
+  const loadedVolumesRef = useRef2(new Map);
   const onLocationChangeRef = useRef2(onLocationChange);
   onLocationChangeRef.current = onLocationChange;
   const onImageLoadedRef = useRef2(onImageLoaded);
@@ -592,7 +673,7 @@ var NvViewer = ({
       canvas.height = 0;
       canvas.remove();
       nvRef.current = null;
-      loadedUrlsRef.current.clear();
+      loadedVolumesRef.current.clear();
     };
   }, []);
   useEffect2(() => {
@@ -603,24 +684,52 @@ var NvViewer = ({
     if (!nv)
       return;
     const desiredUrls = new Set((volumes ?? []).map((v) => v.url));
-    const currentUrls = loadedUrlsRef.current;
-    for (const url of currentUrls) {
+    const currentVolumes = loadedVolumesRef.current;
+    for (const url of currentVolumes.keys()) {
       if (!desiredUrls.has(url)) {
         const vol = nv.volumes.find((v) => v.url === url || v.name === url);
         if (vol)
           nv.removeVolume(vol);
-        currentUrls.delete(url);
+        currentVolumes.delete(url);
       }
     }
+    let needsGLUpdate = false;
     for (const opts of volumes ?? []) {
-      if (!currentUrls.has(opts.url)) {
-        currentUrls.add(opts.url);
+      if (!currentVolumes.has(opts.url)) {
+        const props = extractVisualProps(opts);
+        currentVolumes.set(opts.url, props);
         nv.addVolumeFromUrl(opts).catch((err) => {
-          currentUrls.delete(opts.url);
+          currentVolumes.delete(opts.url);
           onErrorRef.current?.(err);
         });
+      } else {
+        const prev = currentVolumes.get(opts.url);
+        const next = extractVisualProps(opts);
+        const vol = nv.volumes.find((v) => v.url === opts.url || v.name === opts.url);
+        if (!vol)
+          continue;
+        if (next.colormap !== undefined && next.colormap !== prev.colormap) {
+          vol.colormap = next.colormap;
+          needsGLUpdate = true;
+        }
+        if (next.cal_min !== undefined && next.cal_min !== prev.cal_min) {
+          vol.cal_min = next.cal_min;
+          needsGLUpdate = true;
+        }
+        if (next.cal_max !== undefined && next.cal_max !== prev.cal_max) {
+          vol.cal_max = next.cal_max;
+          needsGLUpdate = true;
+        }
+        if (next.opacity !== undefined && next.opacity !== prev.opacity) {
+          const volIdx = nv.volumes.indexOf(vol);
+          nv.setOpacity(volIdx, next.opacity);
+        }
+        currentVolumes.set(opts.url, next);
       }
     }
+    if (needsGLUpdate) {
+      nv.updateGLVolume();
+    }
   }, [volumes]);
   return /* @__PURE__ */ jsxDEV2("div", {
     ref: containerRef,

package/dist/types/nvscene-controller.d.ts

@@ -108,6 +108,9 @@ export declare class NvSceneController {
     getNiivue(index: number): Niivue | undefined;
     getAllNiivue(): Niivue[];
     forEachNiivue(callback: NiivueCallback): void;
+    private hasSyncableContent;
+    private safeBroadcastTo;
+    private rewireBroadcasting;
     setBroadcasting(enabled: boolean, options?: Partial<BroadcastOptions>): void;
     isBroadcasting(): boolean;
     setViewerSliceLayout(index: number, layout: SliceLayoutTile[] | null): void;
@@ -118,6 +121,17 @@ export declare class NvSceneController {
     loadVolume(index: number, opts: ImageFromUrlOptions): Promise<NVImage>;
     loadVolumes(index: number, opts: ImageFromUrlOptions[]): Promise<NVImage[]>;
     removeVolume(index: number, url: string): void;
+    /**
+     * Look up the Niivue instance and NVImage at the given viewer and volume indices.
+     * Returns undefined if either index is out of bounds.
+     */
+    private findVolume;
+    /** Set the colormap for a volume at the given viewer and volume index. */
+    setColormap(viewerIndex: number, volumeIndex: number, colormap: string): void;
+    /** Set the intensity range (cal_min / cal_max) for a volume at the given viewer and volume index. */
+    setCalMinMax(viewerIndex: number, volumeIndex: number, cal_min: number, cal_max: number): void;
+    /** Set the opacity for a volume at the given viewer and volume index. */
+    setOpacity(viewerIndex: number, volumeIndex: number, opacity: number): void;
     private incrementLoading;
     private decrementLoading;
     private addError;

package/dist/types/types.d.ts

@@ -10,6 +10,9 @@ export interface NvSceneEventMap {
     error: (viewerIndex: number, error: unknown) => void;
     volumeAdded: (viewerIndex: number, imageOptions: ImageFromUrlOptions, image: NVImage) => void;
     volumeRemoved: (viewerIndex: number, url: string) => void;
+    colormapChanged: (viewerIndex: number, volumeIndex: number, colormap: string) => void;
+    intensityChanged: (viewerIndex: number, volumeIndex: number, cal_min: number, cal_max: number) => void;
+    opacityChanged: (viewerIndex: number, volumeIndex: number, opacity: number) => void;
 }
 export interface ViewerState {
     id: string;

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@niivue/nvreact",
-  "version": "0.1.0",
+  "version": "0.1.2",
   "private": false,
   "type": "module",
   "main": "./dist/lib.js",
@@ -31,12 +31,16 @@
   },
   "dependencies": {},
   "peerDependencies": {
-    "@niivue/niivue": "0.67.1-dev.2",
+    "@niivue/niivue": "^0.68.1",
     "react": "^19",
     "react-dom": "^19"
   },
   "devDependencies": {
-    "@niivue/niivue": "0.67.1-dev.2",
+    "@happy-dom/global-registrator": "^20.6.1",
+    "@niivue/niivue": "^0.68.1",
+    "@testing-library/dom": "^10.4.1",
+    "@testing-library/jest-dom": "^6.9.1",
+    "@testing-library/react": "^16.3.2",
     "@types/bun": "latest",
     "@types/react": "^19",
     "@types/react-dom": "^19",