v2.4.2

🚨 Breaking Changes

• Updated Scene class properties to support multiple clip planes - by @AnthonyAndroulakis (c0feec7)
• Removed clipThick, clipVolumeLow, and clipVolumeHigh config options - by @neurolabusc (7a45a68)

🚀 Features

New Example Notebooks:

• Added document.load.ipynb - by @AnthonyAndroulakis (8b1b1f9)
• Added clipplanes.ipynb - by @neurolabusc (7a45a68)
• Added basic.vox.connect.ipynb - by @neurolabusc (27e76b6)
• Added freesurfer.ipynb - by @neurolabusc (d1e3b48)
• Added mesh.atlas.suit.ipynb - by @neurolabusc (6168f4d)
• Added mesh.mosaic.ipynb - by @neurolabusc (2e52eb5)

New Methods:

• Added load_document method to load .nvd files from URLs or local file paths - by @AnthonyAndroulakis in #211 (9b73018)
• Added support for multiple clip planes with enhanced control - by @neurolabusc in #219 (7a45a68)
  • Added set_clip_plane_color method
  • Added set_clip_planes method
  • Added set_cutaway method
• Added support for connectomes from .jcon files - by @neurolabusc (27e76b6) in #221
• Added mesh atlas support with per-parcel custom statistics - by @neurolabusc (2e52eb5) in #222
• Added support accessing draw_bitmap binary data to enable bitmap drawing operations - by @AnthonyAndroulakis (6f03c60)
• Added update_gl_volume method - by @neurolabusc (d1e3b48)
• Added draw_scene method - by @neurolabusc (d1e3b48)

Documentation:

• Added architecture documentation - by @christian-oreilly and @AnthonyAndroulakis in #205 (c781a72)

Internal Improvements:

• Added requires_canvas utility decorator for methods that need an attached canvas - by @AnthonyAndroulakis (9b73018)
• Improved frontend-backend data synchronization for volumes and meshes - by @AnthonyAndroulakis in #211
• Added utility method sph2cart_deg - by @neurolabusc (7a45a68)

Other

• Updated to [email protected] (from 0.62.1) - by @neurolabusc in #219

    View changes on GitHub

v2.4.1

🚨 Breaking Changes

• Removed ability to set config options directly on NiiVue object - by @AnthonyAndroulakis in #202 (7108b5f)
  • Config options must now be set via the opts trait (e.g., nv.opts.pen_value = 1.0)

🚀 Features

New Example Notebooks:

• Added alphathreshold.ipynb notebook example - by @AnthonyAndroulakis in #196
• Added denoise.ipynb notebook example - by @AnthonyAndroulakis in #190
• Added modulatescalar.ipynb notebook example - by @AnthonyAndroulakis in #191
• Added segment.ipynb notebook example - by @AnthonyAndroulakis in #192
• Added mosaics1.ipynb and mosaics2.ipynb notebook examples - by @AnthonyAndroulakis in #197
• Added worldspace.ipynb and worldspace2.ipynb notebook examples - by @AnthonyAndroulakis in #198
• Added sync.bidirectional.ipynb notebook example - by @AnthonyAndroulakis in #199

New Methods:

• Added set_opacity method to NiiVue class (a20279f)
• Added set_modulation_image method to NiiVue class (5af854c)
• Added set_colormap_negative method to NiiVue class (72cdd9e)
• Added set_corner_orientation_text method to NiiVue class (41225e3)
• Added set_mesh_thickness_on_2d method to NiiVue class (41225e3)
• Added set_slice_mosaic_string method to NiiVue class (75c8309)
• Added set_multiplanar_pad_pixels method to NiiVue class (4d3f709)
• Added scene_extents_min_max method to NiiVue class (46afd0b)
• Added mm2frac and frac2mm methods to NiiVue class (4e886a2)
• Added broadcast_to and sync methods for syncing multiple NiiVue instances (bb774d3)
• Added convert_frac2mm and convert_mm2frac methods to Volume class (4e886a2)
• Added save_to_disk method to Volume class (72cdd9e)
• Added on_canvas_attached event handler to NiiVue class (bb774d3)

New Properties:

• Added scene property to NiiVue class for managing scene state (5af854c)
• Added overlay_outline_width property to NiiVue class (7ff942d)
• Added overlay_alpha_shader property to NiiVue class (590b9b8)
• Added cal_min_neg and cal_max_neg properties to Volume class (72cdd9e)
• Added colormap_type property to Volume class (72cdd9e)
• Added modulation_image and modulate_alpha properties to Volume class (5af854c)
• Added extents_min_ortho, extents_max_ortho, frac2mm, frac2mm_ortho, dims_ras, and mat_ras properties to Volume class (979a72d)
• Added extents_min and extents_max properties to Mesh class (83abf11)

New Traits & Classes:

• Added Scene trait class for scene configuration (5af854c)
• Added VolumeObject3DData trait class for 3D volume object metadata (979a72d)
• Added ColormapType enum (72cdd9e)
• Added PenType enum (7c65b3c)

Misc

• Updated to [email protected] - by @AnthonyAndroulakis in #195
• Fixed atlas.ipynb example to respond properly to mouse clicks (bd15c31)
• Removed deprecated DragModePrimary enum, merged functionality into DragMode (bd15c31)
• Updated enum documentation for new DragMode values (b08821e)
• Added new serializers and deserializers (979a72d)

    View changes on GitHub

v2.4.0

Reworked data input/loading in #187 by @AnthonyAndroulakis

• add url and data+name input options for Volumes
• add url and data+name input options for Meshes
• add url and data+name input options for MeshLayers
• save volume hdr info and dim info on image load
• organize serializers/deserializers into their own file
• save volume img data on image load (chunked)
• save mesh data (pts and tris) on mesh load (chunked)
• be able to change binary data (ex: volume.img) from backend/python and have it update on the frontend

    View changes on GitHub

In-depth details / Design decisions

Volume, Mesh, and MeshLayer Inputs

The Volume, Mesh, and MeshLayer classes have been updated to support loading from one of three sources:

1. Path: Load from a local file path.
2. URL: Load from a remote URL.
3. Data + Name: Load from binary data with a specified name.

Examples

Loading a Volume from Path, URL, or Data

from ipyniivue import NiiVue, Volume

# Load from a local file path
volume1 = Volume(path="path/to/volume.nii.gz")

# Load from a URL
volume2 = Volume(url="https://example.com/volume.nii.gz")

# Load from binary data with a name
with open("path/to/volume.nii.gz", "rb") as f:
    data = f.read()
volume3 = Volume(data=data, name="volume.nii.gz")

# Load volumes into NiiVue
nv = NiiVue()
nv.load_volumes([volume1, volume2, volume3])

The same approach can be applied to Mesh and MeshLayer objects.

Using Dictionaries or Objects

In addition to using dictionaries, you can now use Volume, Mesh, or MeshLayer objects directly when loading or adding to NiiVue. This is done for 2 reasons:

1. can add on-change handlers or traitlets-specific functions to volumes, meshes, and mesh layer objects before adding them onto the main widget
2. can feel more pythonic than interacting with dictionaries. You can still use dictionaries since that mirrors NiiVue JS usage.

# Use Volume objects directly
nv.load_volumes([volume1, volume2, volume3])

# Or use dictionaries
nv.load_volumes([
    {"path": "path/to/volume.nii.gz"},
    {"url": "https://example.com/volume.nii.gz"},
    {"data": data, "name": "volume.nii.gz"}
])

# You can also have a list that contains a mix of dictionaries and Volume objects.

Communication Updates

Chunked Communication from Frontend to Backend

ipywidgets uses tornado for websocket communication. Once major limitation is that tornado limits incoming messages to 10 mb. This is a known issue without an official implementation. See:

• jupyter-widgets/ipywidgets#2522
• jupyter/notebook#3468

Of course, one solution would be to just ask users to update their jupyterlab config when using ipyniivue, but this isn't ideal since it requires:

1. the user to do extra work
2. you can already send data from backend -> frontend that's way over 10 mb, why not allow the opposite (frontend -> backend)

And so, I've made the decision to implement chunking (specifically, thru the state-change communication line). I've tested my implementation in jupyter lab, jupyter notebook, google colab, and marimo. Marimo uses POST requests instead of WebSockets for frontend -> backend communication, so special handling has been implemented for that.

Visualization

Chunked Data Transfer from Frontend to Backend:

Frontend                             Backend
+------------+                       +------------+
|            | -- Chunk 1 ----------> |            |
|            | -- Chunk 2 ----------> |            |
| Large Data | -- Chunk 3 ----------> |            |
|            |          ...           | Reassemble |
|            | -- Chunk N ----------> |            |
+------------+                       +------------+

• Frontend breaks the large data into smaller chunks.
• Chunks are sent to the backend with index and type information.
• Backend receives chunks and reassembles them into the complete data.

Numpy arrays are used in the backend so that array type information can be properly communicated.

Updates from Backend to Frontend

Instead of sending the entire array, only the differences are sent:

Backend                                Frontend
+------------+        Only Changes       +------------+
|            | -- Indices & Values --->  |            |
| Large Data |                           | Large Data |
| (Modified) |                           | (Updated)  |
+------------+                           +------------+

• Backend identifies changes (modified indices and new values).
• Changes are sent to the frontend.
• Frontend applies updates to its local copy based on received indices and values.

If the array type is changed, then the entire array along with the new type is sent to the frontend.

    View changes on GitHub

v2.3.3

   🚨 Breaking Changes

• frame4D: Rename 'frame4D' to 'frame_4d'  -  by @AnthonyAndroulakis (12467)

    View changes on GitHub

v2.3.2

• fix save_html method
• update ConfigOptions to niivue 0.58.0
• add complex.ipynb notebook example
• add test_images.ipynb notebook example

    View changes on GitHub

v2.3.1

   🚀 Features

• graph: Add afni.ipynb notebook example  -  by @AnthonyAndroulakis (249d8)
• draw: Add draw2.ipynb notebook example (adds load_drawing method)

    View changes on GitHub

v2.3.0

   🚨 Breaking Changes

• Rename NiiVue._meshes and NiiVue._volumes  -  by @AnthonyAndroulakis (9779e)
• Remove NiiVue.id property  -  by @AnthonyAndroulakis (d01d0)
• opts: Move NiiVue options to 'opts' attribute  -  by @AnthonyAndroulakis (a87a9)
  • it's still possible to directly set options onto the NiiVue object, but doing so will be removed starting version 2.4.1.
    Until then, a DeprecationWarning is shown when directly setting options onto NiiVue.
    Please use nv.opts.[option name] to get/set option values. Ex: nv.opts.pen_value = 0.0

    Other changes

• Fix pen_value to properly store EraseCluster (-0.0) by @AnthonyAndroulakis (0999790)

    View changes on GitHub

v2.2.2

   🚀 Features

New Notebooks:

• Add vox.tradeoffs.ipynb notebook example - by @AnthonyAndroulakis in #159
• Add mesh.matcap.ipynb notebook example - by @AnthonyAndroulakis in #161
• Add tracts.ipynb notebook example - by @AnthonyAndroulakis in #162
• Add atlas.ipynb notebook example - by @AnthonyAndroulakis in #167
• Add atlas.sparse.ipynb notebook example - by @AnthonyAndroulakis in #168
• Add draw.ui.ipynb notebook example - by @AnthonyAndroulakis in #169

New Methods:

• Add set_colormap_label method to Volume class
• Add set_volume_render_illumination method to NiiVue class
• Add set_high_resolution_capable method to NiiVue class
• Add close method to NiiVue class
• Add set_mesh_property method to NiiVue class
• Add load_mat_cap_texture method to NiiVue class
• Add set_radiological_convention method to NiiVue class
• Add close_drawing method to NiiVue class
• Add draw_undo method to NiiVue class
• Add set_slice_mm method to NiiVue class
• Add remove_haze method to NiiVue class
• Add move_crosshair_in_vox method to NiiVue class
• Add draw_grow_cut method to NiiVue class
• Add draw_otsu method to NiiVue class
• Add set_draw_colormap method to NiiVue class
• Add colormap_from_key method to NiiVue class
• Add set_drawing_enabled method to NiiVue class
• Add set_pen_value method to NiiVue class

New Properties:

• Add colormap_negative property to Volume class
• Add colormap_label property to Volume class
• Add mesh_shader_index property to Mesh class
• Add colorbar_visible property to Mesh class
• Add fiber_radius, fiber_length, fiber_dither, fiber_color, fiber_decimation_stride, and colormap properties to Mesh class
• Add clip_plane_depth_azi_elev property to NiiVue class
• Add gradient_amount, gradient_opacity, and force_device_pixel_ratio options to NiiVue class
• Add crosshair_gap and atlas_outline options to NiiVue class

Documentation Updates:

• Add close method to docs
• Add ColorMap and LUT classes to docs

Utility Functions:

• Add make_draw_lut, make_label_lut serialize_options, and deserialize_options utility methods

   🐞 Bug Fixes

• Update checks in set_colormap_label(8c0a11e)
• Fix drawing setup(194308a)
• Fix colormap_label implementation
• Fix create_volume colorbar range
• Fix set_render_azimuth_elevation by adding custom message handler
• Fix order of mesh shader names in build.js
• Fix Mesh.rgba255 default value
• Fix colormap functions to use ColorMap class for structure validation

    View changes on GitHub

v2.2.1

   🐞 Bug Fixes

• widget: Use anywidget as base class  -  by @AnthonyAndroulakis (c7de9)

    View changes on GitHub

v2.2.0

Core

• Renamed modules (_widget.py → widget.py, etc.) - by @christian-oreilly and @hanayik in #105 (7812824)
• Shifted from name-based to ID-based system for models - by @AnthonyAndroulakis in #139 (e1eae5b)
• Update ipyniivue to use latest niivue version (as of now, 0.57.0) - by @AnthonyAndroulakis in #138 (1ad7e57) and #153 (4d0d0c0)

🚀 Features

• Created documentation site by @bcalford in #99 (4ae99ce) and @AnthonyAndroulakis in #150 (47a5667)
• Added Drawing model and methods - by @bcalford in 04ebe9c
• Added download_dataset - by @bcalford in 44487b9
• Add CI testing - by @christian-oreilly and @hanayik in #105 (7812824)
• Added MeshLayer model - by @AnthonyAndroulakis in #151 (ba4d21b)
• Added event-based synchronization between frontend and backend and all Niivue event hooks - by @AnthonyAndroulakis in #145 (25c9d97)
• Niivue instance and display persistence across cells in Jupyter notebooks (each model points to 1 nv object) - by @AnthonyAndroulakis in #148 (42b36ec)
• Support drag-and-dropped data from frontend (<fromfrontend> name placeholder) - by @AnthonyAndroulakis in #144 (2181a58)
• New methods:
  • colormaps, add_colormap, set_colormap, set_selection_box_color, set_crosshair_color, set_crosshair_width, set_gamma, set_slice_type, set_clip_plane, set_render_azimuth_elevation, set_mesh_shader, mesh_shader_names - by @AnthonyAndroulakis in #152 (bbc7754)
  • save_document, save_html, save_image, and save_scene - by @bcalford in #124 (150ff1f)
• New properties:
  • name in Volume and Mesh - by @AnthonyAndroulakis in #144 (2181a58)
  • colormap_invert in Volume, Mesh, and MeshLayer - by @AnthonyAndroulakis in #152 (bbc7754)
  • background_masks_overlays in NiiVue - by @AnthonyAndroulakis in #152 (bbc7754)
  • multiplanar_show_render option - by @AnthonyAndroulakis in #152 (bbc7754)
  • frame4D in Volume - by @Jolinda and @christian-oreilly in #119 (70baed9)
  • frame4D in MeshLayer - by @AnthonyAndroulakis in #152 (bbc7754)
  • colorbar_visible in MeshLayer - by @AnthonyAndroulakis in #154 (e44b1b6)
• New Constants:
  • ShowRender: Controls when the 3D render view is displayed (NEVER, ALWAYS, AUTO) - by @AnthonyAndroulakis in #152 (bbc7754)

📝 Added new examples

• add_from_frontend.ipynb - by @AnthonyAndroulakis in #144 (2181a58)
• colormaps.ipynb, colormaps.mesh.ipynb, mask.ipynb, and mesh.4d.ipynb - by @AnthonyAndroulakis in #152 (bbc7754)
• drawing.ipynb - by @bcalford in c100924
• example_4d.ipynb - by @Jolinda and @christian-oreilly in #119 (70baed9)
• mesh_and_volume.ipynb - by @kolibril13 in cb6103a
• mosaic.ipynb - by @Jolinda in #143 (13c9d70)
• on_event.ipynb - by @AnthonyAndroulakis in #145 (25c9d97)
• prototypes/meshes_(GIfTI, FreeSurfer, MZ3, OBJ, STL, legacy VTK).ipynb - by @kolibril13 in cb6103a
• prototypes/torso_regions.ipynb - by @kolibril13 in cb6103a
• prototypes/trajectory.ipynb - by @kolibril13 in cb6103a
• saving.ipynb - by @bcalford in #124 (150ff1f)

    View changes on GitHub