核心图像类型——Image<F>、ImageView<F> 与 ImageBuilder<F>

如果你之前用 OpenCV 写过图像处理代码，那你一定跟 cv::Mat 打过不少交道。说实话 cv::Mat 能干活，但它有一个让人非常头疼的问题——它是动态类型的。你可以在运行时把一张 CV_8UC3 的 BGR 彩色图像塞给一个期望灰度图的函数，编译器完全不会拦你，等到运行时才发现数据全乱了。这种 bug 特别难查，因为图像数据"看起来"像是对的，只是通道数或者像素类型不对。

edgecv 的核心设计思路就是把这些信息全部提升到编译期。Image<BGR> 和 Image<Gray> 是完全不同的类型，你根本不可能把前者悄悄传给一个需要后者的函数——编译器直接报错，连运行的机会都不给你。这一章我们就来搞清楚 edgecv 里三个最核心的图像类型：只读视图 ImageView<F>、可变视图 ImageMutView<F>、以及拥有所有权的图像容器 Image<F>，最后再看负责从磁盘加载图像的 ImageBuilder<F>。

从 ImageView<F> 说起——不拥有数据的"窗口"

我们先看最简单的 ImageView<F>。为什么先讲它而不是 Image<F>？因为 ImageView 不依赖 cv::Mat 来理解它的本质——它就是一个指向外部内存的轻量级非拥有视图。如果你对"非拥有视图"这个概念还不太熟悉，请先阅读 primer/span-and-views.md，那里我们详细解释了为什么需要这种设计。

来看看它的定义：

template <is_pixel_format F>
class ImageView {
    const value_type* data_ = nullptr;
    int width_  = 0;
    int height_ = 0;
    size_t stride_ = 0;
    // ...
};

四个成员变量，干净利落。data_ 是一个 const 指针，指向外部的像素数据缓冲区；width_ 和 height_ 是图像的宽高；stride_ 稍微有点讲究，我们待会儿单独说。默认构造函数会把所有字段初始化为零，所以默认构造出来的 ImageView 是一个"空视图"，调用 empty() 会返回 true。

你可能注意到了模板参数 F 必须满足 is_pixel_format 这个 concept。在 edgecv 里，像素格式是通过标签类型来表达的，比如 BGR、Gray、Float1 等等，每个标签都带有 channels 和 value_type 两个编译期信息：

struct BGR {
    static constexpr int channels = 3;
    using value_type = uint8_t;
};

这样一来，ImageView<BGR>::value_type 就是 uint8_t，channels() 返回 3，全部在编译期确定，没有任何运行时开销。

像素访问与 stride 的故事

ImageView 的像素访问通过 at(row, col, ch) 完成：

[[nodiscard]] const value_type& at(int row, int col, int ch = 0) const noexcept {
    return data_[row * stride_ + col * F::channels + ch];
}

这个公式 row * stride_ + col * channels + ch 就是经典的二维像素寻址方式。这里 stride_ 表示的是一行有多少个 value_type 元素（不是字节数）。对于一张没有任何行填充的 BGR 图像来说，stride 就等于 width * 3，非常直观。

但 ⚠️ stride 不总是 width * channels。在某些场景下（比如 ROI 操作、或者底层库为了内存对齐做了行填充），每行末尾可能会有额外的 padding 字节。如果你手写 row * width * channels + col * channels + ch 来访问像素，一旦遇到有填充的图像数据就会踩到错误的位置。edgecv 通过显式的 stride_ 字段来避免这个问题，而 stride 的值总是从 cv::Mat::step 正确计算得来的，后面讲到 Image 的时候你会看到具体怎么算的。

ImageView 还提供了 data() 返回裸指针、empty() 判断是否为空（实现方式就是检查 data_ == nullptr）。这些接口都很轻量，不涉及任何堆分配。

很好，现在我们理解了只读视图。接下来看它的可变版本。

ImageMutView<F>——可以写数据的视图

ImageMutView 和 ImageView 几乎一模一样，唯一的本质区别是它的内部指针是 value_type* 而不是 const value_type*，这意味着你可以通过它修改像素数据。at() 方法返回的是非常量引用：

[[nodiscard]] value_type& at(int row, int col, int ch = 0) noexcept {
    return data_[row * stride_ + col * F::channels + ch];
}

此外它还提供了一个很有用的降级方法 as_const_view()，可以把可变视图转换成只读的 ImageView：

[[nodiscard]] ImageView<F> as_const_view() const noexcept {
    return ImageView<F>(data_, width_, height_, stride_);
}

这在函数传参的时候非常方便——如果你的函数只需要读图像数据，你可以接受 ImageView，调用者即使手里拿的是 ImageMutView，也可以通过 as_const_view() 安全地传给你，编译器会确保你不会意外修改数据。

从测试里我们可以看到这个"通过视图修改原始数据"的特性是怎么工作的：

TEST(ImageMutView, ModifyThroughView) {
    Image<BGR> img(4, 4, 0);
    auto mv = img.mutable_view();
    mv.at(2, 3, 1) = 200;
    EXPECT_EQ(img.at(2, 3, 1), 200);  // 通过视图的修改反映到了原始 Image 上
}

这里有一个非常关键的生命周期问题。视图不拥有数据，它只是一个指针的薄包装。所以 ⚠️ 如果原始的 Image 被销毁了或者被移动了，你手里的视图就变成了悬空指针（dangling pointer），再通过它访问数据就是未定义行为。这跟原生的 std::string_view 指向已销毁的 std::string 是同一个坑。如不熟悉 RAII 和移动语义，请参阅 primer/raii-and-move-semantics.md。

好，视图讲完了，接下来我们进入重头戏——Image<F>。

Image<F>——拥有像素数据的类型安全容器

终于到了 Image<F>。我们先来看类声明中的关键部分，搞清楚它的设计哲学：

template <is_pixel_format format_type>
class Image {
public:
    using value_type = format_type::value_type;

    Image() = default;
    Image(int width, int height);
    Image(int width, int height, value_type fill_value);
    explicit Image(cv::Mat image);

    // 移动语义：允许，零成本
    Image(Image&&) noexcept = default;
    Image& operator=(Image&&) noexcept = default;

    // 拷贝语义：禁止！想要深拷贝请显式调用 clone()
    Image(const Image&) = delete;
    Image& operator=(const Image&) = delete;

    [[nodiscard]] Image clone() const;

    // ... 视图、访问器、convert_to 等方法
private:
    cv::Mat mat_;
};

这里有几个设计决策值得说道说道。

首先，Image 的底层存储就是一个 cv::Mat mat_。没错，edgecv 并没有重新发明轮子，它把 OpenCV 的内存管理直接拿来用了。cv::Mat 本身使用引用计数来管理内存，所以移动操作天然是零成本的——只是偷走指针和引用计数而已。

其次，拷贝构造被显式 delete 了。这是故意的。图像数据通常很大（一张 4K 的 BGR 图就是 24MB），隐式拷贝会导致难以察觉的性能问题。如果你真的需要一份独立的副本，必须显式调用 clone()，这样一来每个深拷贝都在代码里留下了明确的痕迹：

Image<BGR> original(1920, 1080, 128);
auto copy = original.clone();    // OK，显式深拷贝
copy.at(0, 0, 0) = 0;
// original 不受影响

第三，几乎所有返回值的方法都标记了 [[nodiscard]]。你会看到像 view()、data()、convert_to() 这些方法，如果你调用了但没用返回值，编译器会直接给你一个警告。这可不是多余的——想象一下你写了 img.convert_to<Gray>() 但忘了接收返回值，新图像被丢掉了，你还在纳闷为什么 img 还是彩色的。

构造函数们

Image 提供了四种构造方式。默认构造创建一个空图像（底层 cv::Mat 为空，empty() 返回 true）。宽高构造分配内存但不初始化。带填充值的构造会把所有像素设成你指定的值：

Image<BGR> blank(640, 480);        // 640x480，像素值未定义
Image<BGR> white(640, 480, 255);   // 640x480，所有通道都是 255
Image<Gray> gray_img(8, 8, 42);    // 8x8 灰度图，所有像素值为 42

还有一个从 cv::Mat 构造的 explicit 构造函数，这是跟 OpenCV 世界的桥梁。它使用移动语义来接管 cv::Mat 的内部数据，避免不必要的拷贝：

cv::Mat m(100, 200, CV_8UC3, cv::Scalar(10, 20, 30));
Image<BGR> img(std::move(m));   // img 接管了 m 的数据

⚠️ 这里有一个容易踩的坑：Image<BGR> 的构造函数并不会验证传入的 cv::Mat 类型是否真的是 CV_8UC3。如果你传入了一个 CV_8UC1 的灰度 Mat，编译不会报错，但后续的所有操作都会产生错误的结果。这属于"信任用户"的设计——在 edgecv 的哲学里，从 cv::Mat 构造 Image 是一个 escape hatch，需要你自己保证类型正确。

事情到这里还没完，我们还需要理解 cv::Mat 的类型系统和 edgecv 的像素格式之间是怎么桥接的。

桥接层——detail::cv_depth 和 detail::cv_type

在 details/image_impl.hpp 里，有两个模板函数负责把 C++ 类型和 edgecv 像素格式映射到 OpenCV 的类型常量。

第一个是 cv_depth<T>()，它把 C++ 的标量类型映射到 OpenCV 的深度常量：

template <typename T> constexpr int cv_depth() {
    if constexpr (std::is_same_v<T, uint8_t>)  return CV_8U;
    else if constexpr (std::is_same_v<T, uint16_t>) return CV_16U;
    else if constexpr (std::is_same_v<T, float>)    return CV_32F;
    else if constexpr (std::is_same_v<T, double>)   return CV_64F;
    else static_assert(!std::is_same_v<T, T>, "Unsupported pixel value type");
}

这个 static_assert(!std::is_same_v<T, T>, ...) 是一个挺巧妙的技巧——因为 T 永远等于 T，所以这个 static_assert 永远失败。但 if constexpr 的分支在编译时就已经排除了不匹配的情况，所以只有当你真的传入了一个不支持的类型时才会触发。而且把它放在最后的 else 分支里，可以得到一条比"template instantiation failed"更清晰的错误信息。

第二个是 cv_type<F>()，它组合了深度和通道数，生成 OpenCV 的完整类型码：

template <is_pixel_format F> constexpr int cv_type() {
    return CV_MAKETYPE(cv_depth<typename F::value_type>(), F::channels);
}

比如 cv_type<BGR>() 就是 CV_MAKETYPE(CV_8U, 3) 也就是 CV_8UC3，cv_type<Float1>() 就是 CV_32FC1。这两个函数在构造函数和类型转换时被大量使用，是 edgecv 类型系统和 OpenCV 运行时类型系统之间的翻译层。

访问器与 stride 的计算

有了前面的铺垫，Image 的访问器实现就很好理解了。width() 直接返回 mat_.cols，height() 返回 mat_.rows，size_bytes() 是 mat_.total() * mat_.elemSize()。data() 用 reinterpret_cast 把 mat_.data（uchar* 类型）转换成 value_type*：

auto Image<format_type>::data() noexcept -> value_type* {
    return reinterpret_cast<value_type*>(mat_.data);
}

然后是 stride 的计算，这可能是最容易出错的地方：

size_t Image<format_type>::stride() const noexcept {
    return mat_.step;
}

等等，这里返回的是 mat_.step，是字节数。但是在创建视图的时候：

ImageView<format_type> Image<format_type>::view() const noexcept {
    return ImageView<format_type>(data(), width(), height(),
                                  mat_.step / sizeof(value_type));
}

注意传给 ImageView 构造函数的 stride 参数是 mat_.step / sizeof(value_type)，也就是把字节数除以单个元素的大小，转换成"一行有多少个 value_type 元素"。这正是 ImageView::at() 里那个 row * stride_ + col * F::channels + ch 公式所需要的单位。

你可能会问，为什么要这么麻烦地除一下？直接在视图里用字节 stride 不行吗？当然可以，但那样的话 at() 的计算就会变成 row * stride_ + col * F::channels * sizeof(value_type) + ch * sizeof(value_type)，到处都是乘法，不但更容易写错，而且性能上也不划算。在视图层面统一用"元素个数"作为 stride 的单位，代码更干净，计算也更高效。

view() 与 mutable_view()——零拷贝借用

Image 提供了三个视图方法：view() 返回只读的 ImageView，mutable_view() 返回可写的 ImageMutView，const_view() 返回 ImageView<const F>。

这三个方法的实现都是零拷贝的——它们只是把 cv::Mat 内部的数据指针和尺寸信息包装成视图对象：

ImageView<format_type> Image<format_type>::view() const noexcept {
    return ImageView<format_type>(data(), width(), height(),
                                  mat_.step / sizeof(value_type));
}

视图和原始 Image 共享同一块内存。这意味着通过 mutable_view() 修改像素会立即反映到 Image 上，反过来也一样。我们在前面看到的测试用例就验证了这一点。

⚠️ 再次强调生命周期问题：视图的生命周期绝不能超过它所引用的 Image。下面这种代码就是典型的 use-after-free：

ImageView<BGR> get_view() {
    Image<BGR> img(100, 100);
    return img.view();   // img 在函数结束时销毁，返回的视图变成悬空指针！
}

如果你需要把图像传出函数，要么返回 Image 本身（利用移动语义，零成本），要么返回一个 clone() 出来的副本。视图只应该在同一个作用域内或者调用链中短暂使用。

convert_to<NewFormat>()——整个库最核心的转换逻辑

如果你问我 edgecv 的 Image 里哪个方法最重要，我会毫不犹豫地说是 convert_to<NewFormat>()。这个方法把图像从一种像素格式转换成另一种，比如 BGR 转灰度、uint8_t 转浮点、RGB 和 BGR 互换等等。它返回 expected<Image<NewFormat>, ConversionalError>，用类型安全的方式处理可能的失败情况。

转换过程分两步走：先做颜色空间转换（如果需要的话），再做数值类型转换（如果需要的话）。

第一步：颜色空间转换

在编译期，一个 consteval 函数 cvt_color_code<Src, Dst>() 会根据源格式和目标格式的组合，返回对应的 OpenCV 颜色转换码。这个函数写得相当详细，覆盖了所有支持的格式对之间的转换：

template <typename Src, typename Dst> consteval int cvt_color_code() {
    if constexpr (std::is_same_v<Src, Dst>) {
        return -1;   // 同格式，不需要颜色转换
    }
    // BGR 家族内部也不需要转换
    if constexpr ((std::is_same_v<Src, BGR> || std::is_same_v<Src, Float3>) &&
                  (std::is_same_v<Dst, BGR> || std::is_same_v<Dst, Float3>)) {
        return -1;
    }
    // BGR -> RGB
    if constexpr (std::is_same_v<Src, BGR> && std::is_same_v<Dst, RGB>) {
        return cv::COLOR_BGR2RGB;
    }
    // ... 其余转换码 ...
    return -2;   // 不支持的组合
}

这里用了几个特殊值：-1 表示不需要颜色转换（同格式或者同族格式，比如 BGR 和 Float3 都属于三通道颜色族），-2 表示完全不支持的格式组合。因为整个函数是 consteval，所以这些分支全部在编译期求值，运行时零开销。

当返回 -2 时，convert_to() 会在编译期就通过 if constexpr 走到一个返回错误的分支，而不会调用 cvtColor。不过由于 static_assert 不太容易在这里使用（我们确实想让某些组合编译通过但运行时报错），所以选择了 expected 的错误返回方式。

第二步：数值类型转换

颜色空间转换完成后，如果源和目标的 value_type 不同，还需要做一步数值转换。这里最关键的就是缩放因子（scale）的选择：

if constexpr (std::is_same_v<Src::value_type, uint8_t> &&
              std::is_same_v<DstVT, float>) {
    scale = 1.0 / 255.0;
} else if constexpr (std::is_same_v<Src::value_type, float> &&
                     std::is_same_v<DstVT, uint8_t>) {
    scale = 255.0;
} else if constexpr (std::is_same_v<Src::value_type, uint8_t> &&
                     std::is_same_v<DstVT, uint16_t>) {
    scale = 257.0;  // 65535 / 255 ≈ 257
}

这里面最常用的就是 uint8_t -> float 的 1/255 缩放。在计算机视觉里，我们经常需要把 [0, 255] 的像素值归一化到 [0.0, 1.0] 的浮点范围，用于神经网络推理或者其他数值计算。edgecv 把这个缩放逻辑内置到了 convert_to 里，你不需要手动去写 pixel / 255.0f。

测试里清楚地展示了这一点：

TEST(Image, ConvertGrayToFloat) {
    Image<Gray> img(2, 2, 255);
    auto f = img.convert_to<Float1>();
    ASSERT_TRUE(f.has_value());
    EXPECT_NEAR(f->at(0, 0, 0), 1.0f, 1e-5f);  // 255 → 1.0
}

反过来，float -> uint8_t 的转换会用 255.0 作为缩放因子，这在前处理的逆过程中很常见。uint8_t <-> uint16_t 之间的缩放因子是 257.0 和 1/257.0，这是因为 65535 / 255 = 257，正好覆盖 16 位的完整范围。

特殊情况

整个 convert_to 方法还有两个边界情况需要处理。如果图像是空的（empty() 返回 true），直接返回错误——对空图像做转换没有任何意义。另外如果颜色转换码是 -2（不支持的组合），也会返回错误。这两种情况都通过 expected 的错误通道返回，而不是抛异常或者触发未定义行为。

来看一个完整的转换示例，体会一下整个流程：

Image<BGR> img(4, 4);
img.at(0, 0, 0) = 10;  // B
img.at(0, 0, 1) = 20;  // G
img.at(0, 0, 2) = 30;  // R

auto rgb = img.convert_to<RGB>();
ASSERT_TRUE(rgb.has_value());
EXPECT_EQ(rgb->at(0, 0, 0), 30);  // R = 原来的 R 通道
EXPECT_EQ(rgb->at(0, 0, 1), 20);  // G = 不变
EXPECT_EQ(rgb->at(0, 0, 2), 10);  // B = 原来的 B 通道

BGR 转 RGB 就是交换 R 和 B 通道的位置。因为 value_type 都是 uint8_t，所以不会触发数值转换步骤，cvtColor 之后就直接返回了。

真正的坑在后面——BGR 和 RGB 的混淆可能是计算机视觉里最常见的 bug 之一。OpenCV 默认使用 BGR 排列，但很多其他库（包括主流的深度学习框架）使用 RGB。如果你的代码里同时用了两种排列，颜色就会看起来很奇怪——不是完全错乱，而是红蓝互换，肉眼看不出来但数值完全不对。edgecv 通过类型系统把 BGR 和 RGB 区分开来，convert_to<RGB>() 会帮你正确地交换通道顺序。

ImageBuilder<F>——从磁盘加载图像

最后我们来看 ImageBuilder<F>，它是负责从文件加载图像的工具类。接口非常简洁：

template <is_pixel_format format_type>
class ImageBuilder {
public:
    expected<Image<format_type>, LoadError> load(std::string_view path);
};

调用方式就是创建一个指定格式的 builder，然后调用 load()：

cvw::ImageBuilder<cvw::BGR> bgr_builder;
auto bgr_result = bgr_builder.load("photo.png");
if (!bgr_result.has_value()) {
    std::cerr << "Failed to load: "
              << static_cast<int>(bgr_result.error()) << '\n';
    return;
}
auto& bgr = bgr_result.value();

返回类型是 expected<Image<format_type>, LoadError>，其中 LoadError 有两个枚举值：FileOpenFailed（文件不存在或无法读取）和 UnsupportedConversion（请求的格式当前不支持加载）。

内部实现

ImageBuilder 的实现同样依赖 OpenCV。首先根据目标像素格式选择合适的 imread 标志位：

template <is_pixel_format F> constexpr int imread_flag() {
    if constexpr (std::is_same_v<F, Gray> || std::is_same_v<F, Float1>) {
        return cv::IMREAD_GRAYSCALE;
    } else if constexpr (std::is_same_v<F, Gray16>) {
        return cv::IMREAD_ANYDEPTH;
    } else if constexpr (std::is_same_v<F, BGRA> || std::is_same_v<F, RGBA>) {
        return cv::IMREAD_UNCHANGED;   // 保留 alpha 通道
    } else {
        return cv::IMREAD_COLOR;       // 默认三通道 BGR
    }
}

这个选择很合理——加载灰度图时直接让 OpenCV 做灰度转换，加载带 alpha 的图像时用 IMREAD_UNCHANGED 保留四个通道，其余情况用 IMREAD_COLOR 加载标准 BGR。

加载之后的后处理逻辑也很精巧。如果目标格式是 BGR、BGRA、Gray 或 Gray16，OpenCV imread 的输出已经就是正确的格式了，直接移动构造即可。如果是 RGB，需要做一次 cvtColor(BGR2RGB) 转换。如果是 Float1 或 Float3，除了读取之外还要做 convertTo 操作，把 uint8_t 的像素值缩放到 [0.0, 1.0] 的浮点范围：

if constexpr (std::is_same_v<format_type, Float3>) {
    raw.convertTo(converted, CV_32FC3, 1.0 / 255.0);
}

这里又出现了我们之前在 convert_to 里看到的 1.0 / 255.0 缩放因子。edgecv 在 ImageBuilder 和 convert_to 两个地方都处理了 uint8 到 float 的转换，保持了语义的一致性。

完整示例

把 ImageBuilder 和前面学到的内容串起来，一个典型的加载-转换-处理流程是这样的：

// 从文件加载 BGR 图像
cvw::ImageBuilder<cvw::BGR> builder;
auto result = builder.load("input.png");
if (!result.has_value()) return;

auto& bgr = result.value();

// 转成灰度图
auto gray = bgr.convert_to<cvw::Gray>();
if (!gray.has_value()) return;

// 创建只读视图
auto view = gray->view();
std::cout << "Pixel at (0,0): "
          << static_cast<int>(view.at(0, 0, 0)) << '\n';

这里值得注意的一点是 convert_to 的返回值是一个 expected，所以在链式操作之前你需要先检查是否成功。虽然多写了一行 has_value() 检查，但这比运行时莫名其妙地 crash 要好得多。

把所有东西放在一起——示例程序解析

examples/image/ 目录下有三个示例程序，分别演示了 Image、视图和 ImageBuilder 的基本用法。

basic_image.cpp 展示了 Image 的构造、像素访问、类型转换和克隆/移动操作。其中像素访问的代码很典型：

cvw::Image<cvw::BGR> filled(320, 240, 128);
filled.at(10, 10, 0) = 255;  // B 通道
filled.at(10, 10, 1) = 255;  // G 通道
filled.at(10, 10, 2) = 0;    // R 通道

注意 at(row, col, ch) 的参数顺序——行、列、通道。这跟 OpenCV 的 cv::Mat::at<Vec3b>(row, col)[ch] 是一致的，但跟某些图像库的 (x, y) 顺序不同，容易搞混。

image_view.cpp 演示了三种视图的用法：view() 获取只读视图、mutable_view() 获取可写视图、以及 as_const_view() 从可写视图降级为只读视图。这三个视图都指向同一份底层数据，任何通过可写视图的修改都会立即在其他视图和原始 Image 上可见。

image_builder.cpp 展示了如何用不同格式加载同一张图像，以及错误路径的处理。它会尝试以 BGR、Gray、RGB 三种格式加载同一个文件，然后故意加载一个不存在的路径来演示 FileOpenFailed 错误。

小结

这一章我们认识了 edgecv 的三个核心图像类型。Image<F> 是拥有像素数据的类型安全容器，底层用 cv::Mat 管理内存，禁止隐式拷贝，强制你用 clone() 来做深拷贝。ImageView<F> 和 ImageMutView<F> 是非拥有的轻量级视图，前者只读后者可写，通过 as_const_view() 可以从可写降级为只读。ImageBuilder<F> 从磁盘加载图像并自动处理格式转换，通过 expected 返回值来优雅地处理加载失败的情况。

convert_to<NewFormat>() 是整个类型系统里最精妙的部分，它把颜色空间转换和数值类型转换拆成两个独立步骤，通过编译期的 consteval 函数映射 OpenCV 的颜色转换码，并在类型不同时自动应用正确的缩放因子。所有这些复杂性都被封装在一个简洁的模板方法调用背后，你只需要写 img.convert_to<Gray>() 就行了。

接下来的章节我们会基于这些基础类型构建更高级的图像处理操作。理解了 Image、ImageView 和 ImageMutView 之间的关系，后面的内容就会顺畅很多。