iss_preprocess.reg package¶

Submodules¶

iss_preprocess.reg.rounds_and_channels module¶

iss_preprocess.reg.rounds_and_channels.align_channels_and_rounds(stack, tforms)¶

Apply the provided transformations to align images across channels and rounds.

Parameters:

stack (np.array) – X x Y x Nchannels x Nrounds images stack
tforms (np.array) – Nch x Nrounds array of transformation matrices (each 3x3)

Returns:

Aligned stack with NaN for missing pixels. Same shape as input stack

Return type:

np.array

iss_preprocess.reg.rounds_and_channels.align_within_channels(stack, ref_round=0, angle_range=1.0, niter=3, nangles=15, upsample=False, median_filter_size=None, min_shift=None, max_shift=None, use_masked_correlation=False, debug=False, multiprocess=True)¶

Align images within each channel.

Parameters:

stack (np.array) – X x Y x Nchannels x Nrounds images stack
upsample (bool, or int) – whether to use subpixel registration, and if so, how much to upsample
ref_round (int) – round to align to
angle_range (float) – range of angles to search for each round
niter (int) – number of iterations to run
nangles (int) – number of angles to search for each iteration
upsample – whether to upsample the image, and if so by what factor
median_filter_size (int) – size of median filter to apply to the stack.
min_shift (int) – minimum shift. Necessary to avoid spurious cross-correlations for images acquired from the same camera
max_shift (int) – maximum shift. Necessary to avoid spurious cross-correlations
use_masked_correlation (bool) – whether to use masked phase correlation
debug (bool) – whether to return debug info, default: False
multiprocess (bool) – whether to use multiprocessing, default: True

Returns:

Nchannels x Nrounds array of angles shifts (np.array): Nchannels x Nrounds x 2 array of shifts debug_info (dict): dictionary with debug info, only if debug=True

Return type:

angles (np.array)

iss_preprocess.reg.rounds_and_channels.apply_corrections(im, matrix=None, scales=None, angles=None, shifts=None, cval=0.0)¶

Apply scale, rotation and shift corrections to a multichannel image.

Parameters:

im (np.array) – X x Y x Nchannels image
matrix (np.array) – Nchannels list of affine transformations matrices. If provided, scales, angles and shifts are ignored.
scales (np.array) – Nchannels array of scale factors
angles (np.array) – Nchannels array of angles
shifts (np.array) – Nchannels x 2 array of shifts
cval (float) – value to fill empty pixels

Returns:

X x Y x Nchannels registered image

Return type:

im_reg (np.array)

iss_preprocess.reg.rounds_and_channels.correct_by_block(im, ch_to_align, median_filter_size=None, block_size=256, overlap=0.5, max_shift=None, correlation_threshold=None, binarise_quantile=None, max_residual=2, debug=False)¶

Estimate affine transformations by block for each channel of a multichannel image

Parameters:

im (np.array) – X x Y x Nchannels image
ch_to_align (int) – channel to align to
median_filter_size (int, optional) – size of median filter to apply to the stack.
block_size (int, optional) – size of the block to use for registration. Default to 256
overlap (float, optional) – overlap between blocks. Default: 0.5
max_shift (int, optional) – maximum shift to avoid spurious cross-correlations. Default: None
correlation_threshold (float, optional) – threshold for correlation to use for fitting affine transformations. None to keep all values. Default to None
binarise_quantile (float, optional) – quantile to use for binarisation of each block. Default to None
max_residual (int, optional) – maximum residual to include shift in the final fit in affine_by_block. defaults to 2
debug (bool, optional) – whether to return debug info, default: False

Returns:

Nchannels list of affine transformations debug_info (dict): dictionary with debug info, only if debug=True

Return type:

output (list)

iss_preprocess.reg.rounds_and_channels.estimate_affine_for_tile(stack, tform_matrix=None, max_shift=None, ref_ch=0, block_size=512, max_residual=2, overlap=0.6, correlation_threshold=0.01, binarise_quantile=None, debug=False)¶

Estimate affine transformations for a single tile

Parameters:

stack (np.array) – X x Y x Nchannels images stack
tform_matrix (np.array, optional) – Nchannels list of affine transformations matrices for initial alignment. Default: None
max_shift (int) – maximum shift to avoid spurious cross-correlations
ref_ch (int) – reference channel
block_size (int) – size of the block to use for registration, default: 512
max_residual (int) – maximum residual to include shift in the final fit in affine_by_block, defaults to 2
overlap (float) – overlap between blocks, default: 0.6
correlation_threshold (float) – threshold for correlation to use for fitting affine transformations, default: 0.01
binarise_quantile (float) – quantile to use for binarisation of each block default: None
debug (bool) – whether to return debug info, default: False

Returns:

Nchannels list of affine transformations matrices debug_info (dict): dictionary with debug info, only if debug=True

Return type:

matrix (np.array)

iss_preprocess.reg.rounds_and_channels.estimate_correction(im, ch_to_align=0, upsample=False, max_shift=None, median_filter_size=None, scale_range=0.05, nangles=3, niter=5, angle_range=1.0, debug=False, use_masked_correlation=False)¶

Estimate scale, rotation and translation for each channel of a multichannel image.

Parameters:

im (np.array) – X x Y x Nchannels image
ch_to_align (int) – channel to align to
upsample (bool, or int) – whether to upsample the image, and if so by what factor
max_shift (int) – maximum shift to avoid spurious cross-correlations
median_filter_size (int) – size of median filter to apply to the stack.
scale_range (float) – range of scale factors to search through
nangles (int) – number of angles to search through
niter (int) – number of iterations to run
angle_range (float) – range of angles to search through
debug (bool) – whether to return debug info, default: False
use_masked_correlation (bool) – whether to use masked phase correlation

Returns:

Nchannels array of scale factors angles (np.array): Nchannels array of angles shifts (np.array): Nchannels x 2 array of shifts

Return type:

scales (np.array)

iss_preprocess.reg.rounds_and_channels.estimate_rotation_angle(reference_fft, target, angle_range, best_angle, nangles, max_shift=None, min_shift=None, debug=False, reference_mask_fft=None, target_mask=None, reference_squared_fft=None)¶

Estimate rotation angle that maximizes phase correlation between the target and the reference image.

Parameters:

reference_fft (numpy.ndarray) – X x Y reference image in Fourier domain
target (numpy.ndarray) – X x Y target image
angle_range (float) – range of angles in degrees to search over
best_angle (float) – initial angle in degrees
nangles (int) – number of angles to try
max_shift (int) – maximum shift to avoid spurious cross-correlations
min_shift (int) – minimum shift to avoid spurious cross-correlations
debug (bool) – whether to return debug info
reference_mask_fft (numpy.ndarray) – Binary mask for reference image. If not None, will compute masked phase correlation. Default: None
target_mask (numpy.ndarray) – Binary mask for target image. If not None, will compute masked phase correlation. Default: None
reference_squared_fft (numpy.ndarray) – FFT of the squared reference image. Required for masked phase correlation. Default: None

Returns:

best_angle (float) in degrees max_cc (float) maximum cross correlation debug_info (dict): dictionary with debug info, only if debug=True

iss_preprocess.reg.rounds_and_channels.estimate_rotation_translation(reference, target, angle_range=5.0, niter=3, nangles=20, reference_mask=None, target_mask=None, upsample=None, min_shift=None, max_shift=None, iter_range_factor=5.0, debug=False)¶

Estimate rotation and translation that maximizes phase correlation between the target and the reference image. Search for the best angle is performed iteratively by decreasing the gradually searching over small and smaller angle range.

Parameters:

reference (numpy.ndarray) – X x Y reference image
target (numpy.ndarray) – X x Y target image
angle_range (float) – initial range of angles in degrees to search over
niter (int) – number of iterations to refine rotation angle
nangles (int) – number of angles to try on each iteration
reference_mask (numpy.ndarray) – Binary mask for reference image. Only used if upsample is not None. Default: None
target_mask (numpy.ndarray) – Binary mask for target image. Only used if upsample is not None. Default: None
upsample (bool, or int) – whether to upsample the image, and if so by what factor
min_shift (int) – minimum shift. Necessary to avoid spurious cross-correlations for images acquired from the same camera
max_shift (int) – maximum shift. Necessary to avoid spurious cross-correlations
iter_range_factor (float) – how much to shrink the angle range for each iteration. Default: 5.
debug (bool) – whether to return debug info

Returns:

best_angle (float) in degrees shift (tuple) of X and Y shifts debug_info (dict): dictionary with debug info, only if debug=True

iss_preprocess.reg.rounds_and_channels.estimate_scale_rotation_translation(reference, target, angle_range=5.0, scale_range=0.01, nscales=15, niter=3, nangles=15, verbose=False, upsample=False, max_shift=None, debug=False, use_masked_correlation=False)¶

Estimate rotation and translation that maximizes phase correlation between the target and the reference image. Search for the best angle is performed iteratively by gradually searching over small and smaller angle range.

Parameters:

reference (numpy.ndarray) – X x Y reference image
target (numpy.ndarray) – X x Y target image
angle_range (float) – initial range of angles in degrees to search over
scale_range (float) – initial range of scales to search over
nscales (int) – number of scales to try
niter (int) – number of iterations to refine rotation angle
nangles (int) – number of angles to try on each iteration
verbose (bool) – whether to print progress of registration
upsample (bool, or int) – whether to upsample the image, and if so but what factor. Default: False
max_shift (int) – maximum shift to avoid spurious cross-correlations
debug (bool) – whether to return debug info. Default: False
use_masked_correlation (bool) – whether to use masked phase correlation

Returns:

best_angle (float) in degrees shift (tuple) of X and Y shifts debug_info (dict): dictionary with debug info, only if debug=True

iss_preprocess.reg.rounds_and_channels.estimate_shifts_and_angles_for_tile(stack, scales=None, ref_ch=0, max_shift=None, debug=False)¶

Estimate shifts and angles for a single tile

Parameters:

stack (np.array) – X x Y x Nchannels images stack
scales (np.array) – Nchannels array of scales
ref_ch (int) – reference channel
max_shift (int) – maximum shift to avoid spurious cross-correlations
debug (bool) – whether to return debug info, default: False

Returns:

Nchannels array of angles, if tfom_matrix is None shifts (np.array): Nchannels x 2 array of shifts, if tfom_matrix is None debug_info (dict): dictionary with debug info, only if debug=True

Return type:

angles (np.array)

iss_preprocess.reg.rounds_and_channels.estimate_shifts_for_tile(stack, angles_within_channels, matrix_between_channels, ref_ch=0, ref_round=0, max_shift=None, min_shift=None, median_filter_size=None)¶

Use precomputed rotations and scale factors to re-estimate shifts for every round and between channels.

Parameters:

stack (np.array) – X x Y x Nchannels x Nrounds images stack
angles_within_channels (np.array) – Nchannels x Nrounds array of angles
matrix_between_channels (list) – Nchannels list of affine transformation matrices
ref_ch (int) – reference channel
ref_round (int) – reference round
max_shift (int) – maximum shift to avoid spurious cross-correlations
min_shift (int) – minimum shift to avoid spurious cross-correlations
median_filter_size (int) – size of median filter to apply to the stack.

Returns:

Nchannels x Nrounds x 2 array of shifts shifts_between_channels (np.array): Nchannels x Nchannels x 2 array of shifts

Return type:

shifts_within_channels (np.array)

iss_preprocess.reg.rounds_and_channels.generate_channel_round_transforms(angles_within_channels, shifts_within_channels, matrix_between_channels, stack_shape, align_channels=True, ref_ch=0)¶

Generate transformation matrices for each channel and round.

Parameters:

angles_within_channels (np.array) – Nchannels x Nrounds array of angles
shifts_within_channels (np.array) – Nchannels x Nrounds x 2 array of shifts
matrix_between_channels (list) – Nchannels list of affine transformation matrices
stack_shape (tuple) – shape of the stack
align_channels (bool) – whether to register channels to each other

Returns:

Nch x Nrounds array of transformation matrices (each 3x3)

Return type:

np.array

iss_preprocess.reg.rounds_and_channels.get_channel_reference_images(stack, angles_channels, shifts_channels)¶

Get registered reference images for each channel from STD or mean projection.

Parameters:

stack (np.array) – X x Y x Nchannels x Nrounds images stack
angles_channels (np.array) – Nchannels x Nrounds array of angles
shifts_channels (np.array) – Nchannels x Nrounds x 2 array of shifts

Returns:

X x Y x Nchannels std projections mean_stack (np.array): X x Y x Nchannels mean projections

Return type:

std_stack (np.array)

iss_preprocess.reg.rounds_and_channels.phase_correlation_by_block(reference, target, block_size=256, overlap=0.1, upsample_factor=1)¶

Estimate translation between two images by dividing them into blocks and estimating translation for each block.

Parameters:

reference (np.array) – reference image
target (np.array) – target image
block_size (int) – size of the blocks
overlap (float) – fraction of overlap between blocks

Returns:

array of shifts for each block

Return type:

shifts (np.array)

iss_preprocess.reg.rounds_and_channels.register_channels_and_rounds(stack, ref_ch=0, ref_round=0, median_filter=None, min_shift=None, max_shift=None, use_masked_correlation=False, align_method='affine', binarise_quantile=None, reg_block_size=512, reg_block_overlap=0.6, correlation_threshold=0.01, max_residual=2, debug=False, verbose=True)¶

Estimate transformation matrices for alignment across channels and rounds.

Parameters:

stack – X x Y x Nchannels x Nrounds images stack
ref_ch (int) – channel to align to
ref_round (int) – round to align to
median_filter (int) – size of median filter to apply to the stack.
min_shift (int) – minimum shift. Necessary to avoid spurious cross-correlations for images acquired from the same camera
max_shift (int) – maximum shift. Necessary to avoid spurious cross-correlations
use_masked_correlation (bool) – whether to use masked phase correlation
align_method (str) – method to use for alignment, either affine or similarity. Default: affine
binarise_quantile (float) – quantile to use for binarisation of each block
reg_block_size (int) – size of the block to use for registration. Default: 512
reg_block_overlap (float) – overlap between blocks, default: 0.6
correlation_threshold (float) – threshold for correlation to use for fitting affine transformations, default: 0.01
max_residual (int) – maximum residual to include shift in the final fit in affine_by_block, defaults to 2
debug (bool) – whether to return debug info, default: False
verbose (bool) – whether to print progress of registration. Default: True

Returns:

Nchannels x Nrounds array of angles shifts_within_channels (np.array): Nchannels x Nrounds x 2 array of shifts accross_channels_params (list): Nchannels list of affine transformations if

affine_by_block, a list of scales_between_channels (Nchannels array of scales), angles_between_channels (Nchannels array of angles), and shifts_between_channels (Nchannels x 2 array of shifts)

debug_info (dict): dictionary with debug info, only if debug=True

Return type:

angles_within_channels (np.array)

iss_preprocess.reg.rounds_and_channels.register_image_channels(align_method, stack, ref_ch, binarise_quantile, rounds_max_shift, reference_tforms=None, reg_block_size=256, reg_block_overlap=0.5, correlation_threshold=0.01, max_residual=2, median_filter_size=None, debug=False, verbose=True)¶

Run the relevant phase correlation on channels of one stack depending on the alignment method.

If align_method is “similarity”, parameters used are: - binarise_quantile - rounds_max_shift - reference_tforms (mandatory)

If align_method is “affine”, parameters used are: - binarise_quantile - rounds_max_shift - reference_tforms (optional) - reg_block_size - reg_block_overlap - correlation_threshold - max_residual - median_filter_size

Parameters:

align_method (str) – Alignment method to use. One of “similarity” or “affine”.
stack (np.array) – Image stack to register.
ref_ch (int) – Reference channel.
binarise_quantile (float) – Quantile to binarise images before registration.
rounds_max_shift (int) – Maximum shift to avoid spurious cross-correlations.
reference_tforms (dict, optional) – Reference transformation parameters. Default: None
reg_block_size (int, optional) – Size of the block to use for registration. Default: 256
reg_block_overlap (float, optional) – Overlap between blocks. Default: 0.5
correlation_threshold (float, optional) – Threshold for correlation to use for fitting affine transformations. Default: 0.01
max_residual (int, optional) – Maximum residual to include shift in the final fit in affine_by_block. Default: 2
median_filter_size (int, optional) – Size of median filter to apply to the stack. Default: None
debug (bool, optional) – Return debug information. Default to False
verbose (bool, optional) – Print registration parameters. Default to True

Returns:

Transformation parameters. dict: Debug information, only if debug is True

Return type:

dict

iss_preprocess.reg package¶

Submodules¶

iss_preprocess.reg.rounds_and_channels module¶

Module contents¶