update

.CondaPkg/env/Lib/site-packages/skimage/restoration/unwrap.py

@@ -0,0 +1,116 @@
+import numpy as np
+
+from .._shared.utils import warn
+
+from ._unwrap_1d import unwrap_1d
+from ._unwrap_2d import unwrap_2d
+from ._unwrap_3d import unwrap_3d
+
+
+def unwrap_phase(image, wrap_around=False, rng=None):
+    '''Recover the original from a wrapped phase image.
+
+    From an image wrapped to lie in the interval [-pi, pi), recover the
+    original, unwrapped image.
+
+    Parameters
+    ----------
+    image : (M[, N[, P]]) ndarray or masked array of floats
+        The values should be in the range [-pi, pi). If a masked array is
+        provided, the masked entries will not be changed, and their values
+        will not be used to guide the unwrapping of neighboring, unmasked
+        values. Masked 1D arrays are not allowed, and will raise a
+        `ValueError`.
+    wrap_around : bool or sequence of bool, optional
+        When an element of the sequence is  `True`, the unwrapping process
+        will regard the edges along the corresponding axis of the image to be
+        connected and use this connectivity to guide the phase unwrapping
+        process. If only a single boolean is given, it will apply to all axes.
+        Wrap around is not supported for 1D arrays.
+    rng : {`numpy.random.Generator`, int}, optional
+        Pseudo-random number generator.
+        By default, a PCG64 generator is used (see :func:`numpy.random.default_rng`).
+        If `rng` is an int, it is used to seed the generator.
+
+        Unwrapping relies on a random initialization. This sets the
+        PRNG to use to achieve deterministic behavior.
+
+    Returns
+    -------
+    image_unwrapped : array_like, double
+        Unwrapped image of the same shape as the input. If the input `image`
+        was a masked array, the mask will be preserved.
+
+    Raises
+    ------
+    ValueError
+        If called with a masked 1D array or called with a 1D array and
+        ``wrap_around=True``.
+
+    Examples
+    --------
+    >>> c0, c1 = np.ogrid[-1:1:128j, -1:1:128j]
+    >>> image = 12 * np.pi * np.exp(-(c0**2 + c1**2))
+    >>> image_wrapped = np.angle(np.exp(1j * image))
+    >>> image_unwrapped = unwrap_phase(image_wrapped)
+    >>> np.std(image_unwrapped - image) < 1e-6   # A constant offset is normal
+    True
+
+    References
+    ----------
+    .. [1] Miguel Arevallilo Herraez, David R. Burton, Michael J. Lalor,
+           and Munther A. Gdeisat, "Fast two-dimensional phase-unwrapping
+           algorithm based on sorting by reliability following a noncontinuous
+           path", Journal Applied Optics, Vol. 41, No. 35 (2002) 7437,
+    .. [2] Abdul-Rahman, H., Gdeisat, M., Burton, D., & Lalor, M., "Fast
+           three-dimensional phase-unwrapping algorithm based on sorting by
+           reliability following a non-continuous path. In W. Osten,
+           C. Gorecki, & E. L. Novak (Eds.), Optical Metrology (2005) 32--40,
+           International Society for Optics and Photonics.
+    '''
+    if image.ndim not in (1, 2, 3):
+        raise ValueError('Image must be 1, 2, or 3 dimensional')
+    if isinstance(wrap_around, bool):
+        wrap_around = [wrap_around] * image.ndim
+    elif hasattr(wrap_around, '__getitem__') and not isinstance(wrap_around, str):
+        if len(wrap_around) != image.ndim:
+            raise ValueError(
+                'Length of `wrap_around` must equal the ' 'dimensionality of image'
+            )
+        wrap_around = [bool(wa) for wa in wrap_around]
+    else:
+        raise ValueError(
+            '`wrap_around` must be a bool or a sequence with '
+            'length equal to the dimensionality of image'
+        )
+    if image.ndim == 1:
+        if np.ma.isMaskedArray(image):
+            raise ValueError('1D masked images cannot be unwrapped')
+        if wrap_around[0]:
+            raise ValueError('`wrap_around` is not supported for 1D images')
+    if image.ndim in (2, 3) and 1 in image.shape:
+        warn(
+            'Image has a length 1 dimension. Consider using an '
+            'array of lower dimensionality to use a more efficient '
+            'algorithm'
+        )
+
+    if np.ma.isMaskedArray(image):
+        mask = np.require(np.ma.getmaskarray(image), np.uint8, ['C'])
+    else:
+        mask = np.zeros_like(image, dtype=np.uint8, order='C')
+
+    image_not_masked = np.asarray(np.ma.getdata(image), dtype=np.float64, order='C')
+    image_unwrapped = np.empty_like(image, dtype=np.float64, order='C', subok=False)
+
+    if image.ndim == 1:
+        unwrap_1d(image_not_masked, image_unwrapped)
+    elif image.ndim == 2:
+        unwrap_2d(image_not_masked, mask, image_unwrapped, wrap_around, rng)
+    elif image.ndim == 3:
+        unwrap_3d(image_not_masked, mask, image_unwrapped, wrap_around, rng)
+
+    if np.ma.isMaskedArray(image):
+        return np.ma.array(image_unwrapped, mask=mask, fill_value=image.fill_value)
+    else:
+        return image_unwrapped