{ "__type": "IngestedDoc", "__tag": 4010, "_content": { "Notes": { "__type": "Section", "__tag": 4015, "children": [ { "__type": "Paragraph", "__tag": 4045, "children": [ { "__type": "Text", "__tag": 4046, "value": "Make sure to set the " }, { "__type": "ParamRef", "__tag": 4071, "name": "channel_axis" }, { "__type": "Text", "__tag": 4046, "value": " parameter appropriately for color images." } ] }, { "__type": "Paragraph", "__tag": 4045, "children": [ { "__type": "Text", "__tag": 4046, "value": "The principle of total variation denoising is explained in " }, { "__type": "FootnoteReference", "__tag": 4066, "label": "2" }, { "__type": "Text", "__tag": 4046, "value": ". It is about minimizing the total variation of an image, which can be roughly described as the integral of the norm of the image gradient. Total variation denoising tends to produce cartoon-like images, that is, piecewise-constant images." } ] } ], "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": "u", "annotation": "ndarray", "desc": [ { "__type": "Paragraph", "__tag": 4045, "children": [ { "__type": "Text", "__tag": 4046, "value": "Denoised image." } ] } ] } ] } ], "title": [], "level": 0, "target": null }, "Summary": { "__type": "Section", "__tag": 4015, "children": [ { "__type": "Paragraph", "__tag": 4045, "children": [ { "__type": "Text", "__tag": 4046, "value": "Perform total variation denoising in nD." } ] } ], "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": "Input image to be denoised. If its dtype is not float, it gets converted with " }, { "__type": "CrossRef", "__tag": 4002, "value": "img_as_float", "reference": { "__type": "RefInfo", "__tag": 4000, "module": "skimage", "version": "*", "kind": "api", "path": "skimage.util.dtype:img_as_float" }, "kind": "module" }, { "__type": "Text", "__tag": 4046, "value": "." } ] } ] }, { "__type": "DocParam", "__tag": 4016, "name": "weight", "annotation": "float, optional", "desc": [ { "__type": "Paragraph", "__tag": 4045, "children": [ { "__type": "Text", "__tag": 4046, "value": "Denoising weight. It is equal to " }, { "__type": "InlineMath", "__tag": 4057, "value": "\\frac{1}{\\lambda}" }, { "__type": "Text", "__tag": 4046, "value": ". Therefore, the greater the " }, { "__type": "ParamRef", "__tag": 4071, "name": "weight" }, { "__type": "Text", "__tag": 4046, "value": ", the more denoising (at the expense of fidelity to " }, { "__type": "ParamRef", "__tag": 4071, "name": "image" }, { "__type": "Text", "__tag": 4046, "value": ")." } ] } ] }, { "__type": "DocParam", "__tag": 4016, "name": "eps", "annotation": "float, optional", "desc": [ { "__type": "Paragraph", "__tag": 4045, "children": [ { "__type": "Text", "__tag": 4046, "value": "Tolerance " }, { "__type": "InlineMath", "__tag": 4057, "value": "\\varepsilon > 0" }, { "__type": "Text", "__tag": 4046, "value": " for the stop criterion (compares to absolute value of relative difference of the cost function " }, { "__type": "InlineMath", "__tag": 4057, "value": "E" }, { "__type": "Text", "__tag": 4046, "value": "): The algorithm stops when " }, { "__type": "InlineMath", "__tag": 4057, "value": "|E_{n-1} - E_n| < \\varepsilon * E_0" }, { "__type": "Text", "__tag": 4046, "value": "." } ] } ] }, { "__type": "DocParam", "__tag": 4016, "name": "max_num_iter", "annotation": "int, optional", "desc": [ { "__type": "Paragraph", "__tag": 4045, "children": [ { "__type": "Text", "__tag": 4046, "value": "Maximal number of iterations used for the optimization." } ] } ] }, { "__type": "DocParam", "__tag": 4016, "name": "channel_axis", "annotation": "int or None, optional", "desc": [ { "__type": "Paragraph", "__tag": 4045, "children": [ { "__type": "Text", "__tag": 4046, "value": "If " }, { "__type": "InlineCode", "__tag": 4051, "value": "None" }, { "__type": "Text", "__tag": 4046, "value": ", the image is assumed to be grayscale (single-channel). Otherwise, this parameter indicates which axis of the array corresponds to channels." } ] }, { "__type": "Admonition", "__tag": 4056, "kind": "versionadded", "base_type": "neutral", "children": [ { "__type": "AdmonitionTitle", "__tag": 4055, "children": [ { "__type": "Text", "__tag": 4046, "value": "versionadded 0.19" } ] }, { "__type": "Paragraph", "__tag": 4045, "children": [ { "__type": "InlineCode", "__tag": 4051, "value": "channel_axis" }, { "__type": "Text", "__tag": 4046, "value": " was added in 0.19." } ] } ] } ] } ] } ], "title": [], "level": 0, "target": null }, "Extended Summary": { "__type": "Section", "__tag": 4015, "children": [ { "__type": "Paragraph", "__tag": 4045, "children": [ { "__type": "Text", "__tag": 4046, "value": "Given " }, { "__type": "InlineMath", "__tag": 4057, "value": "f" }, { "__type": "Text", "__tag": 4046, "value": ", a noisy image (input data), total variation denoising (also known as total variation regularization) aims to find an image " }, { "__type": "InlineMath", "__tag": 4057, "value": "u" }, { "__type": "Text", "__tag": 4046, "value": " with less total variation than " }, { "__type": "InlineMath", "__tag": 4057, "value": "f" }, { "__type": "Text", "__tag": 4046, "value": ", under the constraint that " }, { "__type": "InlineMath", "__tag": 4057, "value": "u" }, { "__type": "Text", "__tag": 4046, "value": " remain similar to " }, { "__type": "InlineMath", "__tag": 4057, "value": "f" }, { "__type": "Text", "__tag": 4046, "value": ". This can be expressed by the Rudin--Osher--Fatemi (ROF) minimization problem:" } ] }, { "__type": "Math", "__tag": 4058, "value": "\\min_{u} \\sum_{i=0}^{N-1} \\left( \\left| \\nabla{u_i} \\right| + \\frac{\\lambda}{2}(f_i - u_i)^2 \\right)" }, { "__type": "Paragraph", "__tag": 4045, "children": [ { "__type": "Text", "__tag": 4046, "value": "where " }, { "__type": "InlineMath", "__tag": 4057, "value": "\\lambda" }, { "__type": "Text", "__tag": 4046, "value": " is a positive parameter. The first term of this cost function is the total variation; the second term represents data fidelity. As " }, { "__type": "InlineMath", "__tag": 4057, "value": "\\lambda \\to 0" }, { "__type": "Text", "__tag": 4046, "value": ", the total variation term dominates, forcing the solution to have smaller total variation, at the expense of looking less like the input data." } ] }, { "__type": "Paragraph", "__tag": 4045, "children": [ { "__type": "Text", "__tag": 4046, "value": "This code is an implementation of the algorithm proposed by Chambolle in " }, { "__type": "FootnoteReference", "__tag": 4066, "label": "1" }, { "__type": "Text", "__tag": 4046, "value": " to solve the ROF problem." } ] } ], "title": [], "level": 0, "target": null }, "Other Parameters": { "__type": "Section", "__tag": 4015, "children": [], "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/_denoise.py", "item_line": 490, "item_type": "function", "aliases": [ "skimage.restoration.denoise_tv_chambolle" ], "example_section_data": { "__type": "Section", "__tag": 4015, "children": [ { "__type": "Text", "__tag": 4046, "value": "2D example on astronaut image:\n\n" }, { "__type": "Code", "__tag": 4050, "value": "from skimage import color, data\nimg = color.rgb2gray(data.astronaut())[:50, :50]\nrng = np.random.default_rng()\nimg += 0.5 * img.std() * rng.standard_normal(img.shape)\ndenoised_img = denoise_tv_chambolle(img, weight=60)\n", "execution_status": "success" }, { "__type": "Text", "__tag": 4046, "value": "\n3D example on synthetic data:\n\n" }, { "__type": "Code", "__tag": 4050, "value": "x, y, z = np.ogrid[0:20, 0:20, 0:20]\nmask = (x - 22)**2 + (y - 20)**2 + (z - 17)**2 < 8**2\nmask = mask.astype(float)\nrng = np.random.default_rng()\nmask += 0.2 * rng.standard_normal(mask.shape)\nres = denoise_tv_chambolle(mask, weight=100)\n", "execution_status": "success" } ], "title": [], "level": 0, "target": null }, "see_also": [ { "__type": "SeeAlsoItem", "__tag": 4028, "name": { "__type": "CrossRef", "__tag": 4002, "value": "denoise_tv_bregman", "reference": { "__type": "LocalRef", "__tag": 4022, "kind": "module", "path": "skimage.restoration._denoise:denoise_tv_bregman" }, "kind": "module" }, "descriptions": [ { "__type": "Paragraph", "__tag": 4045, "children": [ { "__type": "Text", "__tag": 4046, "value": "Perform total variation denoising using split-Bregman optimization." } ] } ], "type": null } ], "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": "weight", "annotation": { "__type": "Empty", "__tag": 4031 }, "kind": "POSITIONAL_OR_KEYWORD", "default": "0.1" }, { "__type": "SigParam", "__tag": 4030, "name": "eps", "annotation": { "__type": "Empty", "__tag": 4031 }, "kind": "POSITIONAL_OR_KEYWORD", "default": "0.0002" }, { "__type": "SigParam", "__tag": 4030, "name": "max_num_iter", "annotation": { "__type": "Empty", "__tag": 4031 }, "kind": "POSITIONAL_OR_KEYWORD", "default": "200" }, { "__type": "SigParam", "__tag": 4030, "name": "channel_axis", "annotation": { "__type": "Empty", "__tag": 4031 }, "kind": "KEYWORD_ONLY", "default": "None" } ], "return_annotation": { "__type": "Empty", "__tag": 4031 }, "target_name": "denoise_tv_chambolle" }, "references": [ ".. [1] A. Chambolle, An algorithm for total variation minimization and", " applications, Journal of Mathematical Imaging and Vision,", " Springer, 2004, 20, 89-97.", ".. [2] https://en.wikipedia.org/wiki/Total_variation_denoising" ], "qa": "skimage.restoration._denoise:denoise_tv_chambolle", "arbitrary": [], "local_refs": [ "channel_axis", "eps", "image", "max_num_iter", "u", "weight" ] }