unravel.core.img_tools module#

This module contains functions processing 3D images:

  • resample: Resample a 3D ndarray.

  • reorient_axes: Reorient an ndarray for registration or warping to atlas space

  • pixel_classification: Segment tif series with Ilastik.

  • pad: Pad an ndarray by a specified percentage.

  • reorient_ndarray: Reorient a 3D ndarray based on the 3 letter orientation code (using the letters RLAPSI).

  • reorient_ndarray2: Reorient a 3D ndarray based on the 3 letter orientation code (using the letters RLAPSI).

  • rolling_ball_subtraction_opencv_parallel: Subtract background from a 3D ndarray using OpenCV.

  • label_IDs: Prints label IDs > min_voxel_count (and optionally their sizes) in a 3D ndarray.

  • find_bounding_box: Finds the bounding box of all clusters or a specific cluster in a cluster index ndarray and optionally writes to file.

unravel.core.img_tools.resample(ndarray, xy_res=None, z_res=None, target_res=None, target_dims=None, scale=None, zoom_order=1)[source]#

Resample a 3D ndarray using target resolution, dimensions, or scale.

Parameters:

  • ndarray (np.ndarray) – Input 3D array to resample.

  • xy_res (float, optional) – Current resolution in the x and y dimensions (e.g., in microns). Required if using target_res.

  • z_res (float, optional) – Current resolution in the z dimension (e.g., in microns). Required if using target_res.

  • target_res (float or tuple of float, optional) – Target resolution for resampling. If a single float, it is assumed to be isotropic (same for x, y, and z). If a tuple/list of three floats, it is assumed to be anisotropic (different for x/y vs. z).

  • target_dims (tuple of int, optional) – Target dimensions for resampling (x, y, z). If provided, it overrides target_res.

  • scale (float or list of float, optional) – Scaling factor for resampling. If a single float, it scales all dimensions equally. If a list of three floats, it scales each dimension independently.

  • zoom_order (int, optional) – SciPy zoom order for interpolation. Default is 1 (linear interpolation). Use 0 for nearest-neighbor interpolation.

Returns:

Resampled 3D array.

Return type:

np.ndarray

Notes

  • This function assumes that the axes of the ndarray are ordered as (x, y, z).

  • The units of measurement should match for xy_res, z_res, and target_res.

unravel.core.img_tools.reorient_axes(ndarray)[source]#

Reorient resampled ndarray for registration or warping to atlas space (mimics orientation change from MIRACL’s tif to .nii.gz conversion)

unravel.core.img_tools.reverse_reorient_axes(ndarray)[source]#

Reorient an ndarray by rotating and flipping to correct axis order for image conversion.

Rotates 90 degrees to the right and flips horizontally.

This can reverse the reorientation done by reorient_axes().

unravel.core.img_tools.pixel_classification(tif_dir, ilastik_project, output_dir, ilastik_executable=None)[source]#

Segment tif series with Ilastik using pixel classification.

unravel.core.img_tools.pad(ndarray, pad_percent=0.25)[source]#

Pads ndarray by a specified percentage.

Parameters:#

ndarraynumpy.ndarray

Input 3D ndarray to pad.

pad_percentfloat

Percentage of padding to add to each dimension. Default: 0.25 (25%%).

Returns:#

padded_ndarraynumpy.ndarray

Padded 3D ndarray.

unravel.core.img_tools.reorient_ndarray(data, orientation_string)[source]#

Reorient a 3D ndarray based on the 3 letter orientation code (using the letters RLAPSI). Assumes initial orientation is RAS (NIFTI convention).

unravel.core.img_tools.reorient_ndarray2(ndarray, orientation_string)[source]#

Reorient a 3D ndarray based on the 3 letter orientation code (using the letters RLAPSI). Assumes initial orientation is RAS (NIFTI convention).

unravel.core.img_tools.process_slice(slice, struct_element)[source]#

Subtract background from <slice> using OpenCV.

unravel.core.img_tools.rolling_ball_subtraction_opencv_parallel(ndarray, radius, threads=8)[source]#

Subtract background from <ndarray> using OpenCV. Uses multiple threads to process slices in parallel. Radius is the radius of the rolling ball in pixels. Returns ndarray with background subtracted.

unravel.core.img_tools.label_IDs(ndarray, min_voxel_count=1, print_IDs=False, print_sizes=False)[source]#

This finds and prints unique intensities in the ndarry with more than min_voxel_count voxels (does not check for connectedness).

Optionally, it also prints the number of voxels for each label ID (intensity).

Parameters:

  • ndarray (numpy.ndarray) – Input array with integer intensities.

  • min_voxel_count (int, optional) – Minimum size threshold for each intensity in voxels. Labels smaller than this threshold are ignored. Default is 1.

  • print_IDs (bool, optional) – If True, print the IDs of labels above the minimum size threshold. Default is False.

  • print_sizes (bool, optional) – If True, print both the IDs and sizes of label IDs above the minimum size threshold. Default is False.

Returns:

List of unique label IDs (intensities) that meet the minimum size threshold.

Return type:

list of int

Examples

>>> import numpy as np
>>> array = np.array([[0, 1, 1], [0, 2, 2], [3, 3, 3]])
>>> cluster_IDs(array, min_voxel_count=2)
[1, 2, 3]

>>> cluster_IDs(array, min_voxel_count=2, print_IDs=True)
1 2 3

>>> cluster_IDs(array, min_voxel_count=2, print_sizes=True)
ID: 1, Size: 2
ID: 2, Size: 2
ID: 3, Size: 3
unravel.core.img_tools.find_bounding_box(ndarray, cluster_ID=None, output_file_path=None)[source]#

Finds the bounding box of all clusters or a specific cluster in a cluster index ndarray and optionally writes to file.

Parameters:

  • ndarray – 3D numpy array to search within.

  • cluster_ID (int) – Cluster intensity to find bbox for. If None, return bbox for all clusters.

  • output_file_path (str) – File path to write the bounding box.

unravel.core.img_tools.crop(ndarray, bbox)[source]#

Crop an ndarray to the specified bounding box (xmin:xmax, ymin:ymax, zmin:zmax)

Parameters:

bbox (str) –