confusius.registration¶

Compose translations, rotations, zooms, and shears into an affine matrix.

Parameters:

• T ¶

  ((N,) numpy.ndarray) –

  Translation vector, where N is usually 3 (3D case).

• R ¶

  ((N, N) numpy.ndarray) –

  Rotation matrix, where N is usually 3 (3D case).

• Z ¶

  ((N,) numpy.ndarray) –

  Zoom (scale) vector, where N is usually 3 (3D case).

• S ¶

  ((P,) numpy.ndarray, default: None ) –

  Shear vector filling the upper triangle above the diagonal of the shear matrix. P is the (N-2)-th triangular number (3 for the 3D case). If None, no shear is applied.

Returns:

• (N+1, N+1) numpy.ndarray –

  Homogeneous affine transformation matrix.

Compute framewise displacement from affine transforms.

Framewise displacement measures how much voxels move between consecutive frames after registration. For each voxel, we compute the Euclidean distance between its position at frame t and frame t+1 after applying the affine transforms.

Parameters:

• affines ¶

  (list[ndarray | None]) –

  List of affine matrices, one per frame. None entries are treated as identity transforms.

• reference ¶

  (DataArray) –

  Spatial DataArray defining the physical grid (spacing and origin derived from its coordinates).

• mask ¶

  (ndarray, default: None ) –

  Boolean mask indicating which voxels to include. If not provided, uses all voxels.

Returns:

• dict –

  Dictionary with keys:

  • "mean_fd": Mean framewise displacement per frame.
  • "max_fd": Maximum framewise displacement per frame.
  • "rms_fd": RMS framewise displacement per frame.

Create a DataFrame with motion parameters and framewise displacement.

Parameters:

• affines ¶

  (list[ndarray | None]) –

  List of affine matrices from registration. None entries (e.g. from B-spline transforms) are treated as identity.

• reference ¶

  (DataArray) –

  Spatial DataArray defining the physical grid for framewise displacement computation.

• mask ¶

  (ndarray, default: None ) –

  Boolean mask for FD computation.

• time_coords ¶

  (ndarray, default: None ) –

  Time coordinates for each frame.

Returns:

• DataFrame –

  DataFrame with columns:

  For 2D:

  • rotation: Rotation angle in radians.
  • trans_x: Translation in x (mm).
  • trans_y: Translation in y (mm).

  For 3D:

  • rot_x, rot_y, rot_z: Rotation angles in radians.
  • trans_x, trans_y, trans_z: Translations (mm).

  Both: - mean_fd: Mean framewise displacement (mm). - max_fd: Maximum framewise displacement (mm). - rms_fd: RMS framewise displacement (mm).

Decompose a 4x4 homogeneous affine into translation, rotation, zoom, shear.

Decomposes A44 into T, R, Z, S such that::

Smat = np.array([[1, S[0], S[1]],
                 [0,    1, S[2]],
                 [0,    0,    1]])
RZS = R @ np.diag(Z) @ Smat
A44[:3, :3] = RZS
A44[:3,  3] = T

Parameters:

• A44 ¶

  ((4, 4) numpy.ndarray) –

  Homogeneous affine matrix.

Returns:

• T ( (3,) numpy.ndarray ) –

  Translation vector.

• R ( (3, 3) numpy.ndarray ) –

  Rotation matrix.

• Z ( (3,) numpy.ndarray ) –

  Zoom (scale) vector. May have one negative zoom to avoid a negative determinant in R.

• S ( (3,) numpy.ndarray ) –

  Shear vector [sxy, sxz, syz] filling the upper triangle of the shear matrix. Zero for pure rotation/zoom affines.

Extract motion parameters from affine matrices.

Decomposes each (N+1, N+1) homogeneous affine into translation and rotation parameters.

For 2D transforms, extracts: [rotation, translation_x, translation_y]. For 3D transforms, extracts: [rot_x, rot_y, rot_z, trans_x, trans_y, trans_z].

Parameters:

• affines ¶

  (list[ndarray | None]) –

  List of affine matrices from registration. None entries (e.g. from B-spline transforms) are treated as identity transforms.

Returns:

• (n_frames, n_params) numpy.ndarray –

  Motion parameters array.

  • For 2D: n_params = 3 (rotation, tx, ty).
  • For 3D: n_params = 6 (rot_x, rot_y, rot_z, trans_x, trans_y, trans_z).

Raises:

• ValueError –

  If any affine does not have shape (3, 3) (2D) or (4, 4) (3D).

Register a single 2D or 3D volume to a fixed reference.

Voxel spacing and origin are automatically extracted from the DataArray coordinates. Both inputs must be spatial-only (no time dimension).

Parameters:

• moving ¶

  (DataArray) –

  Volume to register to fixed. Must be 2D or 3D.

• fixed ¶

  (DataArray) –

  Reference volume. Must be 2D or 3D. Need not have the same shape as moving.

• transform ¶

  ((translation, rigid, affine, bspline), default: "translation" ) –

  Transform model to use during registration. "translation" allows only shifts. "rigid" adds rotation. "affine" adds scaling and shearing. "bspline" fits a non-linear deformable transform (see mesh_size).

• metric ¶

  ((correlation, mattes_mi), default: "correlation" ) –

  Similarity metric. "correlation" (normalized cross-correlation) is appropriate for same-modality registration. "mattes_mi" (Mattes mutual information) is better suited for multi-modal registration or when the intensity relationship between images is non-linear.

• number_of_histogram_bins ¶

  (int, default: 50 ) –

  Number of histogram bins used by Mattes mutual information. Only relevant when using "mattes_mi" metric.

• learning_rate ¶

  (float or auto, default: "auto" ) –

  Optimizer step size in normalized units. "auto" re-estimates the rate at every iteration. A float uses that value directly; if registration diverges or fails to converge, reduce it.

• number_of_iterations ¶

  (int, default: 100 ) –

  Maximum number of optimizer iterations.

• convergence_minimum_value ¶

  (float, default: 1e-6 ) –

  Value used for convergence checking in conjunction with the energy profile of the similarity metric that is estimated in the given window size.

• convergence_window_size ¶

  (int, default: 10 ) –

  Number of values of the similarity metric which are used to estimate the energy profile of the similarity metric.

• initialization ¶

  ((geometry, moments, none), default: "geometry" ) –

  Transform initializer applied before optimization. "geometry" aligns the image centers (safe default, no assumptions about content). "moments" aligns centers of mass (better when images are offset but share the same content). "none" uses the identity transform. Ignored for transform="bspline".

• optimizer_weights ¶

  (list of float or None, default: None ) –

  Per-parameter weights applied on top of the auto-estimated physical shift scales. None uses identity weights (all ones). A list is passed directly to SimpleITK's SetOptimizerWeights; its length must match the number of transform parameters (3 for 2D rigid, 6 for 3D rigid, 6 for 2D affine, 12 for 3D affine). The weight for each parameter is multiplied into the effective step size: 0 freezes a parameter entirely, values in (0, 1) slow it down, and 1 leaves it unchanged. For the 3D Euler transform the parameter order is [angleX, angleY, angleZ, tx, ty, tz]; to disable rotations around x and y set weights to [0, 0, 1, 1, 1, 1].

• initial_transform ¶

  ((N+1, N+1) numpy.ndarray or None, default: None ) –

  Pre-computed affine matrix (pull/inverse convention, as returned by a previous call to register_volume) used as a warm-start before optimisation. When provided the child transform (transform) is composed on top of this pre-alignment. Primarily useful for the affine → B-spline composition workflow: run an affine registration first, then pass its result here together with transform="bspline" to refine the deformation. When None (the default) the existing initialization behaviour is unchanged.

• mesh_size ¶

  (tuple of int, default: (10, 10, 10) ) –

  Number of B-spline mesh nodes along each spatial dimension. Only used when transform="bspline".

• use_multi_resolution ¶

  (bool, default: False ) –

  Whether to use a multi-resolution pyramid during registration. When True, registration proceeds from a coarse downsampled version of the images to the full resolution, which improves convergence for large displacements and reduces the risk of local minima.

• shrink_factors ¶

  (sequence of int, default: (6, 2, 1) ) –

  Downsampling factor at each pyramid level, from coarsest to finest. Must have the same length as smoothing_sigmas. Only used when use_multi_resolution=True.

• smoothing_sigmas ¶

  (sequence of int, default: (6, 2, 1) ) –

  Gaussian smoothing sigma (in voxels) applied at each pyramid level, from coarsest to finest. Must have the same length as shrink_factors. Only used when use_multi_resolution=True.

• resample ¶

  (bool, default: False ) –

  Whether to resample the moving volume onto the fixed grid after estimating the transform. When True, the output is resampled onto the fixed grid and its coordinates match fixed. When False (the default), only the transform is computed and the moving volume is returned unchanged with its original coordinates.

• resample_interpolation ¶

  ((linear, bspline), default: "linear" ) –

  Interpolator used when resampling the moving volume onto the fixed grid. "linear" is fast and appropriate for most cases. "bspline" (3rd-order B-spline) produces smoother results and reduces ringing, useful for atlas registration. Only used when resample=True.

• sitk_threads ¶

  (int, default: -1 ) –

  Number of threads SimpleITK may use internally. Negative values resolve to max(1, os.cpu_count() + 1 + sitk_threads), so -1 means all CPUs, -2 means all minus one, and so on. You may want to set this to a lower value or 1 when running multiple registrations in parallel (e.g. with joblib) to avoid over-subscribing the CPU.

• show_progress ¶

  (bool, default: False ) –

  Whether to display a live progress plot during registration. The plot is shown in a Jupyter notebook or in an interactive matplotlib window depending on the active backend.

• plot_metric ¶

  (bool, default: True ) –

  Whether to include the optimizer metric curve in the progress plot. Ignored when show_progress=False.

• plot_composite ¶

  (bool, default: True ) –

  Whether to include a fixed/moving composite overlay in the progress plot. Requires resampling the moving image at every iteration. Ignored when show_progress=False.

Returns:

• registered ( DataArray ) –

  When resample=True, the moving volume resampled onto the fixed grid with coordinates matching fixed. When resample=False, the original moving volume with a registration attribute added to its metadata.

• transform ( (N+1, N+1) numpy.ndarray or xarray.DataArray or None ) –

  Estimated registration transform. For linear transforms ("translation", "rigid", "affine"), returns a homogeneous affine matrix of shape (N+1, N+1) in physical space, where N is the spatial dimensionality (2 or 3). Follows SimpleITK's pull/inverse convention: the matrix maps fixed-space coordinates to moving-space coordinates. For transform="bspline", returns a DataArray encoding the B-spline control-point grid (see [confusius.registration.bspline][] for the DataArray schema). When initial_transform was also supplied, the DataArray includes attrs["affines"]["bspline_initialization"] so that the full composite (pre-affine + B-spline) can be reconstructed for resampling.

Raises:

• ValueError –

  If either input contains a time dimension or is not 2D or 3D.

• ValueError –

  If transform, metric, initialization, or resample_interpolation is not a recognised value.

• ValueError –

  If learning_rate is not a positive finite float or "auto".

• ValueError –

  If number_of_iterations, convergence_window_size, or number_of_histogram_bins is not a positive integer.

• ValueError –

  If shrink_factors and smoothing_sigmas have different lengths.

• ValueError –

  If initial_transform is provided and its shape does not match the image dimensionality.

Register all volumes in a fUSI recording to a reference volume.

Parameters:

• data ¶

  (DataArray) –

  Input data to register.

• reference_time ¶

  (int, default: 0 ) –

  Index of the time point to use as registration target.

• n_jobs ¶

  (int, default: -1 ) –

  Number of parallel jobs. Negative values resolve to max(1, os.cpu_count() + 1 + n_jobs), so -1 means all CPUs, -2 means all minus one, and so on. Use 1 for serial processing.

• transform ¶

  ((translation, rigid, affine), default: "translation" ) –

  Transform model to use during registration. "translation" allows only shifts. "rigid" adds rotation. "affine" adds scaling and shearing. B-spline is not available for motion correction.

• metric ¶

  ((correlation, mattes_mi), default: "correlation" ) –

  Similarity metric. "correlation" (normalized cross-correlation) is appropriate for same-modality registration. "mattes_mi" (Mattes mutual information) is better suited for multi-modal registration or when the intensity relationship between images is non-linear.

• number_of_histogram_bins ¶

  (int, default: 50 ) –

  Number of histogram bins used by Mattes mutual information. Only relevant when metric="mattes_mi".

• learning_rate ¶

  (float or auto, default: "auto" ) –

  Optimizer step size in normalised units (after SetOptimizerScalesFromPhysicalShift). "auto" re-estimates the rate at every iteration. A float uses that value directly; if registration diverges or fails to converge, reduce it.

• number_of_iterations ¶

  (int, default: 100 ) –

  Maximum number of optimizer iterations.

• convergence_minimum_value ¶

  (float, default: 1e-6 ) –

  Convergence threshold. Optimization stops early when the estimated energy profile falls below this value.

• convergence_window_size ¶

  (int, default: 10 ) –

  Number of recent metric values used to estimate the energy profile for convergence checking.

• initialization ¶

  ((geometry, moments, none), default: "geometry" ) –

  Transform initializer applied before optimization. "geometry" aligns the image centers (safe default, no assumptions about content). "moments" aligns centers of mass (better when images are offset but share the same content). "none" uses the identity transform.

• optimizer_weights ¶

  (list of float or None, default: None ) –

  Per-parameter weights applied on top of the auto-estimated physical shift scales. None uses identity weights (all ones). A list is passed directly to SimpleITK's SetOptimizerWeights; its length must match the number of transform parameters (3 for 2D rigid, 6 for 3D rigid, 6 for 2D affine, 12 for 3D affine). The weight for each parameter is multiplied into the effective step size: 0 freezes a parameter entirely, values in (0, 1) slow it down, and 1 leaves it unchanged. For the 3D Euler transform the parameter order is [angleX, angleY, angleZ, tx, ty, tz]; to disable rotations around x and y set weights to [0, 0, 1, 1, 1, 1].

• use_multi_resolution ¶

  (bool, default: False ) –

  Whether to use a multi-resolution pyramid during registration. When True, registration proceeds from a coarse downsampled version of the images to the full resolution, which improves convergence for large displacements and reduces the risk of local minima.

• shrink_factors ¶

  (sequence of int, default: (6, 2, 1) ) –

  Downsampling factor at each pyramid level, from coarsest to finest. Must have the same length as smoothing_sigmas. Only used when use_multi_resolution=True.

• smoothing_sigmas ¶

  (sequence of int, default: (6, 2, 1) ) –

  Gaussian smoothing sigma (in voxels) applied at each pyramid level, from coarsest to finest. Must have the same length as shrink_factors. Only used when use_multi_resolution=True.

• resample_interpolation ¶

  ((linear, bspline), default: "linear" ) –

  Interpolator used when resampling each volume onto the reference grid. "linear" is fast and appropriate for motion correction. "bspline" (3rd-order B-spline) produces smoother results at the cost of speed.

Returns:

• DataArray –

  Registered data with same coordinates and attributes as input.

Resample a volume onto the grid of a reference DataArray.

Convenience wrapper around resample_volume that extracts the output grid (shape, spacing, origin) from reference's coordinates.

Parameters:

• moving ¶

  (DataArray) –

  2D or 3D spatial DataArray to resample, or 3D+t DataArray with a time dimension. If a time dimension is present, the same transform is applied to all time points.

• reference ¶

  (DataArray) –

  DataArray defining the output grid. Must be 2D or 3D spatial (no time dimension).

• transform ¶

  ((N+1, N+1) numpy.ndarray or xarray.DataArray) –

  Registration transform, as returned by register_volume. Maps points from the reference physical space to moving physical space (pull/inverse convention).

  • Affine (numpy.ndarray): homogeneous matrix.
  • B-spline (xarray.DataArray): control-point DataArray.

• interpolation ¶

  ((linear, bspline), default: "linear" ) –

  Interpolation method used during resampling.

• default_value ¶

  (float, default: 0.0 ) –

  Value assigned to voxels that fall outside the moving image's field of view after resampling.

• sitk_threads ¶

  (int, default: os.cpu_count() or 1 ) –

  Number of threads SimpleITK may use for the Resample call. Defaults to all available CPUs.

Returns:

• DataArray –

  Resampled volume on the grid of reference, with reference's coordinates and dimensions and moving's attributes. If moving had a time dimension, the output will also have a time dimension.

Raises:

• ValueError –

  If reference contains a time dimension or is not 2D or 3D.

Resample a volume onto an explicit output grid using a pre-computed transform.

Low-level resampling primitive. For the common case of resampling onto the grid of another DataArray, use resample_like instead.

Parameters:

• moving ¶

  (DataArray) –

  2D or 3D spatial DataArray to resample, or 3D+t or 2D+t DataArray with a time dimension. If a time dimension is present, the same transform is applied to all time points.

• transform ¶

  ((N+1, N+1) numpy.ndarray or xarray.DataArray) –

  Registration transform, as returned by register_volume.

  • Affine (numpy.ndarray): homogeneous matrix of shape (N+1, N+1) mapping output (fixed) physical coordinates to moving physical coordinates (pull/inverse convention).
  • B-spline (xarray.DataArray): control-point DataArray as returned by register_volume(transform="bspline").

• shape ¶

  (sequence of int) –

  Number of voxels along each output axis, in DataArray dimension order.

• spacing ¶

  (sequence of float) –

  Voxel spacing along each output axis, in DataArray dimension order.

• origin ¶

  (sequence of float) –

  Physical origin (first voxel centre) along each output axis, in DataArray dimension order.

• dims ¶

  (sequence of str) –

  Dimension names of the output DataArray.

• interpolation ¶

  ((linear, bspline), default: "linear" ) –

  Interpolation method used during resampling.

• default_value ¶

  (float, default: 0.0 ) –

  Value assigned to voxels that fall outside the moving image's field of view after resampling.

• sitk_threads ¶

  (int, default: -1 ) –

  Number of threads SimpleITK may use internally. Negative values resolve to max(1, os.cpu_count() + 1 + sitk_threads), so -1 means all CPUs, -2 means all minus one, and so on. You may want to set this to a lower value or 1 when running multiple registrations in parallel (e.g. with joblib) to avoid over-subscribing the CPU.

Returns:

• DataArray –

  Resampled volume on the specified grid with moving's attributes. If the input had a time dimension, the output will also have a time dimension.

Raises:

• ValueError –

  If moving is not 2D, 3D+t, 3D, or 3D+t.

• ValueError –

  If transform is a numpy array whose shape does not match the spatial image dimensionality.