{ "__type": "IngestedDoc", "__tag": 4010, "_content": { "Notes": { "__type": "Section", "__tag": 4015, "children": [ { "__type": "Paragraph", "__tag": 4045, "children": [ { "__type": "Text", "__tag": 4046, "value": "A centrosymmetric matrix is a matrix that is symmetric about the center. See " }, { "__type": "FootnoteReference", "__tag": 4066, "label": "1" }, { "__type": "Text", "__tag": 4046, "value": " for more information." } ] }, { "__type": "Paragraph", "__tag": 4045, "children": [ { "__type": "Text", "__tag": 4046, "value": "The " }, { "__type": "ParamRef", "__tag": 4071, "name": "structure" }, { "__type": "Text", "__tag": 4046, "value": " matrix must be centrosymmetric to ensure two-way connections. For instance, if the " }, { "__type": "ParamRef", "__tag": 4071, "name": "structure" }, { "__type": "Text", "__tag": 4046, "value": " matrix is not centrosymmetric and is defined as " } ] }, { "__type": "Code", "__tag": 4050, "value": "[[0,1,0],\n [1,1,0],\n [0,0,0]]", "execution_status": null }, { "__type": "Paragraph", "__tag": 4045, "children": [ { "__type": "Text", "__tag": 4046, "value": "and the " }, { "__type": "ParamRef", "__tag": 4071, "name": "input" }, { "__type": "Text", "__tag": 4046, "value": " is " } ] }, { "__type": "Code", "__tag": 4050, "value": "[[1,2],\n [0,3]]", "execution_status": null }, { "__type": "Paragraph", "__tag": 4045, "children": [ { "__type": "Text", "__tag": 4046, "value": "then the structure matrix would indicate the entry 2 in the input is connected to 1, but 1 is not connected to 2." } ] }, { "__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": "CrossRef", "__tag": 4002, "value": "label", "reference": { "__type": "RefInfo", "__tag": 4000, "module": null, "version": null, "kind": "local", "path": "label" }, "kind": "local" }, { "__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": "label", "annotation": "ndarray or int", "desc": [ { "__type": "Paragraph", "__tag": 4045, "children": [ { "__type": "Text", "__tag": 4046, "value": "An integer ndarray where each unique feature in " }, { "__type": "ParamRef", "__tag": 4071, "name": "input" }, { "__type": "Text", "__tag": 4046, "value": " has a unique label in the returned array." } ] } ] }, { "__type": "DocParam", "__tag": 4016, "name": "num_features", "annotation": "int", "desc": [ { "__type": "Paragraph", "__tag": 4045, "children": [ { "__type": "Text", "__tag": 4046, "value": "How many objects were found." } ] }, { "__type": "Paragraph", "__tag": 4045, "children": [ { "__type": "Text", "__tag": 4046, "value": "If " }, { "__type": "ParamRef", "__tag": 4071, "name": "output" }, { "__type": "Text", "__tag": 4046, "value": " is None, this function returns a tuple of (" }, { "__type": "InlineRole", "__tag": 4003, "value": "labeled_array", "domain": null, "role": null, "inventory": null }, { "__type": "Text", "__tag": 4046, "value": ", " }, { "__type": "CrossRef", "__tag": 4002, "value": "num_features", "reference": { "__type": "RefInfo", "__tag": 4000, "module": null, "version": null, "kind": "local", "path": "num_features" }, "kind": "local" }, { "__type": "Text", "__tag": 4046, "value": ")." } ] }, { "__type": "Paragraph", "__tag": 4045, "children": [ { "__type": "Text", "__tag": 4046, "value": "If " }, { "__type": "ParamRef", "__tag": 4071, "name": "output" }, { "__type": "Text", "__tag": 4046, "value": " is a ndarray, then it will be updated with values in " }, { "__type": "InlineRole", "__tag": 4003, "value": "labeled_array", "domain": null, "role": null, "inventory": null }, { "__type": "Text", "__tag": 4046, "value": " and only " }, { "__type": "CrossRef", "__tag": 4002, "value": "num_features", "reference": { "__type": "RefInfo", "__tag": 4000, "module": null, "version": null, "kind": "local", "path": "num_features" }, "kind": "local" }, { "__type": "Text", "__tag": 4046, "value": " will be returned by this function." } ] } ] } ] } ], "title": [], "level": 0, "target": null }, "Summary": { "__type": "Section", "__tag": 4015, "children": [ { "__type": "Paragraph", "__tag": 4045, "children": [ { "__type": "Text", "__tag": 4046, "value": "Label features in an array." } ] } ], "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": "An array-like object to be labeled. Any non-zero values in " }, { "__type": "ParamRef", "__tag": 4071, "name": "input" }, { "__type": "Text", "__tag": 4046, "value": " are counted as features and zero values are considered the background." } ] } ] }, { "__type": "DocParam", "__tag": 4016, "name": "structure", "annotation": "array_like, optional", "desc": [ { "__type": "Paragraph", "__tag": 4045, "children": [ { "__type": "Text", "__tag": 4046, "value": "A structuring element that defines feature connections. " }, { "__type": "ParamRef", "__tag": 4071, "name": "structure" }, { "__type": "Text", "__tag": 4046, "value": " must be centrosymmetric (see Notes). If no structuring element is provided, one is automatically generated with a squared connectivity equal to one. That is, for a 2-D " }, { "__type": "ParamRef", "__tag": 4071, "name": "input" }, { "__type": "Text", "__tag": 4046, "value": " array, the default structuring element is " } ] }, { "__type": "Code", "__tag": 4050, "value": "[[0,1,0],\n [1,1,1],\n [0,1,0]]", "execution_status": null } ] }, { "__type": "DocParam", "__tag": 4016, "name": "output", "annotation": "(None, data-type, array_like), optional", "desc": [ { "__type": "Paragraph", "__tag": 4045, "children": [ { "__type": "Text", "__tag": 4046, "value": "If " }, { "__type": "ParamRef", "__tag": 4071, "name": "output" }, { "__type": "Text", "__tag": 4046, "value": " is a data type, it specifies the type of the resulting labeled feature array. If " }, { "__type": "ParamRef", "__tag": 4071, "name": "output" }, { "__type": "Text", "__tag": 4046, "value": " is an array-like object, then " }, { "__type": "ParamRef", "__tag": 4071, "name": "output" }, { "__type": "Text", "__tag": 4046, "value": " will be updated with the labeled features from this function. This function can operate in-place, by passing output=input. Note that the output must be able to store the largest label, or this function will raise an Exception." } ] } ] } ] } ], "title": [], "level": 0, "target": null }, "Extended Summary": { "__type": "Section", "__tag": 4015, "children": [], "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/_measurements.py", "item_line": 43, "item_type": "function", "aliases": [ "scipy.ndimage.label" ], "example_section_data": { "__type": "Section", "__tag": 4015, "children": [ { "__type": "Text", "__tag": 4046, "value": "Create an image with some features, then label it using the default\n(cross-shaped) structuring element:\n\n" }, { "__type": "Code", "__tag": 4050, "value": "from scipy.ndimage import label, generate_binary_structure\nimport numpy as np\na = np.array([[0,0,1,1,0,0],\n [0,0,0,1,0,0],\n [1,1,0,0,1,0],\n [0,0,0,1,0,0]])\nlabeled_array, num_features = label(a)\n", "execution_status": "success" }, { "__type": "Text", "__tag": 4046, "value": "\nEach of the 4 features are labeled with a different integer:\n\n" }, { "__type": "Code", "__tag": 4050, "value": "num_features\nlabeled_array\n", "execution_status": "success" }, { "__type": "Text", "__tag": 4046, "value": "\nGenerate a structuring element that will consider features connected even\nif they touch diagonally:\n\n" }, { "__type": "Code", "__tag": 4050, "value": "s = generate_binary_structure(2,2)\n", "execution_status": "success" }, { "__type": "Text", "__tag": 4046, "value": "\nor,\n\n" }, { "__type": "Code", "__tag": 4050, "value": "s = [[1,1,1],\n [1,1,1],\n [1,1,1]]\n", "execution_status": "success" }, { "__type": "Text", "__tag": 4046, "value": "\nLabel the image using the new structuring element:\n\n" }, { "__type": "Code", "__tag": 4050, "value": "labeled_array, num_features = label(a, structure=s)\n", "execution_status": "success" }, { "__type": "Text", "__tag": 4046, "value": "\nShow the 2 labeled features (note that features 1, 3, and 4 from above are\nnow considered a single feature):\n\n" }, { "__type": "Code", "__tag": 4050, "value": "num_features\nlabeled_array\n", "execution_status": "success" } ], "title": [], "level": 0, "target": null }, "see_also": [ { "__type": "SeeAlsoItem", "__tag": 4028, "name": { "__type": "CrossRef", "__tag": 4002, "value": "find_objects", "reference": { "__type": "RefInfo", "__tag": 4000, "module": "current-module", "version": "current-version", "kind": "to-resolve", "path": "find_objects" }, "kind": "module" }, "descriptions": [ { "__type": "Paragraph", "__tag": 4045, "children": [ { "__type": "Text", "__tag": 4046, "value": "generate a list of slices for the labeled features (or objects); useful for finding features' position or dimensions" } ] } ], "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": "structure", "annotation": { "__type": "Empty", "__tag": 4031 }, "kind": "POSITIONAL_OR_KEYWORD", "default": "None" }, { "__type": "SigParam", "__tag": 4030, "name": "output", "annotation": { "__type": "Empty", "__tag": 4031 }, "kind": "POSITIONAL_OR_KEYWORD", "default": "None" } ], "return_annotation": { "__type": "Empty", "__tag": 4031 }, "target_name": "label" }, "references": [ ".. [1] James R. Weaver, \"Centrosymmetric (cross-symmetric)", " matrices, their basic properties, eigenvalues, and", " eigenvectors.\" The American Mathematical Monthly 92.10", " (1985): 711-717." ], "qa": "scipy.ndimage._measurements:label", "arbitrary": [], "local_refs": [ "input", "label", "num_features", "output", "structure" ] }