utils - josalggui/MaRGE GitHub Wiki

utils.py — Utility Functions for MRI Reconstruction and Processing

This module contains a collection of utility functions used throughout the MRI acquisition and reconstruction pipeline.
It includes tools for image orientation, decimation, k-space processing, reconstruction, denoising, SNR estimation, and file export (DICOM / NIfTI).

Contents

  • Image orientation and visualization helpers
  • DICOM and NIfTI export utilities
  • k-space filtering and reconstruction
  • Oversampled data decimation
  • Echo alignment utilities
  • Image denoising (BM4D)
  • SNR estimation utilities

Image Orientation & Visualization

fix_image_orientation

Adjusts the orientation of a 3D image array to match standard anatomical planes.

Description

  • Reorders and flips image axes based on acquisition geometry.
  • Generates metadata for visualization and DICOM export.

Parameters

  • image (np.ndarray): 3D image data.
  • axes (list[int]): Current axis order.
  • orientation (str, optional): Patient orientation (default 'FFS').
  • rd_direction (int, optional): Readout direction sign.

Returns

  • output (dict): Visualization metadata (widget, data, labels, title).
  • image (np.ndarray): Reoriented image.
  • dicom_orientation (list): DICOM ImageOrientationPatient tag.

File Export

save_dicom

Save a 2D or 3D image as a DICOM file with appropriate metadata.

Features

  • Handles orientation, resolution, pixel spacing, and slice thickness.
  • Supports session-based metadata (scanner, subject, study).

Parameters

  • axes_orientation, n_points, fov, image
  • file_path (str)
  • meta_data (dict, optional)
  • session (dict, optional)

save_nifti

Save a reconstructed volume as a NIfTI file.

Parameters

  • axes_orientation, n_points, fov, dfov
  • image (np.ndarray)
  • file_path (str)

k-Space Filtering & Reconstruction

run_cosbell_filter

Apply a Cosbell filter in k-space along readout, phase, and slice directions.

Parameters

  • sampled (ndarray): k-space coordinates.
  • data (ndarray): k-space data (sl, ph, rd).
  • cosbell_order (list[int]): Filter order per direction.

Returns

  • Filtered k-space data.

run_dfft

Direct FFT from image space to k-space.

run_ifft

Inverse FFT from k-space to image space.

run_zero_padding

Zero-pad (or crop) k-space to a desired matrix size while preserving centering.

Parameters

  • k_space (np.ndarray)
  • new_size (list[int]): (rd, ph, sl)

hanning_filter

Apply a Hanning window near the edges of k-space to reduce ringing.

run_pocs_reconstruction

Perform POCS (Projection Onto Convex Sets) reconstruction for partial k-space data.

Features

  • Iterative phase-constrained reconstruction
  • Correlation-based convergence stopping

run_zero_padding_reconstruction

Simple partial Fourier reconstruction using zero-padding.

Echo & Readout Utilities

fix_echo_position

Align the echo center (k=0) within oversampled readout windows.

Description

  • Uses dummy pulses to estimate true echo position.
  • Shifts signal to center k-space before decimation.

Returns

  • Decimated, echo-aligned data.

Decimation

decimate

Convert oversampled ADC data to target bandwidth using a two-stage decimation approach.

Description

  1. FIR decimation with anti-aliasing
  2. Optional averaging-based decimation to complete oversampling reduction

Parameters

  • data_over (np.ndarray): Oversampled data
  • n_adc (int): Number of ADC windows
  • option ('PETRA' | 'Normal')
  • remove (bool)
  • add_rd_points (int)
  • oversampling_factor (int)
  • decimation_factor (int)

Returns

  • Decimated data array

Notes

  • Total effective decimation = oversampling_factor
  • PETRA mode reduces FIR ringing at readout start

Denoising

run_bm4d_filter

Apply BM4D denoising to a 3D image.

Features

  • Automatic noise estimation (if std=0)
  • Preserves structural details

Parameters

  • image_data (np.ndarray)
  • std (float, optional)

Returns

  • Denoised image

SNR Estimation

get_snr_histogram

Estimate SNR using histogram-based noise estimation.

get_snr_3d

Voxel-wise SNR using local mean / local standard deviation.

get_snr_2d

Slice-wise SNR estimation for 3D volumes.

get_snr_from_individual_acquisitions

Compute SNR from repeated acquisitions (4D data).

Description

  • Signal: mean magnitude across acquisitions
  • Noise: standard deviation across acquisitions

Notes

  • All functions assume NumPy array conventions (sl, ph, rd) unless stated otherwise.
  • Many utilities are designed to work seamlessly with runBatches.
  • DICOM export follows DICOM 3.0 conventions.
  • This module is intended to grow with additional filters and reconstruction methods.

TODO

  • Integrate additional filters and reconstruction utilities.
  • Extend multi-channel (MIMO) support.
⚠️ **GitHub.com Fallback** ⚠️