medpy.graphcut.generate.graph_from_labels

medpy.graphcut.generate.graph_from_labels(label_image, fg_markers, bg_markers, regional_term=False, boundary_term=False, regional_term_args=False, boundary_term_args=False)

Create a graph-cut ready graph to segment a nD image using the region neighbourhood.

Create a GraphDouble object for all regions of a nD label image.

Every region of the label image is regarded as a node. They are connected to their immediate neighbours by arcs. If to regions are neighbours is determined using \(ndim*2\)-connectedness (e.g. \(3*2=6\) for 3D). In the next step the arcs weights (n-weights) are computed using the supplied boundary_term function (see energy_voxel for a selection).

Implicitly the graph holds two additional nodes: the source and the sink, so called terminal nodes. These are connected with all other nodes through arcs of an initial weight (t-weight) of zero. All regions that are under the foreground markers are considered to be tightly bound to the source: The t-weight of the arc from source to these nodes is set to a maximum value. The same goes for the background markers: The covered regions receive a maximum (MAX) t-weight for their arc towards the sink.

All other t-weights are set using the supplied regional_term function (see energy_voxel for a selection).

Parameters:

label_image: ndarray

The label image as an array cwhere each voxel carries the id of the region it belongs to. Note that the region labels have to start from 1 and be continuous (can be achieved with relabel).

fg_markersndarray

The foreground markers as binary array of the same shape as the original image.

bg_markersndarray

The background markers as binary array of the same shape as the original image.

regional_termfunction

This can be either False, in which case all t-weights are set to 0, except for the nodes that are directly connected to the source or sink; or a function, in which case the supplied function is used to compute the t_edges. It has to have the following signature regional_term(graph, regional_term_args), and is supposed to compute (source_t_weight, sink_t_weight) for all regions of the image and add these to the passed GCGraph object. The weights have only to be computed for nodes where they do not equal zero. Additional parameters can be passed to the function via the regional_term_args parameter.

boundary_termfunction

This can be either False, in which case all n-edges, i.e. between all nodes that are not source or sink, are set to 0; or a function, in which case the supplied function is used to compute the edge weights. It has to have the following signature boundary_term(graph, boundary_term_args), and is supposed to compute the edges between all adjacent regions of the image and to add them to the supplied GCGraph object. Additional parameters can be passed to the function via the boundary_term_args parameter.

regional_term_argstuple

Use this to pass some additional parameters to the regional_term function.

boundary_term_argstuple

Use this to pass some additional parameters to the boundary_term function.

Returns:

graphGraphDouble

The created graph, ready to execute the graph-cut.

Raises:

AttributeError

If an argument is malformed.

FunctionError

If one of the supplied functions returns unexpected results.

Notes

If a voxel is marked as both, foreground and background, the background marker is given higher priority.

All arcs whose weight is not explicitly set are assumed to carry a weight of zero.