Add VolumeObject3DData trait + _volume_object_3d_data

- for use in frac2mm and mm2frac calculations
- also, organized some code into js/types.ts
- also, moved updateGLVolume() call for options + graph updates to be more direct instead of automatic (to prevent unnecessary extra calls)

Author: AnthonyAndroulakis

js/lib.ts

@@ -1,4 +1,5 @@
 import type { AnyModel, TypedBufferPayload } from "./types.ts";
+import type { NVConfigOptions } from "@niivue/niivue";
 
 function delay(ms: number) {
 	return new Promise((resolve) => setTimeout(resolve, ms));
@@ -14,6 +15,33 @@ function dataViewToBase64(dataView: DataView) {
 	return btoa(binaryString);
 }
 
+export function deserializeOptions(
+	options: Partial<Record<keyof NVConfigOptions, unknown>>,
+): NVConfigOptions {
+	const result: Partial<NVConfigOptions> = {};
+	const specialValues: Record<string, number> = {
+		Infinity: Number.POSITIVE_INFINITY,
+		"-Infinity": Number.NEGATIVE_INFINITY,
+		NaN: Number.NaN,
+		"-0": -0,
+	};
+
+	for (const [key, value] of Object.entries(options) as [
+		keyof NVConfigOptions,
+		unknown,
+	][]) {
+		if (typeof value === "string" && value in specialValues) {
+			// biome-ignore lint/suspicious/noExplicitAny: NVConfigOptions
+			(result as any)[key] = specialValues[value];
+		} else {
+			// biome-ignore lint/suspicious/noExplicitAny: NVConfigOptions
+			(result as any)[key] = value;
+		}
+	}
+
+	return result as NVConfigOptions;
+}
+
 export function handleBufferMsg(
 	// biome-ignore lint/suspicious/noExplicitAny: targetObject can be any
 	targetObject: any,

js/types.ts

@@ -11,6 +11,16 @@ export interface AnyModel<T extends object = object> extends BaseAnyModel<T> {
 	onChange: (value: Partial<T>) => void;
 }
 
+// just part of the NiivueObject3D in niivue
+export type NiivueObject3D = {
+	id: number;
+	extents_min: number[];
+	extents_max: number[];
+	scale: number[];
+	furthest_vertex_from_origin?: number;
+	field_of_view_de_oblique_mm?: number[];
+};
+
 interface FileInput {
 	name: string;
 	data: DataView;
@@ -94,7 +104,7 @@ export type VolumeModel = AnyModel<{
 	modulation_image: number | null;
 	modulate_alpha: number;
 
-	hdr: Partial<NIFTI1>;
+	hdr: Partial<NIFTI1>; // only updated via frontend...but this might change in the future..
 	img: DataView;
 	dims: number[];
 }>;
@@ -166,6 +176,8 @@ export type Model = AnyModel<{
 	scene: Scene;
 	overlay_outline_width: number;
 	overlay_alpha_shader: number;
+
+	_volume_object_3d_data: NiivueObject3D; // only updated via frontend (1-way comm)
 }>;
 
 // Custom message datas
@@ -214,6 +226,7 @@ export type CustomMessagePayload =
 	| { type: "set_gamma"; data: SetGammaData }
 	| { type: "resize_listener"; data: [] }
 	| { type: "draw_scene"; data: [] }
+	| { type: "update_gl_volume"; data: [] }
 	| {
 			type: "set_volume_render_illumination";
 			data: SetVolumeRenderIlluminationData;

js/widget.ts

@@ -10,39 +10,13 @@ import type {
 	CustomMessagePayload,
 	MeshModel,
 	Model,
+	NiivueObject3D,
 	Scene,
 	VolumeModel,
 } from "./types.ts";
 
 let nv: niivue.Niivue;
 
-function deserializeOptions(
-	options: Partial<Record<keyof niivue.NVConfigOptions, unknown>>,
-): niivue.NVConfigOptions {
-	const result: Partial<niivue.NVConfigOptions> = {};
-	const specialValues: Record<string, number> = {
-		Infinity: Number.POSITIVE_INFINITY,
-		"-Infinity": Number.NEGATIVE_INFINITY,
-		NaN: Number.NaN,
-		"-0": -0,
-	};
-
-	for (const [key, value] of Object.entries(options) as [
-		keyof niivue.NVConfigOptions,
-		unknown,
-	][]) {
-		if (typeof value === "string" && value in specialValues) {
-			// biome-ignore lint/suspicious/noExplicitAny: NVConfigOptions
-			(result as any)[key] = specialValues[value];
-		} else {
-			// biome-ignore lint/suspicious/noExplicitAny: NVConfigOptions
-			(result as any)[key] = value;
-		}
-	}
-
-	return result as niivue.NVConfigOptions;
-}
-
 // Attach model event handlers
 function attachModelEventHandlers(
 	nv: niivue.Niivue,
@@ -60,13 +34,13 @@ function attachModelEventHandlers(
 		}
 	});
 
-	// Any time we change the options, we need to update the nv gl
+	// Any time the backend changes the options, we need to update the nv gl
+	// but...need to filter out changes that are *actually* from the frontend
+	// so, we don't call updateGLVolume here (instead, it's explicitly called from the backend)
 	model.on("change:opts", () => {
 		const serializedOpts = model.get("opts");
-		const opts = deserializeOptions(serializedOpts);
-
+		const opts = lib.deserializeOptions(serializedOpts);
 		nv.document.opts = { ...nv.opts, ...opts };
-		nv.updateGLVolume();
 	});
 
 	// Other nv prop changes
@@ -111,9 +85,6 @@ function attachModelEventHandlers(
 			// biome-ignore lint/suspicious/noExplicitAny: Update graph vals, only clear out old vals when needed
 			(nv.graph as any)[key] = value;
 		}
-		if (nv._gl) {
-			nv.updateGLVolume();
-		}
 	}
 
 	function scene_changed() {
@@ -214,6 +185,10 @@ function attachModelEventHandlers(
 					nv.drawScene();
 					break;
 				}
+				case "update_gl_volume": {
+					nv.updateGLVolume();
+					break;
+				}
 				case "set_volume_render_illumination": {
 					if (nv._gl) {
 						let [gradientAmount] = data;
@@ -333,6 +308,29 @@ function attachNiivueEventHandlers(nv: niivue.Niivue, model: Model) {
 		},
 	});
 
+	const originalRefreshLayersMethod = nv.refreshLayers;
+	nv.refreshLayers = new Proxy(originalRefreshLayersMethod, {
+		apply: (target, thisArg, argumentsList) => {
+			Reflect.apply(target, thisArg, argumentsList);
+
+			if (nv.volumeObject3D) {
+				const currentVolumeObject3D: NiivueObject3D = {
+					id: nv.volumeObject3D.id,
+					extents_min: nv.volumeObject3D.extentsMin,
+					extents_max: nv.volumeObject3D.extentsMax,
+					scale: nv.volumeObject3D.scale,
+					furthest_vertex_from_origin:
+						nv.volumeObject3D.furthestVertexFromOrigin,
+					field_of_view_de_oblique_mm: nv.volumeObject3D
+						.fieldOfViewDeObliqueMM as number[],
+				};
+				model.set("_volume_object_3d_data", currentVolumeObject3D);
+				model.save_changes();
+				console.log("_volume_object_3d_data set");
+			}
+		},
+	});
+
 	nv.onImageLoaded = async (volume: niivue.NVImage) => {
 		// Check if the volume is already in the backend
 		const volumeID = volume.id;
@@ -652,7 +650,7 @@ export default {
 		if (!nv) {
 			console.log("Creating new Niivue instance");
 			const serializedOpts = model.get("opts") ?? {};
-			const opts = deserializeOptions(serializedOpts);
+			const opts = lib.deserializeOptions(serializedOpts);
 			nv = new niivue.Niivue(opts);
 		}
 

src/ipyniivue/serializers.py

@@ -21,6 +21,7 @@
     Graph,
     NIFTI1Hdr,
     Scene,
+    VolumeObject3DData,
 )
 from .utils import is_negative_zero
 
@@ -355,3 +356,40 @@ def serialize_enum(instance: enum.Enum, widget: object):
     if isinstance(instance, enum.Enum):
         return instance.value
     return instance
+
+
+def serialize_to_none(instance: object, widget: object):
+    """
+    Serialize to None.
+
+    Parameters
+    ----------
+    instance : object
+        The object to serialize.
+    widget : object
+        The NiiVue widget the instance is a part of.
+
+    Returns
+    -------
+    None
+    """
+    return None
+
+
+def deserialize_volume_object_3d_data(instance: dict, widget: object):
+    """
+    Deserialize serialized VolumeObject3DData.
+
+    Parameters
+    ----------
+    instance : dict
+        The dictionary from the frontend.
+    widget : object
+        The NiiVue widget the instance is a part of.
+
+    Returns
+    -------
+    VolumeObject3DData
+        The deserialized VolumeObject3DData instance.
+    """
+    return VolumeObject3DData(**instance)

src/ipyniivue/traits.py

@@ -450,6 +450,58 @@ def _propagate_parent_change(self, change):
             self._parent._notify_scene_changed()
 
 
+class VolumeObject3DData(t.HasTraits):
+    """
+    Represents data from a 3D volume object, partial of niivue's NiivueObject3D.
+
+    Properties
+    ----------
+    id : int
+        Unique identifier for the object.
+    extents_min : list of float
+        Minimum extents of the object in each dimension.
+    extents_max : list of float
+        Maximum extents of the object in each dimension.
+    scale : list of float
+        Scale factors for each dimension.
+    furthest_vertex_from_origin : float or None
+        Distance to the furthest vertex from the origin.
+    field_of_view_de_oblique_mm : list of float or None
+        Field of view in de-oblique millimeters.
+    """
+
+    id = t.Int().tag(sync=False)
+    extents_min = t.List(t.Float()).tag(sync=False)
+    extents_max = t.List(t.Float()).tag(sync=False)
+    scale = t.List(t.Float()).tag(sync=False)
+    furthest_vertex_from_origin = t.Float(allow_none=True, default_value=None).tag(
+        sync=False
+    )
+    field_of_view_de_oblique_mm = t.List(
+        t.Float(), allow_none=True, default_value=None
+    ).tag(sync=False)
+
+    @t.validate(
+        "id",
+        "extents_min",
+        "extents_max",
+        "scale",
+        "furthest_vertex_from_origin",
+        "field_of_view_de_oblique_mm",
+    )
+    def _validate_no_change(self, proposal):
+        trait_name = proposal["trait"].name
+        if (
+            trait_name in self._trait_values
+            and (
+                self._trait_values[trait_name] or self._trait_values[trait_name] == 0.0
+            )
+            and self._trait_values[trait_name] != proposal["value"]
+        ):
+            raise t.TraitError(f"Cannot modify '{trait_name}' once set.")
+        return proposal["value"]
+
+
 CAMEL_TO_SNAKE_SCENE = {
     "renderAzimuth": "render_azimuth",
     "renderElevation": "render_elevation",

src/ipyniivue/widget.py

@@ -33,6 +33,7 @@
     deserialize_hdr,
     deserialize_options,
     deserialize_scene,
+    deserialize_volume_object_3d_data,
     serialize_colormap_label,
     serialize_enum,
     serialize_file,
@@ -41,13 +42,15 @@
     serialize_ndarray,
     serialize_options,
     serialize_scene,
+    serialize_to_none,
 )
 from .traits import (
     LUT,
     ColorMap,
     Graph,
     NIFTI1Hdr,
     Scene,
+    VolumeObject3DData,
 )
 from .utils import (
     ChunkedDataHandler,
@@ -682,6 +685,11 @@ class NiiVue(BaseAnyWidget):
     )
 
     _canvas_attached = t.Bool(False).tag(sync=True)
+    _volume_object_3d_data = t.Instance(VolumeObject3DData, allow_none=True).tag(
+        sync=True,
+        to_json=serialize_to_none,
+        from_json=deserialize_volume_object_3d_data,
+    )
 
     # other props
     background_masks_overlays = t.Int(0).tag(sync=True)
@@ -758,6 +766,7 @@ def _notify_opts_changed(self):
                 "type": "change",
             }
         )
+        self.send({"type": "update_gl_volume", "data": []})
 
     def _notify_graph_changed(self):
         self.notify_change(
@@ -769,6 +778,7 @@ def _notify_graph_changed(self):
                 "type": "change",
             }
         )
+        self.send({"type": "update_gl_volume", "data": []})
 
     def _notify_scene_changed(self):
         self.notify_change(