# cpp-starter

**Repository Path**: aaron-zzh/cpp-starter

## Basic Information

- **Project Name**: cpp-starter
- **Description**: 现代 C++ 开发脚手架
- **Primary Language**: Unknown
- **License**: Apache-2.0
- **Default Branch**: master
- **Homepage**: None
- **GVP Project**: No

## Statistics

- **Stars**: 0
- **Forks**: 0
- **Created**: 2025-08-15
- **Last Updated**: 2026-01-28

## Categories & Tags

**Categories**: Uncategorized

**Tags**: None

## README

# CPP-Starter

现代C++开发脚手架

## 核心特性

| **类别**       | **功能**                                    | **价值点**                      |
| -------------- | ------------------------------------------- | ------------------------------- |
| **智能构建**   | 现代模块化 CMake 架构，CPM.cmake 依赖包管理 | 支持header-only及任意规模的项目 |
| **质量保障**   | GTest 测试框架 + Codecov 覆盖               | 测试驱动开发闭环                |
| **自动化工效** | GitHub Actions 五合一流水线                 | 构建/测试/文档/多平台自动验证   |
| **代码规范**   | 强约束格式化（clang-format + cmake-format） | 统一团队编码风格                |
| **文档体系**   | Doxygen + GitHub Pages                      | 专业文档自动生成与发布          |
| **生产级支持** | Sanitizers/静态分析器集成                   | 内存安全与代码质量双重保障      |
| **依赖管理**   | 轻量级                                      | 解决依赖地狱                    |

## 目录结构

```bash
arts/
├── src/arts                    # 库源码，源文件及头文件在同一目录
├── all/                        # 一键编译所有项目
├── tests/                      # 测试代码
├── examples/                   # 库开发示例
├── standalone/                 # 应用源码，main 入口
├── docs/                       # vuepress + doxygen 文档
├── cmake/                      # CMake 模块和配置
├── tools/                      # 系统脚本和工具
├── libs/                       # 通用库封装
├── .github/workflows/          # CI 配置
├── .clang-format               # 代码格式配置
├── .cmake-format               # CMake 格式配置
├── codecov.yaml                # 代码覆盖率配置
└── CMakeLists.txt              # 主构建文件
```

## 快速开始

### 当前项目使用 CMake + Ninja + VS2022 编译

```bash
D:/program/cmake-3.29/bin/cmake -DCMAKE_BUILD_TYPE:STRING=Debug -DCMAKE_INSTALL_PREFIX:STRING=d:/arts/src/arts-scan/dist -DCMAKE_PREFIX_PATH:STRING=D:/code/cpp/dist -DBUILD_SHARED_LIBS:STRING=OFF -DUSE_CCACHE:STRING=ON -DCMAKE_EXPORT_COMPILE_COMMANDS:BOOL=TRUE --no-warn-unused-cli -S D:/arts/src/arts-scan/all -B d:/arts/src/arts-scan/build-win -G Ninj
```

1. vscode 界面，通过 `.vscode/settings.json` 配置
2. windwos + gcc 命令行
3. linux + gcc 命令行

```bash
# bash(MSYS2) 参考指令
export PATH=$PATH:/c/msys64/ucrt64/bin # 临时添加环境变量 gcc
export PATH=$PATH:/f/vs/Common7/IDE/CommonExtensions/Microsoft/CMake/CMake/bin # vs 内置 cmake
export PATH=$PATH:/d/program/bin # ninja、ccache
export PATH=$PATH:/d/program/cmake-3.31.8/bin:/d/program/Git/bin # 安装的

# cmake -S . -B build -G<gen> # <gen> can be Ninja, "Unix Makefiles", XCode, "Visual Studio 15 Win64", etc.
# cmake --build build --config Release
# cmake --install ./build --prefix ./dist/ # 支持安装到指定目录
```

### 构建全部

该项目同时提供了 `all` 目录，通过 `add_subdirectory`，支持一次性构建所有目标。

1. 已安装 `ccache --version`，`ninja --version`
2. 安装 cmake-format、clang-format: `pip install clang-format==14.0.6 cmake_format==0.6.11 pyyaml`
3. 需要手动安装的依赖库：liburing、openssl, 其他可自动下载也可提前安装，参考 `cmake/Depends.cmake`
   - 应用管理器安装：`apt install -y liburing-devel openssl`
   - 下载源码编译安装

```bash
# 开启编译缓存 -DUSE_CCACHE=ON，设置环境变量 CPM_SOURCE_CACHE(默认当前目录.cache)，需要安装 ccache
cmake -S all -B build -G "Ninja" -DUSE_CCACHE=ON # build-<linux|win>
cmake --build build

# 通过 ctest 批量运行测试，或直接运行具体测试程序
cmake --build build --target test # 或 cd build;ctest

# 格式化 需要安装 clang-format + cmake-format
cmake --build build --target format # 修改预览
cmake --build build --target check-format # 遇到错误停止
cmake --build build --target fix-format # 执行格式化

# 运行可执行程序
./build/standalone/Greeter --help
# 生成文档
cmake --build build --target GenerateDocs
```

### 编译及运行 test

```bash
cmake -S test -B build/test # -DENABLE_TEST_COVERAGE=1 测试覆盖率
cmake --build build/test
CTEST_OUTPUT_ON_FAILURE=1 cmake --build build/test --target test

# 直接运行: 
./build/test/GreeterTests
```

### 生成文档

文档会在创建[GitHub Release 版本](https://help.github.com/en/github/administering-a-repository/managing-releases-in-a-repository) 时自动构建并发布。  
若要手动构建文档执行以下命令（已安装 Doxygen, jinja2 及 Pygments）：

```bash
cmake -S docs -B build/doc
cmake --build build/doc --target GenerateDocs # 生成 doxygen 文档
cmake --build build/doc --target GenerateDocsFull # 生成 vuepress 部署的全部文档
# 预览
open build/doc/doxygen/html/index.html
```

## 图像处理流程

### 美术作品扫描处理

针对美术作品抓拍图像的智能处理流程，实现从原始图像到纯净作品的自动化处理。

1. 格式检测与预处理
目标: 检测图像格式、分辨率，进行基础优化

技术方案:
cv::imread() 读取图像
cv::getRotationMatrix2D() + cv::warpAffine() 纠正倾斜
cv::GaussianBlur() 降噪
cv::convertScaleAbs() 调整对比度和亮度

1. 条形码识别
目标: 定位并识别左上角的条形码区域

技术方案:
cv::cvtColor() 转灰度图
cv::threshold() 二值化
cv::findContours() 轮廓检测
cv::boundingRect() 获取条码边界框
ZBar/ZXing库进行条码解码

1. 作品区域检测
目标: 识别并定位中央绘画作品区域

技术方案:
cv::Canny() 边缘检
cv::HoughLinesP() 直线检测找到作品边框
cv::approxPolyDP() 多边形逼近获取矩形区域
cv::getPerspectiveTransform() 计算透视变换矩阵

1. 精确裁剪
目标: 裁剪出纯净的作品图像

技术方案:
cv::warpPerspective() 透视校正
cv::getRectSubPix() 精确裁剪
cv::resize() 标准化尺寸

#### 处理步骤

| **步骤** | **功能** | **OpenCV技术方案** |
| ---------- | ---------- | ------------------- |
| **格式检测** | 图像预处理与优化 | `cv::imread()` + `cv::getRotationMatrix2D()` + `cv::GaussianBlur()` |
| **条码识别** | 定位并解码条形码 | `cv::cvtColor()` + `cv::threshold()` + `cv::findContours()` + ZBar |
| **区域检测** | 识别作品边界 | `cv::Canny()` + `cv::HoughLinesP()` + `cv::approxPolyDP()` |
| **精确裁剪** | 提取纯净作品 | `cv::getPerspectiveTransform()` + `cv::warpPerspective()` |

#### 依赖配置

```cmake
# cmake/Depends.cmake 添加
find_package(OpenCV REQUIRED)
pkg_check_modules(ZBAR REQUIRED zbar)
```

#### 核心接口

```cpp
class ImageProcessor {
private:
    cv::Mat detectAndCorrectSkew(const cv::Mat& image);
    std::string recognizeBarcode(const cv::Mat& image);
    cv::Rect detectArtworkRegion(const cv::Mat& image);
    cv::Mat cropArtwork(const cv::Mat& image, const cv::Rect& region);
};
```

### 坐标标注模式处理

当提供条形码、标记点、内容区域的精确坐标时，采用直接定位方案，提高处理效率和准确性。

#### 标注数据结构

```cpp
struct AnnotationData {
    cv::Rect barcodeRegion;    // 条形码区域坐标
    std::vector<cv::Point2f> markerPoints;  // 标记点坐标
    cv::Rect contentRegion;    // 内容区域坐标
    float rotationAngle;       // 旋转角度(可选)
};
```

#### 坐标模式处理步骤

| **步骤** | **功能** | **技术方案** |
| ---------- | ---------- | ------------- |
| **坐标验证** | 验证标注数据有效性 | 边界检查 + 区域重叠检测 |
| **直接提取** | 基于坐标直接提取 | `cv::Rect` 直接裁剪 |
| **几何校正** | 基于标记点校正 | `cv::getPerspectiveTransform()` |
| **精确裁剪** | 按坐标精确裁剪 | `cv::Mat::operator()` 区域提取 |

#### 坐标模式接口

```cpp
class AnnotatedImageProcessor {
public:
    bool processWithAnnotation(const cv::Mat& image, const AnnotationData& annotation);
    std::string extractBarcodeByRegion(const cv::Mat& image, const cv::Rect& region);
    cv::Mat correctByMarkers(const cv::Mat& image, const std::vector<cv::Point2f>& markers);
    cv::Mat cropByRegion(const cv::Mat& image, const cv::Rect& region);
};
```

### 坐标标注工具

#### 标注方式

| **方式** | **工具** | **适用场景** | **精度** |
| ---------- | ---------- | ------------- | ---------- |
| **手动标注** | 自定义GUI工具 | 少量模板 | 最高 |
| **半自动** | OpenCV + 人工校正 | 批量处理 | 高 |
| **模板匹配** | 基于标准模板 | 标准化格式 | 中等 |

#### 标注数据格式

```json
{
  "template_id": "art_exam_2024",
  "image_size": {"width": 2480, "height": 3508}, // 拍摄图片大小
  "barcode_region": {"x": 50, "y": 50, "width": 200, "height": 100},
  "marker_points": [
    {"x": 100, "y": 200},
    {"x": 2380, "y": 200},
    {"x": 2380, "y": 3300},
    {"x": 100, "y": 3300}
  ],
  "content_region": {"x": 150, "y": 350, "width": 2180, "height": 2800}
}
```

#### 标注复用策略

条件 是否需要重新标注 说明
试卷格式相同 ❌ 不需要 同一套试卷模板可复用
相机位置固定 ❌ 不需要 固定支架，位置不变
相机参数不变 ❌ 不需要 焦距、角度、高度固定
试卷格式变更 ✅ 需要 新的试卷布局
相机位置调整 ✅ 需要 支架移动或角度改变

## 注意

VS Code 通过插件 CMake Tools 并采用 Visual Studio Community 2022 Release - amd64 编译时，报错或无响应：

- [ctest] 运行 ctest 来确定可用的测试可执行文件时出错。
- 无响应：Cmake 无法执行配置，运行无响应，cmake.cleanConfigure 已完成(已返回 -1)

查看全部环境变量中是否有**中文路径**，去掉或修改

## 提交发布规范

校验工具​​：`@commitlint/cli` + `@commitlint/config-conventional`（确保消息合规）。
​​交互工具​​：`commitizen` + `@commitlint/cz-commitlint` + `inquirer`（降低使用门槛）。
版本管理和发布工具: ​semantic-release​
根据提交信息自动生成版本及发行日志（github）