`skimage.morphology.footprints:disk`

source: /dev/scikit-image/src/skimage/morphology/footprints.py :487

Signature

   def     disk (    radius    ,    dtype    =  <class 'numpy.uint8'>   ,  * ,     strict_radius    =  True   ,    decomposition    =  None     )

Summary

Generates a flat, disk-shaped footprint.

Extended Summary

A pixel is within the neighborhood if the Euclidean distance between it and the origin is no greater than radius (This is only approximately True, when decomposition == 'sequence').

Parameters

radius : int: The radius of the disk-shaped footprint.

Returns

footprint : ndarray: The footprint where elements of the neighborhood are 1 and 0 otherwise.

Other Parameters

dtype : dtype-like, optional: The data type of the footprint.
strict_radius : bool, optional: If False, extend the radius by 0.5. This allows the circle to expand further within a cube that remains of size 2 * radius + 1 along each axis. This parameter is ignored if decomposition is not None.
decomposition : {None, 'sequence', 'crosses'}, optional: If None, a single array is returned. For 'sequence', a tuple of smaller footprints is returned. Applying this series of smaller footprints will given a result equivalent to a single, larger footprint, but with better computational performance. For disk footprints, the 'sequence' or 'crosses' decompositions are not always exactly equivalent to decomposition=None. See Notes for more details.

Notes

When decomposition is not None, each element of the footprint tuple is a 2-tuple of the form (ndarray, num_iter) that specifies a footprint array and the number of iterations it is to be applied.

The disk produced by the decomposition='sequence' mode may not be identical to that with decomposition=None. A disk footprint can be approximated by applying a series of smaller footprints of extent 3 along each axis. Specific solutions for this are given in ^[1] for the case of 2D disks with radius 2 through 10. Here, we numerically computed the number of repetitions of each element that gives the closest match to the disk computed with kwargs strict_radius=False, decomposition=None.

Empirically, the series decomposition at large radius approaches a hexadecagon (a 16-sided polygon ^[2]). In ^[3], the authors demonstrate that a hexadecagon is the closest approximation to a disk that can be achieved for decomposition with footprints of shape (3, 3).

The disk produced by the decomposition='crosses' is often but not always identical to that with decomposition=None. It tends to give a closer approximation than decomposition='sequence', at a performance that is fairly comparable. The individual cross-shaped elements are not limited to extent (3, 3) in size. Unlike the 'seqeuence' decomposition, the 'crosses' decomposition can also accurately approximate the shape of disks with strict_radius=True. The method is based on an adaption of algorithm 1 given in ^[4].

Aliases

skimage.morphology.disk