unveil-python 0.4.0__tar.gz → 0.5.0__tar.gz

unveil_python-0.5.0/PKG-INFO

@@ -0,0 +1,74 @@
+Metadata-Version: 2.4
+Name: unveil-python
+Version: 0.5.0
+Summary: Implementation of UNVEIL
+Author-email: Nicolas Delinte <nicolas.delinte@uclouvain.be>
+License-Expression: GPL-3.0-only
+Project-URL: GitHub, https://github.com/DelinteNicolas/UNVEIL
+Keywords: tractography,viewer
+Classifier: Intended Audience :: Science/Research
+Classifier: Natural Language :: English
+Classifier: Programming Language :: Python
+Description-Content-Type: text/markdown
+License-File: LICENSE
+Requires-Dist: dipy
+Requires-Dist: pyvista
+Requires-Dist: pyvistaqt
+Requires-Dist: PyQt6
+Dynamic: license-file
+
+# UNVEIL
+[![PyPI](https://img.shields.io/pypi/v/unveil-python?label=pypi%20package)](https://pypi.org/project/unveil-python/)
+[![PyPI - Downloads](https://img.shields.io/pypi/dm/unveil-python)](https://pypi.org/project/unveil-python/)
+![GitHub repo size](https://img.shields.io/github/repo-size/DelinteNicolas/unveil)
+
+
+UNVEIL is a Python-based visualization tool for interactive exploration of diffusion MRI tractography, anatomical volumes, cortical surfaces, and ROI segmentations. It combines a 3D PyVista viewer with an orthogonal slice viewer.
+
+<img width="1297" height="757" alt="image" src="https://github.com/user-attachments/assets/28807e18-17fb-485b-a8ce-2179cdef796b" />
+
+## Install
+
+The GUI is launched with the following python command in a python console:
+
+```
+import unveil.__main__
+```
+or with
+```
+python -c "import unveil.__main__"
+```
+from a terminal with a python environment activated.
+
+## Features
+
+- **3D Tractography Visualization**
+    - Load and display `.trk` streamline files.
+    - RGB orientation coloring or scalar-based coloring from NIfTI volumes.
+    - Adjustable opacity and point/line rendering.
+- **Volume Rendering**
+    - Load `.nii.gz` images.
+    - Interactive volume rendering and orthogonal slice planes.
+    - Adjustable opacity.
+- **ROI Visualization**
+    - Load ROI masks from `.nii` / `.nii.gz`.
+    - Automatic surface extraction and smoothing.
+    - Individual visibility and color control.
+- **Surface Visualization**
+    - Load GIFTI (`.gii`) cortical surfaces.
+    - Adjustable opacity and smooth shading.
+- **Orthogonal Viewer**
+    - Axial, coronal, and sagittal views.
+    - Mouse-wheel slice navigation.
+    - Click-to-navigate crosshair synchronization.
+    - ROI overlay display.
+    - Screenshot export.
+- **Scene Management**
+    - Actor visibility control.
+    - ROI color editing.
+    - Background color toggle.
+    - Color-blind-friendly tractography coloring.
+- **Export**
+    - 3D screenshots.
+    - Orthogonal-view screenshots.
+    - Animated 360° GIF generation.

unveil_python-0.5.0/README.md

@@ -0,0 +1,55 @@
+# UNVEIL
+[![PyPI](https://img.shields.io/pypi/v/unveil-python?label=pypi%20package)](https://pypi.org/project/unveil-python/)
+[![PyPI - Downloads](https://img.shields.io/pypi/dm/unveil-python)](https://pypi.org/project/unveil-python/)
+![GitHub repo size](https://img.shields.io/github/repo-size/DelinteNicolas/unveil)
+
+
+UNVEIL is a Python-based visualization tool for interactive exploration of diffusion MRI tractography, anatomical volumes, cortical surfaces, and ROI segmentations. It combines a 3D PyVista viewer with an orthogonal slice viewer.
+
+<img width="1297" height="757" alt="image" src="https://github.com/user-attachments/assets/28807e18-17fb-485b-a8ce-2179cdef796b" />
+
+## Install
+
+The GUI is launched with the following python command in a python console:
+
+```
+import unveil.__main__
+```
+or with
+```
+python -c "import unveil.__main__"
+```
+from a terminal with a python environment activated.
+
+## Features
+
+- **3D Tractography Visualization**
+    - Load and display `.trk` streamline files.
+    - RGB orientation coloring or scalar-based coloring from NIfTI volumes.
+    - Adjustable opacity and point/line rendering.
+- **Volume Rendering**
+    - Load `.nii.gz` images.
+    - Interactive volume rendering and orthogonal slice planes.
+    - Adjustable opacity.
+- **ROI Visualization**
+    - Load ROI masks from `.nii` / `.nii.gz`.
+    - Automatic surface extraction and smoothing.
+    - Individual visibility and color control.
+- **Surface Visualization**
+    - Load GIFTI (`.gii`) cortical surfaces.
+    - Adjustable opacity and smooth shading.
+- **Orthogonal Viewer**
+    - Axial, coronal, and sagittal views.
+    - Mouse-wheel slice navigation.
+    - Click-to-navigate crosshair synchronization.
+    - ROI overlay display.
+    - Screenshot export.
+- **Scene Management**
+    - Actor visibility control.
+    - ROI color editing.
+    - Background color toggle.
+    - Color-blind-friendly tractography coloring.
+- **Export**
+    - 3D screenshots.
+    - Orthogonal-view screenshots.
+    - Animated 360° GIF generation.

{unveil_python-0.4.0 → unveil_python-0.5.0}/src/unveil/__init__.py

@@ -1,5 +1,5 @@
 """
 This package contains an UNVEIL, a lightweight tractography viewer implemented in python."""
 
-__version__ = "0.4.0"
+__version__ = "0.5.0"
 __author__ = 'Nicolas Delinte'

{unveil_python-0.4.0 → unveil_python-0.5.0}/src/unveil/core.py

@@ -10,14 +10,17 @@ import nibabel as nib
 import pyvista as pv
 from pyvistaqt import QtInteractor
 from PyQt6.QtCore import Qt
-from PyQt6.QtGui import QAction
 from PyQt6.QtWidgets import (QApplication, QWidget, QHBoxLayout, QVBoxLayout,
                              QPushButton, QFileDialog, QCheckBox, QSlider,
                              QLabel, QComboBox, QMainWindow, QLineEdit,
-                             QDockWidget, QTreeWidget, QTreeWidgetItem)
+                             QDockWidget, QTreeWidget, QTreeWidgetItem,
+                             QColorDialog, QTabWidget)
+from PyQt6.QtGui import QAction, QColor
 from dipy.io.streamline import load_tractogram
 from matplotlib import pyplot as plt
 from matplotlib.colors import LinearSegmentedColormap
+from matplotlib.backends.backend_qtagg import FigureCanvasQTAgg
+from matplotlib.figure import Figure
 # from unravel.utils import get_streamline_density
 
 
@@ -185,11 +188,9 @@ def plot_trk(trk_file, scalar=None, color_map='plasma', opacity: float = 1,
 class TrkViewer(QWidget):
     def __init__(self):
         super().__init__()
-        self.trk_file = None
-        self.nii_file = None
         self.nii_data = None
         self.grid = None
-        self.names = []
+        self.actor_types = {}
         self.x = 0
         self.y = 0
         self.z = 0
@@ -197,6 +198,9 @@ class TrkViewer(QWidget):
         self.background = 'white'
         self.color_blind = False
         self.flicker = False
+        self.roi_colors = {}
+        self.roi_volumes = {}
+        self.roi_visibility = {}
 
     def initUI(self):
         # Create the main layout
@@ -209,10 +213,10 @@ class TrkViewer(QWidget):
         btn_xy = QPushButton("Axe 1")
         btn_xz = QPushButton("Axe 2")
         btn_yz = QPushButton("Axe 3")
-        btn_iso.clicked.connect(self.view_isometric)
-        btn_xy.clicked.connect(self.view_xy)
-        btn_xz.clicked.connect(self.view_xz)
-        btn_yz.clicked.connect(self.view_yz)
+        btn_iso.clicked.connect(lambda: self.set_view("view_isometric"))
+        btn_xy.clicked.connect(lambda: self.set_view("view_xy"))
+        btn_xz.clicked.connect(lambda: self.set_view("view_xz"))
+        btn_yz.clicked.connect(lambda: self.set_view("view_yz"))
         cam_layout.addWidget(camera_label)
         cam_layout.addWidget(btn_iso)
         cam_layout.addWidget(btn_xy)
@@ -284,7 +288,8 @@ class TrkViewer(QWidget):
         self.XSlider.setMinimum(0)
         self.XSlider.setMaximum(100)
         self.XSlider.setValue(100)
-        self.XSlider.sliderReleased.connect(self._update_nii_x)
+        self.XSlider.sliderReleased.connect(
+            lambda: self._update_slice('x', 'nii_x'))
         control_layout.addWidget(self.XSlider)
         self.y_label = QLabel('Y')
         control_layout.addWidget(self.y_label)
@@ -292,7 +297,8 @@ class TrkViewer(QWidget):
         self.YSlider.setMinimum(0)
         self.YSlider.setMaximum(100)
         self.YSlider.setValue(100)
-        self.YSlider.sliderReleased.connect(self._update_nii_y)
+        self.YSlider.sliderReleased.connect(
+            lambda: self._update_slice('y', 'nii_y'))
         control_layout.addWidget(self.YSlider)
         self.z_label = QLabel('Z')
         control_layout.addWidget(self.z_label)
@@ -300,7 +306,8 @@ class TrkViewer(QWidget):
         self.ZSlider.setMinimum(0)
         self.ZSlider.setMaximum(100)
         self.ZSlider.setValue(100)
-        self.ZSlider.sliderReleased.connect(self._update_nii_z)
+        self.ZSlider.sliderReleased.connect(
+            lambda: self._update_slice('z', 'nii_z'))
         control_layout.addWidget(self.ZSlider)
 
         # Gifti
@@ -333,23 +340,22 @@ class TrkViewer(QWidget):
             return
 
         for trk_path in filePaths:
-            self.trk_file = trk_path
-            print(f"Loaded TRK file: {self.trk_file}")
-            self.names.append(self.trk_file)
+            print(f"Loaded TRK file: {trk_path}")
+            self.actor_types[trk_path] = 'trk'
 
         self.update_trk_viewer(reset_camera=True)
-        self.parent().refreshActorList()
+        self.window().refreshActorList()
 
     def loadNiftiFile(self):
         options = QFileDialog.Options()
         filePath, _ = QFileDialog.getOpenFileName(
             self, "Open .nii.gz File", "", "Nifti Files (*.nii.gz)", options=options)
         if filePath:
-            self.nii_file = filePath
-            print(f"Loaded NIfTI file: {self.nii_file}")
+            print(f"Loaded NIfTI file: {filePath}")
             img = nib.load(filePath)
             self.nii_affine = img.affine
             self.nii_data = img.get_fdata()
+
             grid = pv.ImageData()
             grid.dimensions = np.array(self.nii_data.shape) + 1
             grid.cell_data['values'] = self.nii_data.flatten(order='F')
@@ -360,7 +366,10 @@ class TrkViewer(QWidget):
         self.ZSlider.setMaximum(self.nii_data.shape[2])
 
         self.update_nii_viewer(reset_camera=False)
-        self.parent().refreshActorList()
+        self.window().refreshActorList()
+
+        self.nii_data[self.nii_data == 0] = None
+        self.window().ortho_viewer.set_volume(self.nii_data, self.nii_affine)
 
     def loadROIFile(self):
         """Load one or multiple ROI nifti volumes and render as surfaces."""
@@ -383,26 +392,34 @@ class TrkViewer(QWidget):
 
             smooth = mesh.smooth_taubin(n_iter=12)
 
-            actor_name = f"roi_{roi_path.split('/')[-1]}"
+            actor_name = f"{roi_path.split('/')[-1]}"
+            self.actor_types[actor_name] = "roi"
+            self.roi_volumes[actor_name] = roi
+            self.roi_visibility[actor_name] = True
+
+            default_color = np.array([1.0, 1.0, 1.0])
+
+            self.roi_colors[actor_name] = default_color
 
             self.plotter.add_mesh(smooth, name=actor_name, opacity=1,
-                                  color="white", user_matrix=img.affine,
+                                  color=default_color, user_matrix=img.affine,
                                   reset_camera=False, point_size=0,
                                   render_lines_as_tubes=True)
 
-            self.parent().refreshActorList()
+            self.window().refreshActorList()
+
+            self.window().ortho_viewer.add_roi(actor_name, roi, default_color)
 
     def loadGiftiFile(self):
         options = QFileDialog.Options()
         filePath, _ = QFileDialog.getOpenFileName(
             self, "Open .gii File", "", "Gifti Files (*.gii)", options=options)
         if filePath:
-            self.gii_file = filePath
-            print(f"Loaded GIfTI file: {self.gii_file}")
+            print(f"Loaded GIfTI file: {filePath}")
             self.gii_mesh = gifti_to_pyvista(filePath)
 
         self.update_gii_viewer(reset_camera=False)
-        self.parent().refreshActorList()
+        self.window().refreshActorList()
 
     def set_background_color(self):
 
@@ -413,29 +430,16 @@ class TrkViewer(QWidget):
 
         self.plotter.background_color = self.background
 
+        self.window().ortho_viewer.set_background(self.background)
+
     def toggleColorBlind(self):
 
         self.color_blind = not self.color_blind
         self.update_trk_viewer()
 
-    def view_isometric(self):
-        self.plotter.view_isometric()
-        self.plotter.camera.azimuth += self.flicker*180
-        self.flicker = not self.flicker
-
-    def view_xy(self):
-        self.plotter.view_xy()
-        self.plotter.camera.azimuth += self.flicker*180
-        self.flicker = not self.flicker
-
-    def view_xz(self):
-        self.plotter.view_xz()
-        self.plotter.camera.azimuth += self.flicker*180
-        self.flicker = not self.flicker
-
-    def view_yz(self):
-        self.plotter.view_yz()
-        self.plotter.camera.azimuth += self.flicker*180
+    def set_view(self, method):
+        getattr(self.plotter, method)()
+        self.plotter.camera.azimuth += self.flicker * 180
         self.flicker = not self.flicker
 
     def take_screenshot(self):
@@ -503,66 +507,38 @@ class TrkViewer(QWidget):
             color_map = self.colorMapEdit.text()
             scalar = self.nii_data
 
-        for file in self.names:
-
-            plot_trk(file, opacity=opacity, plotter=self.plotter, scalar=scalar,
-                     show_points=show_points, color_map=color_map,
-                     name=file, background=self.background,
-                     reset_camera=reset_camera, color_blind=self.color_blind)
+        for file in list(self.actor_types):
 
-    def _update_nii_x(self):
-
-        if self.showSlicesCheckbox.isChecked():
+            if self.actor_types.get(file) == 'trk':
 
-            center = (self.XSlider.value(),
-                      self.YSlider.value(), self.ZSlider.value())
-
-            slice_x = self.grid.slice('x', center)
-            self.plotter.add_mesh(slice_x, cmap='grey', name='nii_x',
-                                  show_scalar_bar=False, point_size=0,
-                                  render_lines_as_tubes=True,
-                                  reset_camera=False,
-                                  user_matrix=self.nii_affine)
-        else:
-            self.plotter.remove_actor('nii_x')
+                plot_trk(file, opacity=opacity, plotter=self.plotter, scalar=scalar,
+                         show_points=show_points, color_map=color_map,
+                         name=file, background=self.background,
+                         reset_camera=reset_camera, color_blind=self.color_blind)
 
-    def _update_nii_y(self):
+    def _update_slice(self, axis, actor_name):
 
         if self.showSlicesCheckbox.isChecked():
 
-            center = (self.XSlider.value(),
-                      self.YSlider.value(), self.ZSlider.value())
-
-            slice_y = self.grid.slice('y', center)
-            self.plotter.add_mesh(slice_y, cmap='grey', name='nii_y',
-                                  show_scalar_bar=False, point_size=0,
-                                  render_lines_as_tubes=True,
-                                  reset_camera=False,
-                                  user_matrix=self.nii_affine)
-        else:
-            self.plotter.remove_actor('nii_y')
-
-    def _update_nii_z(self):
+            center = (self.XSlider.value(), self.YSlider.value(),
+                      self.ZSlider.value())
 
-        if self.showSlicesCheckbox.isChecked():
+            slice_mesh = self.grid.slice(axis, origin=center)
 
-            center = (self.XSlider.value(),
-                      self.YSlider.value(), self.ZSlider.value())
-
-            slice_z = self.grid.slice('z', center)
-            self.plotter.add_mesh(slice_z, cmap='grey', name='nii_z',
+            self.plotter.add_mesh(slice_mesh, cmap='grey', name=actor_name,
                                   show_scalar_bar=False, point_size=0,
                                   render_lines_as_tubes=True,
                                   reset_camera=False,
                                   user_matrix=self.nii_affine)
+
         else:
-            self.plotter.remove_actor('nii_z')
+            self.plotter.remove_actor(actor_name)
 
     def update_nii_viewer(self, reset_camera: bool = False):
 
-        self._update_nii_x()
-        self._update_nii_y()
-        self._update_nii_z()
+        self._update_slice('x', 'nii_x')
+        self._update_slice('y', 'nii_y')
+        self._update_slice('z', 'nii_z')
 
         opacity = self.nii_opacitySlider.value()/1000
         self.plotter.add_volume(self.grid, cmap='gray', opacity=[0, opacity],
@@ -580,11 +556,209 @@ class TrkViewer(QWidget):
                               render_lines_as_tubes=True,)
 
 
+class OrthogonalViewer(QWidget):
+
+    def __init__(self):
+        super().__init__()
+
+        self.volume = None
+        self.affine = None
+
+        self.rois = {}
+        self.roi_visibility = {}
+
+        self.background = "white"
+
+        layout = QVBoxLayout(self)
+
+        toolbar = QHBoxLayout()
+
+        btn_screenshot = QPushButton("Screenshot")
+        btn_screenshot.clicked.connect(self.take_screenshot)
+
+        toolbar.addStretch()
+        toolbar.addWidget(btn_screenshot)
+
+        layout.addLayout(toolbar)
+
+        self.fig = Figure(figsize=(12, 4), layout='constrained')
+        self.canvas = FigureCanvasQTAgg(self.fig)
+
+        self.ax_axial = self.fig.add_subplot(131)
+        self.ax_coronal = self.fig.add_subplot(132)
+        self.ax_sagittal = self.fig.add_subplot(133)
+
+        layout.addWidget(self.canvas)
+
+        self.x = 0
+        self.y = 0
+        self.z = 0
+
+        self.canvas.mpl_connect("scroll_event", self.on_scroll)
+        self.canvas.mpl_connect("button_press_event", self.on_click)
+
+    def set_volume(self, volume, affine=None):
+
+        self.volume = volume
+        self.affine = affine
+
+        self.x = volume.shape[0] // 2
+        self.y = volume.shape[1] // 2
+        self.z = volume.shape[2] // 2
+
+        self.update_views()
+
+    def add_roi(self, name, roi, color):
+
+        self.rois[name] = {"data": roi, "color": color}
+        self.roi_visibility[name] = True
+        self.update_views()
+
+    def draw_roi(self, ax, roi_slice, color):
+
+        if roi_slice.max() == 0:
+            return
+
+        ax.contour(roi_slice, levels=[0.5], colors=[color], linewidths=1.5,
+                   antialiased=True)
+        ax.contourf(roi_slice, levels=[0.5, roi_slice.max()+1], colors=[color],
+                    alpha=0.5)
+
+    def update_views(self):
+
+        if self.volume is None:
+            return
+
+        x = self.x
+        y = self.y
+        z = self.z
+
+        axial = self.volume[:, :, z]
+        coronal = self.volume[:, y, :]
+        sagittal = self.volume[x, :, :]
+
+        self.ax_axial.clear()
+        self.ax_coronal.clear()
+        self.ax_sagittal.clear()
+
+        for ax in (self.ax_axial, self.ax_coronal, self.ax_sagittal):
+            ax.axis("off")
+
+        self.ax_axial.imshow(np.rot90(axial), cmap="gray", vmin=0)
+        self.ax_coronal.imshow(np.rot90(coronal), cmap="gray", vmin=0)
+        self.ax_sagittal.imshow(np.rot90(sagittal), cmap="gray", vmin=0)
+
+        for name, roi_info in self.rois.items():
+
+            if not self.roi_visibility[name]:
+                continue
+
+            roi = roi_info["data"]
+            color = roi_info["color"]
+
+            self.draw_roi(self.ax_axial, np.rot90(roi[:, :, z]), color)
+            self.draw_roi(self.ax_coronal, np.rot90(roi[:, y, :]), color)
+            self.draw_roi(self.ax_sagittal, np.rot90(roi[x, :, :]), color)
+
+        self.canvas.draw_idle()
+
+        # self.window().viewer.XSlider.setValue(self.x)
+        # self.window().viewer.YSlider.setValue(self.y)
+        # self.window().viewer.ZSlider.setValue(self.z)
+
+        # self.window().viewer._update_slice('x', 'nii_x')
+        # self.window().viewer._update_slice('y', 'nii_y')
+        # self.window().viewer._update_slice('z', 'nii_z')
+
+    def take_screenshot(self):
+
+        options = QFileDialog.Options()
+
+        file_path, _ = QFileDialog.getSaveFileName(self,
+                                                   "Save Orthogonal View", "",
+                                                   "PNG Image (*.png);;JPEG Image (*.jpg);;TIFF Image (*.tif);; SVG Image (*.svg)",
+                                                   options=options
+                                                   )
+
+        if file_path:
+            self.fig.savefig(file_path, dpi=300, transparent=True)
+
+    def set_background(self, color):
+
+        self.background = color
+
+        self.fig.patch.set_facecolor(color)
+
+        for ax in (self.ax_axial, self.ax_coronal, self.ax_sagittal):
+            ax.set_facecolor(color)
+
+        self.canvas.draw_idle()
+
+    def on_scroll(self, event):
+
+        if self.volume is None:
+            return
+
+        step = 1 if event.button == "up" else -1
+
+        if event.inaxes == self.ax_axial:
+            self.z = np.clip(self.z + step, 0, self.volume.shape[2]-1)
+
+        elif event.inaxes == self.ax_coronal:
+            self.y = np.clip(self.y + step, 0, self.volume.shape[1]-1)
+
+        elif event.inaxes == self.ax_sagittal:
+            self.x = np.clip(self.x + step, 0, self.volume.shape[0]-1)
+
+        self.update_views()
+
+    def on_click(self, event):
+
+        if self.volume is None:
+            return
+
+        if event.inaxes is None:
+            return
+
+        if event.xdata is None or event.ydata is None:
+            return
+
+        col = int(round(event.xdata))
+        row = int(round(event.ydata))
+
+        if event.inaxes == self.ax_axial:
+
+            self.x = np.clip(col, 0, self.volume.shape[0]-1)
+            self.y = np.clip(
+                self.volume.shape[1]-1-row, 0, self.volume.shape[1]-1)
+
+        elif event.inaxes == self.ax_coronal:
+
+            self.x = np.clip(col, 0, self.volume.shape[0]-1)
+            self.z = np.clip(
+                self.volume.shape[2]-1-row, 0, self.volume.shape[2]-1)
+
+        elif event.inaxes == self.ax_sagittal:
+
+            self.y = np.clip(col, 0, self.volume.shape[1]-1)
+            self.z = np.clip(
+                self.volume.shape[2]-1-row, 0, self.volume.shape[2]-1)
+
+        self.update_views()
+
+
 class MainWindow(QMainWindow):
     def __init__(self):
         super().__init__()
+        self.tabs = QTabWidget()
+
         self.viewer = TrkViewer()
-        self.setCentralWidget(self.viewer)
+        self.ortho_viewer = OrthogonalViewer()
+
+        self.tabs.addTab(self.viewer, "3D Viewer")
+        self.tabs.addTab(self.ortho_viewer, "Orthogonal Viewer")
+
+        self.setCentralWidget(self.tabs)
         self.initActorDock()
         self.initMenuBar()
         self.setWindowTitle("UNVEIL - Tractography Viewer")
@@ -639,9 +813,14 @@ class MainWindow(QMainWindow):
         self.actorDock.setAllowedAreas(Qt.DockWidgetArea.RightDockWidgetArea)
 
         self.actorTree = QTreeWidget()
-        self.actorTree.setHeaderLabels(["Actor", "Visible"])
-        self.actorTree.setColumnCount(2)
-        self.actorTree.setColumnWidth(0, 200)
+
+        self.actorTree.setHeaderLabels(["Visible", "Color", "Actor"])
+        self.actorTree.setColumnCount(3)
+        self.actorTree.setIndentation(5)
+
+        self.actorTree.setColumnWidth(0, 45)
+        self.actorTree.setColumnWidth(1, 40)
+        self.actorTree.setColumnWidth(2, 220)
 
         self.actorDock.setWidget(self.actorTree)
         self.addDockWidget(
@@ -653,15 +832,20 @@ class MainWindow(QMainWindow):
         self.viewer.plotter.mesh_added_callback = self.refreshActorList
         self.viewer.plotter.mesh_removed_callback = self.refreshActorList
 
+        self.actorTree.itemDoubleClicked.connect(self.changeActorColor)
+
+        # Connect visibility toggles
+        self.actorTree.itemChanged.connect(self.onActorVisibilityChanged)
+
     def toggleActorDock(self, checked):
         if checked:
-
             self.actorDock.show()
         else:
             self.actorDock.hide()
 
     def refreshActorList(self):
         """Rebuild the hierarchical actor list grouped by class."""
+        self.actorTree.blockSignals(True)
         self.actorTree.clear()
 
         # Groups
@@ -676,43 +860,91 @@ class MainWindow(QMainWindow):
         self.actorTree.addTopLevelItem(group_roi)
         # Loop through PyVista actors
         for name, actor in self.viewer.plotter.actors.items():
-            item = QTreeWidgetItem([name, ""])
-            item.setCheckState(
-                1, Qt.CheckState.Checked if actor.GetVisibility() else Qt.CheckState.Unchecked)
+
+            item = QTreeWidgetItem(["", "", name])
+
+            item.setCheckState(0, Qt.CheckState.Checked if actor.GetVisibility()
+                               else Qt.CheckState.Unchecked)
 
             # Store name for callback
             item.actor_name = name
 
+            if self.viewer.actor_types.get(name) == 'roi':
+
+                rgb = self.viewer.roi_colors.get(name, (1, 1, 1))
+
+                qcolor = QColor(int(rgb[0] * 255), int(rgb[1] * 255),
+                                int(rgb[2] * 255))
+                item.setBackground(1, qcolor)
+
             # Insert into the correct group
-            if name.endswith(".trk"):
+            if self.viewer.actor_types.get(name) == 'trk':
                 group_trk.addChild(item)
             elif name.startswith("nii_"):
                 group_nii.addChild(item)
             elif name.startswith("gii_"):
                 group_gii.addChild(item)
-            elif name.startswith("roi_"):
+            elif self.viewer.actor_types.get(name) == 'roi':
                 group_roi.addChild(item)
             else:
                 group_trk.addChild(item)  # default bucket
 
-        # Connect visibility toggles
-        self.actorTree.itemChanged.connect(self.onActorVisibilityChanged)
+        self.actorTree.blockSignals(False)
 
     def onActorVisibilityChanged(self, item, column):
         """Toggle visibility when user clicks checkbox."""
-        if column != 1:
+        if column != 0:
             return
 
         actor_name = item.actor_name
-        visible = item.checkState(1) == Qt.CheckState.Checked
+        visible = item.checkState(0) == Qt.CheckState.Checked
 
         try:
             self.viewer.plotter.actors[actor_name].SetVisibility(visible)
         except KeyError:
             pass
 
+        self.viewer.roi_visibility[actor_name] = visible
+        self.ortho_viewer.roi_visibility[actor_name] = visible
+        self.ortho_viewer.update_views()
+
         self.viewer.plotter.render()
 
+    def changeActorColor(self, item, column):
+
+        if column != 1:
+            return
+
+        actor_name = getattr(item, "actor_name", None)
+
+        if actor_name is None:
+            return
+
+        if self.viewer.actor_types.get(actor_name) != "roi":
+            return
+
+        color = QColorDialog.getColor()
+
+        if not color.isValid():
+            return
+
+        rgb = (color.red() / 255, color.green() / 255, color.blue() / 255)
+
+        self.viewer.roi_colors[actor_name] = rgb
+        if actor_name in self.ortho_viewer.rois:
+            self.ortho_viewer.rois[actor_name]["color"] = rgb
+            self.ortho_viewer.update_views()
+
+        item.setBackground(1, color)
+
+        try:
+            actor = self.viewer.plotter.actors[actor_name]
+            actor.GetProperty().SetColor(*rgb)
+            self.viewer.plotter.render()
+
+        except Exception:
+            pass
+
 
 if __name__ == '__main__':
     app = QApplication(sys.argv)

unveil_python-0.5.0/src/unveil_python.egg-info/PKG-INFO

@@ -0,0 +1,74 @@
+Metadata-Version: 2.4
+Name: unveil-python
+Version: 0.5.0
+Summary: Implementation of UNVEIL
+Author-email: Nicolas Delinte <nicolas.delinte@uclouvain.be>
+License-Expression: GPL-3.0-only
+Project-URL: GitHub, https://github.com/DelinteNicolas/UNVEIL
+Keywords: tractography,viewer
+Classifier: Intended Audience :: Science/Research
+Classifier: Natural Language :: English
+Classifier: Programming Language :: Python
+Description-Content-Type: text/markdown
+License-File: LICENSE
+Requires-Dist: dipy
+Requires-Dist: pyvista
+Requires-Dist: pyvistaqt
+Requires-Dist: PyQt6
+Dynamic: license-file
+
+# UNVEIL
+[![PyPI](https://img.shields.io/pypi/v/unveil-python?label=pypi%20package)](https://pypi.org/project/unveil-python/)
+[![PyPI - Downloads](https://img.shields.io/pypi/dm/unveil-python)](https://pypi.org/project/unveil-python/)
+![GitHub repo size](https://img.shields.io/github/repo-size/DelinteNicolas/unveil)
+
+
+UNVEIL is a Python-based visualization tool for interactive exploration of diffusion MRI tractography, anatomical volumes, cortical surfaces, and ROI segmentations. It combines a 3D PyVista viewer with an orthogonal slice viewer.
+
+<img width="1297" height="757" alt="image" src="https://github.com/user-attachments/assets/28807e18-17fb-485b-a8ce-2179cdef796b" />
+
+## Install
+
+The GUI is launched with the following python command in a python console:
+
+```
+import unveil.__main__
+```
+or with
+```
+python -c "import unveil.__main__"
+```
+from a terminal with a python environment activated.
+
+## Features
+
+- **3D Tractography Visualization**
+    - Load and display `.trk` streamline files.
+    - RGB orientation coloring or scalar-based coloring from NIfTI volumes.
+    - Adjustable opacity and point/line rendering.
+- **Volume Rendering**
+    - Load `.nii.gz` images.
+    - Interactive volume rendering and orthogonal slice planes.
+    - Adjustable opacity.
+- **ROI Visualization**
+    - Load ROI masks from `.nii` / `.nii.gz`.
+    - Automatic surface extraction and smoothing.
+    - Individual visibility and color control.
+- **Surface Visualization**
+    - Load GIFTI (`.gii`) cortical surfaces.
+    - Adjustable opacity and smooth shading.
+- **Orthogonal Viewer**
+    - Axial, coronal, and sagittal views.
+    - Mouse-wheel slice navigation.
+    - Click-to-navigate crosshair synchronization.
+    - ROI overlay display.
+    - Screenshot export.
+- **Scene Management**
+    - Actor visibility control.
+    - ROI color editing.
+    - Background color toggle.
+    - Color-blind-friendly tractography coloring.
+- **Export**
+    - 3D screenshots.
+    - Orthogonal-view screenshots.
+    - Animated 360° GIF generation.

unveil_python-0.4.0/PKG-INFO

@@ -1,40 +0,0 @@
-Metadata-Version: 2.4
-Name: unveil-python
-Version: 0.4.0
-Summary: Implementation of UNVEIL
-Author-email: Nicolas Delinte <nicolas.delinte@uclouvain.be>
-License-Expression: GPL-3.0-only
-Project-URL: GitHub, https://github.com/DelinteNicolas/UNVEIL
-Keywords: tractography,viewer
-Classifier: Intended Audience :: Science/Research
-Classifier: Natural Language :: English
-Classifier: Programming Language :: Python
-Description-Content-Type: text/markdown
-License-File: LICENSE
-Requires-Dist: dipy
-Requires-Dist: pyvista
-Requires-Dist: pyvistaqt
-Requires-Dist: PyQt6
-Dynamic: license-file
-
-# UNVEIL
-[![PyPI](https://img.shields.io/pypi/v/unveil-python?label=pypi%20package)](https://pypi.org/project/unveil-python/)
-[![PyPI - Downloads](https://img.shields.io/pypi/dm/unveil-python)](https://pypi.org/project/unveil-python/)
-![GitHub repo size](https://img.shields.io/github/repo-size/DelinteNicolas/unveil)
-
-
-A simple tractography viewer implemented in python.
-
-<img width="1297" height="757" alt="image" src="https://github.com/user-attachments/assets/28807e18-17fb-485b-a8ce-2179cdef796b" />
-
-
-The GUI is launched with the following python command in a python console:
-
-```
-import unveil.__main__
-```
-or with
-```
-python -c "import unveil.__main__"
-```
-from a terminal with a python environment activated.

unveil_python-0.4.0/README.md

@@ -1,21 +0,0 @@
-# UNVEIL
-[![PyPI](https://img.shields.io/pypi/v/unveil-python?label=pypi%20package)](https://pypi.org/project/unveil-python/)
-[![PyPI - Downloads](https://img.shields.io/pypi/dm/unveil-python)](https://pypi.org/project/unveil-python/)
-![GitHub repo size](https://img.shields.io/github/repo-size/DelinteNicolas/unveil)
-
-
-A simple tractography viewer implemented in python.
-
-<img width="1297" height="757" alt="image" src="https://github.com/user-attachments/assets/28807e18-17fb-485b-a8ce-2179cdef796b" />
-
-
-The GUI is launched with the following python command in a python console:
-
-```
-import unveil.__main__
-```
-or with
-```
-python -c "import unveil.__main__"
-```
-from a terminal with a python environment activated.

unveil_python-0.4.0/src/unveil_python.egg-info/PKG-INFO

@@ -1,40 +0,0 @@
-Metadata-Version: 2.4
-Name: unveil-python
-Version: 0.4.0
-Summary: Implementation of UNVEIL
-Author-email: Nicolas Delinte <nicolas.delinte@uclouvain.be>
-License-Expression: GPL-3.0-only
-Project-URL: GitHub, https://github.com/DelinteNicolas/UNVEIL
-Keywords: tractography,viewer
-Classifier: Intended Audience :: Science/Research
-Classifier: Natural Language :: English
-Classifier: Programming Language :: Python
-Description-Content-Type: text/markdown
-License-File: LICENSE
-Requires-Dist: dipy
-Requires-Dist: pyvista
-Requires-Dist: pyvistaqt
-Requires-Dist: PyQt6
-Dynamic: license-file
-
-# UNVEIL
-[![PyPI](https://img.shields.io/pypi/v/unveil-python?label=pypi%20package)](https://pypi.org/project/unveil-python/)
-[![PyPI - Downloads](https://img.shields.io/pypi/dm/unveil-python)](https://pypi.org/project/unveil-python/)
-![GitHub repo size](https://img.shields.io/github/repo-size/DelinteNicolas/unveil)
-
-
-A simple tractography viewer implemented in python.
-
-<img width="1297" height="757" alt="image" src="https://github.com/user-attachments/assets/28807e18-17fb-485b-a8ce-2179cdef796b" />
-
-
-The GUI is launched with the following python command in a python console:
-
-```
-import unveil.__main__
-```
-or with
-```
-python -c "import unveil.__main__"
-```
-from a terminal with a python environment activated.