Change reference system - josalggui/MaRGE GitHub Wiki

Step-by-Step Tutorial: Changing the Scanner's Reference System

The latest version of MaRGE (pending publication in the master branch) introduces functionality to modify the scanner's initial reference system. This enables adjustments to the position and orientation of the scanner's axes. For the moment this works only with RARE sequence, but future release will expand this functionality to all the sequences.

While changing the position of the axes might not have a clear use case, adjusting the orientation can be valuable when the scanner's axes are not properly aligned with the laboratory's reference system.

Parameters for Changing the Reference System

Three new parameters in the hw_config.py file allow you to modify the reference system:

  • rotations: A list of rotations.
  • dfovs: A list of displacements in millimeters.
  • fovs: A list of field-of-view (FOV) values in centimeters. (This parameter may not have a specific function at the moment, but it's included for completeness.)

Each parameter is represented as a list of lists, where each inner list defines one modification step. These steps are applied consecutively to the reference system.

Example Configuration

For instance, let's define the following parameters:

rotations = [rotation1], [rotation2], [rotation3], [rotation4](/josalggui/MaRGE/wiki/rotation1],-[rotation2],-[rotation3],-[rotation4)
dfovs = [dfov1], [dfov2], [dfov3], [dfov4](/josalggui/MaRGE/wiki/dfov1],-[dfov2],-[dfov3],-[dfov4)
fovs = [fov1], [fov2], [fov3], [fov4](/josalggui/MaRGE/wiki/fov1],-[fov2],-[fov3],-[fov4)

This setup applies four consecutive changes to the reference system, in the order specified by the indices (from 1 to 4).

Understanding the rotations Parameter

The rotations parameter specifies a list of rotation instructions. Each instruction is defined as a list:

[ux, uy, uz, theta]

Where:

  • ux, uy, uz: Components of the rotation axis as a unit vector, satisfying ( u_x^2 + u_y^2 + u_z^2 = 1 ).
  • theta: Rotation angle in degrees.

Example:

[0, 0.7071, 0.7071, 45.0]

This example defines a 45-degree rotation around an axis that is:

  • Perpendicular to the x-axis, and
  • Forms a 45-degree angle with the y-axis.

Step-by-Step Instructions Using the GUI

By default, the hw_config.py file has empty lists for these parameters:

rotations = []
dfovs = []
fovs = []

At this point, the scanner uses the axes defined by the gradients. To align the reference system with a phantom of known shape (randomly oriented inside the scanner), follow these steps:

  1. Configure a Localizer to run projections along the three orthogonal planes.
  2. Note that Localizer inherits from RAREProtocols, which doesn’t support rotations. To handle rotations:
    • Define new localizers in a Protocol from the RARE sequence, or
    • Use the Custom tab to run RARE projection images directly.

The figure below shows three projections obtained using the localizers:

Projection 1

Adjusting the FOV and Recording Values

  1. Select the transversal plane, activate the FOV button, and rotate it to align with the image.
  2. Important: Before running the sequence, record the values for Angle (º) and Rotation axis.

Step 1

  • Example values:
    • Angle: 30º
    • Rotation axis: [1, 0, 0]

After recording these values, run the sequence to align the image correctly in this plane:

Step 2

Repeating for Other Orientations

Repeat the process for another projection (e.g., axis [2, 0, 1]):

  1. Adjust the FOV and annotate the Angle and Rotation axis.

Step 3

  • Example values:
    • Angle: 9.16º
    • Rotation axis: [0, 1, 0]

After recording these values, run the sequence to get an aligned image:

Step 4

Finally, repeat for the remaining orientation (e.g., axis [0, 1, 2]):

Step 5

  • Example values:
    • Angle: 5.53º
    • Rotation axis: [0, 0, 1]

Run the sequence, and the aligned image should appear:

Step 6

Saving the Reference System to hw_config.py

At this stage, your reference system is aligned with the phantom. Running new projections should give consistent results:

Aligned Projections

To preserve this reference system after closing MaRGE, update the hw_config.py file with the recorded values. Note: Convert angles from degrees to radians.

Example:

rotations = [
    [1, 0, 0, 30.0 * np.pi / 180],
    [0, 1, 0, 9.16 * np.pi / 180],
    [0, 0, 1, 5.53 * np.pi / 180],
]
dfovs = [
    [0.0, 0.0, 0.0],
    [0.0, 0.0, 0.0],
    [0.0, 0.0, 0.0],
]
fovs = [
    [0.0, 0.0, 0.0],
    [0.0, 0.0, 0.0],
    [0.0, 0.0, 0.0],
]

After saving these changes and restarting MaRGE, the scanner will use the updated reference system by default, ensuring that future projections remain aligned:

Final Image