使用 SWIG 封装 C 函数时正确传递 NumPy 数组的完整指南-Python教程-PHP中文网

使用 SWIG 封装 C 函数时正确传递 NumPy 数组的完整指南

本文详解如何通过 SWIG 4.3 正确封装带多维 const 指针参数和原地输出数组的 C 函数，解决 TypeError: argument X of type 'T const *' 等典型问题，并提供可直接复用的接口定义与 Python 调用范式。

本文详解如何通过 swig 4.3 正确封装带多维 `const` 指针参数和原地输出数组的 c 函数，解决 `typeerror: argument x of type 't const *'` 等典型问题，并提供可直接复用的接口定义与 python 调用范式。

在使用 SWIG 将 C 函数（如图像白平衡算法 AesAutoWhiteBalance_Balance）暴露给 Python 时，直接传递 NumPy 数组常因类型不匹配、const 修饰符冲突或输出参数映射错误而触发 TypeError。核心症结在于：SWIG 的 NumPy typemaps 默认不支持 const T* 输入指针，且无法自动推导多数组共享维度；同时，float* outR, outG, outB 这类分散的输出参数需统一为单个可写数组（如长度为 3 的 float[3]），否则无法应用 INPLACE_ARRAY1 映射。

以下是经过验证的完整解决方案，分为三步：

✅ 1. 修正 SWIG 接口文件（`.i`）

避免直接 %include 原始头文件（会绕过 typemap 应用），改用 %inline 手动封装，并显式处理类型与校验：

%module AesAutoWhiteBalance

%{
#define SWIG_FILE_WITH_INIT
#include "AesAutoWhiteBalance.h"
%}

// 启用 NumPy 支持
%include "numpy.i"
%init %{
import_array();
%}

// 关键：移除 const，使用非 const 指针 + IN_ARRAY1 映射
%apply (unsigned short* IN_ARRAY1, int DIM1) {
  (unsigned short* measurementsR, int size_r),
  (unsigned short* measurementsG, int size_g),
  (unsigned short* measurementsB, int size_b)
};

// 输出参数映射为单个长度为 3 的 float 数组
%apply (float* INPLACE_ARRAY1, int DIM1) { (float* balancingCoeffs, int out_size) };

// 手动封装函数（含输入校验与调用转发）
%inline %{
void balance(
    unsigned short* measurementsR, int size_r,
    unsigned short* measurementsG, int size_g,
    unsigned short* measurementsB, int size_b,
    int bitWidth,
    float* balancingCoeffs, int out_size
) {
    // 强制输出数组长度为 3
    if (out_size != 3) {
        PyErr_SetString(PyExc_ValueError, "balancingCoeffs must be a 1D array of length 3");
        return;
    }
    // 校验三通道数据长度一致
    if (size_r != size_g || size_r != size_b) {
        PyErr_Format(PyExc_ValueError,
            "Measurement arrays must have equal length: R=%d, G=%d, B=%d",
            size_r, size_g, size_b);
        return;
    }

    // 调用原始 C 函数（仅传 size_r 作为 measureCount）
    AesAutoWhiteBalance_Balance(
        measurementsR, measurementsG, measurementsB,
        static_cast<unsigned>(size_r),  // 注意类型转换
        static_cast<unsigned>(bitWidth),
        balancingCoeffs
    );
}
%}</unsigned></unsigned>

⚠️ 注意事项：

必须删除原始声明中的 const（SWIG typemaps 不识别 const unsigned short*）；

INPLACE_ARRAY1 要求目标数组是 C-contiguous 且可写（flags.writeable == True），调用前需检查；

%apply 中的参数名（如 size_r）必须与 %inline 函数签名严格一致，否则映射失效。

✅ 2. Python 端正确调用方式

确保 NumPy 数组满足内存布局与类型要求：

import numpy as np
from PIL import Image
import AesAutoWhiteBalance

# 加载并预处理图像
img = Image.open(image_path).convert('RGB')
img_array = np.array(img, dtype=np.uint16)  # 显式指定 dtype

# 提取并展平三通道（保持 C-order）
red   = img_array[:, :, 0].flatten()  # shape: (N,)
green = img_array[:, :, 1].flatten()
blue  = img_array[:, :, 2].flatten()

# 创建输出数组（必须为 float32、C-contiguous、可写）
coeffs = np.zeros(3, dtype=np.float32)
coeffs.flags.writeable = True  # 确保可写（SWIG INPLACE_ARRAY1 所需）

# 调用封装函数
AesAutoWhiteBalance.balance(
    red,   red.size,
    green, green.size,
    blue,  blue.size,
    8,     # bitWidth
    coeffs, coeffs.size  # out_size = 3
)

print("Balancing coefficients:", coeffs)  # [r_coeff, g_coeff, b_coeff]

✅ 3. 编译与调试建议

编译时确保链接 numpy 头文件路径（如 -I$(python -c "import numpy; print(numpy.get_include())")）；
若仍报错 TypeError，用 print(red.dtype, red.flags) 检查数组是否为 uint16 且 C_CONTIGUOUS/WRITEABLE；
使用 swig -python -c++ -I/path/to/numpy AesAutoWhiteBalance.i 显式指定选项；
错误信息中若出现 expected 1D array，说明传入了标量（如 identity_matrix[0][0]）——切勿传入标量替代数组！