Qt 桥接——cv::Mat 与 QImage 的零拷贝互转

如果你写过哪怕一个稍微像样的图像处理 GUI 应用，那你大概率同时用过 Qt 和 OpenCV。Qt 负责 GUI——窗口、控件、信号槽、事件循环，QImage 是它表示图像的核心类型。OpenCV 负责视觉算法——滤波、特征检测、几何变换，cv::Mat 是它表示图像的核心类型。两个库各有各的生态，谁也替代不了谁，所以真实项目里经常是两个一起上。问题来了：Qt 的 QImage 和 OpenCV 的 cv::Mat 是两个完全独立的类型系统，它们之间没有内置的互转机制。你有一张 cv::Mat 想在 QLabel 上显示？你得转成 QImage。你在 Qt 里通过文件对话框选了一张图想用 OpenCV 处理？你得从 QImage 转成 cv::Mat。

听起来不复杂，但这个转换背后有一堆坑等着你。首先是格式对齐问题——OpenCV 的三通道图默认是 BGR 排列，而 Qt 的 Format_RGB888 期望 RGB 排列，直接共享内存的话红蓝通道就反了。然后是内存布局问题——cv::Mat 的行步长（step）可能不等于 width * channels（尤其是 ROI 子图），而 QImage 的 bytesPerLine 也有自己的对齐策略。还有就是深拷贝和浅拷贝的选择——共享内存性能好但有生命周期陷阱，独立拷贝安全但有内存开销。edgecv 的 cvw::qt/bridging.hpp 就是来解决这些问题的，它提供了一套类型安全的双向转换函数，让你在 cv::Mat（以及 Image<F>）和 QImage 之间灵活切换，同时把格式不匹配的隐患暴露在编译期或明确地交由调用者处理。

ConvertionalError 和 ConvertionalMethod

我们先看两个配套的枚举。ConvertionalError 是转换过程可能出现的错误：

enum class ConvertionalError : uint8_t {
    InternalError,       // 输入为空（empty Mat / null QImage）
    UnsupportedFormat    // 像素格式不在支持列表中
};

只有两种错误，语义很清晰：要么你传了个空对象进来，要么你传了个 edgecv 不认识的格式。InternalError 这个名字起得不太好（其实叫 EmptyInput 更贴切），但它和库内其他模块的错误枚举保持了命名一致性。

ConvertionalMethod 控制转换时内存的处理方式：

enum class ConvertionalMethod : uint8_t {
    Copy,    // 深拷贝——数据独立，生命周期互不影响
    Shared   // 共享——两个对象指向同一块内存
};

这两个枚举不是作为函数参数传递的，而是作为模板参数——转换函数是函数模板，Method 在编译期确定：

template <ConvertionalMethod Method>
expected<QImage, ConvertionalError> from_cv(const cv::Mat& mat);

template <ConvertionalMethod Method>
expected<cv::Mat, ConvertionalError> to_cv(const QImage& image);

用模板参数而不是运行时参数有好处——如果你用 Shared 模式，编译器知道不需要调用 copy() 或 clone()，生成的代码路径更短；而且如果你后续想改成 Copy 模式，改模板参数就行，不用改调用逻辑。

from_cv<Method>(mat)——cv::Mat 转 QImage

我们先看 cv::Mat 到 QImage 的方向。from_cv 接受一个 cv::Mat，根据 mat.type() 自动匹配 QImage 的像素格式：

template <ConvertionalMethod Method>
inline cvw::expected<QImage, ConvertionalError> from_cv(const cv::Mat& mat) {
    if (mat.empty()) {
        return cvw::unexpected(ConvertionalError::InternalError);
    }

    QImage::Format fmt;
    switch (mat.type()) {
        case CV_8UC1:  fmt = QImage::Format_Grayscale8;  break;
        case CV_8UC3:  fmt = QImage::Format_RGB888;      break;
        case CV_8UC4:  fmt = QImage::Format_RGBA8888;    break;
        default:
            return cvw::unexpected(ConvertionalError::UnsupportedFormat);
    }
    // ...
}

格式映射关系是一对一的：单通道 8 位对应 Grayscale8，三通道 8 位对应 RGB888，四通道 8 位对应 RGBA8888。如果你的 cv::Mat 是 CV_32FC1（浮点单通道）或者 CV_16UC1（16 位无符号），直接返回 UnsupportedFormat 错误——这些格式 QImage 本身也不原生支持，edgecv 不会偷偷帮你做有损的类型转换，那是你的责任。

格式确定后，接下来是构造 QImage：

QImage img(mat.data, mat.cols, mat.rows, static_cast<int>(mat.step), fmt);

这里有几个细节值得展开说说。第一，mat.data 是 uchar*，而 QImage 的构造函数接受的也是 uchar*，类型直接匹配。第二，mat.step 被传给了 QImage 的 bytesPerLine 参数——这确保了行步长的正确传递，即使你的 cv::Mat 是一个 ROI 子图（step 可能不等于 cols * channels），QImage 也能正确地寻址。第三，这个构造出来的 img 对象本身不拥有数据，它只是持有一个指向 mat.data 的指针。

然后根据 Method 做分流：

if constexpr (Method == ConvertionalMethod::Copy) {
    return img.copy();   // QImage::copy() 深拷贝像素数据
} else {
    return img;          // 直接返回，共享 mat 的内存
}

Copy 模式调用 QImage::copy()，这会分配新的内存并把像素数据逐行复制过去，返回的 QImage 和原始的 mat 没有任何内存关联，你随便改一个另一个不受影响。Shared 模式直接返回构造出来的 img——此时 QImage 内部指向的就是 mat.data，两者共享同一块内存。

BGR/RGB 的陷阱

到这里必须说一个让无数开发者栽过跟头的坑：OpenCV 的三通道图像是 BGR 排列，Qt 的 Format_RGB888 是 RGB 排列。from_cv 不会帮你做通道重排——它只是把 mat.data 的原始字节搬到 QImage 里。这意味着如果你拿一张 cv::Mat（BGR 顺序）直接 from_cv<Shared> 成 QImage，然后显示出来，红色和蓝色会反过来。

这是有意的设计决定，不是 bug。原因很简单：通道重排需要逐像素操作，这是一个 O(width * height) 的计算过程，把它偷偷藏在"桥接"函数里会让调用者误以为这个操作是零开销的。正确的做法是在调用 from_cv 之前先用 OpenCV 的 cv::cvtColor(mat, mat, cv::COLOR_BGR2RGB) 把通道顺序排好，或者干脆用 cv::cvtColor 产生一个临时副本再桥接。如果你只是要做算法处理然后写回 Mat，通道顺序其实无所谓——反正 OpenCV 的算法都认 BGR。只有最终要显示的时候才需要关心这个问题。

单通道的灰度图和四通道的 BGRA/RGBA 没有这个问题。灰度图只有一个通道，不存在顺序问题。四通道的情况稍微微妙一些——OpenCV 里叫 BGRA，Qt 里叫 RGBA8888，但 from_cv 并没有做 B↔R 交换，它只是把四个字节原封不动地搬过去了。这意味着如果你在 OpenCV 里创建了一张 CV_8UC4 的图像并填充了 BGRA 值，转成 QImage 后这些字节会被按照 RGBA 的语义来解读——同样会有红蓝反过来的问题。所以对于四通道图像，你在桥接前同样需要 cv::cvtColor(mat, mat, cv::COLOR_BGRA2RGBA) 处理一下。这些在 bridging.hpp 的头文件注释里也有说明。

stride 的正确处理

刚才提到 mat.step 被传给了 QImage 的 bytesPerLine，这个设计解决了一个很容易被忽略的问题。考虑这样的代码：

cv::Mat big(100, 100, CV_8UC1, cv::Scalar(0));
cv::Rect roi(10, 10, 20, 20);
cv::Mat sub = big(roi);   // sub 是 big 的一个 ROI 子图

sub 的 data 指向 big.data + 10 * big.step + 10，但 sub.step 仍然是 big.step（即 100），而不是 20。因为 sub 共享 big 的底层内存，每行在内存里仍然是 100 字节宽，只是你只关心前 20 个。如果把 sub 传给 from_cv<Copy>，QImage 会根据 bytesPerLine = 100 正确地跳过每行末尾的 80 字节，复制出一张干干净净的 20x20 图像。

但 from_cv<Shared> 就需要小心了——共享模式下 QImage 指向的是 sub.data，也就是 big 内部的一个偏移位置。此时 QImage 的 bytesPerLine 是 100，它看到的"图像数据"实际上跨越了 big 的多行，这完全正确，但前提是 big 必须在 QImage 的整个生命周期内都有效。如果 big 先被销毁了，QImage 就指向了已释放的内存。测试代码里有专门的 ROI 测试用例验证了 stride 处理的正确性。

to_cv<Method>(qimage)——QImage 转 cv::Mat

反向转换的逻辑是对称的。to_cv 接受一个 QImage，根据 image.format() 匹配 OpenCV 的矩阵类型：

template <ConvertionalMethod Method>
inline cvw::expected<cv::Mat, ConvertionalError> to_cv(const QImage& image) {
    if (image.isNull()) {
        return cvw::unexpected(ConvertionalError::InternalError);
    }

    int type;
    switch (image.format()) {
        case QImage::Format_Grayscale8:  type = CV_8UC1;  break;
        case QImage::Format_RGB888:      type = CV_8UC3;  break;
        case QImage::Format_RGBA8888:
        case QImage::Format_ARGB32:      type = CV_8UC4;  break;
        default:
            return cvw::unexpected(ConvertionalError::UnsupportedFormat);
    }
    // ...
}

格式映射基本是 from_cv 的逆映射，有一个小差异值得注意：Format_RGBA8888 和 Format_ARGB32 都映射到了 CV_8UC4。这两种 QImage 格式都是四通道的，区别在于字节排列顺序——RGBA8888 是 R-G-B-A 四字节依次排列，ARGB32 在 x86 上是 B-G-R-A（取决于字节序）。to_cv 不做字节重排，统一映射成 CV_8UC4，调用者需要知道原始的 QImage 格式是什么，按需做通道转换。

接下来构造 cv::Mat：

cv::Mat mat(image.height(), image.width(), type,
            const_cast<uchar*>(image.constBits()),
            static_cast<size_t>(image.bytesPerLine()));

这里有一行 const_cast 值得解释。image.constBits() 返回的是 const uchar*，但 cv::Mat 的构造函数要求 void*（非 const）。这个 const_cast 是安全的，因为 cv::Mat 不会通过这个指针修改数据——至少在你不对 Mat 调用修改操作的时候不会。在 Shared 模式下，如果你后续通过 mat.at<Vec3b>(y,x) = ... 修改了像素，实际上是在修改 QImage 底层的内存。这和 from_cv<Shared> 里 QImage 修改 Mat 数据是同一个硬币的两面。

image.bytesPerLine() 被传给了 cv::Mat 的 step 参数。QImage 的 bytesPerLine 不一定等于 width * channels——Qt 内部可能为了对齐做了行填充。通过显式传递步长，cv::Mat 能正确寻址 QImage 的每一行，不会因为对齐填充而读错数据。

然后根据 Method 分流：

if constexpr (Method == ConvertionalMethod::Copy) {
    return mat.clone();   // cv::Mat::clone() 深拷贝
} else {
    return mat;           // 共享 QImage 的内存
}

Copy 模式调用 mat.clone()，这是 OpenCV 的标准深拷贝操作，会分配独立的内存并复制所有像素数据。Shared 模式直接返回——此时 cv::Mat 的 data 指针指向的是 image.constBits()，两者共享同一块内存。测试代码里专门验证了这个行为：

TEST(ToCv, RGB888SharedDataPointer) {
    auto img = makeRGBQImage(4, 4);
    auto r = to_cv<ConvertionalMethod::Shared>(img);
    ASSERT_TRUE(r.has_value());
    EXPECT_EQ(r->data, img.constBits());   // 指针相等 = 内存共享
}

共享模式的验证——修改一个，另一个跟着变

关于共享模式最让人关心的就是"真的共享了吗"？测试代码做了非常充分的验证。以灰度图为例：

TEST(FromCv, Gray8SharedModifiesOriginal) {
    auto mat = makeGray(4, 4, 100);
    auto r = from_cv<ConvertionalMethod::Shared>(mat);
    ASSERT_TRUE(r.has_value());
    *(r->bits()) = 42;
    EXPECT_EQ(mat.at<uchar>(0, 0), 42);   // 改了 QImage，Mat 也变了
}

通过 from_cv<Shared> 拿到 QImage 后，直接修改 QImage 的第一个像素为 42，然后检查 mat 的第一个像素——也是 42。指针是同一个，内存是同一块，改谁都改的是同一个地方。

反向也一样——to_cv<Shared> 拿到的 Mat 修改后 QImage 也会变：

TEST(ToCv, Grayscale8SharedModifiesOriginal) {
    QImage img(4, 4, QImage::Format_Grayscale8);
    img.fill(100);
    auto r = to_cv<ConvertionalMethod::Shared>(img);
    ASSERT_TRUE(r.has_value());
    r->at<uchar>(0, 0) = 42;
    EXPECT_EQ(*(img.constBits()), 42);    // 改了 Mat，QImage 也变了
}

而 Copy 模式下的测试则确认了独立性：

TEST(FromCv, Gray8CopyDoesNotModifyOriginal) {
    auto mat = makeGray(4, 4, 100);
    auto r = from_cv<ConvertionalMethod::Copy>(mat);
    ASSERT_TRUE(r.has_value());
    *(r->bits()) = 42;
    EXPECT_EQ(mat.at<uchar>(0, 0), 100);  // 改了 QImage 的拷贝，原 Mat 不受影响
}

这些测试不只是为了凑覆盖率——它们验证了桥接函数最核心的行为契约：Shared 模式下内存真的共享，Copy 模式下数据真的独立。在实际项目里，当你选择了 Shared 模式，你必须时刻记住这个生命周期约束：Mat 必须比共享的 QImage 活得长（from_cv 方向），或者 QImage 必须比共享的 Mat 活得长（to_cv 方向）。如果你把共享来的 QImage 存到了某个长期持有的数据结构里，而原始的 Mat 已经在函数结束时被析构了，那张 QImage 就指向了已释放的内存——典型的 use-after-free，调试起来非常痛苦。

便捷包装：to_qimage_view 和 to_qimage_copy

from_cv 和 to_cv 是基于 cv::Mat 的底层桥接函数。如果你的代码里已经有了 Image<F> 对象（edgecv 的类型安全图像容器），直接用 from_cv 需要先调用 img.mat() 暴露出内部的 cv::Mat。为了减少这种样板代码，bridging.hpp 提供了两个便捷包装：

template <is_pixel_format F>
[[nodiscard]] inline cvw::expected<QImage, ConvertionalError>
to_qimage_view(const Image<F>& img) {
    return from_cv<ConvertionalMethod::Shared>(img.mat());
}

template <is_pixel_format F>
[[nodiscard]] inline cvw::expected<QImage, ConvertionalError>
to_qimage_copy(const Image<F>& img) {
    return from_cv<ConvertionalMethod::Copy>(img.mat());
}

命名上 _view 和 _copy 直接表达了语义：to_qimage_view 返回的是共享内存的视图（不拥有数据），to_qimage_copy 返回的是独立的拷贝。这两个函数完全是对 from_cv 的薄包装，没有额外的逻辑，但名字更直观，用起来也更省心：

Image<BGR> bgr = /* ... */;
auto display = to_qimage_copy(bgr);
if (display) {
    label->setPixmap(QPixmap::fromImage(*display));
}

注意这里用了 to_qimage_copy 而不是 to_qimage_view——因为 Image<BGR> 可能是一个临时对象或者马上就要被算法消费掉，你需要一份独立的拷贝来保证 QImage 的数据在显示期间有效。如果你的 Image<F> 是一个长期持有的对象（比如类的成员变量），用 to_qimage_view 避免拷贝开销是合理的选择，但要确保 Image<F> 的生命周期覆盖 QImage 的使用周期。

完整的往返验证

桥接函数的正确性最终要通过往返测试来验证——Mat 转 QImage 再转回 Mat，数据必须一字不差。测试代码覆盖了所有三种格式：

TEST(RoundTrip, Gray8CopyRoundTrip) {
    cv::Mat original(8, 8, CV_8UC1);
    for (int i = 0; i < 64; ++i)
        original.data[i] = static_cast<uchar>(i * 4);

    auto to_q = from_cv<ConvertionalMethod::Copy>(original);
    ASSERT_TRUE(to_q.has_value());

    auto back = to_cv<ConvertionalMethod::Copy>(*to_q);
    ASSERT_TRUE(back.has_value());

    for (int y = 0; y < 8; ++y)
        for (int x = 0; x < 8; ++x)
            EXPECT_EQ(back->at<uchar>(y, x), original.at<uchar>(y, x));
}

这段测试先创建了一张 8x8 的灰度图，每个像素的值从 0 递增到 252（步长 4），然后 Mat → QImage → Mat 走一个来回，最后逐像素比较。BGR 和 BGRA 的往返测试也是同样的模式，唯一的区别是通道数变成了 3 和 4。反向的 QImage → Mat → QImage 往返测试同样存在且通过，覆盖了 Format_Grayscale8、Format_RGB888、Format_RGBA8888 三种格式。这些测试的核心思想是：如果你的桥接函数有任何格式映射或 stride 处理的 bug，往返测试一定能抓出来，因为两次转换会把错误放大成可以观测的像素值差异。

错误输入的处理

最后我们看看错误情况是怎么处理的。空输入是最基本的：

TEST(FromCv, EmptyMatReturnsError) {
    cv::Mat empty;
    auto r = from_cv<ConvertionalMethod::Copy>(empty);
    EXPECT_FALSE(r.has_value());
    EXPECT_EQ(r.error(), ConvertionalError::InternalError);
}

默认构造的 cv::Mat 的 empty() 返回 true，from_cv 检测到后直接返回错误。类似地，默认构造的 QImage 的 isNull() 返回 true，to_cv 也会拒绝它：

TEST(ToCv, NullQImageReturnsError) {
    QImage nullImg;
    auto r = to_cv<ConvertionalMethod::Copy>(nullImg);
    EXPECT_FALSE(r.has_value());
    EXPECT_EQ(r.error(), ConvertionalError::InternalError);
}

不支持的格式也被正确拒绝了——CV_32FC1（浮点）、CV_16UC1（16位）、CV_8UC2（双通道）都会返回 UnsupportedFormat，Qt 端的 Format_Mono 和 Format_Indexed8 同样如此。这些格式在各自的目标类型里都不存在对应的表示方式，拒绝它们是合理的。

实际项目里你可能会遇到 QImage 加载了一张带调色板的 PNG，格式是 Format_Indexed8——直接转 to_cv 会失败。你需要先调用 QImage::convertToFormat(QImage::Format_Grayscale8) 或 Format_RGB888 把它转成标准格式，然后再桥接。这不是 edgecv 的限制，而是 QImage 的调色板格式在 cv::Mat 里没有直接对应物，任何桥接库都得面对这个问题。

实际使用场景

让我们用一个完整的例子把这一章的内容串起来。下面这段代码来自 edgecv 的 examples/qt/cv_qt_convert/main.cpp，展示了典型的桥接使用模式：

// 创建一张 BGR 的 Mat（蓝色填充，因为 OpenCV 里 B=255, G=0, R=0 是蓝色）
cv::Mat mat(100, 200, CV_8UC3, cv::Scalar(255, 0, 0));

// Copy 模式桥接——安全，独立
auto qimg_copy = cvw::from_cv<cvw::ConvertionalMethod::Copy>(mat);
if (qimg_copy.has_value()) {
    std::cout << "Copy mode: " << qimg_copy->width() << 'x'
              << qimg_copy->height() << '\n';
}

// Shared 模式桥接——零拷贝，但 mat 必须活得比 qimg_shared 长
auto qimg_shared = cvw::from_cv<cvw::ConvertionalMethod::Shared>(mat);
if (qimg_shared.has_value()) {
    std::cout << "Shared mode: shares memory with Mat\n";
}

反向也类似——从 QImage 创建 Mat：

QImage qimage(100, 100, QImage::Format_RGB888);
qimage.fill(Qt::red);   // Qt 里 fill(Qt::red) 设置 R=255, G=0, B=0

auto mat_copy = cvw::to_cv<cvw::ConvertionalMethod::Copy>(qimage);
auto mat_shared = cvw::to_cv<cvw::ConvertionalMethod::Shared>(qimage);

在实际的 Qt 应用里，最常见的模式是这样的：后台线程用 OpenCV 处理图像，处理完后通过 from_cv<Copy> 转成独立的 QImage，然后通过信号槽发送给 GUI 线程显示。这里必须用 Copy 模式，因为后台线程的 cv::Mat 在下一次处理循环时会被覆盖，如果你用 Shared 模式，GUI 线程显示的时候数据可能已经变了。反过来，从 GUI 线程拿到的 QImage 需要传给后台处理时，如果 QImage 是短期临时对象就用 Copy，如果是长期持有的（比如从文件加载后缓存的）就可以用 Shared。

总结一下 edgecv 的 Qt 桥接设计哲学：格式映射明确、内存策略由调用者显式选择、不做隐式的通道重排、错误通过 expected 报告而不是抛异常。这套设计让你在 Qt 和 OpenCV 之间切换时有充分的控制权，不会被隐式行为坑到——虽然这也意味着你需要自己对 BGR/RGB 转换和生命周期管理负责，但至少每个决定都是你自己做的，出了问题也知道自己该查哪里。