还原二维缠绕相位并处理遮罩边界-未完纪

原文：https://scikit-image.org/docs/0.26.x/auto_examples/filters/plot_phase_unwrap.html。作者／维护方：scikit-image team（原页未署个人作者）。中文翻译整理与校注：未完纪；源文核对日期：2026-10-05。

一些信号只能观测到模 2π 的结果：相位超过一个周期后，会重新回到同一个取值区间。这种现象也会出现在二维或三维图像中。相位解缠绕要做的，是从周期折返后的数据恢复一个连续的相位场。scikit-image 的 unwrap_phase 支持一维、二维和三维输入；本文按照官方示例，先处理一幅二维图像，再观察遮罩和周期边界如何改变解缠绕路径。

这里使用的是人为生成的相位数据，目的是理解算法和边界条件，并非测量仪器采集的相位图。本次核对的页面属于 scikit-image 0.26.x 文档，代码和图均来自原示例；图中的数值是上游生成的结果，不是本文重新执行得到的结果。

把普通图像变成缠绕相位

第一步载入 scikit-image 自带的 Chelsea 猫图，用 img_as_float 转成浮点数据，再用 color.rgb2gray 转成灰度图。随后将强度重新缩放到 [0, 4π]，把灰度值当作相位。表达式 np.exp(1j * image) 将相位映射到单位圆，np.angle 再取其主值，从而产生周期折返。

原例注释将缠绕区间写成 [-π, π)；更严格地说，NumPy 的角度主值通常表述为 (-π, π]，边界还涉及浮点数和带符号零。这里的核心是每隔 2π 出现一次折返，这个端点记法不影响示例要展示的解缠绕过程。

import numpy as np
from matplotlib import pyplot as plt
from skimage import data, img_as_float, color, exposure
from skimage.restoration import unwrap_phase


# Load an image as a floating-point grayscale
image = color.rgb2gray(img_as_float(data.chelsea()))
# Scale the image to [0, 4*pi]
image = exposure.rescale_intensity(image, out_range=(0, 4 * np.pi))
# Create a phase-wrapped image in the interval [-pi, pi)
image_wrapped = np.angle(np.exp(1j * image))
# Perform phase unwrapping
image_unwrapped = unwrap_phase(image_wrapped)

fig, ax = plt.subplots(2, 2, sharex=True, sharey=True)
ax1, ax2, ax3, ax4 = ax.ravel()

fig.colorbar(ax1.imshow(image, cmap='gray', vmin=0, vmax=4 * np.pi), ax=ax1)
ax1.set_title('Original')

fig.colorbar(ax2.imshow(image_wrapped, cmap='gray', vmin=-np.pi, vmax=np.pi), ax=ax2)
ax2.set_title('Wrapped phase')

fig.colorbar(ax3.imshow(image_unwrapped, cmap='gray'), ax=ax3)
ax3.set_title('After phase unwrapping')

fig.colorbar(ax4.imshow(image_unwrapped - image, cmap='gray'), ax=ax4)
ax4.set_title('Unwrapped minus original')

图 1：官方示例的第一组输出。左上为映射到 0 至 4π 的原相位，右上为缠绕相位，左下为解缠绕结果，右下为结果与原图之差。图片来自 scikit-image 0.26.x 文档；底层 Chelsea 图像由摄影师 Stefan van der Walt 以 CC0 提供。

unwrap_phase(image_wrapped) 依据相邻像素之间的信息恢复相位连续性。四个面板共享横纵坐标，便于对照同一位置；第一幅和缠绕图分别固定了颜色范围，解缠绕结果及差值图则由 Matplotlib 自动确定范围。因此，看起来相似的灰度并不自动意味着数值完全相等，判断时需要读色条和差值。

相位观测不能区分相差整数个 2π 的值，解缠绕结果可能整体加上或减去若干个完整周期。差值图正是用来检查这一点：即使恢复了空间变化形状，绝对相位基准仍可能没有确定。不能把“形状恢复”直接表述成所有像素都恢复到了唯一的绝对真值。

页面还显示 Matplotlib 的对象表示 Text(0.5, 1.0, 'Unwrapped minus original')。它只是设置最后一个标题时返回的对象，不是算法输出的评价指标。

遮罩把一个相位场分成两个区域

unwrap_phase 可以接收 NumPy 的掩码数组，还可以选择把图像某个维度的两端视为相连。第二个实验使用一个 100 × 100 的相位坡度：沿第 0 维从 0 线性增长到 8π，同一行内各列取值相同。把第 50 行整行设为遮罩后，上下两个区域就被横向隔开了。

下面的第一遍解缠绕使用 wrap_around=(False, False)，两个维度都不跨边界连接；第二遍使用 wrap_around=(True, False)，只允许第 0 维，也就是上下边界之间的连接。

# Create a simple ramp
image = np.ones((100, 100)) * np.linspace(0, 8 * np.pi, 100).reshape((-1, 1))
# Mask the image to split it in two horizontally
mask = np.zeros_like(image, dtype=bool)
mask[image.shape[0] // 2, :] = True

image_wrapped = np.ma.array(np.angle(np.exp(1j * image)), mask=mask)
# Unwrap image without wrap around
image_unwrapped_no_wrap_around = unwrap_phase(image_wrapped, wrap_around=(False, False))
# Unwrap with wrap around enabled for the 0th dimension
image_unwrapped_wrap_around = unwrap_phase(image_wrapped, wrap_around=(True, False))

fig, ax = plt.subplots(2, 2)
ax1, ax2, ax3, ax4 = ax.ravel()

fig.colorbar(ax1.imshow(np.ma.array(image, mask=mask), cmap='rainbow'), ax=ax1)
ax1.set_title('Original')

fig.colorbar(ax2.imshow(image_wrapped, cmap='rainbow', vmin=-np.pi, vmax=np.pi), ax=ax2)
ax2.set_title('Wrapped phase')

fig.colorbar(ax3.imshow(image_unwrapped_no_wrap_around, cmap='rainbow'), ax=ax3)
ax3.set_title('Unwrapped without wrap_around')

fig.colorbar(ax4.imshow(image_unwrapped_wrap_around, cmap='rainbow'), ax=ax4)
ax4.set_title('Unwrapped with wrap_around')

plt.tight_layout()
plt.show()

图 2：官方示例的遮罩与周期边界对比。白色横线是被屏蔽的行；左下不连接上下边界，右下允许第 0 维周期连接。来源：scikit-image 0.26.x Phase Unwrapping。

白色横线使中间一行不参与计算。关闭周期连接时，遮罩上方和下方无法沿有效像素路径互通，相当于分别解缠绕两幅独立图像。每个区域可以有自己任意整数倍 2π 的常数偏移，因此两边的相位基准可能不一致。

开启第 0 维的周期连接后，路径可以从最底部跨到最顶部，也可以反向跨越。这样一来，原本被遮罩隔开的两部分有了另一条连接路径，算法便能利用这条路径确定区域间的相对偏移。原文解释左下图时写了 “Without unwrapping”，但该图实际上已经解缠绕，只是没有启用 wrap around；本文按对应代码与图标题校正这一处表述。

周期边界是一项关于数据的假设，不是普遍提高结果质量的开关。这个合成坡度专门用来展示边界连通性。如果真实图像的首尾并不相邻，把它们强行连起来会向算法引入不存在的邻接关系。遮罩区域也不会凭空得到可信的观测值；最终结果能恢复什么，取决于有效区域的连通性、相位差和所采用的边界条件。

复现时应核对什么

本例只需要 NumPy、Matplotlib 和 scikit-image，不需要外部相位文件或测量设备。输入图像由 data.chelsea() 提供；坡度、缠绕和遮罩都在代码中构造。作为待验证的复现基线，可以使用 CPython 3.11、scikit-image 0.26.0、NumPy 2.2.6、SciPy 1.15.3 和 Matplotlib 3.10.3。这个组合依据已发布包的约束核对提出，并未在本文环境安装或运行，也不是完整锁定文件。

代码审查确认两段示例的数据维度、遮罩布尔类型和 wrap_around 元组长度相互对应。unwrap_phase 的输入应是有效的相位值，不能假设任意不连续、含噪或存在错误遮罩的数据都能唯一恢复。原页显示脚本总用时约 0.906 秒，这是上游文档构建时的记录，不是跨硬件性能保证。

算法参考、来源与许可

本例引用：Miguel Arevallilo Herraez、David R. Burton、Michael J. Lalor、Munther A. Gdeisat，Fast two-dimensional phase-unwrapping algorithm based on sorting by reliability following a noncontinuous path，Applied Optics，41 卷，35 期，第 7437 页起，2002 年。该文是官方示例列出的二维算法参考。

原文：Phase Unwrapping。维护方为 scikit-image team，原页没有可确认的个人署名。官方提供对应示例源码，以及 unwrap_phase 实现入口。Chelsea 图片在 data fetchers 中注明由摄影师 Stefan van der Walt 以 CC0 提供。

版权与许可全文

以下保留本页涉及的来源材料或示例代码的版权、许可条件与免责声明；各自适用范围依原声明。中文翻译及编辑标注：未完纪，2026-10-05。

LICENSE.txt

Files: *
Copyright: 2009-2022 the scikit-image team
License: BSD-3-Clause

Files: doc/source/themes/scikit-image/layout.html
Copyright: 2007-2010 the Sphinx team
License: BSD-3-Clause
Files: skimage/feature/_canny.py
       skimage/filters/edges.py
       skimage/filters/_rank_order.py
       skimage/morphology/_skeletonize.py
       skimage/morphology/tests/test_watershed.py
       skimage/morphology/watershed.py
       skimage/segmentation/heap_general.pxi
       skimage/segmentation/heap_watershed.pxi
       skimage/segmentation/_watershed.py
       skimage/segmentation/_watershed_cy.pyx
Copyright: 2003-2009 Massachusetts Institute of Technology
           2009-2011 Broad Institute
           2003 Lee Kamentsky
           2003-2005 Peter J. Verveer
License: BSD-3-Clause
Files: skimage/filters/thresholding.py
       skimage/graph/_mcp.pyx
       skimage/graph/heap.pyx
Copyright: 2009-2015 Board of Regents of the University of
           Wisconsin-Madison, Broad Institute of MIT and Harvard,
           and Max Planck Institute of Molecular Cell Biology and
           Genetics
           2009 Zachary Pincus
           2009 Almar Klein
License: BSD-2-Clause
File: skimage/morphology/grayreconstruct.py
      skimage/morphology/tests/test_reconstruction.py
Copyright: 2003-2009 Massachusetts Institute of Technology
           2009-2011 Broad Institute
           2003 Lee Kamentsky
License: BSD-3-Clause
File: skimage/morphology/_grayreconstruct.pyx
Copyright: 2003-2009 Massachusetts Institute of Technology
           2009-2011 Broad Institute
           2003 Lee Kamentsky
           2022 Gregory Lee (added a 64-bit integer variant for large images)
License: BSD-3-Clause

File: skimage/segmentation/_expand_labels.py
Copyright: 2020 Broad Institute
           2020 CellProfiler team
License: BSD-3-Clause

File: skimage/exposure/_adapthist.py
Copyright: 1994 Karel Zuiderveld
License: BSD-3-Clause
Function: skimage/morphology/_skeletonize_various_cy.pyx:_skeletonize_loop
Copyright: 2003-2009 Massachusetts Institute of Technology
           2009-2011 Broad Institute
           2003 Lee Kamentsky
License: BSD-3-Clause

Function: skimage/_shared/version_requirements.py:_check_version
Copyright: 2013 The IPython Development Team
License: BSD-3-Clause

Function: skimage/_shared/version_requirements.py:is_installed
Copyright: 2009-2011 Pierre Raybaut
License: MIT
File: skimage/feature/_fisher_vector.py
Copyright: 2014 2014 Dan Oneata
License: MIT

File: skimage/_vendored/numpy_lookfor.py
Copyright: 2005-2023, NumPy Developers
License: BSD-3-Clause

File: skimage/transform/_thin_plate_splines.py
Copyright: 2007 Zachary Pincus
License: BSD-3-Clause

License: BSD-2-Clause
Redistribution and use in source and binary forms, with or without
modification, are permitted provided that the following conditions
are met:
1. Redistributions of source code must retain the above copyright
   notice, this list of conditions and the following disclaimer.
2. Redistributions in binary form must reproduce the above copyright
   notice, this list of conditions and the following disclaimer in the
   documentation and/or other materials provided with the distribution.
.
THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS
``AS IS'' AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT
LIMITED TO, THE IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR
A PARTICULAR PURPOSE ARE DISCLAIMED. IN NO EVENT SHALL THE HOLDERS OR
CONTRIBUTORS BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL,
EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT LIMITED TO,
PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES; LOSS OF USE, DATA, OR
PROFITS; OR BUSINESS INTERRUPTION) HOWEVER CAUSED AND ON ANY THEORY OF
LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT (INCLUDING
NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE OF THIS
SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE.
License: BSD-3-Clause
Redistribution and use in source and binary forms, with or without
modification, are permitted provided that the following conditions
are met:
1. Redistributions of source code must retain the above copyright
   notice, this list of conditions and the following disclaimer.
2. Redistributions in binary form must reproduce the above copyright
   notice, this list of conditions and the following disclaimer in the
   documentation and/or other materials provided with the distribution.
3. Neither the name of the University nor the names of its contributors
   may be used to endorse or promote products derived from this software
   without specific prior written permission.
.
THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS
``AS IS'' AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT
LIMITED TO, THE IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR
A PARTICULAR PURPOSE ARE DISCLAIMED. IN NO EVENT SHALL THE HOLDERS OR
CONTRIBUTORS BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL,
EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT LIMITED TO,
PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES; LOSS OF USE, DATA, OR
PROFITS; OR BUSINESS INTERRUPTION) HOWEVER CAUSED AND ON ANY THEORY OF
LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT (INCLUDING
NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE OF THIS
SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE.
License: MIT

Permission is hereby granted, free of charge, to any person obtaining a copy
of this software and associated documentation files (the "Software"), to deal
in the Software without restriction, including without limitation the rights
to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
copies of the Software, and to permit persons to whom the Software is
furnished to do so, subject to the following conditions:
The above copyright notice and this permission notice shall be included in all
copies or substantial portions of the Software.
THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
SOFTWARE.

文章版权归作者所有，未经允许请勿转载。

THE END