populse_mia.user_interface.data_browser.mini_viewer

This module provides the MiniViewer class, which is a PyQt-based widget designed for rapid visualization of medical scans. The MiniViewer allows users to view and interact with 3D, 4D, and 5D NIfTI images, providing tools to navigate through slices and time points.

Key Features:

• Visualize single images per scan with cursors to move in multiple dimensions.

• Display all images of the greater dimension of the scan.

• Support for 3D, 4D, and 5D NIfTI images.

• Configurable display settings, including orientation and slice navigation.

• Integration with project-specific configurations and preferences.

Classes

MiniViewer(project)

MiniViewer allows rapid visualization of scans with either a single image per scan or all images of the greater dimension of the scan.

class populse_mia.user_interface.data_browser.mini_viewer.MiniViewer(project)

Bases: QWidget

MiniViewer allows rapid visualization of scans with either a single image per scan or all images of the greater dimension of the scan.

Displayed images depend on their dimension:

• 3D: Display all slices.

• 4D: Display the middle slice of the third dimension for each time of the fourth dimension.

• 5D: Display the middle slice of the third dimension for the first time of the fourth dimension for each time of the fifth dimension.

Note

• idx corresponds to the index of the displayed image.

• idx in [0, self.max_scans].

• most of the class’s attributes are lists of 0 to self.max_scans elements.

Contains:

Methods:

• _create_layouts: Create the layouts for the MiniViewer.

• _create_top_bar: Create the top bar with the checkboxes and the orientation label.

• _initialize_checkboxes: Initialize the checkboxes for the MiniViewer.

• _initialize_components: Initialize the components of the MiniViewer.

• boxSlider: Create sliders, their connections and thumbnail labels for a selected index.

• changePosValue: Change the value of a cursor for the selected index.

• check_box_cursors_state_changed: Updates the config file.

• clear: Remove the Nibabel images to be able to remove it in the unit tests.

• clear_layouts: Clear the final layout.

• createDimensionLabels: Create the dimension labels for the selected index.

• createFieldValue: Create a field where will be displayed the position of a cursor.

• create_slider: Create a slider.

• displayPosValue: Display the position of each cursor for the selected index.

• enableSliders: Enable each slider of the selected index.

• image2DModifications: Apply modifications to the image to display it correctly.

• image_to_pixmap: Create a 2D pixmap from a N-D Nifti image.

• indexImage: Update the sliders values depending on the size of the selected image.

• mem_release: Reset all object lists to zero in order to preserve memory.

• navigImage: Display the 2D image for the selected index.

• openTagsPopUp: Opens a pop-up to select the legend of the thumbnails.

• setThumbnail: Set the thumbnail tag value under the image frame.

• show_slices: Create the thumbnails from the selected file paths.

• update_nb_slices: Update the config file and the thumbnails.

• update_visualization: Update the config file and the thumbnails.

• verify_slices: Verify the number of selected documents.

__init__(project)

Initialize the MiniViewer with project configuration.

The MiniViewer provides a thumbnail preview interface for scans, initially hidden to maximize space for the data browser.

Parameters:

project – The current project instance containing scan data and project-specific configuration.

_create_layouts()

Initialize and configure all layout managers for the MiniViewer widget.

Creates a hierarchical layout structure with:

• Horizontal layouts for images, sliders (3D/4D/5D), checkboxes, and thumbnails.

• Vertical layouts for main content organization and slider grouping.

• Sets the final vertical layout as the widget’s root layout.

All layouts are stored as instance attributes for later population with widgets.

_create_top_bar()

Create and configure the top control bar of the MiniViewer.

This method initializes a persistent horizontal container holding the main interactive controls of the viewer, including:

• A checkbox to enable/disable cursor display.

• An orientation label centered in the layout.

• A checkbox to switch to “all slices” display mode.

• Slice configuration controls (label + line edit), hidden by default.

_initialize_checkboxes()

Initialize checkboxes for controlling visualization behavior.

Creates two checkboxes:

• ‘Show all slices’: Toggles between displaying all slices or using cursors.

• ‘Chain cursors’: Links cursors across multiple selected documents.

Both checkboxes are initialized with their states from the current config and connected to their respective event handlers.

Contains:

Inner functions:

• _create_checkbox: Create a configured checkbox.

_initialize_components()

Initialize UI components for the MiniViewer.

Creates and configures the main UI elements including:

• Frame containers and scroll area for layout management.

• Slice count control with label and editable line input.

• Orientation label (radiological vs neurological view).

• Empty collections for dynamic image display elements (sliders, labels, images).

Note

Image-related collections are initialized as empty lists and populated dynamically based on the loaded data dimensions.

boxSlider(idx)

Initialize dimensional sliders and value fields for a given index.

Creates three sliders (3D, 4D, 5D) with their corresponding text fields and connects each slider’s valueChanged signal to the appropriate position update handler.

Parameters:

idx – (int) The index position where sliders should be inserted.

Note

Each slider is connected to changePosValue with dimension offsets:

• 3D slider: dimension 1.

• 4D slider: dimension 2.

• 5D slider: dimension 3.

changePosValue(idx, cursor_to_change)

Synchronize cursor positions across multiple image viewers when chain mode is enabled.

When the “Chain cursors” checkbox is checked, this method propagates the cursor value from the modified viewer to all other viewers, scaling the value proportionally to account for different cursor ranges.

Parameters:

• idx – (int) Index of the viewer whose cursor was changed.

• cursor_to_change – (int) Cursor identifier (1=3D, 2=4D, 3=5D).

Notes

• If chain mode is disabled, only updates the image for the given index.

• Boundary values (min/max) are preserved exactly.

• Intermediate values are scaled linearly to maintain relative position.

check_box_cursors_state_changed()

Update cursor chaining configuration based on checkbox state.

Synchronizes the cursor chaining setting in the configuration with the current state of the checkbox. When enabled, cursors will be chained together across views.

clear()

Clear cached Nibabel image to free memory.

Removes the internal image reference if it exists, allowing the image object to be garbage collected.

clear_layouts()

Remove and safely delete all widgets from the dynamic content layout.

This method clears the self.content_layout by iteratively removing each item and scheduling any associated QWidget for deletion using deleteLater(). This ensures proper memory management and avoids immediate deletion issues within the Qt event loop. Only widgets contained in self.content_layout are affected. Persistent UI elements (such as the top control bar) must not be part of this layout and are therefore preserved.

createDimensionLabels(idx)

Create and configure dimension labels for the specified index.

Creates three QLabel widgets (3D, 4D, and 5D) at the given index position, configures them with a 9-point font, and sets their text labels.

Parameters:

idx – The index position where the labels should be inserted.

createFieldValue()

Create a read-only field for displaying cursor position.

Returns:

(QLineEdit) A disabled, center-aligned text field with fixed width (65px) and font size (9pt) for displaying coordinate values.

create_slider(minimum=0, maximum=0, position=0)

Create a horizontal slider widget.

Parameters:

• minimum – The minimum value of the slider. Defaults to 0.

• maximum – The maximum value of the slider. Defaults to 0.

• position – The initial position/value of the slider. Defaults to 0.

Returns:

(QSlider) A configured horizontal slider widget, initially disabled.

Note

The slider is created with strong focus policy and a tick interval of 1. It starts in a disabled state. With default parameters (min=0, max=0), the slider has no range and should be configured before enabling.

displayPosValue(idx)

Update position display for all dimensional sliders at the given index.

Updates the text labels for 3D, 4D, and 5D sliders to show the current position (1-indexed) and maximum value in the format “current / max”.

Parameters:

idx – Index of the slider group to update (0-based).

enableSliders(idx)

Enable sliders at the specified index across all dimensions.

Parameters:

idx – Index of the sliders to enable across 3D, 4D, and 5D slider collections.

image2DModifications(idx, im2D=None)

Apply display modifications to a 2D image slice.

Processes an image for optimal display by:

1. Resizing to standard display dimensions.

2. Rescaling intensities with percentile-based clipping.

3. Converting to appropriate display data type.

4. Applying orientation rotation (radiological/neurological).

Parameters:

• idx – Index of the image slice in the internal array.

• im2D – Optional 2D numpy array to modify. If None, uses self.im_2D[idx].

Note

When im2D is not provided, the modified image is stored in self.im_2D[idx].

Contains:

Inner functions:

• _resize_image: Resize image with anti-aliasing handling.

• _rescale_intensities: Rescale image intensities using percentile-based normalization.

• _apply_rotation: Apply orientation-specific rotation to image.

image_to_pixmap(im, i)

Convert an N-dimensional NIfTI image to a 2D Qt pixmap.

Extracts a 2D slice from multi-dimensional medical imaging data and converts it to a Qt pixmap for display. The extraction strategy depends on dimensionality:

• 3D images: Extract slice at index i along the z-axis.

• 4D images: Extract middle z-slice from the 3D volume at time index i.

• 5D images: Extract middle z-slice from the 3D volume at time index 1 of the 4D volume at the 5th dimension index i.

Parameters:

• im – NIfTI image object with a dataobj attribute.

• i – Index for slice/volume selection along the outermost variable dimension.

Returns:

(QPixmap) Qt pixmap ready for display, or pixmap from empty array if dimensionality is unsupported.

indexImage(idx)

Update the displayed 2D image slice and adjust slider ranges according to the dimensionality of the selected image.

The current values of the 3D, 4D, and 5D sliders are used to extract the corresponding slice from the image data. Sliders that exceed the image dimensionality are reset to a maximum value of 0.

Parameters:

idx – Index of the selected image.

mem_release()

Release memory by clearing all internal lists holding images, sliders, labels, and related UI elements.

This method empties the existing lists in place (without reassigning them) to ensure that all references are removed and memory can be reclaimed.

navigImage(idx)

Display the 2D image corresponding to the given index.

This method updates the navigation state, applies image-specific modifications, converts the image to a Qt pixmap, and displays it in the associated label.

Parameters:

idx – (int) Index of the image to display.

openTagsPopUp()

Open a modal dialog allowing the user to select the tag used as the thumbnail legend.

If the dialog is accepted, slice verification is triggered for the current file paths.

Note

The dialog instance is stored on self.popUp to allow access from unit tests.

setThumbnail(file_path_db, idx)

Set the thumbnail description label for a given image index.

Retrieves the value of the configured thumbnail tag from the database and displays it under the image frame. If the value is not defined, a default placeholder is used. The tooltip shows the tag name.

Parameters:

• file_path_db – (str) Path of selected image in database format (ex. data/raw_data/mymri.nii’).

• idx – (int) Index of the image in the UI.

show_slices(file_paths)

Display thumbnail previews of neuroimaging files with interactive controls.

Creates a thumbnail viewer showing either cursor-controlled slices or multiple slices from the selected neuroimaging files. On first call, makes the MiniViewer visible. Does nothing if the viewer is hidden by the user.

The viewer supports two display modes:

• Cursor mode (default): Shows one slice per image with interactive 3D/4D/5D sliders.

• All slices mode: Displays multiple consecutive slices from each image.

Parameters:

file_paths – List of paths to neuroimaging files (NIfTI format) to display. Invalid or non-existent files are automatically filtered out with warnings.

Side effects:

• Modifies self.file_paths by removing invalid entries.

• Updates self.img list with loaded image objects.

• Creates and configures numerous Qt widgets for the thumbnail display.

• Logs warnings for files that cannot be loaded or displayed.

Note

Maximum thumbnails displayed is controlled by self.config.get_max_thumbnails() in cursor mode, and by self.line_edit_nb_slices.text() in all slices mode.

update_nb_slices()

Update slice configuration and refresh thumbnails.

Triggered when the user modifies the number of slices to visualize. Updates the configuration with the new slice count and re-validates the current file paths to regenerate thumbnails accordingly.

Note

The slice count is retrieved from the UI line edit widget and applied to all loaded files.

update_visualization()

Update visualization settings and refresh thumbnails.

Synchronizes the slice visualization preference (show all slices vs. single slice) based on the checkbox state, updates the configuration, and regenerates thumbnails for the current file paths. This method is triggered when the user toggles the “show all slices” checkbox.

verify_slices(file_paths)

Update slice display settings based on the number of selected files.

When multiple files are selected, the “Show all slices” checkbox is disabled and unchecked to prevent viewing slices from multiple files simultaneously. For single file selection, the checkbox remains enabled.

Parameters:

file_paths – List or collection of selected document file paths.