segmentationmetrics.surface_distance package

Submodules

segmentationmetrics.surface_distance.lookup_tables module

Lookup tables used by surface distance metrics.

segmentationmetrics.surface_distance.lookup_tables.create_table_neighbour_code_to_contour_length(spacing_mm)[source]

Returns an array mapping neighbourhood code to the contour length.

For the list of possible cases and their figures, see page 38 from: https://nccastaff.bournemouth.ac.uk/jmacey/MastersProjects/MSc14/06/thesis.pdf

In 2D, each point has 4 neighbors. Thus, are 16 configurations. A configuration is encoded with ‘1’ meaning “inside the object” and ‘0’ “outside the object”. The points are ordered: top left, top right, bottom left, bottom right.

The x0 axis is assumed vertical downward, and the x1 axis is horizontal to the right:

(0, 0) –> (0, 1)

(1, 0)

Parameters:

spacing_mm – 2-element list-like structure. Voxel spacing in x0 and x1 directions.

segmentationmetrics.surface_distance.lookup_tables.create_table_neighbour_code_to_surface_area(spacing_mm)[source]

Returns an array mapping neighbourhood code to the surface elements area.

Note that the normals encode the initial surface area. This function computes the area corresponding to the given spacing_mm.

Parameters:

spacing_mm – 3-element list-like structure. Voxel spacing in x0, x1 and x2 direction.

segmentationmetrics.surface_distance.metrics module

Module exposing surface distance based measures.

segmentationmetrics.surface_distance.metrics.compute_average_surface_distance(surface_distances)[source]

Returns the average surface distance.

Computes the average surface distances by correctly taking the area of each surface element into account. Call compute_surface_distances(…) before, to obtain the surface_distances dict.

Parameters:

  • surface_distances – dict with “distances_gt_to_pred”, “distances_pred_to_gt”

  • "surfel_areas_gt"

  • by ("surfel_areas_pred" created)

  • compute_surface_distances()

Returns:

  • the average distance (in mm) from the ground truth surface to the predicted surface

  • the average distance from the predicted surface to the ground truth surface.

Return type:

A tuple with two float values

segmentationmetrics.surface_distance.metrics.compute_dice_coefficient(mask_gt, mask_pred)[source]

Computes soerensen-dice coefficient.

compute the soerensen-dice coefficient between the ground truth mask mask_gt and the predicted mask mask_pred.

Parameters:

  • mask_gt – 3-dim Numpy array of type bool. The ground truth mask.

  • mask_pred – 3-dim Numpy array of type bool. The predicted mask.

Returns:

the dice coeffcient as float. If both masks are empty, the result is NaN.

segmentationmetrics.surface_distance.metrics.compute_robust_hausdorff(surface_distances, percent)[source]

Computes the robust Hausdorff distance.

Computes the robust Hausdorff distance. “Robust”, because it uses the percent percentile of the distances instead of the maximum distance. The percentage is computed by correctly taking the area of each surface element into account.

Parameters:

  • surface_distances – dict with “distances_gt_to_pred”, “distances_pred_to_gt” “surfel_areas_gt”, “surfel_areas_pred” created by compute_surface_distances()

  • percent – a float value between 0 and 100.

Returns:

a float value. The robust Hausdorff distance in mm.

segmentationmetrics.surface_distance.metrics.compute_surface_dice_at_tolerance(surface_distances, tolerance_mm)[source]

Computes the _surface_ DICE coefficient at a specified tolerance.

Computes the _surface_ DICE coefficient at a specified tolerance. Not to be confused with the standard _volumetric_ DICE coefficient. The surface DICE measures the overlap of two surfaces instead of two volumes. A surface element is counted as overlapping (or touching), when the closest distance to the other surface is less or equal to the specified tolerance. The DICE coefficient is in the range between 0.0 (no overlap) to 1.0 (perfect overlap).

Parameters:

  • surface_distances – dict with “distances_gt_to_pred”, “distances_pred_to_gt” “surfel_areas_gt”, “surfel_areas_pred” created by compute_surface_distances()

  • tolerance_mm – a float value. The tolerance in mm

Returns:

A float value. The surface DICE coefficient in [0.0, 1.0].

segmentationmetrics.surface_distance.metrics.compute_surface_distances(mask_gt, mask_pred, spacing_mm)[source]

Computes closest distances from all surface points to the other surface.

This function can be applied to 2D or 3D tensors. For 2D, both masks must be 2D and spacing_mm must be a 2-element list. For 3D, both masks must be 3D and spacing_mm must be a 3-element list. The description is done for the 2D case, and the formulation for the 3D case is present is parenthesis, introduced by “resp.”.

Finds all contour elements (resp surface elements “surfels” in 3D) in the ground truth mask mask_gt and the predicted mask mask_pred, computes their length in mm (resp. area in mm^2) and the distance to the closest point on the other contour (resp. surface). It returns two sorted lists of distances together with the corresponding contour lengths (resp. surfel areas). If one of the masks is empty, the corresponding lists are empty and all distances in the other list are inf.

Parameters:

  • mask_gt – 2-dim (resp. 3-dim) bool Numpy array. The ground truth mask.

  • mask_pred – 2-dim (resp. 3-dim) bool Numpy array. The predicted mask.

  • spacing_mm – 2-element (resp. 3-element) list-like structure. Voxel spacing in x0 anx x1 (resp. x0, x1 and x2) directions.

Returns:

“distances_gt_to_pred”: 1-dim numpy array of type float. The distances in mm

from all ground truth surface elements to the predicted surface, sorted from smallest to largest.

”distances_pred_to_gt”: 1-dim numpy array of type float. The distances in mm

from all predicted surface elements to the ground truth surface, sorted from smallest to largest.

”surfel_areas_gt”: 1-dim numpy array of type float. The length of the

of the ground truth contours in mm (resp. the surface elements area in mm^2) in the same order as distances_gt_to_pred.

”surfel_areas_pred”: 1-dim numpy array of type float. The length of the

of the predicted contours in mm (resp. the surface elements area in mm^2) in the same order as distances_gt_to_pred.

Return type:

A dict with

Raises:

ValueError – If the masks and the spacing_mm arguments are of incompatible shape or type. Or if the masks are not 2D or 3D.

segmentationmetrics.surface_distance.metrics.compute_surface_overlap_at_tolerance(surface_distances, tolerance_mm)[source]

Computes the overlap of the surfaces at a specified tolerance.

Computes the overlap of the ground truth surface with the predicted surface and vice versa allowing a specified tolerance (maximum surface-to-surface distance that is regarded as overlapping). The overlapping fraction is computed by correctly taking the area of each surface element into account.

Parameters:

  • surface_distances – dict with “distances_gt_to_pred”, “distances_pred_to_gt” “surfel_areas_gt”, “surfel_areas_pred” created by compute_surface_distances()

  • tolerance_mm – a float value. The tolerance in mm

Returns:

A tuple of two float values. The overlap fraction in [0.0, 1.0] of the ground truth surface with the predicted surface and vice versa.

Module contents

Surface distance module: https://github.com/deepmind/surface-distance .