{ "__type": "IngestedDoc", "__tag": 4010, "_content": { "Notes": { "__type": "Section", "__tag": 4015, "children": [ { "__type": "Paragraph", "__tag": 4045, "children": [ { "__type": "Text", "__tag": 4046, "value": "This implementation assumes that dark pixels correspond to the background. If you have a bright background, invert the image before passing it to this function, e.g., using " }, { "__type": "CrossRef", "__tag": 4002, "value": "skimage.util.invert", "reference": { "__type": "RefInfo", "__tag": 4000, "module": "skimage", "version": "*", "kind": "api", "path": "skimage.util._invert:invert" }, "kind": "module" }, { "__type": "Text", "__tag": 4046, "value": "." } ] }, { "__type": "Paragraph", "__tag": 4045, "children": [ { "__type": "Text", "__tag": 4046, "value": "For this method to give meaningful results, the radius of the ball (or typical size of the kernel, in the general case) should be larger than the typical size of the image features of interest." } ] }, { "__type": "Paragraph", "__tag": 4045, "children": [ { "__type": "Text", "__tag": 4046, "value": "This algorithm is sensitive to noise (in particular salt-and-pepper noise). If this is a problem in your image, you can apply mild Gaussian smoothing before passing the image to this function." } ] }, { "__type": "Paragraph", "__tag": 4045, "children": [ { "__type": "Text", "__tag": 4046, "value": "This algorithm's complexity is polynomial in the radius, with degree equal to the image dimensionality (a 2D image is N^2, a 3D image is N^3, etc.), so it can take a long time as the radius grows beyond 30 or so (" }, { "__type": "FootnoteReference", "__tag": 4066, "label": "2" }, { "__type": "Text", "__tag": 4046, "value": ", " }, { "__type": "FootnoteReference", "__tag": 4066, "label": "3" }, { "__type": "Text", "__tag": 4046, "value": "). It is an exact N-dimensional calculation; if all you need is an approximation, faster options to consider are top-hat filtering " }, { "__type": "FootnoteReference", "__tag": 4066, "label": "4" }, { "__type": "Text", "__tag": 4046, "value": " or downscaling-then-upscaling to reduce the size of the input processed." } ] } ], "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": "background", "annotation": "ndarray", "desc": [ { "__type": "Paragraph", "__tag": 4045, "children": [ { "__type": "Text", "__tag": 4046, "value": "The estimated background of the image." } ] } ] } ] } ], "title": [], "level": 0, "target": null }, "Summary": { "__type": "Section", "__tag": 4015, "children": [ { "__type": "Paragraph", "__tag": 4045, "children": [ { "__type": "Text", "__tag": 4046, "value": "Estimate background intensity using the rolling-ball 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": "image", "annotation": "ndarray", "desc": [ { "__type": "Paragraph", "__tag": 4045, "children": [ { "__type": "Text", "__tag": 4046, "value": "The image to be filtered." } ] } ] }, { "__type": "DocParam", "__tag": 4016, "name": "radius", "annotation": "int, optional", "desc": [ { "__type": "Paragraph", "__tag": 4045, "children": [ { "__type": "Text", "__tag": 4046, "value": "Radius of the ball-shaped kernel to be rolled under the image landscape. Used only if " }, { "__type": "ParamRef", "__tag": 4071, "name": "kernel" }, { "__type": "Text", "__tag": 4046, "value": " is " }, { "__type": "InlineCode", "__tag": 4051, "value": "None" }, { "__type": "Text", "__tag": 4046, "value": "." } ] } ] }, { "__type": "DocParam", "__tag": 4016, "name": "kernel", "annotation": "ndarray, optional", "desc": [ { "__type": "Paragraph", "__tag": 4045, "children": [ { "__type": "Text", "__tag": 4046, "value": "An alternative way to specify the rolling ball, as an arbitrary kernel. It must have the same number of axes as " }, { "__type": "ParamRef", "__tag": 4071, "name": "image" }, { "__type": "Text", "__tag": 4046, "value": "." } ] } ] }, { "__type": "DocParam", "__tag": 4016, "name": "nansafe", "annotation": "bool, optional", "desc": [ { "__type": "Paragraph", "__tag": 4045, "children": [ { "__type": "Text", "__tag": 4046, "value": "If " }, { "__type": "InlineCode", "__tag": 4051, "value": "False" }, { "__type": "Text", "__tag": 4046, "value": " (default), the function assumes that none of the values in " }, { "__type": "ParamRef", "__tag": 4071, "name": "image" }, { "__type": "Text", "__tag": 4046, "value": " are " }, { "__type": "InlineCode", "__tag": 4051, "value": "np.nan" }, { "__type": "Text", "__tag": 4046, "value": ", and uses a faster implementation." } ] } ] }, { "__type": "DocParam", "__tag": 4016, "name": "workers", "annotation": "int, optional", "desc": [ { "__type": "Paragraph", "__tag": 4045, "children": [ { "__type": "Text", "__tag": 4046, "value": "The maximum number of threads to use. If " }, { "__type": "InlineCode", "__tag": 4051, "value": "None" }, { "__type": "Text", "__tag": 4046, "value": ", use the OpenMP default value; typically equal to the maximum number of virtual cores. Note: This is an upper limit to the number of threads. The exact number is determined by the system's OpenMP library." } ] }, { "__type": "Admonition", "__tag": 4056, "kind": "versionadded", "base_type": "neutral", "children": [ { "__type": "AdmonitionTitle", "__tag": 4055, "children": [ { "__type": "Text", "__tag": 4046, "value": "versionadded 0.26" } ] }, { "__type": "Paragraph", "__tag": 4045, "children": [ { "__type": "Text", "__tag": 4046, "value": "Replaces deprecated parameter " }, { "__type": "ParamRef", "__tag": 4071, "name": "num_threads" }, { "__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 is a generalization of the rolling-ball algorithm " }, { "__type": "FootnoteReference", "__tag": 4066, "label": "1" }, { "__type": "Text", "__tag": 4046, "value": " to estimate the background intensity of an n-dimensional image. This is typically useful for background subtraction in case of uneven exposure. Think of the image as a landscape (where altitude is determined by intensity), under which a ball of given radius is rolled. At each position, the ball's apex gives the resulting background intensity." } ] } ], "title": [], "level": 0, "target": null }, "Other Parameters": { "__type": "Section", "__tag": 4015, "children": [ { "__type": "Parameters", "__tag": 4026, "children": [ { "__type": "DocParam", "__tag": 4016, "name": "num_threads", "annotation": "DEPRECATED", "desc": [ { "__type": "Paragraph", "__tag": 4045, "children": [ { "__type": "Text", "__tag": 4046, "value": "Deprecated in favor of " }, { "__type": "ParamRef", "__tag": 4071, "name": "workers" }, { "__type": "Text", "__tag": 4046, "value": "." } ] }, { "__type": "Admonition", "__tag": 4056, "kind": "deprecated", "base_type": "neutral", "children": [ { "__type": "AdmonitionTitle", "__tag": 4055, "children": [ { "__type": "Text", "__tag": 4046, "value": "deprecated 0.26" } ] } ] } ] } ] } ], "title": [], "level": 0, "target": null } }, "_ordered_sections": [ "Summary", "Extended Summary", "Parameters", "Returns", "Yields", "Receives", "Raises", "Warns", "Other Parameters", "Attributes", "Methods", "Notes", "Warnings" ], "item_file": "/dev/scikit-image/src/skimage/restoration/_rolling_ball.py", "item_line": 11, "item_type": "function", "aliases": [ "skimage.restoration.rolling_ball" ], "example_section_data": { "__type": "Section", "__tag": 4015, "children": [ { "__type": "Code", "__tag": 4050, "value": "import numpy as np\nimport skimage as ski\nimage = ski.data.coins()\nbackground = ski.restoration.rolling_ball(image)\nfiltered_image = image - background\n", "execution_status": "success" }, { "__type": "Text", "__tag": 4046, "value": "\n" }, { "__type": "Code", "__tag": 4050, "value": "import numpy as np\nimport skimage as ski\nimage = ski.data.coins()\nkernel = ski.restoration.ellipsoid_kernel((101, 101), 75)\nbackground = ski.restoration.rolling_ball(image, kernel=kernel)\nfiltered_image = image - background\n", "execution_status": "success" } ], "title": [], "level": 0, "target": null }, "see_also": [], "signature": { "__type": "SignatureNode", "__tag": 4029, "kind": "function", "parameters": [ { "__type": "SigParam", "__tag": 4030, "name": "image", "annotation": { "__type": "Empty", "__tag": 4031 }, "kind": "POSITIONAL_OR_KEYWORD", "default": { "__type": "Empty", "__tag": 4031 } }, { "__type": "SigParam", "__tag": 4030, "name": "radius", "annotation": { "__type": "Empty", "__tag": 4031 }, "kind": "KEYWORD_ONLY", "default": "100" }, { "__type": "SigParam", "__tag": 4030, "name": "kernel", "annotation": { "__type": "Empty", "__tag": 4031 }, "kind": "KEYWORD_ONLY", "default": "None" }, { "__type": "SigParam", "__tag": 4030, "name": "nansafe", "annotation": { "__type": "Empty", "__tag": 4031 }, "kind": "KEYWORD_ONLY", "default": "False" }, { "__type": "SigParam", "__tag": 4030, "name": "num_threads", "annotation": { "__type": "Empty", "__tag": 4031 }, "kind": "KEYWORD_ONLY", "default": "" }, { "__type": "SigParam", "__tag": 4030, "name": "workers", "annotation": { "__type": "Empty", "__tag": 4031 }, "kind": "KEYWORD_ONLY", "default": "None" } ], "return_annotation": { "__type": "Empty", "__tag": 4031 }, "target_name": "rolling_ball" }, "references": [ ".. [1] Sternberg, Stanley R. \"Biomedical image processing.\" Computer 1", " (1983): 22-34. :DOI:`10.1109/MC.1983.1654163`", ".. [2] https://github.com/scikit-image/scikit-image/issues/5193", ".. [3] https://github.com/scikit-image/scikit-image/issues/7423", ".. [4] https://forum.image.sc/t/59267/7" ], "qa": "skimage.restoration._rolling_ball:rolling_ball", "arbitrary": [], "local_refs": [ "background", "image", "kernel", "nansafe", "num_threads", "radius", "workers" ] }