utils.rano_utils module

utils.rano_utils.circle_opening(seg, labels, radius)

Given a segmentation, this function performs a circle opening operation on the specified labels. The opening operation is performed in 3 steps: 1. A mask is created as the union of the specified labels 2. The distance map of the mask is calculated and used to threshold the mask such that only the pixels that are at least radius away from the boundary of the mask are kept. This mask corresponds to the valid centers of the structuring element (the circle). 3. The mask is dilated by the structuring element (the circle) to get the final segmentation (the circle opened mask).

Parameters:

• seg – a 2D numpy array where background is 0 and foreground is > 0

• labels – list of labels to combine for the circle opening operation

• radius – the distance from the boundary of the combined labels (corresponds to the radius of the circle)

Returns:

a 2D numpy array where background is 0 and foreground is 1

Return type:

seg_circle_open

utils.rano_utils.circle_opening_on_slices_perpendicular_to_axis(segmentationArray, axes, labels, radius, slice_idx=None)

Given a 3D segmentation, this function performs a circle opening operation on the specified labels in the slices perpendicular to each of the specified axes, then returns the union of segmentations from all axes.

Parameters:

• segmentationArray – a 3D numpy array with the segmentation

• axes – the axis perpendicular to the slices where the circle opening operation is performed

• labels – list of labels to combine for the circle opening operation

• radius – radius of the circle for the circle opening operation

• slice_idx – if the slice index is specified, the circle opening operation is only performed on that slice. If

• None

• specified (the operation is performed on all slices along the axis. If multiple axes are)

• be (slice_idx must)

• axes. (a list of the same length as)

Returns:

the circle-opened segmentation along the specified axis

utils.rano_utils.find_closest_plane(coords)

Given two lines, this function returns the axis of the plane in which the lines are placed.

Parameters:

coords – a list of two lines, where each line is a list of two points (2 lines x 2 points x 3 coordinates)

Returns:

the index of the axis that is perpendicular to the plane in which the lines are placed

Return type:

axis_idx

utils.rano_utils.find_plane_of_coords(coords)

Given two lines, this function returns the axis of the plane in which the lines are placed.

Parameters:

coords – a list of two lines, where each line is a list of two points with shape (2 lines x 2 points x 3 coordinates)

Returns:

the axis that is perpendicular to the plane in which the lines are placeddinate

Return type:

axis_of_const_coordinate_values

utils.rano_utils.get_all_contained_lines(plane)

Given a plane, this function returns all the lines from one boundary pixel to another that are fully contained within the foreground.

Parameters:

plane – a 2D numpy array where background is 0 and foreground is > 0

Returns:

a list of lines, where each line is a list of two points

Return type:

contained_lines

utils.rano_utils.get_ijk_to_world_matrix(node)

Given a node, this function returns the IJK to world matrix of the binary labelmap

Parameters:

node – the segmentation node or volume node

Returns:

the IJK to world matrix of the binary labelmap

Return type:

ijkToWorld

utils.rano_utils.get_instance_segmentation_by_connected_component_analysis(bin_seg)

Convert a binary segmentation into a segmentation where each connected component gets a different label > 0.

Parameters:

bin_seg – Binary segmentation with shape W, H, D and labels 0 and 1

Returns:

Segmentation with shape W, H, D and labels 0, …, num_ccs (number of connected components)

Return type:

instance_seg

utils.rano_utils.get_max_orthogonal_line_product_coords(seg, valid_axes=(0, 1, 2), center=None, center_tol=5, opening_radius=None, ijkToWorld=None)

Given a segmentation, this function returns the two lines that are orthogonal to each other and have the largest product of their lengths. It does so by looping over views (axial, coronal, sagittal) and planes and finding the two lines with the largest product of their lengths that are orthogonal to each other.

Parameters:

• seg – a 3D numpy array where background is 0 and foreground is > 0. The array defines the IJK space.

• valid_axes – the IJK orientations to consider for finding the orthogonal lines

• center – IJK coordinates of a point that the plane must be close to

• center_tol – IJK tolerance for the distance between the plane and the center point

• opening_radius – the radius of the circle opening operation to apply to the slice segmentation before finding

• lines (the orthogonal)

• ijkToWorld – the transformation matrix to convert from voxel coordinates to world coordinates

Returns:

a list of two lines, where each line is a list of two points and the product of their lengths is maximal. The coordinates are in world space.

Return type:

max_ortho_line_coords

utils.rano_utils.get_max_orthogonal_line_product_coords_plane(line_coords, degree_tol=0)

Given a set of lines, this function returns the two lines that are orthogonal to each other and have the largest product of their lengths. The third condition is that the lines must intersect. The function loops over all lines and checks if the angle between the lines is orthogonal (within the given tolerance). It is assumed that all lines lie in a plane (one of the acquisition planes). This plane can have any orientation in world space.

Parameters:

• line_coords – numpy array of shape (nb_lines, 2, 3) (lines x 2 points x 3 coordinates)

• degree_tol – the tolerance in degrees for the orthogonality of the lines

Returns:

a list of two lines, where each line is a list of two points and the product of their lengths is maximal

Return type:

ortho_line_max_prod_coords

utils.rano_utils.keep_contained_lines(boundary_coords, mask, sample_distance=0.2)

Given a set of boundary coordinates, this method returns the lines that are fully contained within the mask.

Parameters:

• boundary_coords – numpy array of shape (nb_boundary_pixels, 2)

• mask – binary numpy array of shape (width, height)

• sample_distance – the distance between samples on the line to check if the line is contained

Returns:

a list of lines, where each line is a list of two points.

Return type:

contained_lines

utils.rano_utils.match_instance_segmentations_by_IoU(instance_segs)

Given a list of instance segmentations, this function relabels the segmentations so that the labels match between timepoints. It does so by finding the optimal matching of labels based on the IoU (Intersection over Union) of the instances.

Parameters:

• instance_segs – list of instance segmentations, where each segmentation is a 3D numpy array with shape (W, H, D) and

• 0 (labels)

• ... (number of instances)

• num_instances (number of instances)

Returns:

list of instance segmentations with matching labels between timepoints

Return type:

matched_instance_segs

utils.rano_utils.point_closest_to_two_lines(coords)

Given two lines, this function returns the point that is closest to both lines. This can be used to find a point that can be annotated that describes a line pair.

Parameters:

coords – a list of two lines, where each line is a list of two points (2 lines x 2 points x 3 coordinates)

Returns:

the point that is closest to both lines

Return type:

closest_point

utils.rano_utils.run_segmentation(inputVolume_list, do_affinereg, input_is_bet, task_dir, tmp_path_in, tmp_path_out, python_executable)

Run the segmentation model using the provided input volumes and parameters.

Parameters:

• inputVolume_list – list of volumes passed as input to the model

• do_affinereg – whether to register input volumes to template image

• input_is_bet – whether to register input volumes to template image

• task_dir – path to the task directory that contains the segmentation model

• tmp_path_in – path to the temporary input directory

• tmp_path_out – path to the temporary output directory

• python_executable – path to python executable (for example a virtual environment)

utils.rano_utils.sphere_opening(seg, labels, radius)

Given a segmentation, this function performs a sphere opening operation on the specified labels. The opening operation is performed in 3 steps: 1. A mask is created as the union of the specified labels 2. The distance map of the mask is calculated and used to threshold the mask such that only the pixels that are at least radius away from the boundary of the mask are kept. This mask corresponds to the valid centers of the structuring element (the sphere). 3. The mask is dilated by the structuring element (the sphere) to get the final segmentation (the sphere opened mask).

Parameters:

• seg – a 3D numpy array where background is 0 and foreground is > 0

• labels – list of labels to combine for the sphere opening operation

• radius – the distance from the boundary of the combined labels (corresponds to the radius of the sphere)

Returns:

a 3D numpy array where background is 0 and foreground is 1

Return type:

seg_open

utils.rano_utils.transform_ijk_to_world_coord(ijk, ijkToWorld_matrix)

Given an IJK coordinate and the IJK to world matrix, this function returns the world coordinate

Parameters:

• ijk – the IJK coordinates (x, y, z)

• ijkToWorld_matrix – the IJK to world matrix

Returns:

the world coordinate (x, y, z)

utils.rano_utils.transform_ijk_to_world_coord_np(coord, ijkToWorld_np)

Transform a coordinate from IJK to world space using the ijkToWorld matrix given as a numpy array.

Parameters:

• coord – the IJK coordinates (x, y, z)

• ijkToWorld_np – the IJK to world matrix as a numpy array

Returns:

the world coordinate (x, y, z)

utils.rano_utils.transform_world_to_ijk_coord(world, worldToIJK_matrix)

Given a world coordinate and the world to IJK matrix, this function returns the IJK coordinate

Parameters:

• world – the world coordinates (x, y, z)

• worldToIJK_matrix – the world to IJK matrix

Returns:

the IJK coordinate (x, y, z)