Skip to content

Latest commit

 

History

History
47 lines (41 loc) · 3.87 KB

README.md

File metadata and controls

47 lines (41 loc) · 3.87 KB
Raw

hdi-reg

High-dimensional image registration workflow as part of the MIAAIM framework. Hdi-reg is written in Python, and utilizes the Elastix library for computations.

Implementation Details

All steps can be run from the command line using command_elastix.py or command_transformix.py. Transformix is reserved for applying existing transformation parameters to images after running Elastix.

Command Line Usage with Docker (recommended):

All image registration can be run with dependecies installed via Docker as follows:

  1. Install Docker on your machine.
  2. Check that Docker is installed with docker images
  3. Pull the hdi-reg docker container docker pull joshuahess/hdi-reg:latest where latest is the version number.
  4. Mount your data in the Docker container and enter shell with docker run -it -v /path/to/data:/data joshuahess/hdi-reg:latest bash
  5. Run the registration with your new data using the following command:
python app/command_elastix.py --f /data/fixedImage.nii --m /data/movingImage.nii -p /data/registrationPars.txt --out_dir /data
  1. Tranforming images, such as multichannel images, with transformix on new data can be run as follows:
python app/command_transformix.py --in_im /data/newIm.nii  --tp /data/registrationPars.txt --out_dir /data

Usage without Docker:

If you are unable to use Docker on your machine, then you can still use hdi-reg:

  1. download the latest version of Elastix.
  2. Make Elastix accessible to your $PATH environment (Ex. on a Mac, access your .bash_profile and add export PATH=~/elastix-latest/bin:$PATH and export DYLD_LIBRARY_PATH=~/elastix-latest/lib:$DYLD_LIBRARY_PATH)
  3. Run registration and transformix as above in step 5.

Input Parameters:

Options for importing data and processing are listed below. Detailed descriptions of each function can be found within source code.

hdi-reg Step Options
1. command_elastix.py image registration between fixed image and moving image
--fixed path to fixed image (Ex. --fixed ./fixedImage.nii)
--moving path to moving image (Ex. --moving ./movingImage.nii)
--out_dir path to output directory (Ex. --out_dir ./outdirectory)
--p path(s) to parameter files for elastix registration (see examples here) (Ex. --p ./affineParameters.txt --p ./nonlinearParameters.txt)
--mp path to manual landmark points (Ex. --mp ./movingPoints.txt)
--fp path to manual landmark points (Ex. --fp ./fixedPoints.txt)
--fMask fixed image mask to draw samples from during optimization (Ex. --fMask ./fixedMask.nii)
2. command_transformix.py transform images using saved transformation from elastix
--in_im path to image to transform (can be multichannel) (Ex. --in_im ./movingMultichannel.nii)
--out_dir path to output directory (Ex. --out_dir ./outdirectory)
--tps path(s) to parameter files exported from elastix (Ex. --tps ./affineTransformParameters.txt --tps ./nonlinearTransformParameters.txt)
--in_target_size tuple indicating target size to rescale image to prior to tranformix (Ex. --in_target_size (1000,1000)
--crops nested dictionary coordinates to crop ROIs from in full image for further refinement

Options:
coords_csv path to csv file indicating coordinates of full image to crop
target_size rescaled size of ROI to produce prior to transforming
correction padding to add to edges of crop to account for misalignment on full tissue
tps transform parameters (as above) focused on ROIs
fixed_pad padding to remove from the resulting image after transforming (if this matches padding added to fixed image, then result will be fully aligned)