align module

Functions for FIJI and alignment.

There are different alignment procedures for FIJI for Linear Stack Alignment with Sift as well as bUnwarpJ alignemnt. These function build the FIJI macro to be run in FIJI and return a stack of aligned images.

Author: Tim Cote, ANL, Fall 2019.

align.apply_buj_trasf2stack(flip_ref: str, unflip_ref: str, stack_paths: List[str], flip_files: List[List[str]], unflip_files: List[List[str]], reference: str, transform_path: str, transformation: Tuple[float, float, float, bool], savename: str) → str

Applies the transformation produced by bUnwarpJ for the unflip<->flip infocus images to all images of the opposite stack.

Once the flip/unflip stack series are generated using the Linear Stack with SIFT alignment, the infocus images of each series are aligned. One of these infocus images is the target to align to, the other image is the source that is aligning to the target. Once these have been aligned with bUnwarpJ, the transformation is applied to all images that are in the stack series of the source image (source stack).

Args:

flip_ref: The datafolder that contains the paths to the dm3 files. unflip_ref: A list of the names of the mask_files.

stack_paths: [flip_path, unflip_path] flip_files: List of all the flip files. unflip_files: List of all the unflip files. reference: The reference value of ‘flip’ or ‘unflip’. transform_path: The path to the transformation file created by bUnwarpJ. transformation: Tuple of image shift and rotation params. savename: The filename for saving the aligned stack.

Returns:

The bUnwarpJ macro for applying the bUnwarpJ transformation.

align.apply_transform(flip: bool, orient_path: str, fnames: List[str], transform_params: Tuple[float, float, float, bool]) → Tuple[int, str]

Create macro that applies transformations for pre-alignment.

Parameters:

• flip (bool) – Option for whether the files are flipped or not.
• orient_path (str) – The orientation path (flip, unflip, tfs).
• fnames (List[str]) – List of filenames.
• transform_params (Tuple[float, float, float, bool]) – Tuple of transformation parameters.

Returns:

Tuple of number of images and shifted rotated macro

• num_files: The number of images files being manipulated.
• transformed_files_macro: The shifted/rotated macro.

align.bUnwarp_align(src_img: str, target_img: str, mask_fn: List[Optional[str]], im_size: int, buj_params: Optional[Dict[str, Any]], transf_savename: str) → str

Carries out the bUnwarpJ alignment.

Aligns the flip and unflip infocus images, defined as the source or target. Mask files can be utilized to select specific regions for aligning.

Parameters:

• src_img – The infocus image to transform.
• target_img – The infocus image to align to.
• mask_fn – The filenames for the mask files, can be [None, None].
• im_size – The pixel size of the sides of the square image.
• buj_params – Dictionary of bunwarpJ parameters.
• transf_savename – The path to the transformation file created by bUnwarpJ.

Returns:

The bUnwarpJ macro for carrying out the bUnwarpJ alignment.

align.check_image_flip(window: int, path1: str, path2: str, ref: str) → Tuple[bool, str]

Check if image requires a horizontal flip.

Parameters:

• window – The number of the window being looked at
• path1 – The 1st pathname for the orientation directory, depending on unflip/flip reference.
• path2 – The 2nd pathname for the orientation directory, depending on unflip/flip reference.
• ref – The selected reference image of ‘unflip’ or ‘flip’.

Returns:

Boolean value for if image needs to be flipped and the pathname

of that image.

align.close_all_windows_macro() → str

Create macro to close all remaining windows.

align.concatenate_stacks_macro(stack_names: str, concat_list: str) → str

Create macro to concatenate all files into one large stack and return.

Parameters:

• stack_names – The shortnames of the stacks to concatenate.
• concat_list – The order for concatenating the stacks.

Returns:

The macro for concatenating stacks.

align.delete_excess_images_macro(files: List[List[str]], short_names: List[List[str]], ref: str) → str

Create macro to trim excess images appearing after stack is aligned.

Parameters:

• files – 2D list of all of the files.
• short_names – The list of shortnames for the aligned stacks.
• ref – The reference infocus image.

Returns:

The macro from trimming excess images from stacks.

align.determine_window_focus(window: int) → Tuple[Tuple[int, int], bool]

Determine if image window is underfocused, infocus, or overfocused.

Parameters:window – The number of the window. - images [2, 3, 5, 6] in/overfocused (+) - images [1, 4] underfocus (-) Returns:

Tuple of place in file list to choose focus during

macro creation later and truth value for whether image is in/overfocus (True) or underfocus (False).

align.extract_SIFT_landmarks_macro(src_img: str, target_img: str, SIFT_params: Optional[Dict[str, Any]]) → str

Extracts SIFT features for bUnwarpJ alignment.

Parameters:

• src_img – The infocus image to transform.
• target_img – The infocus image to align to.
• SIFT_params – Dictionary of bunwarpJ parameters.

Returns:

The bUnwarpJ macro for SIFT feature extraction for bUnwarpJ alignment.

align.fijify_macro(unready_macro: str) → str

Converts macro into FIJI format and returns macro.

The Fiji format uses ‘;’ as end lines, and sometimes contains additional whitespace. This function accounts for that, edits the macro string, and returns it in the correct format.

Parameters:unready_macro – The un-formatted FIJI macro. Returns:The correctly formatted FIJI macro. Return type:fiji_ready_macro

align.format_macro(all_macros: List[str]) → str

Format the full macro so it will be ready for use in FIJI.

Parameters:all_macros – All formatted FIJI macros for alignment. Returns:The finalized FIJI macro. Return type:fiji_ready_macro

align.get_shift_rot_macro(transformation: Tuple[float, float, float, bool], stack: bool = False) → str

Creates macro for applying shifts and rotations for images .

Parameters:

• transformation – Tuple of transformation values.
• stack – Option of whether image is a stack or single image

Returns:

The macro for shift and rotation transformations

Return type:

apply_transform

align.ls_alignment(path1: str, path2: str, sift_params: Dict[str, Any], transform_params: Tuple[float, float, float, bool], ref: str, all_files: List[List[str]]) → Tuple[List[str], List[str]]

Create ImageJ macros for each defocus and orientation other than infocus.

Parameters:

• path1 – The first unflip/flip path/directory.
• path2 – The first unflip/flip path/directory.
• sift_params – The Linear SIFT params.
• transform_params – The shifting and rotation transformation params.
• ref – The reference image for flip/unflip.
• all_files – All ordered filenames in under [[underfocus], [infocus] [overfocus]]

Returns:

Tuple of list of both macros and shortnames.

align.ls_macro(sift_params: Dict[str, Any]) → str

Create macro for running SIFT alignment. Read ‘feature extraction’ on ImageJ for more information.

Parameters:sift_params – Dictionary of sift parameter values. Returns:

The macro for running the linear stack alignment

with SIFT.

Return type:marco

align.order_windows_for_selection_macro(shortnames: List[List[str]], ref: str) → Tuple[str, str]

Select windows in the order they will be combined.

Parameters:

• shortnames – The list of shortnames for the aligned stacks.
• ref – The reference infocus image.

Returns:

Window order macro and the macro for concatenating stacks.

align.post_ls_alignment(macros: List[str], short_names: List[List[str]], files: List[List[str]], stack_name: str, ref: str) → List[str]

Runs all saving, concatenation, deleting of excess files.

Parameters:

• macros – The current list of macros to feed into FIJI.
• short_names – The list of stack shortnames
• files – The 2D list of all image files.
• stack_name – The name to give the final fully aligned stack.
• ref – The reference infocus filename.

Returns:

List of macros for post LS alignment procedure.

align.post_single_ls_alignment(macros: List[str], shortnames: List[List[str]], files: List[List[str]], stack_name: str, ref: str) → List[str]

Runs all saving, concatenation, deleting of excess files for single tfs.

Parameters:

• macros – The current list of macros to feed into FIJI.
• shortnames – The list of stack shortnames
• files – The 2D list of all image files.
• stack_name – The name to give the final fully aligned stack.
• ref – The reference infocus filename.

Returns:

List of macros for post LS alignment procedure.

align.pre_bUnwarp_align(unflip_ref: str, flip_ref: str, mask_files: List[Optional[str]], reference: str, transformation: Tuple[float, float, float, bool]) → Tuple[str, str, str, List[Optional[str]]]

Precursor to bUnwarpJ alignment to collect files, references, and masks..

Determine the source and target images for bUnwarpJ. Apply any pre-transformations necessary to help with bUnwarpJ alignment. Open and return the masks for source and target.

Parameters:

• unflip_ref – The unflip infocus image path.
• flip_ref – The flip infocus image path.
• mask_files – The filenames for the mask files, can be [None, None].
• reference – The reference value for ‘unflip’/’flip’.
• transformation – The pre-shift/rotation to align the infocus images.

Returns:

The bUnwarpJ macro for carrying out the bUnwarpJ alignment. Additionally

returns the source and target path names, as well as the associated masks for each image.

align.pre_ls_alignment(reference: str, check_sift: bool, path1: str, path2: str, fls_files: List[str], tfs_value: str, fls_value: str) → Tuple[str, Tuple[List[List[str]], Optional[str], Optional[List[str]]]]

Pre-alignment file manipulations for linear stack alignment with SIFT.

Check setup, get reference image to align to, and get all image filenames.

Parameters:

• reference – The type of reference to dictate alignment. Options: ‘tfs’, ‘unflip’, ‘flip’
• check_sift (bool) – Option for checking SIFT alignment.
• path1 – The first unflip/flip/single path/directory.
• path2 – The first unflip/flip/single path/directory.
• fls_files – A list of the FLS filenames.
• tfs_value – The through-focal series option. Options: Unflip/FLip, Single
• fls_value – The FLS option. Options: One, Two

Returns:

A tuple of the reference file as well as all other filenames.

• vals[0]: The reference filename.
• vals[1][0]: 2D list of all files
• vals[1][1]: 2D list of ordered image files for path1
• vals[1][2]: 2D list of ordered image files for path2

Return type:

vals

align.run_bUnwarp_align(datafolder: str, mask_files: List[Optional[str]], reference: str, transformation: Tuple[float, float, float, bool], im_size: int, stack_paths: List[Optional[str]], sift_FE_params: Optional[Dict[str, Any]] = None, buj_params: Optional[Dict[str, Any]] = None, savenames: Tuple[str, str] = ('default.txt', 'default.tif'), fls_files: Optional[List[str]] = None) → str

Uses bUnwarpJ to align all ‘dm3’ files in the ‘datafolder’ and saves an aligned Tiff stack in the datafolder.

Parameters:

• datafolder – The datafolder that contains the paths to the dm3 files.
• mask_files – A list of the names of the mask_files. - This can be a list of [None, None] if no masks are used.
• reference – The reference tag that will be used for aligning.
• transformation – Tuple of image shift and rotation params.
• im_size – Integer pixel size of the image.
• stack_paths – [flip_path, unflip_path]
• sift_FE_params – Dictionary of SIFT feature extract params.
• buj_params – Dictionary of bUnwarpJ params.
• savenames – The filenames for saving the aligned stacks.
• fls_files – The list of fls files

Returns:

The full run bUnwarpJ align macro.

align.run_ls_align(datafolder: str, reference: str = 'unflip', check_sift: bool = False, sift_params: Optional[Dict[str, Any]] = None, transform_params: Optional[Tuple[float, float, float, bool]] = None, stack_name: str = 'uf_aligned_ls_stack.tif', tfs_value: str = 'Unflip/Flip', fls_value: str = 'Two', fls_files: Optional[List[str]] = None) → str

Aligns all ‘dm3’ files in the ‘datafolder’ and saves an aligned Tiff stack in the datafolder.

Parameters:

• datafolder – The datafolder that contains the paths to the dm3 files.
• reference – The reference tag that will be used for aligning.
• check_sift – Option for full align (False) or check SIFT params align (True).
• sift_params – Dictionary of SIFT params.
• transform_params – Tuple of image shift and rotation params.
• stack_name – The filename for saving the aligned stack.
• tfs_value – Value for the type of tfs.
• fls_value – Value for the number of fls files.
• fls_files – The list of fls files.

Returns:

The full run LS align macro.

align.run_single_ls_align(datafolder: str, reference: str = '', sift_params: Optional[Dict[str, Any]] = None, stack_name: str = 'test_ls_align.tif', fls_files: Optional[List[str]] = None) → str

Aligns all ‘dm3’ files in the ‘datafolder’ and saves an aligned tiff stack in the datafolder for a single tfs.

Parameters:

• datafolder – The datafolder that contains the paths to the dm3 files.
• reference – The reference tag that will be used for aligning.
• sift_params – Dictionary of SIFT params.
• stack_name – The filename for saving the aligned stack.
• fls_files – The list of fls files

Returns:

The full run LS align macro for single tfs..

align.save_stack_macro(savename: str) → str

Create macro to save and close all remaining windows.

align.set_default_bUnwarp() → Dict[str, Any]

Create the default bUnwarpJ parameters.

Default bUnwarpJ parameters

{‘reg_mode’: ‘Fast’,

‘img_sub_factor’: 0, ‘init_def’: ‘Very Coarse’, ‘final_def’: ‘Very Fine’, ‘div_weight’: 0.1, ‘curl_weight’: 0.1, ‘landmark_weight’: 1.0, ‘img_weight’: 1.0, ‘cons_weight’: 10, ‘stop_thresh’: 0.01}

Returns:All necessary bUnwarpJ parameters. Return type:bUnwarp_params

align.set_default_sift() → Dict[str, Any]

Set the default sift parameters.

Default SIFT parameters

{‘igb’: 1.6, ‘spso’: 3, ‘min_im’: 48, ‘max_im’: 1200, ‘fds’: 4, ‘fdob’: 8, ‘cnc’: 0.95, ‘max_align_err’: 5, ‘inlier_rat’: 0.05, ‘exp_transf’: ‘Affine’, ‘interpolate’: True}

Returns:All necessary Linear Stack Align with SIFT parameters. Return type:sift_params

align.set_shortnames(files: List[List[str]], place: Tuple[int, int]) → Tuple[List[str], str]

Return the filenames along with shortened names for

FIJI window.

Parameters:

• files – List of list of image filenames.
• place – The indices to be checking in the ‘files’ list.

Returns:

List of image filenames and shortnames

• fnames: List of image filenames.

• short: The shortened name for the files to be aligning

  • first character refers to flip/unlip,
  • last character to under/in/over-focus.

align.single_ls_alignment(sift_params: Dict[str, Any], files: List[List[str]], path: str, param_test: bool = False, ref: Optional[str] = None) → Tuple[List[str], List[str]]

Create ImageJ macros for each defocus and orientation

other than the reference infocus image for a single stack.

Args:

sift_params: The Linear SIFT params. files: All ordered filenames in under [[underfocus], [infocus] [overfocus]] path: The single path/directory. param_test: Boolean for whether LS alignment is being checked ref: The reference filename.

Returns:Tuple of list of both macros and shortnames.

align.trim_and_reverse_single_stack(filenames: List[List[str]], shortname: str) → Tuple[str, str]

Removes excess images for a single stack.

Similar to trim_and_reverse_stacks but for a single tfs stack.

Parameters:

• filenames – List of image filenames.
• shortname – The shortened name for the files to be aligning - first character refers to flip/unlip, - last character to under/in/over-focus.

Returns:

Macros for deleting slices and reversing a stack.

• delete: Macro for deleting slices from stack.
• reverse: Macro for reversing an image stack.

align.trim_and_reverse_stacks(filenames: List[List[str]], shortname: str, ref: str, pos: bool) → Tuple[str, str]

Removes excess images and reverses images after initial SIFT alignment.

The images for linear stack alignment with SIFT produce the best results by aligning images to an infocus image. However the stacks that are made in FIJI require the first image be the infocus, so when concatenating multiple stacks together, there are extra infocus images that may need to be removed. This function takes care of that. Images with only 2 images wait to be trimmed as you can’t concatenate a single image with a stack in FIJI.

Parameters:

• filenames – List of image filenames.
• shortname – The shortened name for the files to be aligning - first character refers to flip/unlip, - last character to under/in/overfocus.
• ref – The reference infocus image filename.
• pos – Option for whether the image is under or overfocus to reverse the image stack.

Returns:

Macros for deleting slices and reversing a stack.

• delete: Macro for deleting slices from stack.
• reverse: Macro for reversing an image stack.

align.write_ls_macro(orient_path: str, ref: str, files: List[List[str]], window: int, place: Tuple[int, int], flip: bool, pos: bool, sift_params: Dict[str, Any], transform_params: Tuple[float, float, float, bool]) → Tuple[str, str]

Create the linear stack alignment with SIFT (LS) macro for specific orientation, sign, and focus.

Takes the orientation of flip/unflip/tfs and focus level of overfocus/underfocus/infocus parameters to write the specific LS macro.

Parameters:

• orient_path – The orientation path (flip, unflip).
• ref – The reference infocus image filename.
• files – List of list of image filenames.
• window – Placeholder for name of new stack being made for bookkeeping when combining all stacks later.
• place – The indices to be checking in the ‘files’ list.
• flip – Option for whether the files are flipped or not.
• pos – Option for whether the image is under or overfocus to reverse the image stack.
• sift_params – Dictionary of sift parameter values.
• transform_params – Tuple of transformation parameters.

Returns:

Macro for specific orientation and focus and its shortname.

align.write_single_ls_macro(ref: str, path: str, files: List[List[str]], window: int, sift_params: Dict[str, Any]) → Tuple[str, str]

Create the linear stack alignment with SIFT (LS) macro for specific orientation, sign, and focus.

Similar to write_ls_macro but for a single through focal series (tfs).

Parameters:

• ref – The reference infocus image filename.
• path – The orientation path (tfs).
• files – List of list of image filenames.
• window – Placeholder for name of new stack being made for bookkeeping when combining all stacks later.
• sift_params – Dictionary of sift parameter values.

Returns:

Macro for specific orientation and focus and its shortname.