diff --git a/README.md b/README.md index 286a5cf..4c0bfbb 100644 --- a/README.md +++ b/README.md @@ -644,6 +644,26 @@ runs/boxes_shap_label_studio/ # 同时也是 Label Studio 的 DOCUMENT_ROOT ### 导入 Label Studio +**图片 URL 必须按 Label Studio 实际的 `DOCUMENT_ROOT` 生成。** 任务里写的是 +`/data/local-files/?d=<相对路径>/images/<图名>.png`，Label Studio 把 `d` 拼到 +`LABEL_STUDIO_LOCAL_FILES_DOCUMENT_ROOT` 后面找文件，相对路径错了就是整个项目 404。 +脚本缺省读这个环境变量，也可以用 `--document-root` 显式指定： + +```bash +# DOCUMENT_ROOT 统一放标注项目，产出仍留在 runs/ +uv run python scripts/prepare_label_studio.py --source runs/boxes_shap \ + --document-root /home/deep/labeling +``` + +| 情形 | 做法 | 图片 URL | +|---|---|---| +| 没设 DOCUMENT_ROOT | 输出目录自己当 DOCUMENT_ROOT | `?d=images/…` | +| 输出目录在 DOCUMENT_ROOT 之下 | 直接用 | `?d=<相对路径>/images/…` | +| 输出目录在 DOCUMENT_ROOT 之外 | 在 DOCUMENT_ROOT 里建同名软链接指向它 | `?d=boxes_shap_label_studio/images/…` | + +DOCUMENT_ROOT 里已有同名的**真目录**（比如手动复制过去的一份）时脚本会报错，不会覆盖它。 +Local files 存储的绝对路径填 `/<访问路径>/images`，脚本打印的步骤里已经算好。 + 脚本结束时会打印带实际路径的导入步骤：设置 `LABEL_STUDIO_LOCAL_FILES_*` 环境变量启动、 粘贴 labeling config、添加 Local files 存储（**只保存不要 Sync**，否则每张图多出一个空任务）、 导入 `tasks.json`。 @@ -652,8 +672,10 @@ runs/boxes_shap_label_studio/ # 同时也是 Label Studio 的 DOCUMENT_ROOT - **为什么是扁平结构**：`label-studio-converter import yolo` 只认 `/{images,labels,classes.txt}`， 且 `os.listdir` 不递归，看不见子目录。 -- **硬链接而不是软链接**：Label Studio 读本地文件时会检查路径是否在 `DOCUMENT_ROOT` 之下， - 软链接解析后可能落到外面。 +- **软链接可以用**：Label Studio（1.23.0 核对过源码）拼文件路径用 `safe_join`（`abspath`）， + 存储路径做 `normpath` 后按字符串前缀比较，都**不解析软链接**，所以 DOCUMENT_ROOT 里放一个 + 指向 `runs/` 的软链接就能访问，不必复制。存储路径也必须是 DOCUMENT_ROOT 的**子目录**， + 与 DOCUMENT_ROOT 相同会被拒绝，这正是要填到 `…/images` 的原因。 - **框作为 predictions 而不是 annotations**：它们是模型生成的。审核员修改提交后才成为 annotation， 哪些审过一目了然，导出时也只导出 annotation，没审过的框不会混进去。 - **不传 `--image-dims`**：图片尺寸有 3,223 种，传了会把同一个宽高写进每条标注。 diff --git a/scripts/prepare_label_studio.py b/scripts/prepare_label_studio.py index 4dfa42b..f149897 100644 --- a/scripts/prepare_label_studio.py +++ b/scripts/prepare_label_studio.py @@ -28,6 +28,16 @@ runs/_label_studio/ # 同时也是 Label Studio 的 DOCUMENT_ROOT └── tasks.label_config.xml ``` +**图片 URL 相对 Label Studio 的 DOCUMENT_ROOT。** 任务里写的是 +`/data/local-files/?d=<相对路径>/images/<图名>.png`，Label Studio 把 `d` 拼到 +`LABEL_STUDIO_LOCAL_FILES_DOCUMENT_ROOT` 后面找文件。所以 URL 必须按实际的 DOCUMENT_ROOT 生成： + + # 缺省读环境变量 LABEL_STUDIO_LOCAL_FILES_DOCUMENT_ROOT；也可显式指定 + --document-root /home/deep/labeling + +输出目录不在 DOCUMENT_ROOT 下时，会在 DOCUMENT_ROOT 里建一个同名软链接指过去， +产出本身仍留在 runs/。没有设置 DOCUMENT_ROOT 时，输出目录自己就当作 DOCUMENT_ROOT。 + 这里**不写 data.yaml、不划分 train/val**：这份材料是给人复核的，不是训练集。 修好标签后，再从 Label Studio 导出、划分到 data/ 下给 YOLO 训练。 复核期间 Label Studio 直接从这个目录读图，**不要删除或 --overwrite 它**。 @@ -52,6 +62,7 @@ import logging import os import shutil import sys +import urllib.parse from collections import Counter, defaultdict from collections.abc import Sequence from pathlib import Path @@ -203,12 +214,56 @@ def assign_names(samples: Sequence[Sample], names: Sequence[str]) -> dict[Path, return mapping -def build_label_studio_tasks(out_dir: Path, num_images: int) -> dict: +DOCUMENT_ROOT_ENV = "LABEL_STUDIO_LOCAL_FILES_DOCUMENT_ROOT" + + +def expose_under_document_root(out_dir: Path, document_root: Path | None) -> tuple[Path, Path]: + """确定 Label Studio 从 DOCUMENT_ROOT 下哪个路径访问输出目录，返回 (document_root, 访问路径)。 + + - 没有 DOCUMENT_ROOT：输出目录自己当 DOCUMENT_ROOT，访问路径就是它； + - 输出目录已在 DOCUMENT_ROOT 之下：直接用； + - 否则在 DOCUMENT_ROOT 下建一个同名软链接指向输出目录。 + + 软链接可用：Label Studio（1.23.0 核对过）拼路径用 abspath/normpath，存储路径校验也是 + 纯字符串的前缀比较，都不解析软链接。所有比较都要在"未解析"的路径上做，否则软链接 + 会被解析到 DOCUMENT_ROOT 外面，反倒对不上。 + """ + out_dir = Path(os.path.abspath(out_dir)) + if document_root is None: + return out_dir, out_dir + root = Path(os.path.abspath(document_root)) + if not root.is_dir(): + raise RuntimeError(f"DOCUMENT_ROOT {root} 不存在或不是目录") + if root == out_dir: + # Label Studio 拒绝与 DOCUMENT_ROOT 相同的存储路径，但存储填的是 /images，没问题 + return root, out_dir + if root in out_dir.parents: + return root, out_dir + + link = root / out_dir.name + if link.is_symlink(): + if Path(os.path.abspath(os.path.join(link.parent, os.readlink(link)))) != out_dir: + raise RuntimeError(f"{link} 已是指向别处的软链接（{os.readlink(link)}），请先确认后删除") + elif link.exists(): + raise RuntimeError( + f"{link} 已存在且不是软链接（可能是之前手动复制的一份）。" + f"删除它后重跑，或者用 --out {link} 直接把材料生成到 DOCUMENT_ROOT 里" + ) + else: + link.symlink_to(out_dir, target_is_directory=True) + return root, link + + +def build_label_studio_tasks( + out_dir: Path, num_images: int, document_root: Path, served_dir: Path +) -> dict: """在输出目录上调用 label-studio-converter，生成 tasks.json 与 labeling config。 converter 的 YOLO 导入只认 `/{images,labels,classes.txt}`，且 os.listdir 不递归—— - 这正是本脚本产出的扁平结构。图片是硬链接而不是软链接也有讲究：Label Studio 本地存储 - 会检查文件是否在 DOCUMENT_ROOT 之下，软链接解析后可能落到外面。 + 这正是本脚本产出的扁平结构。 + + 图片 URL 是 `/data/local-files/?d=/images/<图名>`： + Label Studio 把 d 拼在 DOCUMENT_ROOT 后面找文件，相对路径错了就是满屏 404。 框以 predictions 导入：它们是 SHAP / Grad-CAM 生成的，不是人工标注。审核员修改提交 之后才成为 annotation，Label Studio 导出时也只导出 annotation，没审过的框不会混进去。 @@ -219,6 +274,9 @@ def build_label_studio_tasks(out_dir: Path, num_images: int) -> dict: raise RuntimeError("需要 label-studio（uv sync 后可用）") from exc tasks_file = out_dir / "tasks.json" + relative = served_dir.relative_to(document_root).as_posix() + image_dir = "images" if relative == "." else f"{relative}/images" + image_root_url = "/data/local-files/?d=" + urllib.parse.quote(image_dir, safe="/") # converter 会往 stdout 打一份缺了环境变量的导入说明，还会刷一串 root logger 的 INFO； # 静音它们，由 main() 打印带实际路径的完整步骤 root_logger = logging.getLogger() @@ -231,6 +289,7 @@ def build_label_studio_tasks(out_dir: Path, num_images: int) -> dict: input_dir=str(out_dir), out_file=str(tasks_file), out_type="predictions", + image_root_url=image_root_url, image_ext=".png", ) finally: @@ -243,7 +302,9 @@ def build_label_studio_tasks(out_dir: Path, num_images: int) -> dict: ) return { "tasks": len(tasks), - "document_root": str(out_dir.resolve()), + "document_root": str(document_root), + "storage_path": str(served_dir / "images"), + "image_root_url": image_root_url, "tasks_file": str(tasks_file.resolve()), "label_config": str((out_dir / "tasks.label_config.xml").resolve()), } @@ -329,6 +390,13 @@ def main() -> int: "注意空标签在 YOLO 里的意思是『此图无缺陷』，缺陷类的空标签走到训练会教模型抑制真实缺陷" ), ) + parser.add_argument( + "--document-root", default=os.environ.get(DOCUMENT_ROOT_ENV), + help=( + f"Label Studio 的 DOCUMENT_ROOT，缺省读环境变量 {DOCUMENT_ROOT_ENV}。" + "图片 URL 按它生成；输出目录不在它下面时会在里面建同名软链接" + ), + ) parser.add_argument( "--keep-names", action="store_true", help="保留源文件名，不按 <类别>_<序号> 重新编号（源文件名需去掉后缀后全局唯一）", @@ -403,6 +471,9 @@ def main() -> int: if args.dry_run: logger.info("输出: %s", out_dir) + logger.info( + "DOCUMENT_ROOT: %s", args.document_root or f"未设置 {DOCUMENT_ROOT_ENV}，用输出目录本身" + ) logger.info("--dry-run：未写入任何文件") return 0 @@ -447,7 +518,12 @@ def main() -> int: write_classes_txt(out_dir / "classes.txt", names) try: - label_studio = build_label_studio_tasks(out_dir, len(samples)) + document_root, served_dir = expose_under_document_root( + out_dir, Path(args.document_root) if args.document_root else None + ) + if served_dir != Path(os.path.abspath(out_dir)): + logger.info("DOCUMENT_ROOT 下的访问路径: %s -> %s", served_dir, out_dir) + label_studio = build_label_studio_tasks(out_dir, len(samples), document_root, served_dir) except RuntimeError as exc: logger.error("%s", exc) return 1 @@ -487,11 +563,12 @@ def main() -> int: " 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" + " 绝对路径填 %s。只保存，不要点 Sync（会给每张图再建一个空任务）\n" " 4) 导入 %s\n" - "复核期间 Label Studio 从 %s 读图，不要删除或 --overwrite 这个目录", + "图片 URL 形如 %s/<图名>.png；复核期间 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"], + label_studio["storage_path"], label_studio["tasks_file"], + label_studio["image_root_url"], out_dir.resolve(), ) return 0 diff --git a/tests/test_prepare_label_studio.py b/tests/test_prepare_label_studio.py index b922699..3aebdb5 100644 --- a/tests/test_prepare_label_studio.py +++ b/tests/test_prepare_label_studio.py @@ -2,6 +2,7 @@ import csv import json +import os import sys from pathlib import Path @@ -19,6 +20,12 @@ import prepare_label_studio as pls # noqa: E402 CLASSES = ["grease", "normal", "whitedot"] +@pytest.fixture(autouse=True) +def _no_document_root_env(monkeypatch): + """开发机上若设了 LABEL_STUDIO_LOCAL_FILES_DOCUMENT_ROOT，会改变缺省行为。""" + monkeypatch.delenv("LABEL_STUDIO_LOCAL_FILES_DOCUMENT_ROOT", raising=False) + + @pytest.fixture def source(tmp_path): """模拟 generate_boxes.py 的产出：images/<类别>/ + labels/<类别>/ + data.yaml。""" @@ -451,3 +458,120 @@ def test_prints_import_steps_with_real_paths(label_studio_out, capsys): out = capsys.readouterr().out assert f"LABEL_STUDIO_LOCAL_FILES_DOCUMENT_ROOT={label_studio_out.resolve()}" in out assert "不要点 Sync" in out + + +# ---------------- DOCUMENT_ROOT 与图片 URL ---------------- + + +def _served_by_label_studio(task, document_root, storage_path): + """照搬 Label Studio 1.23.0 localfiles_data() 的判定：能返回 200 才算 True。 + + d 拼到 DOCUMENT_ROOT 后（safe_join，不解析软链接），文件所在目录要以存储路径开头，且文件存在。 + """ + django_os = pytest.importorskip("django.utils._os") + import posixpath + import urllib.parse as up + + query = up.urlparse(task["data"]["image"]).query + d = posixpath.normpath(up.parse_qs(query)["d"][0]).lstrip("/") + full_path = django_os.safe_join(str(document_root), d) + full_dir = os.path.normpath(os.path.dirname(full_path)) + return full_dir.startswith(os.path.normpath(str(storage_path))) and os.path.exists(full_path) + + +@pytest.fixture +def ls_env(): + pytest.importorskip("label_studio_sdk.converter.imports.yolo") + + +def test_without_document_root_urls_are_relative_to_output(source, tmp_path, ls_env): + out = tmp_path / "runs" / "boxes_label_studio" + assert run(source, out) == 0 + summary = json.loads((out / "summary.json").read_text(encoding="utf-8"))["label_studio"] + assert summary["image_root_url"] == "/data/local-files/?d=images" + assert all(_served_by_label_studio(t, out, summary["storage_path"]) for t in _tasks(out)) + + +def test_output_outside_document_root_gets_symlinked(source, tmp_path, ls_env): + """用户实际的配置：DOCUMENT_ROOT=/home/deep/labeling，产出留在 runs/ 下。""" + root = tmp_path / "labeling" + root.mkdir() + out = tmp_path / "runs" / "boxes_label_studio" + assert run(source, out, "--document-root", str(root)) == 0 + + link = root / "boxes_label_studio" + assert link.is_symlink() and link.resolve() == out.resolve() + summary = json.loads((out / "summary.json").read_text(encoding="utf-8"))["label_studio"] + assert summary["image_root_url"] == "/data/local-files/?d=boxes_label_studio/images" + assert summary["storage_path"] == str(link / "images") + tasks = _tasks(out) + assert len(tasks) == 13 + assert all(_served_by_label_studio(t, root, summary["storage_path"]) for t in tasks) + + +def test_old_urls_would_404_under_a_different_root(source, tmp_path, ls_env): + """回归：没按 DOCUMENT_ROOT 生成的 ?d=images/... 在 /home/deep/labeling 下全部找不到。""" + root = tmp_path / "labeling" + root.mkdir() + out = tmp_path / "runs" / "boxes_label_studio" + assert run(source, out) == 0 # 不告诉它 DOCUMENT_ROOT + (root / "boxes_label_studio").symlink_to(out) # 即使手动把目录放进去 + storage = root / "boxes_label_studio" / "images" + assert not any(_served_by_label_studio(t, root, storage) for t in _tasks(out)) + + +def test_output_inside_document_root_needs_no_symlink(source, tmp_path, ls_env): + root = tmp_path / "labeling" + out = root / "projects" / "boxes" + root.mkdir() + assert run(source, out, "--document-root", str(root)) == 0 + assert not [p for p in root.iterdir() if p.is_symlink()] + summary = json.loads((out / "summary.json").read_text(encoding="utf-8"))["label_studio"] + assert summary["image_root_url"] == "/data/local-files/?d=projects/boxes/images" + assert all(_served_by_label_studio(t, root, summary["storage_path"]) for t in _tasks(out)) + + +def test_document_root_defaults_to_environment(source, tmp_path, monkeypatch, ls_env): + root = tmp_path / "labeling" + root.mkdir() + monkeypatch.setenv("LABEL_STUDIO_LOCAL_FILES_DOCUMENT_ROOT", str(root)) + out = tmp_path / "runs" / "boxes_label_studio" + assert run(source, out) == 0 + assert (root / "boxes_label_studio").is_symlink() + + +def test_rerun_reuses_existing_symlink(source, tmp_path, ls_env): + root = tmp_path / "labeling" + root.mkdir() + out = tmp_path / "runs" / "boxes_label_studio" + assert run(source, out, "--document-root", str(root)) == 0 + assert run(source, out, "--document-root", str(root), "--overwrite") == 0 + assert (root / "boxes_label_studio").resolve() == out.resolve() + + +def test_refuses_to_replace_a_real_directory_in_document_root(source, tmp_path, capsys, ls_env): + """DOCUMENT_ROOT 里已有同名的真目录（例如手动复制的一份），不能覆盖。""" + root = tmp_path / "labeling" + (root / "boxes_label_studio").mkdir(parents=True) + (root / "boxes_label_studio" / "keep.txt").write_text("x", encoding="utf-8") + out = tmp_path / "runs" / "boxes_label_studio" + assert run(source, out, "--document-root", str(root)) != 0 + assert "不是软链接" in capsys.readouterr().out + assert (root / "boxes_label_studio" / "keep.txt").exists() + + +def test_refuses_symlink_pointing_elsewhere(source, tmp_path, capsys, ls_env): + root = tmp_path / "labeling" + root.mkdir() + elsewhere = tmp_path / "elsewhere" + elsewhere.mkdir() + (root / "boxes_label_studio").symlink_to(elsewhere) + out = tmp_path / "runs" / "boxes_label_studio" + assert run(source, out, "--document-root", str(root)) != 0 + assert "指向别处" in capsys.readouterr().out + + +def test_missing_document_root_is_an_error(source, tmp_path, capsys, ls_env): + out = tmp_path / "runs" / "boxes_label_studio" + assert run(source, out, "--document-root", str(tmp_path / "nope")) != 0 + assert "不存在" in capsys.readouterr().out