Skip to main content

A simple, laplacian-based unwrapping pipeline for MRI phase images in Python.

Project description

MRI Phase Unwrapping

DOI

A simple, laplacian-based unwrapping pipeline for MRI phase images.

If you use this code in your work, please cite:

Blake E. Dewey. (2022). Laplacian-based Phase Unwrapping in Python. Zenodo. [https://doi.org/10.5281/zenodo.7198990](https://doi.org/10.5281/zenodo.7198991)

Install with pip

pip install phase_unwrap

Basic Usage

unwrap-phase /path/to/phase_image.nii.gz

This will produce an unwrapped phase image in the same directory as the input image with _unwrapped appended to the filename.

NOTE: Some have reported the best results when the phase image is reoriented to the axial plane before unwrapping. This can be done with the --orientation option:

unwrap-phase /path/to/phase_image.nii.gz --orientation RAI

If you would like the unwrapped image returned in the original orientation, use the --undo-reorient option.

CLI Options

Option Description Default
Path to phase image Required
-o/--output Output path Optional
--orientation Reorient to this before unwrapping (RAI, RSA, or ASR) Optional
--undo-reorient Return image to orientation after unwrapping False

Using the --output option will save the unwrapped image to that path. If not provided, the unwrapped image will be saved to the same directory as the input image with _unwrapped appended to the filename (before the .nii.gz).

--orientation can be used to reorient the image before unwrapping. This script uses 2D functions for unwrapping and will slice the data according to the slice direction of the volume (last dimension). If the slice direction is not the desired orientation, use this option to reorient the image before unwrapping. RAI will give you an axial image. RSA will give you a coronal image. ASR will give you a sagittal image. If you would like the unwrapped image returned in the original orientation, use the --undo-reorient option.

Docker Usage

The docker file in this package is used to build a container with the necessary dependencies to run the unwrapping script. You can pull it directly from Docker Hub with:

docker pull blakedewey/phase_unwrap:v2.0.0

After pulling the image, you can run the unwrapping script with:

docker run -it --rm -v /path/to/data:/data blakedewey/phase_unwrap:v2.0.0 /data/phase_image.nii.gz

All of the same CLI options will work with the Docker container as well. Remember to mount the directory containing the data to a place in the container (/data in the example). You will also have to specify the path to the image relative to the mounted directory.

Upgrading from v1.0.0

The CLI options have changed slightly from v1.0.0 to v2.0.0:

  • The -p/--phase-image option has been replaced with a positional argument for the path to the phase image.
  • In v1.0.0, image paths were assumed to be in /data for use in Docker. This is no longer the case. You must specify the full path to the image or output, even in the Docker container.
  • In v1.0.0, the default for --orientation was RAI. This has been removed. If you want to reorient the image, you must specify the orientation. Use --orientation RAI to get the same behavior as v1.0.0.
  • The --undo-reorient option has been added to return the image to the original orientation after unwrapping.

Works Using This Code

This processing has been used in a number of published manuscripts detailing phase-rim lesions in multiple sclerosis.

  1. Absinta et al. "Persistent 7-tesla phase rim predicts poor outcome in new multiple sclerosis patient lesions" Journal of Clinical Investigation (doi: 10.1172/JCI86198)

Project details


Download files

Download the file for your platform. If you're not sure which to choose, learn more about installing packages.

Source Distribution

phase_unwrap-2.0.0.tar.gz (20.0 kB view details)

Uploaded Source

Built Distribution

phase_unwrap-2.0.0-py3-none-any.whl (20.4 kB view details)

Uploaded Python 3

File details

Details for the file phase_unwrap-2.0.0.tar.gz.

File metadata

  • Download URL: phase_unwrap-2.0.0.tar.gz
  • Upload date:
  • Size: 20.0 kB
  • Tags: Source
  • Uploaded using Trusted Publishing? Yes
  • Uploaded via: twine/5.1.0 CPython/3.12.4

File hashes

Hashes for phase_unwrap-2.0.0.tar.gz
Algorithm Hash digest
SHA256 d92f922c6e6056ccb1f5daf384d29ae9dacde45c310ef8ee41a34a7f9b056c5a
MD5 8fedd8c2f3b911a2799bdb54e1b6d2fa
BLAKE2b-256 c8e69c508075fbe2af5ea066bdbe503b6fa8b7b7157487335bc98e70a1d776c9

See more details on using hashes here.

File details

Details for the file phase_unwrap-2.0.0-py3-none-any.whl.

File metadata

  • Download URL: phase_unwrap-2.0.0-py3-none-any.whl
  • Upload date:
  • Size: 20.4 kB
  • Tags: Python 3
  • Uploaded using Trusted Publishing? Yes
  • Uploaded via: twine/5.1.0 CPython/3.12.4

File hashes

Hashes for phase_unwrap-2.0.0-py3-none-any.whl
Algorithm Hash digest
SHA256 763499392d4ee71d57fadb59502e00e8b3b9494a9e54a8c39ba43331dc4ab716
MD5 2805e7ddd9ece07d6f533721ba5b6674
BLAKE2b-256 bbb64b76586a8e4eab80a037acc4c13aab2d61fcbe05aa8e34222e791d5cde4a

See more details on using hashes here.

Supported by

AWS AWS Cloud computing and Security Sponsor Datadog Datadog Monitoring Fastly Fastly CDN Google Google Download Analytics Microsoft Microsoft PSF Sponsor Pingdom Pingdom Monitoring Sentry Sentry Error logging StatusPage StatusPage Status page