clearex.file_operations.tools

Functions

`crop_overlapping_datasets`(fixed_roi, ...[, ...])	Crop two 3D images to the maximal overlapping bounding box containing foreground signal.
`delete_filetype`(data_path, filetype)	Delete any files with the designated filetype in the specified directory.
`get_moving_image_paths`(directory, idx)	Get a list of .tif and .tiff image paths for a given round index in a directory.
`get_roi_indices`(image[, roi_size])	Get indices for a centered ROI of size roi_size x roi_size x roi_size
`get_variable_size`(variable)	Get the size of a variable in MB.
`identify_minimal_bounding_box`(image[, ...])	Identify the minimal bounding box that encloses foreground signal in a 3D image using Otsu thresholding.
`identify_robust_bounding_box`(binary[, ...])	Compute a robust bounding box from binary 3D mask by ignoring outliers.
`load_variable_from_disk`(path)	Load a variable from disk.
`merge_bounding_boxes`(box1, box2)	Compute a minimal bounding box that encompasses two input bounding boxes.
`save_variable_to_disk`(variable, path)	Save a variable to disk.

clearex.file_operations.tools.get_moving_image_paths(directory, idx)

Get a list of .tif and .tiff image paths for a given round index in a directory.

Parameters:

directory (str or Path) – The directory to search for image files.
idx (int) – The round index to match in the filenames.

Returns:

List of matching image file paths.

Return type:

list of Path

clearex.file_operations.tools.get_variable_size(variable)

Get the size of a variable in MB.

Parameters:: variable (Any) – The variable to get the size of.
Returns:: The size of the variable in MB.
Return type:: float

clearex.file_operations.tools.save_variable_to_disk(variable, path)

Save a variable to disk.

Parameters:

variable (Any) – The variable to save.
path (str) – The path to save the variable to.

Return type:

None

clearex.file_operations.tools.load_variable_from_disk(path)

Load a variable from disk.

Parameters:: path (str) – The path to load the variable from.
Returns:: The loaded variable
Return type:: Any
Raises:: FileNotFoundError – If the file is not found.

clearex.file_operations.tools.delete_filetype(data_path, filetype)

Delete any files with the designated filetype in the specified directory.

Parameters:

data_path (str) – The path to the directory containing the files.
filetype (str) – The filetype to delete. E.g. ‘pdf’

Return type:

None

clearex.file_operations.tools.get_roi_indices(image, roi_size=256)

Get indices for a centered ROI of size roi_size x roi_size x roi_size

Parameters:

image (np.ndarray) – The input image from which to extract the ROI.
roi_size (int, optional) – The size of the ROI to extract from the center of the image. Default is 256.

Returns:

A tuple containing the start and end indices for each dimension (z_start, z_end, y_start, y_end, x_start, x_end).

Return type:

tuple

clearex.file_operations.tools.identify_robust_bounding_box(binary, lower_pct=5, upper_pct=95)

Compute a robust bounding box from binary 3D mask by ignoring outliers.

Parameters:

binary (np.ndarray) – 3D binary array (dtype=bool or 0/1).
lower_pct (float) – Lower percentile cutoff (e.g., 5).
upper_pct (float) – Upper percentile cutoff (e.g., 95).

Returns:

(z0, z1, y0, y1, x0, x1) – Bounding box indices in the form: [z_start:z_end, y_start:y_end, x_start:x_end]

Return type:

Tuple of ints

clearex.file_operations.tools.identify_minimal_bounding_box(image, down_sampling=8, robust=False, lower_pct=5, upper_pct=95)

Identify the minimal bounding box that encloses foreground signal in a 3D image using Otsu thresholding.

This function performs downsampling-based Otsu thresholding to detect foreground voxels, computes the minimal bounding box in the downsampled space, and scales the result back to the original image resolution.

Parameters:

image (np.ndarray or ants.core.ants_image.ANTsImage) – A 3D image in either NumPy array or ANTsImage format. If an ANTsImage is provided, it will be converted to a NumPy array internally.
down_sampling (int, optional) – Downsampling factor applied to the input image before Otsu thresholding. Used to speed up thresholding and bounding box computation. Default is 8.
robust (bool) – Run the robust boundary detection method. Default is False.
lower_pct (float) – Lower percentage for cut-off for robust boundary detection. Values between 0 and 100 and valid.
upper_pct (float) – Upper percentage for cut-off for robust boundary detection. Values between 0 and 100 and valid.

Returns:

z_start (int) – Starting index (inclusive) of the bounding box along the z-axis in full resolution.
z_end (int) – Ending index (exclusive) of the bounding box along the z-axis in full resolution.
y_start (int) – Starting index (inclusive) of the bounding box along the y-axis in full resolution.
y_end (int) – Ending index (exclusive) of the bounding box along the y-axis in full resolution.
x_start (int) – Starting index (inclusive) of the bounding box along the x-axis in full resolution.
x_end (int) – Ending index (exclusive) of the bounding box along the x-axis in full resolution.

Raises:

TypeError – If the input image is not a NumPy array or ANTsImage.
ValueError – If no foreground signal is detected in the thresholded binary image.

Return type:

Tuple[int, int, int, int, int, int]

Notes

The bounding box is returned in (z_start, z_end, y_start, y_end, x_start, x_end) order and is compatible with slicing: image[z_start:z_end, y_start:y_end, x_start:x_end].

Examples

>>> bbox = identify_minimal_bounding_box(image, down_sampling=8)
>>> z0, z1, y0, y1, x0, x1 = bbox
>>> cropped = image[z0:z1, y0:y1, x0:x1]

clearex.file_operations.tools.merge_bounding_boxes(box1, box2)

Compute a minimal bounding box that encompasses two input bounding boxes.

This function takes two bounding boxes in the form of 6-element tuples (z_start, z_end, y_start, y_end, x_start, x_end), and returns a new bounding box that spans both inputs. It ensures start coordinates are minimized and end coordinates are maximized to fully include both regions. The output is returned as a tuple of slice objects for direct use in array indexing.

Parameters:

box1 (tuple of int or np.integer) – Bounding box coordinates in the format (z_start, z_end, y_start, y_end, x_start, x_end).
box2 (tuple of int or np.integer) – Another bounding box to merge, in the same format as box1.

Returns:

bounding_box_slices – A merged bounding box that fully encompasses both box1 and box2, returned as a tuple of slice objects in the order (z, y, x), and ready for use in array slicing.

Return type:

tuple of slice

Examples

>>> bounding_box_1 = (10, 50, 20, 60, 30, 80)
>>> bounding_box_2 = (15, 55, 10, 70, 25, 85)
>>> merged_slices = merge_bounding_boxes(bounding_box_1, bounding_box_2)
>>> image[merged_slices]  # Direct indexing into a 3D image

clearex.file_operations.tools.crop_overlapping_datasets(fixed_roi, transformed_image, robust=False, lower_pct=5, upper_pct=95)

Crop two 3D images to the maximal overlapping bounding box containing foreground signal.

This function computes the minimal foreground bounding boxes for each input image and then determines a merged bounding box that encompasses both regions. Each image is then cropped to this merged region. Foreground detection is based on intensity thresholding (e.g., Otsu), with an optional robust mode to reduce sensitivity to outliers.

Parameters:

fixed_roi (np.ndarray or ants.core.ants_image.ANTsImage) – The fixed image or ROI volume. Must be a 3D image.
transformed_image (np.ndarray or ants.core.ants_image.ANTsImage) – The transformed moving image aligned to the fixed ROI. Must also be 3D.
robust (bool, optional) – If True, uses a robust method to detect foreground and exclude outliers when computing the bounding boxes. If False, uses strict minimum and maximum coordinates. Default is False.
lower_pct (float, optional) – Lower percentage for cut-off for robust boundary detection. Values between 0 and 100 and valid. Default is 5.
upper_pct (float, optional) – Upper percentage for cut-off for robust boundary detection. Values between 0 and 100 and valid. Default is 95.

Returns:

fixed_cropped (np.ndarray) – Cropped version of the fixed image limited to the shared bounding box.
transformed_cropped (np.ndarray) – Cropped version of the transformed image limited to the shared bounding box.
bounding_box (np.ndarray) – The bounding box used to slice the data.

Raises:

ValueError – If no foreground is detected in either image.

Return type:

tuple[numpy.ndarray[tuple[int, …], Any], numpy.ndarray[tuple[int, …], Any], Union[Iterable, tuple[slice]]]

Notes

If input images are ANTsImage objects, they will be converted to NumPy arrays ( dtype uint16) before cropping. The bounding box is computed in (z_start:z_end, y_start:y_end, x_start:x_end) order.

Examples

>>> fixed_crop, moving_crop, bounding_box = crop_overlapping_datasets(fixed_img, moving_img, robust=True, lower_pct=2, upper_pct=98)