pl-images-register
is a ChRIS
ds plugin which takes in ... as input files and
creates ... as output files.
This plugin registers one or more images from its input directory to a single reference or fixed image.
pl-images-register
is a ChRIS plugin, meaning it can
run from either within ChRIS or the command-line.
To get started with local command-line usage, use Apptainer
(a.k.a. Singularity) to run pl-images-register
as a container:
apptainer exec docker://fnndsc/pl-images-register images_register [--args values...] input/ output/
To print its available options, run:
apptainer exec docker://fnndsc/pl-images-register images_register --help
images_register
requires two positional arguments: a directory containing input images, i.e.
a fixed_image and a moving_image, and a directory where to create output data, i.e. registered_image and
transform_matrix. First, create the input directory and move input data into it.
mkdir incoming outgoing
mv fixed_image.nii.gz moving_image.nii.gz incoming
apptainer exec docker://fnndsc/pl-images-register:latest images_register [--args] incoming outgoing
If there is only one moving image, it will be registered onto the fixed image.
All images (fixed, moving, and registered images) should be in .nii.gz
format.
The registered image and the transform matrix will be saved with these names:
moving_image.nii.gz
--> moving_image_registered.nii.gz
and moving_image_transform.mat
.
Example 1:
Inputs:
input_dir/fixed_image.nii.gz
input_dir/moving_image.nii.gz
Outputs:
output_dir/moving_image_registered.nii.gz
output_dir/moving_image_transform.mat
If there are multiple moving images, each one will be registered to the fixed image separately.
For multiple moving images, all of them should be placed in a folder, and the folder should be passed to the
parser under moving_images_folder
.
Example 2:
Inputs:
input_dir/fixed_image.nii.gz
input_dir/moving_images_folder/moving_image1.nii.gz, moving_image2.nii.gz, moving_image3.nii.gz, etc.
Outputs:
output_dir/moving_images_folder/moving_image1_registered.nii.gz, moving_image2_registered.nii.gz,
moving_image3.nii.gz, etc.
output_dir/moving_images_folder/moving_image1_transform.mat, moving_image2_transform.mat,
moving_image3_transform.mat, etc.
The registration algorithms are found in images_register.py module.
Build a local container image:
docker build -t localhost/fnndsc/pl-images-register .
Mount the source code images_register.py
into a container to try out changes without rebuild.
docker run --rm -it --userns=host -u $(id -u):$(id -g) \
-v $PWD/images_register.py:/usr/local/lib/python3.12/site-packages/images_register.py:ro \
-v $PWD/in:/incoming:ro -v $PWD/out:/outgoing:rw -w /outgoing \
localhost/fnndsc/pl-images-register images_register /incoming /outgoing
Run unit tests using pytest
.
It's recommended to rebuild the image to ensure that sources are up-to-date.
Use the option --build-arg extras_require=dev
to install extra dependencies for testing.
docker build -t localhost/fnndsc/pl-images-register:dev --build-arg extras_require=dev .
docker run --rm -it localhost/fnndsc/pl-images-register:dev pytest
Steps for release can be automated by Github Actions. This section is about how to do those steps manually.
Increase the version number in setup.py
and commit this file.
Build and push an image tagged by the version. For example, for version 1.2.3
:
docker build -t docker.io/fnndsc/pl-images-register:1.2.3 .
docker push docker.io/fnndsc/pl-images-register:1.2.3
Run chris_plugin_info
to produce a JSON description of this plugin, which can be uploaded to ChRIS.
docker run --rm docker.io/fnndsc/pl-images-register:1.2.3 chris_plugin_info -d docker.io/fnndsc/pl-images-register:1.2.3 > chris_plugin_info.json
Intructions on how to upload the plugin to ChRIS can be found here: https://chrisproject.org/docs/tutorials/upload_plugin