edgecv

现代 C++20 计算机视觉库 | A Modern C++20 Computer Vision Library

编译期类型安全、零拷贝视图、Expected 错误处理——从零手搓的视觉库

特性

• 🛡️ 编译期格式标签 — 用空结构体表示像素格式，格式不匹配直接编译报错，不再等到运行时才爆炸
• ⚡ Expected 错误处理 — 从零手搓 expected<T, E> 含单子操作，不依赖异常机制，嵌入式友好
• 🖼️ Image / ImageView — 强类型图像容器，明确区分拥有和借用语义，零拷贝视图
• 🔬 算法封装 — 颜色转换、滤波、边缘检测、几何变换，受 Concepts 约束的算法接口
• 🔗 Pipeline 管线 — operator| 组合链，make_pipeline 自动推导，错误自动短路
• 🎨 Qt 桥接 — cv::Mat 与 QImage 零拷贝互转，格式对齐与生命周期管理
• 📦 Header-only — 核心库完全由头文件组成，集成只需包含头文件 + 链接 OpenCV
• 🏗️ 嵌入式就绪 — 支持 -fno-exceptions / -fno-rtti，提供 ARM 交叉编译工具链

快速开始

前置依赖

依赖	版本要求	说明
C++ 编译器	GCC 12+ / Clang 15+ / MSVC 19.28+	需支持 C++20
CMake	3.22+	构建系统
OpenCV	4.x	core, imgproc, imgcodecs 模块
Qt	6.x（可选）	桥接模块需要

克隆与构建

git clone https://github.com/Awesome-Embedded-Learning-Studio/edgecv.git
cd edgecv
cmake -B build
cmake --build build -j$(nproc)
ctest --test-dir build --output-on-failure

作为依赖集成

edgecv 是 header-only 库，最简集成方式：

# 方法 1：add_subdirectory
add_subdirectory(edgecv)
target_link_libraries(your_target PRIVATE edgecv)

# 方法 2：直接包含头文件（需自行处理 OpenCV 依赖）
target_include_directories(your_target PRIVATE edgecv/include)

用法示例

Pipeline 管线

#include <cvw/cvw.hpp>

using namespace cvw;
using namespace cvw::pipe_ops;

int main() {
    // 加载 BGR 图像 → 缩放 → 灰度化 → 高斯去噪 → Canny 边缘检测
    auto result = load<BGR>("input.png")
        | steps::resize(320, 240)
        | steps::to_gray()
        | steps::gaussian_blur(5)
        | steps::canny(50, 150);

    if (result) {
        save(*result, "edges.png");
    } else {
        // 错误自动短路：任意步骤失败都会立即传播
        std::cerr << "Pipeline failed\n";
    }

    // 可复用的管线对象
    auto edge_detector = make_pipeline(
        steps::resize(320, 240),
        steps::to_gray(),
        steps::gaussian_blur(5),
        steps::canny(50, 150)
    );

    auto img1 = edge_detector(load<BGR>("photo1.png").value());
    auto img2 = edge_detector(load<BGR>("photo2.png").value());
}

编译期类型安全

Image<BGR> color(640, 480);
Image<Gray> gray(640, 480);

to_gray(color);     // ✓ BGR → Gray
to_gray(gray);      // ✗ 编译错误: Gray → Gray 无意义，Concepts 约束报错

构建选项

选项	默认值	说明
CVW_BUILD_TESTS	ON	构建 GoogleTest 测试套件
CVW_BUILD_EXAMPLES	ON	构建示例程序
CVW_WITH_QT	ON	启用 Qt 桥接模块（找不到 Qt 时自动跳过）
CVW_NO_EXCEPTIONS	OFF	禁用异常（-fno-exceptions / /EHs-）
CVW_NO_RTTI	OFF	禁用 RTTI（-fno-rtti / /GR-）
CVW_BUILD_OPENCV	OFF	从 third_party/opencv 子模块编译 OpenCV

# 最小构建（无测试、无示例、无 Qt）
cmake -B build -DCVW_BUILD_TESTS=OFF -DCVW_BUILD_EXAMPLES=OFF -DCVW_WITH_QT=OFF

# 嵌入式交叉编译（ARM）
cmake -B build-arm --toolchain cmake/arm-linux-gnueabihf.cmake \
      -DCVW_BUILD_TESTS=OFF -DCVW_BUILD_EXAMPLES=OFF

# 从源码编译 OpenCV
git submodule update --init third_party/opencv
cmake -B build -DCVW_BUILD_OPENCV=ON

文档

完整教程与 API 文档请访问：edgecv 文档站

• 教程系列：从零手搓 edgecv — 8 章逐步讲解设计与实现
• C++20 补课 — Concepts、Expected、span 等前置知识
• API 参考 — Doxygen 生成的完整 API 文档

参与贡献

欢迎贡献代码、报告问题或提出建议！请阅读 CONTRIBUTING.md 了解：

• 代码风格（.clang-format + .clang-tidy）
• 提交 PR 的流程
• Issue 报告模板

许可证

本项目基于 MIT License 开源。

Copyright (c) 2026 Charliechen

致谢

• OpenCV — 底层图像处理引擎（Apache 2.0）
• Qt — GUI 图像互操作桥接
• GoogleTest — 测试框架
• VitePress — 文档站点构建

---

English

edgecv is a modern C++20 computer vision library designed for education. It provides compile-time type-safe pixel format tags, zero-copy image views, a custom expected<T, E> for exception-free error handling, and a pipeline composition API with operator|.

Key features: header-only, CMake 3.22+, OpenCV 4.x backend, Qt6 bridging, ARM cross-compile support, -fno-exceptions compatible.

Documentation | Tutorials | API Reference