cv_resnet18_ocr-detection train_gts目录：标注文件存放规范-开发者社区

cv_resnet18_ocr-detection train_gts目录：标注文件存放规范

1. 模型与工具背景说明

1.1 cv_resnet18_ocr-detection 是什么

cv_resnet18_ocr-detection 是一个轻量级、高可用的 OCR 文字检测模型，基于 ResNet-18 主干网络构建，专为中文场景优化。它不负责文字识别（OCR Recognition），只做文字区域定位——也就是找出图片中所有文字所在的矩形框（或四边形框）位置。这种“检测先行、识别后置”的设计，让模型更专注、更高效，也更适合嵌入式设备或边缘部署。

这个模型由科哥独立完成工程化封装与 WebUI 集成，已通过大量真实业务图片验证，对电商截图、商品包装、文档扫描、手机界面等常见场景具备稳定检测能力。

1.2 为什么需要规范的 train_gts 目录

训练效果好不好，七分靠数据，三分靠模型。而数据质量的核心，就藏在train_gts/这个看似简单的文件夹里。它存放的是每张训练图片对应的人工标注文件（ground truth），是模型学习“哪里有文字”的唯一依据。

如果标注格式错一位、路径写错一层、坐标顺序乱一次，训练过程可能无声无息地失败——模型不是报错，而是默默学偏：把阴影当文字、把边框当文本、漏掉小字号内容……最终上线后，你看到的不是“检测不准”，而是“根本检不出来”。

所以，这不是一个技术细节，而是一条不能妥协的数据生命线。

2. train_gts 目录结构与命名规则

2.1 基础目录结构要求

train_gts/必须是训练数据集根目录下的同级子目录，且与train_images/平行存在。标准结构如下：

custom_data/ ├── train_list.txt ├── train_images/ │ ├── 001.jpg │ ├── 002.png │ └── 003.bmp ├── train_gts/ │ ├── 001.txt │ ├── 002.txt │ └── 003.txt ├── test_list.txt ├── test_images/ └── test_gts/

关键约束：

train_gts/中每个.txt文件名，必须与train_images/中对应图片完全一致（含扩展名除外）
001.jpg→ 对应train_gts/001.txt
receipt_2024.png→ 对应train_gts/receipt_2024.txt
不支持中文空格、特殊符号（如#,&,[,]），建议仅用字母、数字、下划线、短横线

2.2 文件命名一致性检查技巧

你不需要手动核对几百个文件。推荐用一行 Shell 命令快速验证：

cd /root/custom_data diff <(ls train_images | sed 's/\..*//') <(ls train_gts | sed 's/\..*//') | grep "^<\|^>" && echo "❌ 存在不匹配文件名" || echo " 文件名全部匹配"

这条命令会比对两个目录去掉后缀后的基础名，输出差异项。只要没报错，就说明命名完全对齐。

3. 标注文件（.txt）内容格式详解

3.1 标准格式：8坐标 + 文本内容

每个.txt文件内，每行代表一个文字区域，严格按以下格式书写：

x1,y1,x2,y2,x3,y3,x4,y4,文本内容

共9 个字段，用英文逗号,分隔，末尾不加空格、不换行、不加引号。

x1,y1：左上角顶点坐标
x2,y2：右上角顶点坐标
x3,y3：右下角顶点坐标
x4,y4：左下角顶点坐标
文本内容：该区域内的原始文字（支持中英文、数字、标点、空格）

正确示例：

120,85,320,85,320,115,120,115,欢迎光临 450,200,680,200,680,235,450,235,订单号：20240105143022

❌ 常见错误：

坐标少于8个（如只写4个点）→ 模型无法解析四边形
中文逗号、全角空格、制表符代替英文逗号 → 解析中断
文本内容含换行符 → 后续行被误认为新标注
坐标为负数或超出图片尺寸 → 训练时崩溃或梯度异常

3.2 坐标系说明：以左上为原点

所有坐标均基于图像左上角(0,0)计算，单位为像素（px），遵循 OpenCV 默认坐标系：

X 轴向右增长
Y 轴向下增长
图片宽×高 =W × H，则合法坐标范围为：
0 ≤ x ≤ W-1，0 ≤ y ≤ H-1

小技巧：用 Python 快速校验单张图标注是否越界：

import cv2 img = cv2.imread("train_images/001.jpg") h, w = img.shape[:2] with open("train_gts/001.txt") as f: for i, line in enumerate(f): parts = line.strip().split(",") if len(parts) < 9: continue coords = list(map(int, parts[:8])) for j in range(0, 8, 2): x, y = coords[j], coords[j+1] if x < 0 or x >= w or y < 0 or y >= h: print(f" 第{i+1}行坐标越界：({x},{y}) 超出图片尺寸({w}×{h})")

4. 特殊情况处理规范

4.1 多行文字如何标注

OCR 检测任务中，“一行文字”指视觉上连贯、基线基本对齐的一组字符。遇到自然换行（如海报竖排文字、表格单元格多行），每行单独标注为一条记录。

❌ 错误做法（合并为一行）：

100,50,700,50,700,180,100,180,第一行文字\n第二行文字

正确做法（拆分为两条）：

100,50,700,50,700,80,100,80,第一行文字 100,100,700,100,700,130,100,130,第二行文字

提示：WebUI 训练模块默认将每行视为独立文本实例，不强制要求语义连贯性。拆得越细，模型对小字号、弯曲文字的适应力越强。

4.2 无文本区域（负样本）怎么处理

本模型采用ICDAR2015 兼容格式，不支持显式负样本标注（即“此处无文字”的声明）。若某张图确实不含任何文字，请直接不要放入训练集。

训练集中只保留“有文字”的图片。模型通过大量正样本学习文字区域特征，其泛化能力来自数据多样性，而非人工标注“空白”。

4.3 特殊符号与空格处理

空格：保留原文中的空格，如"订单号： 2024"→ 标注为订单号： 2024
冒号、顿号、省略号等中文标点：如实保留
英文标点（.,!?）：同样保留，不转义
不支持控制字符（\n,\t,\r）——保存 txt 时请用纯文本编辑器（如 VS Code、Notepad++），编码选 UTF-8 无 BOM

5. train_list.txt 列表文件编写规范

5.1 格式要求：图片路径 + 标注路径，空格分隔

train_list.txt是训练启动的“索引表”，每行包含两个路径，用单个英文空格分隔：

train_images/001.jpg train_gts/001.txt train_images/002.png train_gts/002.txt

注意：

路径为相对路径，起点是train_list.txt所在目录（即数据集根目录）
不要加前导./，也不要写绝对路径/root/...
不能有多余空格、制表符、空行
行末不能有空格或不可见字符（可用cat -A train_list.txt查看）

5.2 自动生成列表文件的可靠方法

手动写几百行极易出错。推荐使用以下脚本一键生成（保存为gen_train_list.py）：

import os data_root = "/root/custom_data" img_dir = os.path.join(data_root, "train_images") gt_dir = os.path.join(data_root, "train_gts") with open(os.path.join(data_root, "train_list.txt"), "w", encoding="utf-8") as f: for fname in sorted(os.listdir(img_dir)): if not fname.lower().endswith((".jpg", ".jpeg", ".png", ".bmp")): continue name_no_ext = os.path.splitext(fname)[0] gt_path = os.path.join("train_gts", name_no_ext + ".txt") if not os.path.exists(os.path.join(data_root, gt_path)): print(f" 警告：{fname} 缺少对应标注 {gt_path}") continue f.write(f"train_images/{fname} {gt_path}\n") print(" train_list.txt 生成完成")

运行后自动校验图片与标注配对，并跳过缺失项，安全可靠。

6. 常见错误排查与修复指南

6.1 训练启动失败：No such file or directory

现象：点击“开始训练”后，状态栏显示训练失败：FileNotFoundError: [Errno 2] No such file or directory: 'train_gts/xxx.txt'

原因：

train_list.txt中路径写错（如trian_gts/xxx.txt拼写错误）
train_gts/下缺少对应.txt文件
文件权限不足（非 root 用户运行时）

修复：

用ls -l train_gts/ | head -5确认文件存在
用head -3 train_list.txt检查路径拼写
执行chmod -R 644 train_gts/*.txt重置权限

6.2 训练中 Loss 为 NaN 或剧烈震荡

现象：训练日志中出现loss: nan或 loss 在 0.001 与 1000 之间跳变

原因：

某个.txt文件中存在非法坐标（如x1=abc字符串、y2=-10负值）
图片尺寸远小于标注坐标（如图片 300×200，但标注写了x1=500）

修复：

运行 3.2 节的坐标校验脚本，定位问题文件
用文本编辑器打开该.txt，删除或修正异常行
重新生成train_list.txt（避免缓存旧索引）

6.3 检测结果框严重偏移或旋转错误

现象：可视化结果中，检测框覆盖了大片空白，或框体明显倾斜、拉伸

原因：

标注点顺序错误（未按顺时针或逆时针连续排列）
四点不构成凸四边形（如三点共线、交叉四边形）

修复：

使用标注工具（如 LabelImg 的 Polygon 模式、CVAT）确保四点按顺时针顺序输入：左上 → 右上 → 右下 → 左下
或用以下 Python 脚本自动规整点序（适用于简单矩形）：

def sort_quadrangle(points): # points = [(x1,y1), (x2,y2), (x3,y3), (x4,y4)] center = np.mean(points, axis=0) angles = [np.arctan2(p[1]-center[1], p[0]-center[0]) for p in points] return [points[i] for i in np.argsort(angles)] # 示例：将 [x1,y1,x2,y2,x3,y3,x4,y4] 转为规整四点 raw = [120,85,320,85,320,115,120,115] pts = [(raw[i], raw[i+1]) for i in range(0,8,2)] sorted_pts = sort_quadrangle(pts) fixed = [coord for pt in sorted_pts for coord in pt] # [x1,y1,x2,y2,x3,y3,x4,y4]

7. 最佳实践建议

7.1 标注质量 > 数量

500 张高质量标注（坐标精准、覆盖多样字体/背景/角度），远胜 5000 张粗标（框大、偏移、漏标）
重点覆盖你的业务场景：电商图多标商品名和价格，文档图多标标题和段落，截图图多标按钮和提示语

7.2 建立标注审核 checklist

每次交付标注前，快速过一遍：

[ ] 所有.txt文件名与图片名一一对应
[ ] 每行恰好 9 个字段，逗号分隔，无空格
[ ] 坐标均为非负整数，且 ≤ 图片宽高-1
[ ] 四点构成合理凸四边形（无交叉、无三点共线）
[ ] 文本内容无乱码，UTF-8 编码保存

7.3 版本化管理你的标注数据

用 Git 管理train_gts/和train_list.txt：

git init git add train_gts/ train_list.txt git commit -m "v1.0: 首批电商截图标注完成"

这样每次微调都有可追溯的数据快照，避免“改着改着不知道哪版好”。

8. 总结

train_gts/目录不是训练流程里的一个可选项，而是整个 OCR 检测能力的地基。它不炫技、不复杂，但要求极致的严谨：

命名要严丝合缝，像齿轮咬合；
格式要毫厘不差，像手术刀精准；
内容要真实可信，像教科书准确。

当你花 10 分钟规范好一个.txt文件，模型在未来几万次推理中都会更稳一分；当你坚持校验每一处坐标，上线后的漏检率就会悄然下降 5%。技术落地的质感，往往就藏在这些“不起眼”的规范里。

现在，打开你的train_gts/文件夹，从第一个.txt开始，亲手把它变成模型最可靠的老师。

获取更多AI镜像
想探索更多AI镜像和应用场景？访问 CSDN星图镜像广场，提供丰富的预置镜像，覆盖大模型推理、图像生成、视频生成、模型微调等多个领域，支持一键部署。

cv_resnet18_ocr-detection train_gts目录：标注文件存放规范