Cython实现3D滑动窗口方差滤波提示np/cython未声明报错

我需要对3D数组执行滑动窗口遍历，每次迭代将窗口移动1个像素，计算对应3D窗口内的方差。出于性能优化考虑，我在Jupyter Notebook中使用Cython实现该功能。

目前可正常运行但运行速度较慢的Python版本代码如下：

## PYTHON
# 3D滑动窗口遍历参考实现
def Variance_Filter_3D_python(image, kernel = 30):
  
    min_var = 10000
    min_var_coord = [0,0,0]
    
    window = np.zeros(shape=(kernel,kernel,kernel), dtype = np.uint8)
    z,y,x = image.shape
    
    for i in np.arange(0,(z-kernel),1):
        for j in np.arange(0,(y-kernel),1):
            for k in np.arange(0,(x-kernel),1):
                window[:,:,:] = image[i:i+kernel,j:j+kernel,k:k+kernel]
                var = np.var(window)
                if var < min_var:
                    min_var = var
                    min_var_coord = [i,j,k]
                print(min_var_coord)
    return min_var,min_var_coord

随后我尝试编写Cython版本代码，声明相关变量类型，代码片段如下：

%%cython

@cython.boundscheck(False)  # 关闭边界检查
@cython.wraparound(False)   # 关闭负索引环绕
def Variance_Filter_3D(image, kernel = 30):
    cdef double min_var = 10000
    cdef list min_var_coord = [0,0,0] 
    cdef unsigned int z,y,x = image.shape
    cdef np.ndarray[float, ndim=3] window = np.zeros(shape=(kernel,kernel,kernel), 
    dtype=FTYPE)

....etc

编译时出现两类报错：

• 在声明window变量的代码行提示'np' is not declared
• 在两个装饰器代码行提示cython未声明

我已经在Cython代码块中提前执行了如下导入语句：

%%cython
cimport numpy as np
cimport cython

核心原因 #

报错由三个常见的Cython编写误区共同导致：

1. cimport 仅导入Cython编译层面的C API声明，不会自动加载Python运行时的模块对象：cimport cython只给编译器提供编译指令识别能力，cimport numpy as np只导入numpy的C类型、C函数声明，二者都不会把cython、numpy模块注入代码运行时的命名空间，因此调用@cython.xxx装饰器、np.zeros()这类Python层面接口时会报未定义错误。
2. Jupyter中每个%%cython单元格会被独立编译为单独的扩展模块，不同单元格之间的导入、类型声明完全不共享。如果把cimport语句写在单独的%%cython单元格，和函数实现拆分到不同单元，导入声明对后续单元的代码完全无效。
3. 代码中用到的FTYPE类型别名没有提前声明，也会触发后续编译错误。

修复方法 #

1. 所有Cython代码（包括魔法指令、导入、类型声明、函数实现）必须放在同一个以%%cython为第一行的单元格内，不要拆分到多个单元。
2. 在cimport语句之后补充普通Python层面的模块导入。
3. 提前声明用到的类型别名，或者直接使用numpy原生类型常量。

修复后的代码头部示例：

%%cython
# 第一步：导入C层面的编译声明
cimport cython
cimport numpy as np
# 第二步：补充Python层面的模块导入
import cython
import numpy as np

# 第三步：声明numpy类型别名（如果需要用FTYPE的话）
ctypedef np.float32_t FTYPE

@cython.boundscheck(False)
@cython.wraparound(False)
def Variance_Filter_3D(image, kernel = 30):
    cdef double min_var = 10000
    cdef list min_var_coord = [0,0,0] 
    cdef unsigned int z = image.shape[0], y = image.shape[1], x = image.shape[2]
    cdef np.ndarray[FTYPE, ndim=3] window = np.zeros(shape=(kernel,kernel,kernel), dtype=np.float32)
    
    # 后续业务逻辑...

额外性能优化提示 #

当前实现还有很大性能提升空间：

• 循环变量i/j/k必须用cdef声明为无符号整型，否则循环还是会走Python对象调度逻辑，Cython加速效果会大打折扣。
• 不需要每次循环都把窗口数据拷贝到独立的window数组，直接在原数组上计算统计值即可，能减少大量内存拷贝开销。
• 可以用三维前缀和（积分图）方案把滑动窗口方差计算的时间复杂度从O(n*k³)降到O(n)，大核场景下速度能提升2~3个数量级。

内容的提问来源于stack exchange，提问作者gmut