Introducing the loading of multi-contrast, multiple images into the viewer simultaneously

[AcastaPaloma]

No description provided.

[AcastaPaloma]

TODO on July 16, 2025: Explain objective very well, approach and potential issues.

[AcastaPaloma]

---

Feature Proposal: Multi-Contrast Subject-Based Workflow

Objective

The primary goal of this feature is to evolve SlicerCART from its current single-file iterator into a robust, multi-contrast, subject-centric platform. This will allow users to load, view, and segment cases that consist of multiple imaging series (e.g., T1, T2, FLAIR) simultaneously, providing critical clinical context and improving workflow efficiency.

---

Proposed Approach

The implementation will be centered around a shift from a file-based to a subject-based logic, broken down into four key stages:

1. Intelligent Subject Grouping:

   • Upon selecting a root directory, a new grouping mechanism will automatically scan for all image files.
   • It will first attempt to group files based on BIDS naming conventions (sub- and ses- identifiers) for maximum reliability.
   • If a BIDS structure is not detected, it will fall back to a heuristic-based approach using regular expressions to identify a common subject "base name" and variable contrast identifiers within filenames.
   • The result will be a mapping of unique subject IDs to their respective lists of contrast image files.

2. UI & Iterator Refactoring:

   • The main case list in the UI will be populated with the unique subject IDs, not individual filenames.
   • The internal logic will be modified to iterate through subjects. Selecting a subject will retrieve all associated file paths for loading.

3. Synchronized Multi-Volume Loading:

   • When a subject is selected, all of its associated contrast volumes will be loaded into the Slicer scene.
   • The layout will automatically adjust to a multi-panel grid (e.g., 2x2), with each viewer displaying a different contrast.
   • All slice viewers will be linked, ensuring that scrolling, panning, or zooming in one view is synchronized across all others.

4. Smart Saving with a Manifest File:

   • To ensure data integrity and reproducibility, the saving mechanism will be updated. Instead of only saving the segmentation mask, two files will be created for each subject:
     • The segmentation mask (..._mask.nii.gz).
     • A JSON manifest file (..._manifest.json).
   • This manifest file will act as a receipt, storing metadata such as the annotator, date, and, most importantly, the paths to all the original source volumes used for the segmentation. This approach avoids data duplication while preserving the crucial link between a mask and its multiple source images.

---

Potential Issues & Considerations

• Grouping Ambiguity: The heuristic-based filename grouping relies on predictable naming patterns. Inconsistently named files within a "dump" folder could lead to incorrect grouping. The regex patterns may need to be user-configurable.
• Reference Geometry: When creating a segmentation based on multiple volumes, a single reference volume must be designated to define the geometry (origin, spacing, orientation) of the output mask. This selection process must be handled explicitly in the logic.
• Performance: Loading numerous large imaging files for each subject may introduce performance bottlenecks, especially on machines with limited memory. Future optimizations may be necessary.
• Layout Complexity: While the layout manager can handle various configurations, creating an elegant and universally functional layout for an arbitrary number of contrasts (e.g., 7 or 8) can be challenging and may require thoughtful design.

[AcastaPaloma]

@AcastaPaloma Use normal dict instead of defaultdict for subjects

[AcastaPaloma]

TODO:
Must do's

• - update self.subjects_to_all_contrasts nested dict to implement switching between true and false (display on viewers or not) - currently, it is only from false to true, no back and forth
• - make UI of configure multicontrast more user-friendly - tooltips for dragging and dropping
• - make sure ordering of contrasts in multicontrast small window matches order loaded in viewer
• - re-enable single image view
• - test with praxis dataset
• - implement saving of multicontrasted images
• - add an errox box if configure multicontrast is clicked despite being no case list loaded
• - implement better regex or subject discernment

Enhancement and not within scope of PR

• - implementing clearing of scene between loads
• - memory management, memory leak resolving

[AcastaPaloma]

Proposed saving mechanism

- [ ] Save in BIDS format

Loading previously multicontrasted sessions will be very hard.

[AcastaPaloma]

https://mantisarchive.slicer.org/view.php?id=2718

vtkCollection vtkMRMLScene::GetNodesByClass(const char className)
vtkCollection vtkMRMLScene::GetNodesByName(const char name)
vtkCollection vtkMRMLScene::GetNodesByClassByName(const char className, const char name)
vtkCollection vtkMRMLScene::GetReferencedNodes(vtkMRMLNode *node)

vtkCollection vtkMRMLLayoutLogic::GetViewsFromLayout(vtkXMLDataElement root)

vtkCollection vtkEventBroker::GetObservationsForSubject ( vtkObject subject )
vtkCollection vtkEventBroker::GetObservationsForObserver ( vtkObject observer )
vtkCollection vtkEventBroker::GetObservationsForCallback ( vtkCallbackCommand callback )

Memory leak is most likely caused by these deprecated methods in the codebase.

[AcastaPaloma]

Impossible to create multicontrast and singlecontrast together, a new widget is required due to saving.

EDIT: resolved. main mode is now multicontrast mode. the segmentations are all linked and saved to one file, as before.