{ "__type": "IngestedDoc", "__tag": 4010, "_content": { "Notes": { "__type": "Section", "__tag": 4015, "children": [ { "__type": "Paragraph", "__tag": 4045, "children": [ { "__type": "Text", "__tag": 4046, "value": "This function employs a slow brute force algorithm. See also the function " }, { "__type": "CrossRef", "__tag": 4002, "value": "distance_transform_cdt", "reference": { "__type": "LocalRef", "__tag": 4022, "kind": "module", "path": "scipy.ndimage._morphology:distance_transform_cdt" }, "kind": "module" }, { "__type": "Text", "__tag": 4046, "value": " for more efficient taxicab " }, { "__type": "FootnoteReference", "__tag": 4066, "label": "1" }, { "__type": "Text", "__tag": 4046, "value": " and chessboard algorithms " }, { "__type": "FootnoteReference", "__tag": 4066, "label": "2" }, { "__type": "Text", "__tag": 4046, "value": "." } ] }, { "__type": "Paragraph", "__tag": 4045, "children": [ { "__type": "Strong", "__tag": 4048, "children": [ { "__type": "Text", "__tag": 4046, "value": "Array API Standard Support" } ] } ] }, { "__type": "Paragraph", "__tag": 4045, "children": [ { "__type": "InlineRole", "__tag": 4003, "value": "distance_transform_bf", "domain": null, "role": null, "inventory": null }, { "__type": "Text", "__tag": 4046, "value": " has experimental support for Python Array API Standard compatible backends in addition to NumPy. Please consider testing these features by setting an environment variable " }, { "__type": "InlineCode", "__tag": 4051, "value": "SCIPY_ARRAY_API=1" }, { "__type": "Text", "__tag": 4046, "value": " and providing CuPy, PyTorch, JAX, or Dask arrays as array arguments. The following combinations of backend and device (or other capability) are supported." } ] }, { "__type": "Code", "__tag": 4050, "value": "==================== ==================== ====================\nLibrary CPU GPU\n==================== ==================== ====================\nNumPy ✅ n/a \nCuPy n/a ⛔ \nPyTorch ✅ ⛔ \nJAX ⚠️ no JIT ⛔ \nDask ⚠️ computes graph n/a \n==================== ==================== ====================", "execution_status": null }, { "__type": "Blockquote", "__tag": 4059, "children": [ { "__type": "Paragraph", "__tag": 4045, "children": [ { "__type": "Text", "__tag": 4046, "value": "See " }, { "__type": "InlineRole", "__tag": 4003, "value": "dev-arrayapi", "domain": null, "role": "ref", "inventory": null }, { "__type": "Text", "__tag": 4046, "value": " for more information." } ] } ] } ], "title": [], "level": 0, "target": null }, "Warns": { "__type": "Section", "__tag": 4015, "children": [], "title": [], "level": 0, "target": null }, "Raises": { "__type": "Section", "__tag": 4015, "children": [], "title": [], "level": 0, "target": null }, "Yields": { "__type": "Section", "__tag": 4015, "children": [], "title": [], "level": 0, "target": null }, "Methods": { "__type": "Section", "__tag": 4015, "children": [], "title": [], "level": 0, "target": null }, "Returns": { "__type": "Section", "__tag": 4015, "children": [ { "__type": "Parameters", "__tag": 4026, "children": [ { "__type": "DocParam", "__tag": 4016, "name": "distances", "annotation": "ndarray, optional", "desc": [ { "__type": "Paragraph", "__tag": 4045, "children": [ { "__type": "Text", "__tag": 4046, "value": "The calculated distance transform. Returned only when " }, { "__type": "ParamRef", "__tag": 4071, "name": "return_distances" }, { "__type": "Text", "__tag": 4046, "value": " is True and " }, { "__type": "ParamRef", "__tag": 4071, "name": "distances" }, { "__type": "Text", "__tag": 4046, "value": " is not supplied. It will have the same shape as the input array." } ] } ] }, { "__type": "DocParam", "__tag": 4016, "name": "indices", "annotation": "int32 ndarray, optional", "desc": [ { "__type": "Paragraph", "__tag": 4045, "children": [ { "__type": "Text", "__tag": 4046, "value": "The calculated feature transform. It has an input-shaped array for each dimension of the input. See distance_transform_edt documentation for an example. Returned only when " }, { "__type": "ParamRef", "__tag": 4071, "name": "return_indices" }, { "__type": "Text", "__tag": 4046, "value": " is True and " }, { "__type": "ParamRef", "__tag": 4071, "name": "indices" }, { "__type": "Text", "__tag": 4046, "value": " is not supplied." } ] } ] } ] } ], "title": [], "level": 0, "target": null }, "Summary": { "__type": "Section", "__tag": 4015, "children": [ { "__type": "Paragraph", "__tag": 4045, "children": [ { "__type": "Text", "__tag": 4046, "value": "Distance transform function by a brute force algorithm." } ] } ], "title": [], "level": 0, "target": null }, "Receives": { "__type": "Section", "__tag": 4015, "children": [], "title": [], "level": 0, "target": null }, "Warnings": { "__type": "Section", "__tag": 4015, "children": [], "title": [], "level": 0, "target": null }, "Attributes": { "__type": "Section", "__tag": 4015, "children": [], "title": [], "level": 0, "target": null }, "Parameters": { "__type": "Section", "__tag": 4015, "children": [ { "__type": "Parameters", "__tag": 4026, "children": [ { "__type": "DocParam", "__tag": 4016, "name": "input", "annotation": "array_like", "desc": [ { "__type": "Paragraph", "__tag": 4045, "children": [ { "__type": "Text", "__tag": 4046, "value": "Input" } ] } ] }, { "__type": "DocParam", "__tag": 4016, "name": "metric", "annotation": "{'euclidean', 'taxicab', 'chessboard'}, optional", "desc": [ { "__type": "Paragraph", "__tag": 4045, "children": [ { "__type": "Text", "__tag": 4046, "value": "'cityblock' and 'manhattan' are also valid, and map to 'taxicab'. The default is 'euclidean'." } ] } ] }, { "__type": "DocParam", "__tag": 4016, "name": "sampling", "annotation": "float, or sequence of float, optional", "desc": [ { "__type": "Paragraph", "__tag": 4045, "children": [ { "__type": "Text", "__tag": 4046, "value": "This parameter is only used when " }, { "__type": "ParamRef", "__tag": 4071, "name": "metric" }, { "__type": "Text", "__tag": 4046, "value": " is 'euclidean'. Spacing of elements along each dimension. If a sequence, must be of length equal to the input rank; if a single number, this is used for all axes. If not specified, a grid spacing of unity is implied." } ] } ] }, { "__type": "DocParam", "__tag": 4016, "name": "return_distances", "annotation": "bool, optional", "desc": [ { "__type": "Paragraph", "__tag": 4045, "children": [ { "__type": "Text", "__tag": 4046, "value": "Whether to calculate the distance transform. Default is True." } ] } ] }, { "__type": "DocParam", "__tag": 4016, "name": "return_indices", "annotation": "bool, optional", "desc": [ { "__type": "Paragraph", "__tag": 4045, "children": [ { "__type": "Text", "__tag": 4046, "value": "Whether to calculate the feature transform. Default is False." } ] } ] }, { "__type": "DocParam", "__tag": 4016, "name": "distances", "annotation": "ndarray, optional", "desc": [ { "__type": "Paragraph", "__tag": 4045, "children": [ { "__type": "Text", "__tag": 4046, "value": "An output array to store the calculated distance transform, instead of returning it. " }, { "__type": "ParamRef", "__tag": 4071, "name": "return_distances" }, { "__type": "Text", "__tag": 4046, "value": " must be True. It must be the same shape as " }, { "__type": "ParamRef", "__tag": 4071, "name": "input" }, { "__type": "Text", "__tag": 4046, "value": ", and of type float64 if " }, { "__type": "ParamRef", "__tag": 4071, "name": "metric" }, { "__type": "Text", "__tag": 4046, "value": " is 'euclidean', uint32 otherwise." } ] } ] }, { "__type": "DocParam", "__tag": 4016, "name": "indices", "annotation": "int32 ndarray, optional", "desc": [ { "__type": "Paragraph", "__tag": 4045, "children": [ { "__type": "Text", "__tag": 4046, "value": "An output array to store the calculated feature transform, instead of returning it. " }, { "__type": "InlineRole", "__tag": 4003, "value": "return_indicies", "domain": null, "role": null, "inventory": null }, { "__type": "Text", "__tag": 4046, "value": " must be True. Its shape must be " }, { "__type": "InlineCode", "__tag": 4051, "value": "(input.ndim,) + input.shape" }, { "__type": "Text", "__tag": 4046, "value": "." } ] } ] } ] } ], "title": [], "level": 0, "target": null }, "Extended Summary": { "__type": "Section", "__tag": 4015, "children": [ { "__type": "Paragraph", "__tag": 4045, "children": [ { "__type": "Text", "__tag": 4046, "value": "This function calculates the distance transform of the " }, { "__type": "ParamRef", "__tag": 4071, "name": "input" }, { "__type": "Text", "__tag": 4046, "value": ", by replacing each foreground (non-zero) element, with its shortest distance to the background (any zero-valued element)." } ] }, { "__type": "Paragraph", "__tag": 4045, "children": [ { "__type": "Text", "__tag": 4046, "value": "In addition to the distance transform, the feature transform can be calculated. In this case the index of the closest background element to each foreground element is returned in a separate array." } ] } ], "title": [], "level": 0, "target": null }, "Other Parameters": { "__type": "Section", "__tag": 4015, "children": [], "title": [], "level": 0, "target": null } }, "_ordered_sections": [ "Summary", "Extended Summary", "Parameters", "Attributes", "Methods", "Returns", "Yields", "Receives", "Other Parameters", "Raises", "Warns", "Warnings", "Notes" ], "item_file": "/scipy/ndimage/_morphology.py", "item_line": 1987, "item_type": "function", "aliases": [ "scipy.ndimage.distance_transform_bf" ], "example_section_data": { "__type": "Section", "__tag": 4015, "children": [ { "__type": "Text", "__tag": 4046, "value": "Import the necessary modules.\n\n" }, { "__type": "Code", "__tag": 4050, "value": "import numpy as np\nfrom scipy.ndimage import distance_transform_bf\nimport matplotlib.pyplot as plt\nfrom mpl_toolkits.axes_grid1 import ImageGrid\n", "execution_status": "success" }, { "__type": "Text", "__tag": 4046, "value": "\nFirst, we create a toy binary image.\n\n" }, { "__type": "Code", "__tag": 4050, "value": "def add_circle(center_x, center_y, radius, image, fillvalue=1):\n # fill circular area with 1\n xx, yy = np.mgrid[:image.shape[0], :image.shape[1]]\n circle = (xx - center_x) ** 2 + (yy - center_y) ** 2\n circle_shape = np.sqrt(circle) < radius\n image[circle_shape] = fillvalue\n return image\nimage = np.zeros((100, 100), dtype=np.uint8)\nimage[35:65, 20:80] = 1\nimage = add_circle(28, 65, 10, image)\nimage = add_circle(37, 30, 10, image)\nimage = add_circle(70, 45, 20, image)\nimage = add_circle(45, 80, 10, image)\n", "execution_status": "success" }, { "__type": "Text", "__tag": 4046, "value": "\nNext, we set up the figure.\n\n" }, { "__type": "Code", "__tag": 4050, "value": "fig = plt.figure(figsize=(8, 8)) # set up the figure structure\ngrid = ImageGrid(fig, 111, nrows_ncols=(2, 2), axes_pad=(0.4, 0.3),\n label_mode=\"1\", share_all=True,\n cbar_location=\"right\", cbar_mode=\"each\",\n cbar_size=\"7%\", cbar_pad=\"2%\")\n", "execution_status": "success" }, { "__type": "Code", "__tag": 4050, "value": "for ax in grid:\n ax.axis('off') # remove axes from images\n", "execution_status": "failure" }, { "__type": "Text", "__tag": 4046, "value": "\nThe top left image is the original binary image.\n\n" }, { "__type": "Code", "__tag": 4050, "value": "binary_image = grid[0].imshow(image, cmap='gray')\ncbar_binary_image = grid.cbar_axes[0].colorbar(binary_image)\ncbar_binary_image.set_ticks([0, 1])\n", "execution_status": "success" }, { "__type": "Code", "__tag": 4050, "value": "grid[0].set_title(\"Binary image: foreground in white\")\n", "execution_status": "failure" }, { "__type": "Text", "__tag": 4046, "value": "\nThe distance transform calculates the distance between foreground pixels\nand the image background according to a distance metric. Available metrics\nin `distance_transform_bf` are: ``euclidean`` (default), ``taxicab``\nand ``chessboard``. The top right image contains the distance transform\nbased on the ``euclidean`` metric.\n\n" }, { "__type": "Code", "__tag": 4050, "value": "distance_transform_euclidean = distance_transform_bf(image)\neuclidean_transform = grid[1].imshow(distance_transform_euclidean,\n cmap='gray')\ncbar_euclidean = grid.cbar_axes[1].colorbar(euclidean_transform)\ncolorbar_ticks = [0, 10, 20]\ncbar_euclidean.set_ticks(colorbar_ticks)\n", "execution_status": "success" }, { "__type": "Code", "__tag": 4050, "value": "grid[1].set_title(\"Euclidean distance\")\n", "execution_status": "failure" }, { "__type": "Text", "__tag": 4046, "value": "\nThe lower left image contains the distance transform using the ``taxicab``\nmetric.\n\n" }, { "__type": "Code", "__tag": 4050, "value": "distance_transform_taxicab = distance_transform_bf(image,\n metric='taxicab')\ntaxicab_transformation = grid[2].imshow(distance_transform_taxicab,\n cmap='gray')\ncbar_taxicab = grid.cbar_axes[2].colorbar(taxicab_transformation)\ncbar_taxicab.set_ticks(colorbar_ticks)\n", "execution_status": "success" }, { "__type": "Code", "__tag": 4050, "value": "grid[2].set_title(\"Taxicab distance\")\n", "execution_status": "failure" }, { "__type": "Text", "__tag": 4046, "value": "\nFinally, the lower right image contains the distance transform using the\n``chessboard`` metric.\n\n" }, { "__type": "Code", "__tag": 4050, "value": "distance_transform_cb = distance_transform_bf(image,\n metric='chessboard')\nchessboard_transformation = grid[3].imshow(distance_transform_cb,\n cmap='gray')\ncbar_taxicab = grid.cbar_axes[3].colorbar(chessboard_transformation)\ncbar_taxicab.set_ticks(colorbar_ticks)\n", "execution_status": "success" }, { "__type": "Code", "__tag": 4050, "value": "grid[3].set_title(\"Chessboard distance\")\n", "execution_status": "failure" }, { "__type": "Code", "__tag": 4050, "value": "plt.show()\n", "execution_status": "success" }, { "__type": "Figure", "__tag": 4024, "value": { "__type": "RefInfo", "__tag": 4000, "module": "scipy", "version": "1.17.1", "kind": "assets", "path": "fig-b65e1bf8eccb13b7.png" } } ], "title": [], "level": 0, "target": null }, "see_also": [ { "__type": "SeeAlsoItem", "__tag": 4028, "name": { "__type": "CrossRef", "__tag": 4002, "value": "distance_transform_cdt", "reference": { "__type": "LocalRef", "__tag": 4022, "kind": "module", "path": "scipy.ndimage._morphology:distance_transform_cdt" }, "kind": "module" }, "descriptions": [ { "__type": "Paragraph", "__tag": 4045, "children": [ { "__type": "Text", "__tag": 4046, "value": "Faster distance transform for taxicab and chessboard metrics" } ] } ], "type": "func" }, { "__type": "SeeAlsoItem", "__tag": 4028, "name": { "__type": "CrossRef", "__tag": 4002, "value": "distance_transform_edt", "reference": { "__type": "LocalRef", "__tag": 4022, "kind": "module", "path": "scipy.ndimage._morphology:distance_transform_edt" }, "kind": "module" }, "descriptions": [ { "__type": "Paragraph", "__tag": 4045, "children": [ { "__type": "Text", "__tag": 4046, "value": "Faster distance transform for euclidean metric" } ] } ], "type": "func" } ], "signature": { "__type": "SignatureNode", "__tag": 4029, "kind": "function", "parameters": [ { "__type": "SigParam", "__tag": 4030, "name": "input", "annotation": { "__type": "Empty", "__tag": 4031 }, "kind": "POSITIONAL_OR_KEYWORD", "default": { "__type": "Empty", "__tag": 4031 } }, { "__type": "SigParam", "__tag": 4030, "name": "metric", "annotation": { "__type": "Empty", "__tag": 4031 }, "kind": "POSITIONAL_OR_KEYWORD", "default": "euclidean" }, { "__type": "SigParam", "__tag": 4030, "name": "sampling", "annotation": { "__type": "Empty", "__tag": 4031 }, "kind": "POSITIONAL_OR_KEYWORD", "default": "None" }, { "__type": "SigParam", "__tag": 4030, "name": "return_distances", "annotation": { "__type": "Empty", "__tag": 4031 }, "kind": "POSITIONAL_OR_KEYWORD", "default": "True" }, { "__type": "SigParam", "__tag": 4030, "name": "return_indices", "annotation": { "__type": "Empty", "__tag": 4031 }, "kind": "POSITIONAL_OR_KEYWORD", "default": "False" }, { "__type": "SigParam", "__tag": 4030, "name": "distances", "annotation": { "__type": "Empty", "__tag": 4031 }, "kind": "POSITIONAL_OR_KEYWORD", "default": "None" }, { "__type": "SigParam", "__tag": 4030, "name": "indices", "annotation": { "__type": "Empty", "__tag": 4031 }, "kind": "POSITIONAL_OR_KEYWORD", "default": "None" } ], "return_annotation": { "__type": "Empty", "__tag": 4031 }, "target_name": "distance_transform_bf" }, "references": [ ".. [1] Taxicab distance. Wikipedia, 2023.", " https://en.wikipedia.org/wiki/Taxicab_geometry", ".. [2] Chessboard distance. Wikipedia, 2023.", " https://en.wikipedia.org/wiki/Chebyshev_distance" ], "qa": "scipy.ndimage._morphology:distance_transform_bf", "arbitrary": [], "local_refs": [ "distances", "indices", "input", "metric", "return_distances", "return_indices", "sampling" ] }