前言：为什么要造这个轮子

如果你用过 OpenCV 的 C++ API，大概对这种经历不陌生：代码写得好好的，编译也过了，运行起来却直接 segfault——最后排查半天发现是 cv::Mat 的类型不匹配，你把一张 CV_8UC1 的灰度图塞给了期望 CV_8UC3 的函数。这种错说大不大，但每次调试都浪费好几个小时，而且最气人的是编译器完全帮不上忙，因为这些信息全是运行时的。我们做了这么久的 C++ 工程，明明有强大的类型系统，却在图像处理这块被动态类型拖了后腿——这感觉真的很糟糕。

OpenCV 的 cv::Mat 采用了动态类型设计，type() 返回一个 int，你拿到的就是一个类似 CV_8UC3 的魔术数字。这意味着编译器根本不知道这张图里到底存的是 BGR 还是灰度、是 uint8_t 还是 float，所有格式检查都被推迟到了运行时。更要命的是 OpenCV 的错误处理也很不一致，有的函数遇到格式不匹配会抛异常，有的默默返回一个空 Mat，有的直接返回错误码，你得挨个查文档才知道该 try-catch 还是检查 empty()。这种不一致性在大型项目里简直是灾难——你永远不知道下一个调用会以什么方式爆炸。

还有一个容易被忽略的问题：cv::Mat 的所有权语义是隐式的引用计数，拷贝一个 Mat 只是增加引用计数，修改的时候又要靠 clone() 来深拷贝。但这套机制和现代 C++ 的值语义、移动语义格格不入，在函数签名里你完全看不出一个 Mat 参数是借用还是拥有——是"我会修改你的数据"还是"我只是读一下"？const cv::Mat& 能解决一部分问题，但无法从根本上区分 view 和 owner。当项目规模一大，这种模糊的所有权语义就会让内存管理变成一团乱麻。

edgecv 想要做什么

所以我们就想：能不能在保留 OpenCV 生态兼容性的前提下，用 C++20 的类型系统把这些坑在编译期就堵上？edgecv 就是这个想法的产物。它的核心思路其实很简单，但实现起来确实需要仔细设计。

首先是编译期格式标签。我们用空结构体（比如 struct BGR）来表示像素格式，每个标签结构体里用 static constexpr 携带通道数和值类型信息。这样一来，格式信息就变成了类型的一部分——你试图把一个 Image<BGR> 传给期望 Image<Gray> 的函数，编译器直接报错，根本不会让它编译通过。相比 OpenCV 那套运行时 int 比较的方案，这种做法把错误发现的时间点从"运行时炸掉"提前到了"编译时就不让你过"，这是质的飞跃。

其次是零拷贝视图。edgecv 明确区分了"拥有数据的 Image"和"不拥有数据的 ImageView"，后者就是一个裸指针加尺寸信息，构造和拷贝几乎零开销。这样函数签名就能清楚地表达"我需要一张完整的图"还是"我只是看一下你的数据"，所有权语义一目了然。而当你确实需要深拷贝的时候，必须显式调用 clone()——没有隐式的引用计数在背后搞小动作。

然后是 Expected 风格的错误处理。我们参考了 std::expected（C++23）的设计思路，在 C++20 里自己实现了一套轻量的 Expected<T, E>。所有可能失败的函数都返回 Expected 而不是抛异常，调用方必须检查返回值才能拿到有效数据。这样的好处是错误路径是显式的、可审计的，而且完全不依赖异常机制——这对嵌入式环境非常友好，因为很多嵌入式工具链要么禁用异常（-fno-exceptions），要么异常开销不可接受。

最后是 header-only 核心库。edgecv 的核心部分完全由头文件组成，没有需要预编译的 .cpp 文件（仅有嵌入式适配模块是编译的静态库）。这意味着集成 edgecv 到你的项目只需要包含头文件目录和链接 OpenCV，不需要单独编译 edgecv 本身——这对于交叉编译和嵌入式部署来说省去了不少麻烦。

你将构建什么

在整个系列教程结束时，你手上会有一个完整的 edgecv 项目，包含以下模块：编译期像素格式标签系统（pixel_format.hpp）、Expected 错误处理框架、强类型 Image/ImageView 容器、常用算法封装、图像处理管线系统、嵌入式平台适配层，以及可选的 Qt 图像互操作桥接。项目结构大致如下：

edgecv/
├── include/cvw/          # 核心 header-only 头文件
│   ├── cvw.hpp           # 伞头文件
│   ├── core.hpp          # 核心类型（占位）
│   ├── pixel_format.hpp  # 编译期格式标签
│   ├── image.hpp         # Image / ImageView
│   ├── algorithms.hpp    # 算法封装
│   ├── pipeline.hpp      # 管线系统
│   └── embedded.hpp      # 嵌入式适配
├── src/                  # 编译模块（仅嵌入式）
├── test/                 # Google Test 单元测试
├── examples/             # 示例程序
├── cmake/                # CMake 查找/封装脚本
├── third_party/          # 子模块（OpenCV 等）
└── CMakeLists.txt        # 根构建文件

你会发现这个结构非常扁平，没有深层的目录嵌套，因为我们的目标是让每一个头文件都自解释、让构建系统一目了然。接下来每一章都会在这个骨架上添砖加瓦，从构建系统到类型系统再到算法和管线，层层递进。

如何使用这个系列

这个系列是按照依赖关系严格排序的，建议你从头到尾按顺序阅读。每一章都建立在前一章的基础上，跳着读可能会导致你错过某些关键的设计决策和上下文。比如说像素格式标签那一章解释了为什么要用空结构体而不是枚举，如果跳过这章直接看 Image 容器，你可能会对模板参数的含义感到困惑。

我们在教程中会使用不少 C++20 的特性，包括 Concepts、constexpr/consteval、std::expected 式的返回类型、范围（ranges）等。如果你对这些特性不太熟悉，不用担心——我们在相关章节会给出 primer 文档的交叉引用，比如讲到 Concepts 的时候会提醒你参阅 primer/concepts.md，讲到 constexpr 变量模板的时候会指向 primer/constexpr-and-consteval.md。这些 primer 文档不是必读的，但如果你发现自己对某个 C++ 特性不太确定，可以随时跳过去补课再回来。

我们的开发环境是这样的：C++20 标准（需要 GCC 12+ 或 Clang 15+ 以上版本的编译器），CMake 3.22 或更高版本作为构建系统，OpenCV 4.x 作为唯一的外部必需依赖。如果你还想使用 Qt 互操作功能，那么可选安装 Qt 6.x（也兼容 Qt 5.x）。整个项目在 Linux 上开发和测试，构建系统也考虑了交叉编译到 ARM 等嵌入式平台的场景。如果你的环境满足这些要求，那就让我们开始吧。