Unwarp (automatic)

Apply slice-by-slice (2D) B-spline unwarping-based image registration to a multi-dimensional stack.

Description

Apply slice-by-slice (2D) B-spline unwarping-based image registration to a multi-dimensional stack. Images can be aligned relative to the first frame in the stack, the previous frame or a separate image in the workspace. The registration transform can also be calculated from a separate stack to the one that it will be applied to. Registration can be performed along either the time or Z axes. The non-registered axis (e.g. time axis when registering in Z) can be "linked" (all frames given the same registration) or "independent" (each stack registered separately).

This module uses the BUnwarpJ plugin to calculate and apply the necessary 2D transforms. Detailed information about how the BUnwarpJ process works can be found at https://imagej.net/BUnwarpJ.

Parameters

ParameterDescription
Input imageImage from workspace to apply registration to.
Apply to input imageWhen selected, the post-operation image will overwrite the input image in the workspace. Otherwise, the image will be saved to the workspace with the name specified by the "Output image" parameter.
Output imageIf "Apply to input image" is not selected, the post-operation image will be saved to the workspace with this name.
Registration axisControls which stack axis the registration will be applied in. For example, when "Time" is selected, all images along the time axis will be aligned. Choices are: Time, Z.
Other axis modeFor stacks with non-registration axis lengths longer than 1 (e.g. the "Z" axis when registering in time) the behaviour of this other axis is controlled by this parameter:
  • "Independent" Each non-registration axis is registered independently. For example, applying separate Z-registrations for each timepoint of a 4D stack.
  • "Linked" All elements of the non-registration axis are registered with a single transform. For example, applying the same registration at a timepoint to all slices of a 4D stack.
Fill modeControls what intensity any border pixels will have. "Borders" in this case correspond to strips/wedges at the image edge corresponding to regions outside the initial image (e.g. the right-side of an output image when the input was translated to the left). Choices are: Black, White.
Show detected pointsWhen enabled, the points used for calculation of the registration will be added as an overlay to the input image and displayed.
Enable multithreadingWhen selected, certain parts of the registration process will be run on multiple threads of the CPU. This can provide a speed improvement when working on a computer with a multi-core CPU.
Reference modeControls what reference image each image will be compared to:
  • "First frame" All images will be compared to the first frame (or slice when in Z-axis mode). For image sequences which continuously evolve over time (e.g. cells dividing) this can lead to reduced likelihood of successfully calculating the transform over time.
  • "Previous N frames" Each image will be compared to the N frames (or slice when in Z-axis mode) immediately before it (number of frames specified by "Number of previous frames"). These reference frames are consolidated into a single reference image using a projection based on the statistic specified by "Previous frames statistic". This mode copes better with image sequences which continuously evolve over time, but can also lead to compounding errors over time (errors in registration get propagated to all remaining slices).
  • "Specific image" All images will be compared to a separate 2D image from the workspace. The image to compare to is selected using the "Reference image" parameter.
Number of previous framesNumber of previous frames (or slices) to use as reference image when "Reference mode" is set to "Previous N frames". If there are insufficient previous frames (e.g. towards the beginning of the stack) the maximum available frames will be used. Irrespective of the number of frames used, the images will be projected into a single reference image using the statistic specified by "Previous frames statistic".
Previous frames statisticStatistic to use when combining multiple previous frames as a reference ("Reference mode" set to "Previous N frames").
Reference imageIf "Reference mode" is set to "Specific image" mode, all input images will be registered relative to this image. This image must only have a single channel, slice and timepoint.
Calculation sourceControls whether the input image will be used to calculate the registration transform or whether it will be determined from a separate image:
  • "External" The transform is calculated from a separate image from the workspace (specified using "External source"). This could be an image with enhanced contrast (to enable better feature extraction), but where the enhancements are not desired in the output registered image. When "Other axis mode" is set to "Linked", the external image must be the same length along the registration axis and have single-valued length along the non-registration axis. However, when set to "Independent", the external image must have the same axis lengths for both the registration and non-registration axes.
  • "Internal" The transform is calculated from the input image.
External sourceIf "Calculation source" is set to "External", registration transforms will be calculated using this image from the workspace. This image will be unaffected by the process.
Calculation channelIf calculating the registration transform from a multi-channel image stack, the transform will be determined from this channel only. Irrespectively, for multi-channel image stacks, the calculated transform will be applied equally to all channels.
Registration mode"The registration mode can be "Accurate", "Fast" and "Mono". The registration mode "Mono" makes the program to perform only unidirectional registration, i.e. from source to target. The two registration modes "Accurate" and "Fast" involve performing bidirectional registration and affect the stopping criteria internally used by the program." Description taken from https://imagej.net/BUnwarpJ
Subsample factor"The registration will be calculated using subsampled versions of the images but the results will be applied to the original ones. The image subsampling parameter can be chosen between 0 and 7, i.e. the image dimensions can be reduced by a factor of 2^0 = 1 to 2^7 = 128. This is very useful when registering large images." Description taken from https://imagej.net/BUnwarpJ
Initial deformation mode"Determines the level of detail of the initial deformation. In bUnwarpJ this is defined by the number of B-splines used to represent the deformations:

DeformationNum. intervals in grid
Very coarse1x1
Coarse2x2
Fine3x3
Very fine8x8
Super fine16x16

If images start very far away from the right alignment, it is usually a good idea to go from "Very Coarse" to "Very Fine". If they start close to the right alignment, using a very coarse initial deformation could cause the algorithm to fail. So, in that case, it would be enough to set initial deformation to "Fine" and final deformation to "Very Fine". Use "Super Fine" only when you need a very high level of accuracy, because it makes the algorithm quite slower depending on the image sizes. Description taken from https://imagej.net/BUnwarpJ
Final deformation modeSee description for "Initial deformation mode"
Divergence weightRegularizes the deformation by penalizing the divergence of the deformation vector field. If you see that your transformations get too rough, it is a good idea to use this parameter. A value of 0.1 is usually good if there's no prior knowledge about the deformation shape. Description taken from https://imagej.net/BUnwarpJ
Curl weightRegularizes the deformation by penalizing the curl of the deformation vector field. If you see that your transformations get too rough, it is a good idea to use this parameter. A value of 0.1 is usually good if there's no prior knowledge about the deformation shape. Description taken from https://imagej.net/BUnwarpJ
Landmark weightForces the deformations to fit the landmark points. Set it to 1.0 unless you're not using landmarks. Description taken from https://imagej.net/BUnwarpJ
Image weightThe weight to control the pixel values difference. Leave it at 1.0 unless you want to do, for instance, landmark-only registration. Description taken from https://imagej.net/BUnwarpJ
Consistency weightForces the resulting deformations to be one (source to target) as close as possible to the inverse of the other one (target to source). Values between 10.0 and 30.0 usually work fine. It is only taken into account for registration modes "Fast" or "Accurate". Description taken from https://imagej.net/BUnwarpJ
Stop thresholdStops the optimization process at each multiresolution level when the error relative change is not larger than this threshold. Description taken from https://imagej.net/BUnwarpJ