A simple, laplacian-based unwrapping pipeline for MRI phase images in Python.
Project description
MRI Phase Unwrapping
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
wasRAI
. 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.
- 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
Release history Release notifications | RSS feed
Download files
Download the file for your platform. If you're not sure which to choose, learn more about installing packages.
Source Distribution
Built Distribution
Hashes for phase_unwrap-2.0.0-py3-none-any.whl
Algorithm | Hash digest | |
---|---|---|
SHA256 | 763499392d4ee71d57fadb59502e00e8b3b9494a9e54a8c39ba43331dc4ab716 |
|
MD5 | 2805e7ddd9ece07d6f533721ba5b6674 |
|
BLAKE2b-256 | bbb64b76586a8e4eab80a037acc4c13aab2d61fcbe05aa8e34222e791d5cde4a |