Visualisation tool¶
DeepReg provides a visuaisation tool which allows the user to generate various visualisations from nifti images. The tool is compatible with outputs from deepreg_predict as well as with other nifti images.
The visualisation tool currently offers four functionalities using the command
deepreg_vis
, with their Python functions explained in the final section of this
document. Run the examples below after changing directory to the root folder DeepReg
.
The creation of .gif
files requires a movie writer that is compatible with
matplotlib
like ffmpeg
in order to be able to write .gif
files. Please refer to
the matplotlib documentation for
more details about writers. The ffmpeg
writer was used to test functionality of this
visualisation tool, however, other writers can also be installed and used.
General arguments for deepreg_vis
¶
-m
or--mode
: This specifies which mode to use to generate the visualisation. See below for available modes.-i
or--image-paths
: This is the path of the image or images that need to be used to generate the visualisation. Multiple paths can be passed using a comma separated string.-s
or--save-path
: This is the path to the directory where the visualisation will be saved. The name of the visualisation is auto generated, however, if--fname
argument is available for a specific mode, then a custom filename can be specified. (default results in saving to current directory)
GIF over image slices¶
This creates an animation which is an iteration through the image slices of a 3D image,
can be accessed by passing --mode 0
or -m 0
.
In addition to the general arguments, the additional arguments applicable to this mode are:
--interval
: This argument is optional and can be used to specify the time, in milliseconds, between successive frames of an animation. (default=50)
The output will be a file with the same name as the original with a .gif
extension. If
multiple image paths are passed in the -i
or --image-paths
argument then multiple
.gif
files will be generated, one for each unique image path passed.
A simple example, which takes an image path and saves a .gif
animation, is shown
below:
deepreg_vis -m 0 -i ./data/test/nifti/unit_test/moving_image.nii.gz -s logs
GIF that shows warping¶
This functionality produces an animation showing warping for a single image slice using
a ddf, can be accessed by passing --mode 1
or -m 1
.
In addition to the general arguments, the additional arguments applicable to this mode are:
--ddf-path
: This argument is required for this mode and specifies the path of the ddf to use for warping the image.--slice-inds
: This argument is optional and can be used to specify the indexes to be used to generate the visualisation. Multiple indexes can be passed by using a comma separated string. (default results in a random slice being used)--interval
: This argument is optional and can be used to specify the time, in milliseconds, between successive frames of an animation. (default=50)--num-interval
: The number of intervals to use for warping. (default=100)
The output will be a file with the slice number appended to the original file name, with
a .gif
extension. For example if a file is named moving_image.nii.gz
and slice
number 2 and 3 three are chosen, the files produced will be moving_image_slice_2.gif
and moving_image_slice_3.gif
.If multiple image paths are passed in the -i
or
--image-paths
argument then multiple .gif
files will be generated, if multiple slice
indexes are specified then multiple .gif
files are generated for each unique image
path passed.
A simple example, which takes an image, slice indexes and a ddf path and saves a .gif
animation for each slice, is shown below:
deepreg_vis -m 1 -i ./data/test/nifti/unit_test/moving_image.nii.gz --ddf-path "./data/test/nifti/unit_test/ddf.nii.gz" --slice-inds '2,3' -s logs
Plot of image slices¶
This functionality produces a plot of image slices from a single or multiple images.
Each column is a different image and each row is a different slice, can be accessed by
passing --mode 2
or -m 2
.
In addition to the general arguments, the additional arguments applicable to this mode are:
--slice-inds
: This argument is optional and can be used to specify the indexes to be used to generate the visualisation. Multiple can be passed by using a comma separated string. (default results in a random slice being used)--col-titles
: This is optional. The title of the column to be used in order from left to right column. (default results in using file name specified in image path as column name)--fname
: Optional argument of file name to save visualisation to; should end with an appropriate file extension like.png
or.jpeg
. (default=’visualisation.png’)
The output is a single file which contains a static visualisation. The visualisation is different images in the columns and different slices in the rows.
A simple example, which takes three images and three slice indexes and saves a .png
file, is shown below (this will create a plot with 3 columns and 3 rows):
deepreg_vis -m 2 -i './data/test/nifti/unit_test/moving_image.nii.gz, ./data/test/nifti/unit_test/moving_image.nii.gz, ./data/test/nifti/unit_test/moving_image.nii.gz' --slice-inds '2,3,4' -s logs
Tiled GIF over image slices¶
This functionality produces an animation with multiple animated images that are tiled
together, can be accessed by passing --mode 3
or -m 3
. The images used as input must
all be of the same size.
--interval
: This argument is optional and can be used to specify the time, in milliseconds, between successive frames of an animation. (default=50)--size
: This is an optional argument and can be used to specify the number of rows and columns for the final tiled animation. For example'2, 3'
means 2 rows and 3 columns, in this case 6 images must be passed for the visualisation. (default=’2,2’)--fname
: Optional argument of file name to save visualisation to; should end with.gif
. (default=’visualisation.gif’)
The output is a single file which contains the tiled animation. The image paths must be passed in the order in which they are to be tiled (order is from left to right and then next row).
A simple example, which takes four images and creates an animation over the slices of the four images in a tiled manner, is shown below:
deepreg_vis -m 3 -i './data/test/nifti/unit_test/moving_image.nii.gz, ./data/test/nifti/unit_test/moving_image.nii.gz, ./data/test/nifti/unit_test/moving_image.nii.gz, ./data/test/nifti/unit_test/moving_image.nii.gz' --size '2,2' -s logs
Using the same functionality by importing python functions¶
The same functionality can be accessed via python functions.
The names of the functions are:
gif_slices
: equivalent to--mode 0
or-m 0
gif_warp
: equivalent to--mode 1
or-m 1
tile_slices
: equivalent to--mode 2
or-m 2
gif_tile_slices
: equivalent to--mode 3
or-m 3
The functions can be imported in a python script as follows:
from deepreg.vis import function_name
For usage details please see the function docstrings. Function docstrings can be accessed in a python prompt by:
help(func_name)