diff --git a/README.md b/README.md index d0c31b5..286a5cf 100644 --- a/README.md +++ b/README.md @@ -589,15 +589,18 @@ runs// ## 检测模型训练（YOLO） -上一步的产出按类别分目录，方便人工核对；YOLO 的类别写在标签第一列，不靠目录名。 -所以先拍平整理，导入 Label Studio 复核，再训练： +`generate_boxes.py` 产出的是弱监督框，要先在 Label Studio 里人工修正，再划分 train/val 训练： ```bash -# 1) 拍平类别目录、统一 PNG、按类别重命名，硬链接到 data/；同时生成 Label Studio 任务 -uv run python scripts/prepare_yolo_dataset.py --source runs/boxes_shap --label-studio +# 1) 生成 Label Studio 复核材料到 runs/boxes_shap_label_studio/ +uv run python scripts/prepare_label_studio.py --source runs/boxes_shap # 先看计划加 --dry-run -# 2) 训练（训练前需要先划分，见下文"不划分 train/val"） +# 2) 在 Label Studio 里修正标签（导入步骤见下文，脚本结束时也会打印） + +# 3) 导出修好的标签，划分 train/val 到 data/boxes_shap/（导出脚本待写） + +# 4) 训练 uv run python detect.py --config configs/detect/film.yaml # 只评估 / 续训 @@ -606,27 +609,26 @@ uv run python detect.py --config configs/detect/film.yaml --eval-only \ uv run python detect.py --config configs/detect/film.yaml --resume ``` -产出： +### 准备 Label Studio 复核材料 ``` -data/boxes_shap/ +runs/boxes_shap_label_studio/ # 同时也是 Label Studio 的 DOCUMENT_ROOT ├── images/<类别>_<序号>.png # 一律 PNG：PNG 原图硬链接，BMP 等无损转换 ├── labels/<类别>_<序号>.txt ├── classes.txt # 每行一个类别名，行号即 class_id ├── name_map.csv # 新文件名 ↔ 源文件路径 -├── data.yaml # train 与 val 都指向 images/ ├── summary.json # 逐类数量、空标签处置、落盘方式 -├── tasks.json # 仅 --label-studio：每张图一个任务，框作为 predictions -└── tasks.label_config.xml # 仅 --label-studio：各类别的 RectangleLabels +├── tasks.json # 每张图一个任务，框作为 predictions +└── tasks.label_config.xml # 各类别的 RectangleLabels ``` -**不划分 train/val。** 这份数据集先导入 Label Studio 复核，划分留到复核之后。`data.yaml` -的 `train` 与 `val` 只能指向同一个 `images/`，ultralytics 能读，但验证指标算的是训练集本身， -mAP 会虚高，早停与 `best.pt` 的选择也随之失真。脚本结束时会告警，`detect.py` 检测到 -train 与 val 相同时也会告警。正式训练前要先划分。 +**不写 `data.yaml`、不划分 train/val。** 这是给人复核的材料，不是训练集，没有 `data.yaml` +也就不会被误拿去训练。复核期间 Label Studio 直接从这个目录读图，**不要删除或 `--overwrite` 它**。 +`detect.py` 若检测到 `data.yaml` 的 train 与 val 相同（`generate_boxes.py` 的产出就是这样）， +也会告警：验证指标算的是训练集本身，mAP 虚高，早停与 `best.pt` 的选择失真。 **图片统一成 PNG。** pearlescent / blue / uv 的原始数据是 BMP（共 10,814 张）， -`generate_boxes.py` 按原后缀链接，于是 YOLO 数据集里会混着两种格式。这一步按**文件头** +`generate_boxes.py` 按原后缀链接，于是产出里混着两种格式。这一步按**文件头** （不是后缀）判断：真 PNG 照旧硬链接不占磁盘，其余无损转 PNG——不缩放像素，归一化的框坐标 原样有效；CMYK 这类 PNG 存不下的模式转 RGB。转换无法硬链接，会占额外磁盘，`--dry-run` 会先报出要转多少张。统一后缀后 `a.png` 与另一目录的 `a.bmp` 会撞名，脚本直接报错。 @@ -634,16 +636,13 @@ train 与 val 相同时也会告警。正式训练前要先划分。 **按类别重新编号。** 源文件名五花八门（`反面纵黑点_1_550mmX1561.71m_20260416160441_0.png`、 `pearlescent_404.bmp`……），输出统一改成 `<类别>_<序号>.png`，如 `blackdot_0042.png`。 类别以标签第一列为准，文件名永远不会与标签矛盾；序号在类内按源路径排序，同一份来源重跑， -同一张图拿到的名字不变。原文件名里的正反面、位置、 -时间戳等信息都在 `name_map.csv` 里（带 BOM，Excel 直接打开中文不乱码）。想保留原名加 `--keep-names`。 +同一张图拿到的名字不变。原文件名里的正反面、位置、时间戳等信息都在 `name_map.csv` 里 +（带 BOM，Excel 直接打开中文不乱码）。想保留原名加 `--keep-names`。 -**classes.txt** 是给 LabelImg / X-AnyLabeling 这类标注工具用的，人工复核、修改框时 -靠它把 class_id 映射回类别名；ultralytics 训练本身只读 `data.yaml`，两者内容严格一致。 +**classes.txt** 是 label-studio-converter 读类别用的（也兼容 LabelImg / X-AnyLabeling）， +行号就是 class_id，内容与来源 `data.yaml` 严格一致。 -### 导入 Label Studio 人工复核 - -弱监督框需要人工把关。加 `--label-studio` 会在数据集根目录额外生成 `tasks.json` 与 -`tasks.label_config.xml`，数据集根目录本身就是 Label Studio 的 `DOCUMENT_ROOT`。 +### 导入 Label Studio 脚本结束时会打印带实际路径的导入步骤：设置 `LABEL_STUDIO_LOCAL_FILES_*` 环境变量启动、 粘贴 labeling config、添加 Local files 存储（**只保存不要 Sync**，否则每张图多出一个空任务）、 @@ -652,7 +651,7 @@ train 与 val 相同时也会告警。正式训练前要先划分。 几个取舍： - **为什么是扁平结构**：`label-studio-converter import yolo` 只认 `/{images,labels,classes.txt}`， - 且 `os.listdir` 不递归，看不见子目录。数据集不划分、直接扁平，正好就是它要的结构。 + 且 `os.listdir` 不递归，看不见子目录。 - **硬链接而不是软链接**：Label Studio 读本地文件时会检查路径是否在 `DOCUMENT_ROOT` 之下， 软链接解析后可能落到外面。 - **框作为 predictions 而不是 annotations**：它们是模型生成的。审核员修改提交后才成为 annotation， @@ -686,7 +685,7 @@ Grad-CAM 没框出东西的有 339 张（占 3%）。它们**默认保留为负 等于在教模型抑制真实缺陷。用 `--empty-policy` 按来源类别分别处置： ```bash -uv run python scripts/prepare_yolo_dataset.py --source runs/boxes_gradcam \ +uv run python scripts/prepare_label_studio.py --source runs/boxes_gradcam \ --empty-policy drop normal=keep black=full edge_clean=full ``` diff --git a/configs/detect/film.yaml b/configs/detect/film.yaml index 968136b..0e82faf 100644 --- a/configs/detect/film.yaml +++ b/configs/detect/film.yaml @@ -1,8 +1,9 @@ -# 在 Grad-CAM / SHAP 生成的弱监督框上训练 YOLO 检测模型。 +# 在人工修正过的弱监督框上训练 YOLO 检测模型。 # # 前置步骤： -# uv run python scripts/generate_boxes.py --config ... --method gradcam # 产出 runs/boxes_gradcam -# uv run python scripts/prepare_yolo_dataset.py --source runs/boxes_gradcam +# uv run python scripts/generate_boxes.py --method shap --out runs/boxes_shap # 生成弱监督框 +# uv run python scripts/prepare_label_studio.py --source runs/boxes_shap # 复核材料 +# 在 Label Studio 里修正标签，导出并划分 train/val 到 data/boxes_shap/ # # 用法： # uv run python detect.py --config configs/detect/film.yaml diff --git a/detect.py b/detect.py index e352a7f..2b33e14 100644 --- a/detect.py +++ b/detect.py @@ -5,7 +5,7 @@ uv run python detect.py --config configs/detect/film.yaml --eval-only \ --checkpoint runs/detect/film/weights/best.pt -数据是 scripts/prepare_yolo_dataset.py 的产物（train/val 已划分好）。 +数据是在 Label Studio 里修正过的标签，导出并划分 train/val 之后放在 data/ 下的数据集。 框来自 Grad-CAM / SHAP 的弱监督标注，不是人工标注——指标该按"与热力区域的一致性" 来读，而不是当成真值上的检测精度。 """ @@ -64,13 +64,13 @@ def main() -> int: data_yaml = Path(cfg["data"]["yaml"]) if not data_yaml.exists(): logger.error( - "找不到 %s；先跑 scripts/prepare_yolo_dataset.py 把 runs/ 下的产出链接到 data/", data_yaml + "找不到 %s；先把 Label Studio 里修好的标签导出、划分 train/val 到 data/ 下", data_yaml ) return 1 meta = yaml.safe_load(data_yaml.read_text(encoding="utf-8")) logger.info("数据集: %s（%d 类）", data_yaml, meta["nc"]) if meta.get("train") == meta.get("val"): - # prepare_yolo_dataset.py / generate_boxes.py 的产出都不划分，两者指向同一目录 + # generate_boxes.py 的产出就不划分，两者指向同一目录 logger.warning( "data.yaml 的 train 与 val 相同（%s）：验证集就是训练集，mAP 会虚高，" "早停与 best.pt 的选择也因此失真。正式训练前请先划分数据集", diff --git a/scripts/prepare_label_studio.py b/scripts/prepare_label_studio.py index 2d43565..4dfa42b 100644 --- a/scripts/prepare_label_studio.py +++ b/scripts/prepare_label_studio.py @@ -1,45 +1,39 @@ #!/usr/bin/env python -"""把 generate_boxes.py 的产出整理成扁平的 YOLO 数据集，放到 data/ 下。 +"""把 generate_boxes.py 的产出整理成 Label Studio 复核材料，输出放在 runs/ 下。 - uv run python scripts/prepare_yolo_dataset.py --source runs/boxes_gradcam + uv run python scripts/prepare_label_studio.py --source runs/boxes_shap -generate_boxes.py 的产出是**按类别**分目录的（便于人工核对）： +generate_boxes.py 生成的是弱监督框，需要人工在 Label Studio 里修正之后才能拿去训练 YOLO。 +它的产出按**类别**分目录（便于人工核对），而 label-studio-converter 的 YOLO 导入只认扁平的 +`/{images,labels,classes.txt}`，且 os.listdir 不递归。这一步做三件事： -``` -runs/boxes_gradcam/ -├── images/<类别>/<图名>.png -└── labels/<类别>/<图名>.txt -``` - -而 YOLO 的类别信息在标签文件的第一列里，不靠目录名。这一步做三件事： - -1. 把按类别分的目录**拍平**，不划分 train/val——这份数据集先导入 Label Studio 复核， - 划分留到复核之后； +1. 把按类别分的目录**拍平**； 2. 图片**统一成 PNG**：本来就是 PNG 的硬链接过去，不占额外磁盘；BMP 等其他格式 （pearlescent / blue / uv 原始数据都是 BMP）无损转成 PNG。不缩放像素， - 归一化的框坐标原样有效。 - + 归一化的框坐标原样有效； 3. 文件**按类别重新编号**：`<类别>_<序号>.png`，序号在类内按源路径排序，重跑结果一致。 原文件名里的正反面、位置、时间戳等信息记在 `name_map.csv` 里，不会丢。 想保留原名加 `--keep-names`。 +然后在输出目录上调用 label-studio-converter，生成可直接导入的任务： + ``` -data// +runs/_label_studio/ # 同时也是 Label Studio 的 DOCUMENT_ROOT ├── images/<类别>_<序号>.png ├── labels/<类别>_<序号>.txt -├── classes.txt # 每行一个类别名，行号即 class_id -├── name_map.csv # 新名 ↔ 源文件对照 -├── data.yaml # train 与 val 都指向 images/，不能直接用于评估 +├── classes.txt # 每行一个类别名，行号即 class_id +├── name_map.csv # 新名 ↔ 源文件对照 ├── summary.json -├── tasks.json # 仅 --label-studio：框作为 predictions -└── tasks.label_config.xml # 仅 --label-studio +├── tasks.json # 每张图一个任务，框作为 predictions +└── tasks.label_config.xml ``` -这个结构正是 label-studio-converter 的 YOLO 导入要求的 `/{images,labels,classes.txt}`， -所以 `--label-studio` 直接在数据集根目录上转换，DOCUMENT_ROOT 就是数据集根目录。 +这里**不写 data.yaml、不划分 train/val**：这份材料是给人复核的，不是训练集。 +修好标签后，再从 Label Studio 导出、划分到 data/ 下给 YOLO 训练。 +复核期间 Label Studio 直接从这个目录读图，**不要删除或 --overwrite 它**。 -没有框的图（标签为空）默认保留：YOLO 训练里它们是负样本，有助于压低误检。但**空标签的 -语义是"这张图什么都没有"**，不是"有缺陷但没定位出来"。来自缺陷类别的空标签如果照搬， +没有框的图（标签为空）默认保留，导入后是一个没有预标注框的任务。但**空标签在 YOLO 里的语义是 +"这张图什么都没有"**，不是"有缺陷但没定位出来"。来自缺陷类别的空标签如果原样走到训练， 等于在教模型抑制真实缺陷，所以可以用 `--empty-policy` 按来源类别分别处置： --empty-policy drop normal=keep black=full @@ -67,7 +61,7 @@ sys.path.insert(0, str(Path(__file__).resolve().parents[1])) import yaml # noqa: E402 -from datasets.yolo import IMAGE_SUFFIXES, write_classes_txt, write_data_yaml # noqa: E402 +from datasets.yolo import IMAGE_SUFFIXES, write_classes_txt # noqa: E402 from utils import setup_logging # noqa: E402 logger = None @@ -210,7 +204,7 @@ def assign_names(samples: Sequence[Sample], names: Sequence[str]) -> dict[Path, def build_label_studio_tasks(out_dir: Path, num_images: int) -> dict: - """在数据集根目录上调用 label-studio-converter，生成 tasks.json 与 labeling config。 + """在输出目录上调用 label-studio-converter，生成 tasks.json 与 labeling config。 converter 的 YOLO 导入只认 `/{images,labels,classes.txt}`，且 os.listdir 不递归—— 这正是本脚本产出的扁平结构。图片是硬链接而不是软链接也有讲究：Label Studio 本地存储 @@ -222,7 +216,7 @@ def build_label_studio_tasks(out_dir: Path, num_images: int) -> dict: try: from label_studio_sdk.converter.imports.yolo import convert_yolo_to_ls except ImportError as exc: - raise RuntimeError("--label-studio 需要 label-studio（uv sync 后可用）") from exc + raise RuntimeError("需要 label-studio（uv sync 后可用）") from exc tasks_file = out_dir / "tasks.json" # converter 会往 stdout 打一份缺了环境变量的导入说明，还会刷一串 root logger 的 INFO； @@ -323,15 +317,16 @@ def main() -> int: description=__doc__, formatter_class=argparse.RawDescriptionHelpFormatter ) parser.add_argument("--source", required=True, help="generate_boxes.py 的产出目录") - parser.add_argument("--out", default=None, help="输出目录；缺省 data/") - parser.add_argument("--data-root", default="data", help="自动推导时的根目录，默认 data") + parser.add_argument( + "--out", default=None, help="输出目录；缺省 runs/_label_studio", + ) parser.add_argument( "--empty-policy", nargs="*", default=[], metavar="POLICY|类别=POLICY", help=( "怎么处置没有框的图（标签为空）。可写一个全局默认，再按类别覆盖，如 " "`--empty-policy drop normal=keep black=full`。" "keep=当负样本保留（默认）、drop=丢弃、full=退化成整图框。" - "注意空标签在 YOLO 里的意思是『此图无缺陷』，缺陷类的空标签照搬会教模型抑制真实缺陷" + "注意空标签在 YOLO 里的意思是『此图无缺陷』，缺陷类的空标签走到训练会教模型抑制真实缺陷" ), ) parser.add_argument( @@ -339,15 +334,14 @@ def main() -> int: help="保留源文件名，不按 <类别>_<序号> 重新编号（源文件名需去掉后缀后全局唯一）", ) parser.add_argument( - "--label-studio", action="store_true", - help="额外在数据集根目录生成 tasks.json 与 labeling config，可直接导入 Label Studio 复核", + "--overwrite", action="store_true", + help="输出目录已存在时先清空。Label Studio 复核期间从这里读图，复核中不要用", ) - parser.add_argument("--overwrite", action="store_true", help="输出目录已存在时先清空") parser.add_argument("--dry-run", action="store_true", help="只打印计划") args = parser.parse_args() source = Path(args.source) - out_dir = Path(args.out) if args.out else Path(args.data_root) / source.name + out_dir = Path(args.out) if args.out else Path("runs") / f"{source.name}_label_studio" logger = setup_logging() try: @@ -383,7 +377,7 @@ def main() -> int: ) if as_negative: logger.warning( - "以上 %s 的空标签会以『此图无缺陷』的身份进入训练。" + "以上 %s 的空标签会以『此图无缺陷』的身份导入，复核时不补框的话会这样进入训练。" "如果其中某些类其实是有缺陷、只是没能定位出来，它们会教模型抑制真实缺陷——" "用 --empty-policy 逐类改成 drop 或 full。", "/".join(as_negative), @@ -408,8 +402,7 @@ def main() -> int: ) if args.dry_run: - if args.label_studio: - logger.info("--label-studio：会在 %s 下生成 tasks.json", out_dir) + logger.info("输出: %s", out_dir) logger.info("--dry-run：未写入任何文件") return 0 @@ -452,17 +445,12 @@ def main() -> int: destination.parent.mkdir(parents=True, exist_ok=True) destination.write_text(f"{sample.full_box} 0.5 0.5 1.0 1.0\n", encoding="utf-8") - # 不划分时 train 与 val 只能指向同一目录：ultralytics 能读，但验证指标算的是训练集本身 - write_data_yaml(out_dir / "data.yaml", names, root=out_dir.resolve(), train="images", val="images") write_classes_txt(out_dir / "classes.txt", names) - - label_studio = None - if args.label_studio: - try: - label_studio = build_label_studio_tasks(out_dir, len(samples)) - except RuntimeError as exc: - logger.error("%s", exc) - return 1 + try: + label_studio = build_label_studio_tasks(out_dir, len(samples)) + except RuntimeError as exc: + logger.error("%s", exc) + return 1 # utf-8-sig：带 BOM，Excel / Numbers 直接打开中文源路径不乱码 with (out_dir / "name_map.csv").open("w", encoding="utf-8-sig", newline="") as handle: writer = csv.writer(handle) @@ -480,7 +468,6 @@ def main() -> int: "empty_policy": {"default": default_policy, **per_class_policy}, "renamed": renamed is not None, "label_studio": label_studio, - "split": False, "per_class": dict(counts), "link_modes": dict(modes), }, @@ -491,25 +478,21 @@ def main() -> int: ) logger.info("图片落盘方式: %s（hard=硬链接, copy=跨盘复制, convert=转成 PNG）", dict(modes)) logger.info("完成 -> %s", out_dir) - logger.warning( - "数据集未划分 train/val，data.yaml 的 train 与 val 都指向 images/。" - "直接拿去训练的话验证指标算的是训练集本身，会虚高；训练前需要另行划分。" + # label-studio-converter 自带的提示漏了环境变量（它在循环里改写了 image_root_url， + # 与默认值比较时就不相等了），这里给出带实际路径的完整步骤 + logger.info( + "Label Studio 任务 %d 个，导入步骤：\n" + " 1) export LABEL_STUDIO_LOCAL_FILES_SERVING_ENABLED=true\n" + " export LABEL_STUDIO_LOCAL_FILES_DOCUMENT_ROOT=%s\n" + " uv run label-studio start\n" + " 2) 新建项目 -> Labeling Setup -> Code，粘贴 %s\n" + " 3) Settings -> Cloud Storage -> Add Source Storage -> Local files，\n" + " 绝对路径填 %s/images。只保存，不要点 Sync（会给每张图再建一个空任务）\n" + " 4) 导入 %s\n" + "复核期间 Label Studio 从 %s 读图，不要删除或 --overwrite 这个目录", + label_studio["tasks"], label_studio["document_root"], label_studio["label_config"], + label_studio["document_root"], label_studio["tasks_file"], label_studio["document_root"], ) - if label_studio: - # label-studio-converter 自带的提示漏了环境变量（它在循环里改写了 image_root_url， - # 与默认值比较时就不相等了），这里给出带实际路径的完整步骤 - logger.info( - "Label Studio 任务 %d 个，导入步骤：\n" - " 1) export LABEL_STUDIO_LOCAL_FILES_SERVING_ENABLED=true\n" - " export LABEL_STUDIO_LOCAL_FILES_DOCUMENT_ROOT=%s\n" - " uv run label-studio start\n" - " 2) 新建项目 -> Labeling Setup -> Code，粘贴 %s\n" - " 3) Settings -> Cloud Storage -> Add Source Storage -> Local files，\n" - " 绝对路径填 %s/images。只保存，不要点 Sync（会给每张图再建一个空任务）\n" - " 4) 导入 %s", - label_studio["tasks"], label_studio["document_root"], label_studio["label_config"], - label_studio["document_root"], label_studio["tasks_file"], - ) return 0 diff --git a/tests/test_prepare_label_studio.py b/tests/test_prepare_label_studio.py index aa50b95..b922699 100644 --- a/tests/test_prepare_label_studio.py +++ b/tests/test_prepare_label_studio.py @@ -1,4 +1,4 @@ -"""把 generate_boxes.py 的产出整理成 YOLO 训练集。""" +"""把 generate_boxes.py 的产出整理成 Label Studio 复核材料。""" import csv import json @@ -14,7 +14,7 @@ import yaml # noqa: E402 from PIL import Image # noqa: E402 sys.path.insert(0, "scripts") -import prepare_yolo_dataset as pyd # noqa: E402 +import prepare_label_studio as pls # noqa: E402 CLASSES = ["grease", "normal", "whitedot"] @@ -55,17 +55,17 @@ def output_of(out, source_stem): def run(source, out, *extra): - argv = ["prepare_yolo_dataset.py", "--source", str(source), "--out", str(out), *extra] + argv = ["prepare_label_studio.py", "--source", str(source), "--out", str(out), *extra] original, sys.argv = sys.argv, argv try: - return pyd.main() + return pls.main() finally: sys.argv = original -def test_flat_layout_without_split(source, tmp_path): - """类别目录被拍平、不划分 train/val：images/ 与 labels/ 下直接是文件，一一对应。""" - out = tmp_path / "data" / "boxes" +def test_flat_layout(source, tmp_path): + """类别目录被拍平：images/ 与 labels/ 下直接是文件，一一对应（converter 不递归）。""" + out = tmp_path / "runs" / "boxes_label_studio" assert run(source, out) == 0 for kind in ("images", "labels"): @@ -74,12 +74,11 @@ def test_flat_layout_without_split(source, tmp_path): labels = sorted(p.stem for p in (out / "labels").iterdir()) assert images == labels assert len(images) == 13 - assert json.loads((out / "summary.json").read_text(encoding="utf-8"))["split"] is False def test_hard_links_share_inode(source, tmp_path): """用硬链接而不是复制，不占额外磁盘。""" - out = tmp_path / "data" / "boxes" + out = tmp_path / "runs" / "boxes_label_studio" assert run(source, out) == 0 original = source / "images" / "grease" / "grease_0.png" linked = output_of(out, "grease_0") @@ -87,21 +86,15 @@ def test_hard_links_share_inode(source, tmp_path): def test_per_class_counts_in_summary(source, tmp_path): - out = tmp_path / "data" / "boxes" + out = tmp_path / "runs" / "boxes_label_studio" assert run(source, out) == 0 per_class = json.loads((out / "summary.json").read_text(encoding="utf-8"))["per_class"] assert per_class == {"grease": 6, "normal": 4, "(无框)": 1, "whitedot": 2} -def test_warns_that_data_is_not_split(source, tmp_path, capsys): - """train 与 val 指向同一目录，直接训练验证指标会虚高，必须提醒。""" - assert run(source, tmp_path / "data" / "boxes") == 0 - assert "未划分" in capsys.readouterr().out - - def test_empty_labels_kept_as_negatives_by_default(source, tmp_path): """无框的图默认保留——YOLO 里它们是压低误检的负样本。""" - out = tmp_path / "data" / "boxes" + out = tmp_path / "runs" / "boxes_label_studio" assert run(source, out) == 0 summary = json.loads((out / "summary.json").read_text(encoding="utf-8")) assert summary["empty_labels"] == {"normal": {"policy": "keep", "count": 1}} @@ -109,7 +102,7 @@ def test_empty_labels_kept_as_negatives_by_default(source, tmp_path): def test_empty_policy_drop_removes_the_image(source, tmp_path): - out = tmp_path / "data" / "boxes" + out = tmp_path / "runs" / "boxes_label_studio" assert run(source, out, "--empty-policy", "drop") == 0 summary = json.loads((out / "summary.json").read_text(encoding="utf-8")) assert summary["num_images"] == 12 @@ -119,7 +112,7 @@ def test_empty_policy_drop_removes_the_image(source, tmp_path): def test_empty_policy_is_per_class(source, tmp_path): """缺陷类的空标签丢掉，normal 的留作负样本——两种处置能共存。""" - out = tmp_path / "data" / "boxes" + out = tmp_path / "runs" / "boxes_label_studio" assert run(source, out, "--empty-policy", "drop", "normal=keep") == 0 summary = json.loads((out / "summary.json").read_text(encoding="utf-8")) assert summary["empty_labels"]["normal"]["policy"] == "keep" @@ -128,7 +121,7 @@ def test_empty_policy_is_per_class(source, tmp_path): def test_empty_policy_full_writes_a_whole_image_box(source, tmp_path): """整图属性的类别退化成整图框：标签要重写，不能链接源文件（内容不同）。""" - out = tmp_path / "data" / "boxes" + out = tmp_path / "runs" / "boxes_label_studio" assert run(source, out, "--empty-policy", "normal=full") == 0 image = output_of(out, "normal_0") @@ -156,17 +149,25 @@ def test_empty_policy_rejects_typos(source, tmp_path, capsys, tokens, expected): assert expected in capsys.readouterr().out -def test_data_yaml_uses_absolute_path_and_source_names(source, tmp_path): - """data.yaml 要能被 ultralytics 从任意工作目录读到，类别顺序沿用来源。""" - out = tmp_path / "data" / "boxes" +def test_no_data_yaml_so_it_cannot_be_trained_on_by_mistake(source, tmp_path): + """复核材料不是训练集：不写 data.yaml，免得没修过的弱监督框被直接拿去训练。""" + out = tmp_path / "runs" / "boxes_label_studio" assert run(source, out) == 0 - meta = yaml.safe_load((out / "data.yaml").read_text(encoding="utf-8")) - assert Path(meta["path"]).is_absolute() - assert meta["nc"] == 3 - assert [meta["names"][i] for i in sorted(meta["names"])] == CLASSES - # 不划分：两者都指向扁平的 images/ - assert meta["train"] == meta["val"] == "images" - assert (Path(meta["path"]) / meta["train"]).is_dir() + assert not (out / "data.yaml").exists() + assert not (out / "images" / "train").exists() + + +def test_default_output_goes_under_runs(source, tmp_path, monkeypatch): + """缺省输出是 runs/_label_studio，不再写到 data/。""" + pytest.importorskip("label_studio_sdk.converter.imports.yolo") + monkeypatch.chdir(tmp_path) + original, sys.argv = sys.argv, ["prepare_label_studio.py", "--source", str(source)] + try: + assert pls.main() == 0 + finally: + sys.argv = original + assert (tmp_path / "runs" / "boxes_label_studio" / "tasks.json").is_file() + assert not (tmp_path / "data").exists() def test_name_collision_after_flattening_is_reported(source, tmp_path, capsys): @@ -175,13 +176,13 @@ def test_name_collision_after_flattening_is_reported(source, tmp_path, capsys): Image.fromarray(np.zeros((32, 32, 3), dtype=np.uint8)).save(duplicate) (source / "labels" / "normal" / "grease_0.txt").write_text("1 0.5 0.5 0.2 0.2\n", encoding="utf-8") - assert run(source, tmp_path / "data" / "boxes", "--keep-names") != 0 + assert run(source, tmp_path / "runs" / "boxes_label_studio", "--keep-names") != 0 assert "冲突" in capsys.readouterr().out def test_refuses_to_clobber_existing_output(source, tmp_path): """输出目录非空时要求显式 --overwrite。""" - out = tmp_path / "data" / "boxes" + out = tmp_path / "runs" / "boxes_label_studio" out.mkdir(parents=True) (out / "keep.txt").write_text("x", encoding="utf-8") assert run(source, out) != 0 @@ -197,7 +198,7 @@ def test_missing_label_is_an_error(source, tmp_path): def test_dry_run_writes_nothing(source, tmp_path): - out = tmp_path / "data" / "boxes" + out = tmp_path / "runs" / "boxes_label_studio" assert run(source, out, "--dry-run") == 0 assert not out.exists() @@ -225,13 +226,13 @@ def test_all_output_images_are_png(source, tmp_path): """BMP / JPEG 来源都要落成真正的 PNG——后缀和文件头都得是。""" _add_sample(source, "grease", "bmp_img", ".bmp", 0, fmt="BMP") _add_sample(source, "normal", "jpg_img", ".jpg", 1, fmt="JPEG") - out = tmp_path / "data" / "boxes" + out = tmp_path / "runs" / "boxes_label_studio" assert run(source, out) == 0 images = _all_outputs(out, "images") assert len(images) == 15 assert {p.suffix for p in images} == {".png"} - assert all(pyd.is_png(p) for p in images) + assert all(pls.is_png(p) for p in images) # 标签跟着改名后的图片走，一一对应 assert sorted(p.stem for p in images) == sorted(p.stem for p in _all_outputs(out, "labels")) @@ -239,7 +240,7 @@ def test_all_output_images_are_png(source, tmp_path): def test_bmp_conversion_is_lossless(source, tmp_path): """转换不能缩放或有损压缩，否则归一化的框就不再对应原来的像素。""" _, original = _add_sample(source, "grease", "bmp_img", ".bmp", 0, fmt="BMP") - out = tmp_path / "data" / "boxes" + out = tmp_path / "runs" / "boxes_label_studio" assert run(source, out) == 0 converted = output_of(out, "bmp_img") @@ -251,7 +252,7 @@ def test_bmp_conversion_is_lossless(source, tmp_path): def test_png_sources_are_still_hard_linked(source, tmp_path): """只有非 PNG 才转换；PNG 照旧硬链接，不占额外磁盘。""" bmp, _ = _add_sample(source, "grease", "bmp_img", ".bmp", 0, fmt="BMP") - out = tmp_path / "data" / "boxes" + out = tmp_path / "runs" / "boxes_label_studio" assert run(source, out) == 0 summary = json.loads((out / "summary.json").read_text(encoding="utf-8")) @@ -264,18 +265,18 @@ def test_png_sources_are_still_hard_linked(source, tmp_path): def test_png_suffix_with_non_png_content_is_converted(source, tmp_path): """按文件头判断而不是后缀：写着 .png 其实是 JPEG 的也要转。""" fake, _ = _add_sample(source, "grease", "fake", ".png", 0, fmt="JPEG") - assert not pyd.is_png(fake) - out = tmp_path / "data" / "boxes" + assert not pls.is_png(fake) + out = tmp_path / "runs" / "boxes_label_studio" assert run(source, out) == 0 output = output_of(out, "fake") - assert pyd.is_png(output) + assert pls.is_png(output) @pytest.mark.parametrize("mode", ["L", "RGBA", "CMYK"]) def test_conversion_handles_pixel_modes(source, tmp_path, mode): """灰度 / 带透明度原样保留；PNG 存不下的 CMYK 转成 RGB。""" _add_sample(source, "grease", "moded", ".tif", 0, fmt="TIFF", mode=mode) - out = tmp_path / "data" / "boxes" + out = tmp_path / "runs" / "boxes_label_studio" assert run(source, out) == 0 output = output_of(out, "moded") with Image.open(output) as image: @@ -286,7 +287,7 @@ def test_conversion_handles_pixel_modes(source, tmp_path, mode): def test_same_stem_different_suffix_collides(source, tmp_path, capsys): """grease_0.png 与另一目录的 grease_0.bmp 统一后缀后会撞成同一个文件，必须报错。""" _add_sample(source, "normal", "grease_0", ".bmp", 1, fmt="BMP") - assert run(source, tmp_path / "data" / "boxes", "--keep-names") != 0 + assert run(source, tmp_path / "runs" / "boxes_label_studio", "--keep-names") != 0 assert "冲突" in capsys.readouterr().out @@ -296,13 +297,13 @@ def test_dry_run_reports_conversion_count(source, tmp_path, capsys): assert "1 张不是 PNG" in capsys.readouterr().out -def test_classes_txt_matches_data_yaml(source, tmp_path): - """classes.txt 的行号就是 class_id，必须与 data.yaml 的 names 严格一致。""" - out = tmp_path / "data" / "boxes" +def test_classes_txt_matches_source_data_yaml(source, tmp_path): + """classes.txt 的行号就是 class_id，必须与来源 data.yaml 的 names 严格一致。""" + out = tmp_path / "runs" / "boxes_label_studio" assert run(source, out) == 0 lines = (out / "classes.txt").read_text(encoding="utf-8").splitlines() - meta = yaml.safe_load((out / "data.yaml").read_text(encoding="utf-8")) + meta = yaml.safe_load((source / "data.yaml").read_text(encoding="utf-8")) assert lines == CLASSES assert lines == [meta["names"][i] for i in range(meta["nc"])] assert (out / "classes.txt").read_text(encoding="utf-8").endswith("\n") @@ -323,7 +324,7 @@ def _stems(out): def test_files_renamed_by_class(source, tmp_path): """默认按 <类别>_<序号> 重新编号，序号在类内从 1 连续编到该类总数。""" - out = tmp_path / "data" / "boxes" + out = tmp_path / "runs" / "boxes_label_studio" assert run(source, out) == 0 assert _stems(out) == ( [f"grease_{i:04d}" for i in range(1, 7)] @@ -335,7 +336,7 @@ def test_files_renamed_by_class(source, tmp_path): def test_renamed_file_class_matches_its_label(source, tmp_path): """文件名里的类别必须与标签第一列一致，否则改名反倒制造了误导。""" - out = tmp_path / "data" / "boxes" + out = tmp_path / "runs" / "boxes_label_studio" assert run(source, out) == 0 for label in _all_outputs(out, "labels"): text = label.read_text(encoding="utf-8").split() @@ -345,7 +346,7 @@ def test_renamed_file_class_matches_its_label(source, tmp_path): def test_name_map_traces_back_to_source(source, tmp_path): """name_map.csv 覆盖每一张输出，且源路径真实存在、内容一致。""" - out = tmp_path / "data" / "boxes" + out = tmp_path / "runs" / "boxes_label_studio" assert run(source, out) == 0 with (out / "name_map.csv").open(encoding="utf-8-sig", newline="") as handle: rows = list(csv.DictReader(handle)) @@ -368,7 +369,7 @@ def test_names_stable_across_reruns(source, tmp_path): def test_keep_names_preserves_source_stems(source, tmp_path): """--keep-names 保留原名，只是后缀统一成 .png。""" _add_sample(source, "grease", "原名_中文", ".bmp", 0, fmt="BMP") - out = tmp_path / "data" / "boxes" + out = tmp_path / "runs" / "boxes_label_studio" assert run(source, out, "--keep-names") == 0 assert "原名_中文" in _stems(out) assert output_of(out, "原名_中文").name == "原名_中文.png" @@ -376,7 +377,7 @@ def test_keep_names_preserves_source_stems(source, tmp_path): def test_kept_empty_labels_named_after_source_folder(source, tmp_path): """空标签没有 class_id，按来源目录名编号；与同类有框的图共用序号，不会撞名。""" - out = tmp_path / "data" / "boxes" + out = tmp_path / "runs" / "boxes_label_studio" assert run(source, out) == 0 assert output_of(out, "normal_0").stem.startswith("normal_") assert len([s for s in _stems(out) if s.startswith("normal_")]) == 5 @@ -385,8 +386,8 @@ def test_kept_empty_labels_named_after_source_folder(source, tmp_path): @pytest.fixture def label_studio_out(source, tmp_path): pytest.importorskip("label_studio_sdk.converter.imports.yolo") - out = tmp_path / "data" / "boxes" - assert run(source, out, "--empty-policy", "normal=keep", "--label-studio") == 0 + out = tmp_path / "runs" / "boxes_label_studio" + assert run(source, out, "--empty-policy", "normal=keep") == 0 return out @@ -394,8 +395,8 @@ def _tasks(out): return json.loads((out / "tasks.json").read_text(encoding="utf-8")) -def test_label_studio_files_at_dataset_root(label_studio_out): - """tasks.json 与 labeling config 直接放在数据集根目录，不再有 label_studio/ 子目录。""" +def test_label_studio_files_at_output_root(label_studio_out): + """tasks.json 与 labeling config 总是生成，直接放在输出根目录（即 DOCUMENT_ROOT）。""" assert (label_studio_out / "tasks.json").is_file() assert (label_studio_out / "tasks.label_config.xml").is_file() assert not (label_studio_out / "label_studio").exists() @@ -442,8 +443,11 @@ def test_label_studio_config_and_summary(label_studio_out): assert Path(summary["label_studio"]["document_root"]) == label_studio_out.resolve() -def test_label_studio_not_built_by_default(source, tmp_path): - out = tmp_path / "data" / "boxes" - assert run(source, out) == 0 - assert not (out / "tasks.json").exists() - assert json.loads((out / "summary.json").read_text(encoding="utf-8"))["label_studio"] is None +def test_prints_import_steps_with_real_paths(label_studio_out, capsys): + """converter 自带提示漏了环境变量，脚本要给出带实际路径的完整步骤。""" + capsys.readouterr() + source = label_studio_out.parent / "boxes" + assert run(source, label_studio_out, "--overwrite") == 0 + out = capsys.readouterr().out + assert f"LABEL_STUDIO_LOCAL_FILES_DOCUMENT_ROOT={label_studio_out.resolve()}" in out + assert "不要点 Sync" in out