Weasis Documentation

When working with MPR, you must distinguish between two types of crosshair position methods to avoid rendering or interaction errors:

getCrossHairPosition() (No arguments)

• Purpose: Returns the raw volume-space center.
• Usage: Used by the rendering pipeline (e.g., VolImageIO.getImageFragment(), MprAxis.updateRotation()) to sample the 3D volume.
• Constraint: It must not apply any canvas projection. It represents a true 3D coordinate in the volume.

getCrossHairPosition(MprAxis axis)

• Purpose: Returns the center projected onto a specific view's 2D canvas.
• Usage: Used for UI and interaction (e.g., mouseMoved() for hit-testing, addCrossline() for drawing graphics, mouseDragged() for computing new positions).
• Constraint: It must apply the full inverse rotation (viewRotation⁻¹) to correctly project the 3D center onto the 2D plane.

The Multi-Planar Reconstruction (MPR) rotation system uses three distinct layers to manage how views are oriented relative to the 3D volume and how user interactions (like tilting crosshairs) affect the display:

1. Base Plane Rotations: Fixed rotations that orient each plane relative to the volume axes.

   • AXIAL: Identity (Canvas XY = Volume XY).
   • CORONAL: Rx(-90°) with a Y-flip S(1, -1, 1) for anatomical orientation.
   • SAGITTAL: Ry(90°) · Rz(90°).

2. Global Rotation: An accumulated rotation applied when a user tilts the crosshair on any view. This affects all views.

3. Per-Plane Rotation Offset: A local offset used to cancel out the globalRotation for the specific view being tilted. This ensures that if you tilt the crosshair on the AXIAL view, the AXIAL view itself remains unchanged while the CORONAL and SAGITTAL views reflect the tilt.

// Example of how global rotation is updated during a tilt:
// In rotateAroundAxis():
Vector3d axis = plane.getDirection();          // (0,0,1) for AXIAL
Quaterniond q = Quaterniond().fromAxisAngleRad(axis, planeAngle);
globalRotation.mul(q);

The Multi-Planar Reconstruction (MPR) system in Weasis uses a four-stage pipeline to transform raw voxel data into a viewable screen image. Understanding this flow is essential for implementing custom rendering or coordinate transformations:

1. Voxel Index Space: The raw 3D integer grid defined by Volume.size.
2. VR-Space (Voxel-Ratio-Scaled Space): An "isotropised" space where equal distances correspond to equal physical distances, compensating for anisotropic voxel spacing.
3. Isotropic Slice Space (Working Space): The 2D/3D space where user interactions (crosshairs, mouse clicks, panning, zooming) occur. It uses a square pixel grid where each pixel represents the smallest physical spacing (min(pixelRatio)).
4. Screen / Viewport Space: The final 2D projection on the user's monitor.

This pipeline ensures that even if the original volume is anisotropic (e.g., thick CT slices), the user interacts with a visually consistent, isotropic representation.

Voxel Index Space           [0, size.i)
      │
      │  × voxelRatio (per-component)
      ▼
VR-Space                    [0, volSize.i)       ← getRealVolumeTransformation output
      │
      │  (conversion only in getRealVolumeTransformation)
      ▼
Isotropic Slice Space       [0, sliceSize]²      ← AxesControl.center, crosshair, mouse
      │
      │  view transform (pan, zoom)
      ▼
Screen / Viewport Space

Weights control how space is distributed when the container resizes.

Grow Weight (Default: 100)

Controls space distribution when the container expands.

• Higher weight: Receives more extra space.
• Weight 0: Fixed size (won't grow beyond preferred size).
• Proportionality: Weights are relative (e.g., a 1:2:1 ratio is implemented as 100, 200, 100).

Shrink Weight (Default: 100)

Controls space reduction when the container shrinks.

• Higher weight: Loses more space when the container shrinks.
• Weight 0: Won't shrink below preferred size.
• Independence: Grow and shrink weights are independent; a component can be configured to grow but not shrink, or vice versa.

Fill Property

Determines if a component expands to occupy the entire cell.

• true: Component fills the cell.
• false: Component uses its preferred size and alignment.

// Three columns growing in 1:2:1 ratio
double[] columnWeights = {100, 200, 100};
model.setColumnWeights(columnWeights);

// First column shrinks slowly, second shrinks quickly
double[] growWeights = {100, 100};
double[] shrinkWeights = {25, 100};
model.setColumnWeights(growWeights, shrinkWeights);

Weasis manages memory across three distinct 'arenas' because DICOM pixel data is often too large for the JVM heap and is allocated via native code (OpenCV) or the GPU. Understanding these boundaries is critical for debugging memory issues:

Note: Runtime.getRuntime().maxMemory() only describes the JVM heap. Weasis calculates its native memory budget based on physical RAM to avoid competing with the OS and the heap.

The Multi-Planar Reconstruction (MPR) system reconstructs three orthogonal slice views (Axial, Coronal, and Sagittal) from a 3D volume. It allows users to navigate the volume by moving a crosshair, rotating (tilting) the crosshair to view oblique slices, scrolling along the slice normal, and adjusting Maximum Intensity Projection (MIP) thickness.

Component Architecture

• MprContainer: The top-level container.
• MprView: Three instances (AXIAL, CORONAL, SAGITTAL) that display the reconstructed slices.
• MprController: A central controller that handles mouse input and crosshair interactions across all views.
• AxesControl: Manages the global state of the crosshair system (position and rotation).
• Volume<?,?>: The underlying 3D voxel data.

┌────────────────────────────────────────────────────────┐
│                     MprContainer                       │
│  ┌──────────────┐  ┌──────────────┐  ┌──────────────┐  │
│  │  MprView     │  │  MprView     │  │  MprView     │  │
│  │  (AXIAL)     │  │  (CORONAL)   │  │  (SAGITTAL)  │  │
│  │              │  │              │  │              │  │
│  │  MprAxis ◄───┼──┼── MprAxis ◄──┼──┼── MprAxis    │  │
│  └──────┬───────┘  └──────┬───────┘  └──────┬───────┘  │
│         │                 │                 │          │
│         └────────┬────────┴────────┬────────┘          │
│                  │                 │                   │
│           MprController       AxesControl              │
│            (mouse input)    (center, rotation)         │
│                  │                 │                   │
│                  └────────┬────────┘                   │
│                           │                            │
│                      Volume<?,?>                       │
│                     (voxel data)                       │
└────────────────────────────────────────────────────────┘