计算机视觉 / 系统课时
建立标准项目结构
建立标准项目结构
一个 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/ |
单元测试和小型固定样本 | 纳入版本控制 |

这套结构不是为了增加目录数量,而是为了让“输入事实”和“运行产物”分离。只要保证原始输入不会被覆盖,同一份代码和配置就可以重复生成处理结果。
一次性创建工程骨架
下面的 Python 脚本跨 Windows、macOS 和 Linux,可重复执行;已存在的目录不会报错,已有文件也不会被覆盖。运行后会创建目录,并写入最小配置、.gitignore 和入口文件。
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)预期输出
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,确认仍能定位项目根目录。只要这两项成立,工程结构就已经具备基本的可复现性。