计算机视觉 / 系统课时

建立标准项目结构

建立标准项目结构

一个 OpenCV 项目如果把脚本、原始图片、模型、配置和运行结果混在同一目录,几次实验后就很难复现。下面建立一套适合中小型视觉项目的工程骨架,并明确哪些内容应只读、哪些可以清理、哪些必须纳入版本控制。

学习目标

  • 能规划 src、data、models、configs、outputs 和 tests 的职责边界。
  • 能用脚本一次性创建可复用的 OpenCV 项目骨架。
  • 能判断哪些文件应提交到 Git,哪些结果应保持在本地或外部存储。

先确定目录职责

推荐把“源数据”和“派生结果”分开。data/raw 只放原始输入,处理后的图片进入 data/processed;程序代码放 src;模型权重放 models;可调参数放 configs;每次运行的图片、日志和指标写入 outputs;自动化检查放 tests。

路径 放什么 默认规则
src/ OpenCV 处理代码、入口脚本 纳入版本控制
data/raw/ 原始图片或视频 尽量只读,不被程序覆盖
data/processed/ 裁剪、缩放、标注转换后的派生数据 可重新生成时不必提交
models/ ONNX、TensorFlow、PyTorch 等模型文件 大文件优先放对象存储或发布附件
configs/ YAML/JSON 参数 纳入版本控制
outputs/ 可视化结果、日志、指标 默认加入 .gitignore
tests/ 单元测试和小型固定样本 纳入版本控制

OpenCV 标准工程目录与数据流关系

这套结构不是为了增加目录数量,而是为了让“输入事实”和“运行产物”分离。只要保证原始输入不会被覆盖,同一份代码和配置就可以重复生成处理结果。

一次性创建工程骨架

下面的 Python 脚本跨 Windows、macOS 和 Linux,可重复执行;已存在的目录不会报错,已有文件也不会被覆盖。运行后会创建目录,并写入最小配置、.gitignore 和入口文件。

python
from pathlib import Path

root = Path("opencv-demo")
dirs = [
    "src",
    "data/raw",
    "data/processed",
    "models",
    "configs",
    "outputs",
    "tests",
]

for rel in dirs:
    (root / rel).mkdir(parents=True, exist_ok=True)

files = {
    "configs/default.yaml": "input_dir: data/raw\noutput_dir: outputs\n",
    ".gitignore": "outputs/\ndata/processed/\n__pycache__/\n*.pyc\n",
    "src/main.py": (
        "from pathlib import Path\n\n"
        "PROJECT_ROOT = Path(__file__).resolve().parents[1]\n"
    ),
}

for rel, content in files.items():
    path = root / rel
    if not path.exists():
        path.write_text(content, encoding="utf-8")

print("root:", root.resolve())
for rel in dirs:
    print("dir:", rel)
for rel in files:
    print("file:", rel)

预期输出

text
root: <PATH>/opencv-demo
dir: src
dir: data/raw
dir: data/processed
dir: models
dir: configs
dir: outputs
dir: tests
file: configs/default.yaml
file: .gitignore
file: src/main.py

<PATH> 会随操作系统和当前工作目录变化。脚本再次运行时目录保持不变,已有的配置文件和入口文件也不会被覆盖,适合当作新项目的初始化模板。

让路径不依赖当前终端目录

视觉项目经常因为“从哪个目录启动脚本”不同而找不到图片。入口文件应先定位项目根目录,再拼接数据与输出路径,而不是在代码里写死绝对路径。上面的 src/main.py 已用 Path(__file__).resolve().parents[1] 得到根目录。

实际读取时可约定输入来自 PROJECT_ROOT / "data" / "raw",输出写入 PROJECT_ROOT / "outputs"。这样无论在项目根目录执行,还是由测试工具从其他目录调用,路径含义都保持一致;Windows 路径也无需手工拼接反斜杠。

用版本控制区分源码和产物

一个简单规则是:能靠源码、配置和原始数据重新生成的内容,通常不必提交到 Git。outputs/、缓存和大批派生图片适合忽略;src/、configs/、tests/ 和小型说明文件应提交。模型若只有几十 MB 且项目允许,可以直接版本化;几百 MB 甚至数 GB 的权重更适合放对象存储并记录下载地址与校验值。

创建项目后做一次人工验收:删除 outputs 中的测试结果后重新运行程序,确认它能自动重建;再从另一个工作目录启动 src/main.py,确认仍能定位项目根目录。只要这两项成立,工程结构就已经具备基本的可复现性。

按自己的节奏,确认真正理解。

目录与阅读设置

阅读设置

17

记录一个想法

建立标准项目结构

0 / 10000 · 笔记保存到账号。未提交的修改会在关闭、离开或刷新后丢失。

登录哪都通