phone-detect-test 0.2.0__tar.gz

phone_detect_test-0.2.0/PKG-INFO

@@ -0,0 +1,203 @@
+Metadata-Version: 2.4
+Name: phone-detect-test
+Version: 0.2.0
+Summary: 考场手机检测：一条命令启动监控台网页，另附检测/训练/数据清洗/标签审计 CLI
+Author: xunfei
+License-Expression: MIT
+Keywords: yolo,object-detection,phone-detection,dataset-clean,label-audit
+Classifier: Programming Language :: Python :: 3
+Classifier: Operating System :: OS Independent
+Classifier: Topic :: Scientific/Engineering :: Artificial Intelligence
+Requires-Python: >=3.10
+Description-Content-Type: text/markdown
+Requires-Dist: ultralytics>=8.4.0
+Requires-Dist: opencv-python
+Requires-Dist: numpy
+Requires-Dist: pyyaml
+Requires-Dist: pillow
+Requires-Dist: fastapi>=0.100
+Requires-Dist: uvicorn>=0.20
+Requires-Dist: python-multipart>=0.0.6
+Provides-Extra: cpu
+Requires-Dist: torch>=2.0.0; extra == "cpu"
+Requires-Dist: torchvision>=0.15.0; extra == "cpu"
+Provides-Extra: full
+Requires-Dist: torch>=2.0.0; extra == "full"
+Requires-Dist: torchvision>=0.15.0; extra == "full"
+
+# phone-detect-test
+
+考场手机检测命令行工具：**检测 / 训练 / 数据清洗 / 标签审计**，一套命令搞定。
+
+基于 YOLO（Ultralytics）封装，把「目标检测项目从数据到上线」的完整流程收敛成统一 CLI，
+不依赖 WorkBuddy，`pip install` 后即可在任意终端使用。
+
+---
+
+## 30 秒上手：一条命令打开监控台
+
+```bash
+pip install phone-detect-test
+phone-detect-test web
+```
+
+`web` 会依次完成：**解析/下载模型权重 → 启动推理服务 → 托管监控台网页 → 自动打开浏览器**。
+页面和接口在**同一个端口**（默认 8080），所以不需要再单独起一个静态服务器，也没有跨域问题。
+
+| 参数 | 作用 |
+| --- | --- |
+| `--port 9000` | 换端口（默认 8080，被占用会自动顺延并打印实际地址） |
+| `--no-browser` | 不自动打开浏览器（服务器/远程场景） |
+| `--device cpu` | 强制用 CPU |
+| `--imgsz 512` | 降分辨率提速 |
+| `--host 0.0.0.0` | 允许局域网访问 |
+| `--weights D:\p\phone_best.pt` | 用本地权重，跳过下载 |
+
+> 摄像头必须通过 `127.0.0.1` / `localhost` 访问（浏览器安全上下文要求），
+> 所以别用 `file://` 直接双击页面。
+
+## 安装
+
+```bash
+pip install phone-detect-test
+```
+
+> `web` 命令需要 `fastapi` / `uvicorn` / `python-multipart`，已写进依赖，装包时自动带上。
+
+### 安装 torch（必选其一）
+
+`torch` 体积大且有 CPU/CUDA 之分，因此**不随包强制安装**，请按你的硬件二选一：
+
+```bash
+# 有 NVIDIA 显卡（推荐，速度快 ~10 倍）
+pip install torch torchvision --index-url https://download.pytorch.org/whl/cu124
+
+# 没有显卡（纯 CPU）
+pip install torch torchvision
+```
+
+> 也可直接 `pip install phone-detect-test[cpu]`（等价于装 CPU 版 torch）。
+
+验证 GPU 是否可用：
+
+```bash
+python -c "import torch; print(torch.cuda.is_available(), torch.cuda.get_device_name(0))"
+```
+
+---
+
+## 快速开始
+
+```bash
+# 1. 检测单张图 / 目录
+phone-detect-test detect --source img.jpg --weights phone_best.pt
+phone-detect-test detect --source test_images/ --output out.json
+
+# 2. 检测并画出框
+phone-detect-test detect --source img.jpg --draw --draw-dir vis/
+
+# 3. 整理数据集
+phone-detect-test prepare --src raw_data/ --out dataset/
+
+# 4. 继续训练
+phone-detect-test train --data dataset/data.yaml --epochs 100
+
+# 5. 验证集评估 + 搜索最优阈值
+phone-detect-test val --data dataset/data.yaml --sweep
+
+# 6. 标签污染审计（找出可疑标注）
+phone-detect-test audit --images dataset/images/train --labels dataset/labels/train --out-dir suspicious/
+```
+
+---
+
+## 命令一览
+
+| 命令 | 功能 | 来源 |
+| --- | --- | --- |
+| `web` | **启动监控台网页 + 推理接口**（一条命令，自动开浏览器） | `web/index.html` + `server/app.py` |
+| `detect` | 单图 / 目录批量检测，输出框或 JSON | `predict.py` |
+| `train` | 在自己数据集上继续训练 / 微调 | `train.py` |
+| `val` | 验证集评估 + 置信度阈值搜索 | `val.py` |
+| `prepare` | 整理图片+标签为 train/val 并生成 data.yaml | `prepare_data.py` |
+| `clean` | 一键清洗数据集（去重/修正/漏标误标检查） | `clean_data.py` |
+| `audit` | 标签污染审计（论文核心方法） | `suspicious_samples.py` |
+| `resample` | 正负样本重采样 | `resample_dataset.py` |
+| `evaluate` | 离线评测（复刻赛题评分规则） | `evaluate.py` |
+
+每个命令加 `--help` 查看完整参数，例如 `phone-detect-test detect --help`。
+
+---
+
+## 模型权重
+
+本包**不内置权重**。解析优先级：
+
+1. `--weights` 显式指定的路径
+2. 本机自动发现（当前目录、`weights/`、`com_phone/weights/` 下的 `phone_best.pt` / `best.pt`）
+3. 从 `PHONE_DETECT_WEIGHTS_URL` 环境变量（或源码里 `DEFAULT_WEIGHTS_URL`）下载
+
+```bash
+# 显式指定
+phone-detect-test detect --source img.jpg --weights /path/to/phone_best.pt
+
+# 配置下载地址（把权重传到 GitHub Release 后）
+export PHONE_DETECT_WEIGHTS_URL="https://github.com/you/repo/releases/download/v1.0/phone_best.pt"
+```
+
+---
+
+## 数据格式
+
+单类别检测，标注里 `class` 固定为 `0`，YOLO 归一化格式：
+
+```
+class  x_center  y_center  width  height
+0      0.512      0.430     0.120   0.250
+```
+
+目录结构：
+
+```
+dataset/
+├── images/
+│   ├── train/*.jpg
+│   └── val/*.jpg
+└── labels/
+    ├── train/*.txt      # 空 txt = 无目标（负样本，很重要）
+    └── val/*.txt
+```
+
+---
+
+## 关于「标签污染审计」
+
+这是本项目最有价值的方法论。核心结论：
+
+> 自动化的「模型否决式」标注清洗会误删大量真目标；且**用清洗模型自己验证自己**会导致
+> 指标系统性虚高 / 失真。审计必须用**独立模型**交叉回检。
+
+`audit` 命令就是这套方法的可复现工具——用独立模型回检标注，输出三类可疑样本
+（漏标 / 错框 / 预测无对应）及可视化对比图。
+
+---
+
+## 开发
+
+```bash
+# 可编辑安装
+pip install -e .
+
+# 构建分发包
+pip install build && python -m build
+```
+
+### 页面文件是「两份」，改完必须同步
+
+监控台页面的**唯一源文件**是仓库里的 `web/index.html`；包里还有一份副本
+（`phone_detect_test/web/index.html`），因为 setuptools 不能把包目录之外的文件打进 wheel。
+
+```bash
+python packaging/sync_web.py           # 改完 web/index.html 后同步进包
+python packaging/sync_web.py --check   # 发布前校验两份是否一致（不一致退出码 1）
+```

phone_detect_test-0.2.0/README.md

@@ -0,0 +1,176 @@
+# phone-detect-test
+
+考场手机检测命令行工具：**检测 / 训练 / 数据清洗 / 标签审计**，一套命令搞定。
+
+基于 YOLO（Ultralytics）封装，把「目标检测项目从数据到上线」的完整流程收敛成统一 CLI，
+不依赖 WorkBuddy，`pip install` 后即可在任意终端使用。
+
+---
+
+## 30 秒上手：一条命令打开监控台
+
+```bash
+pip install phone-detect-test
+phone-detect-test web
+```
+
+`web` 会依次完成：**解析/下载模型权重 → 启动推理服务 → 托管监控台网页 → 自动打开浏览器**。
+页面和接口在**同一个端口**（默认 8080），所以不需要再单独起一个静态服务器，也没有跨域问题。
+
+| 参数 | 作用 |
+| --- | --- |
+| `--port 9000` | 换端口（默认 8080，被占用会自动顺延并打印实际地址） |
+| `--no-browser` | 不自动打开浏览器（服务器/远程场景） |
+| `--device cpu` | 强制用 CPU |
+| `--imgsz 512` | 降分辨率提速 |
+| `--host 0.0.0.0` | 允许局域网访问 |
+| `--weights D:\p\phone_best.pt` | 用本地权重，跳过下载 |
+
+> 摄像头必须通过 `127.0.0.1` / `localhost` 访问（浏览器安全上下文要求），
+> 所以别用 `file://` 直接双击页面。
+
+## 安装
+
+```bash
+pip install phone-detect-test
+```
+
+> `web` 命令需要 `fastapi` / `uvicorn` / `python-multipart`，已写进依赖，装包时自动带上。
+
+### 安装 torch（必选其一）
+
+`torch` 体积大且有 CPU/CUDA 之分，因此**不随包强制安装**，请按你的硬件二选一：
+
+```bash
+# 有 NVIDIA 显卡（推荐，速度快 ~10 倍）
+pip install torch torchvision --index-url https://download.pytorch.org/whl/cu124
+
+# 没有显卡（纯 CPU）
+pip install torch torchvision
+```
+
+> 也可直接 `pip install phone-detect-test[cpu]`（等价于装 CPU 版 torch）。
+
+验证 GPU 是否可用：
+
+```bash
+python -c "import torch; print(torch.cuda.is_available(), torch.cuda.get_device_name(0))"
+```
+
+---
+
+## 快速开始
+
+```bash
+# 1. 检测单张图 / 目录
+phone-detect-test detect --source img.jpg --weights phone_best.pt
+phone-detect-test detect --source test_images/ --output out.json
+
+# 2. 检测并画出框
+phone-detect-test detect --source img.jpg --draw --draw-dir vis/
+
+# 3. 整理数据集
+phone-detect-test prepare --src raw_data/ --out dataset/
+
+# 4. 继续训练
+phone-detect-test train --data dataset/data.yaml --epochs 100
+
+# 5. 验证集评估 + 搜索最优阈值
+phone-detect-test val --data dataset/data.yaml --sweep
+
+# 6. 标签污染审计（找出可疑标注）
+phone-detect-test audit --images dataset/images/train --labels dataset/labels/train --out-dir suspicious/
+```
+
+---
+
+## 命令一览
+
+| 命令 | 功能 | 来源 |
+| --- | --- | --- |
+| `web` | **启动监控台网页 + 推理接口**（一条命令，自动开浏览器） | `web/index.html` + `server/app.py` |
+| `detect` | 单图 / 目录批量检测，输出框或 JSON | `predict.py` |
+| `train` | 在自己数据集上继续训练 / 微调 | `train.py` |
+| `val` | 验证集评估 + 置信度阈值搜索 | `val.py` |
+| `prepare` | 整理图片+标签为 train/val 并生成 data.yaml | `prepare_data.py` |
+| `clean` | 一键清洗数据集（去重/修正/漏标误标检查） | `clean_data.py` |
+| `audit` | 标签污染审计（论文核心方法） | `suspicious_samples.py` |
+| `resample` | 正负样本重采样 | `resample_dataset.py` |
+| `evaluate` | 离线评测（复刻赛题评分规则） | `evaluate.py` |
+
+每个命令加 `--help` 查看完整参数，例如 `phone-detect-test detect --help`。
+
+---
+
+## 模型权重
+
+本包**不内置权重**。解析优先级：
+
+1. `--weights` 显式指定的路径
+2. 本机自动发现（当前目录、`weights/`、`com_phone/weights/` 下的 `phone_best.pt` / `best.pt`）
+3. 从 `PHONE_DETECT_WEIGHTS_URL` 环境变量（或源码里 `DEFAULT_WEIGHTS_URL`）下载
+
+```bash
+# 显式指定
+phone-detect-test detect --source img.jpg --weights /path/to/phone_best.pt
+
+# 配置下载地址（把权重传到 GitHub Release 后）
+export PHONE_DETECT_WEIGHTS_URL="https://github.com/you/repo/releases/download/v1.0/phone_best.pt"
+```
+
+---
+
+## 数据格式
+
+单类别检测，标注里 `class` 固定为 `0`，YOLO 归一化格式：
+
+```
+class  x_center  y_center  width  height
+0      0.512      0.430     0.120   0.250
+```
+
+目录结构：
+
+```
+dataset/
+├── images/
+│   ├── train/*.jpg
+│   └── val/*.jpg
+└── labels/
+    ├── train/*.txt      # 空 txt = 无目标（负样本，很重要）
+    └── val/*.txt
+```
+
+---
+
+## 关于「标签污染审计」
+
+这是本项目最有价值的方法论。核心结论：
+
+> 自动化的「模型否决式」标注清洗会误删大量真目标；且**用清洗模型自己验证自己**会导致
+> 指标系统性虚高 / 失真。审计必须用**独立模型**交叉回检。
+
+`audit` 命令就是这套方法的可复现工具——用独立模型回检标注，输出三类可疑样本
+（漏标 / 错框 / 预测无对应）及可视化对比图。
+
+---
+
+## 开发
+
+```bash
+# 可编辑安装
+pip install -e .
+
+# 构建分发包
+pip install build && python -m build
+```
+
+### 页面文件是「两份」，改完必须同步
+
+监控台页面的**唯一源文件**是仓库里的 `web/index.html`；包里还有一份副本
+（`phone_detect_test/web/index.html`），因为 setuptools 不能把包目录之外的文件打进 wheel。
+
+```bash
+python packaging/sync_web.py           # 改完 web/index.html 后同步进包
+python packaging/sync_web.py --check   # 发布前校验两份是否一致（不一致退出码 1）
+```

phone_detect_test-0.2.0/phone_detect_test/__init__.py

@@ -0,0 +1,12 @@
+"""phone-detect-test：考场手机检测工具。
+
+一条命令启动监控台（网页 + 推理接口，同端口）：
+    phone-detect-test web
+
+也可作为 CLI 工具，覆盖目标检测任务的完整生命周期：
+检测（detect）、训练（train）、评估（val）、数据集整理（prepare）、
+数据清洗（clean）、标签污染审计（audit）、正负样本重采样（resample）、
+离线评分（evaluate）、权重下载（download-weights）。
+"""
+
+__version__ = "0.2.0"

phone_detect_test-0.2.0/phone_detect_test/__main__.py

@@ -0,0 +1,10 @@
+# -*- coding: utf-8 -*-
+"""支持 `python -m phone_detect_test ...`，等价于 `phone-detect-test ...`。
+
+这样即使 pip 装的 Scripts 目录不在 PATH 里，也能用：
+    python -m phone_detect_test web
+"""
+from .cli import main
+
+if __name__ == "__main__":
+    main()

phone_detect_test-0.2.0/phone_detect_test/audit.py

@@ -0,0 +1,155 @@
+# -*- coding: utf-8 -*-
+"""audit：标签污染审计。
+
+这是本项目论文的核心方法：用「一个独立模型」回检已有标注，找出三类可疑样本——
+  1. missing_gt    ：无标注但模型高置信检出 -> 可能漏标
+  2. gt_unmatched  ：有标注但 GT 框没有任何预测匹配 -> 可能错误标注
+  3. pred_unmatched：模型高置信检出但 GT 无对应 -> 可能漏标
+
+关键原则（来自论文结论）：审计用的模型必须「独立于」当初做标注/清洗的模型，
+否则会陷入"自己验证自己"的循环，指标失真。
+"""
+import shutil
+from pathlib import Path
+
+from .utils import IMG_EXTS, pick_device, resolve_weights
+
+
+def _compute_iou(box1, box2):
+    """box = (xc, yc, w, h) 归一化。"""
+    x1min, y1min = box1[0] - box1[2] / 2, box1[1] - box1[3] / 2
+    x1max, y1max = box1[0] + box1[2] / 2, box1[1] + box1[3] / 2
+    x2min, y2min = box2[0] - box2[2] / 2, box2[1] - box2[3] / 2
+    x2max, y2max = box2[0] + box2[2] / 2, box2[1] + box2[3] / 2
+    ix1, iy1 = max(x1min, x2min), max(y1min, y2min)
+    ix2, iy2 = min(x1max, x2max), min(y1max, y2max)
+    inter = max(0, ix2 - ix1) * max(0, iy2 - iy1)
+    a1 = (x1max - x1min) * (y1max - y1min)
+    a2 = (x2max - x2min) * (y2max - y2min)
+    union = a1 + a2 - inter
+    return inter / union if union > 0 else 0.0
+
+
+def _read_gt(label_path, class_id):
+    boxes = []
+    p = Path(label_path)
+    if not p.exists():
+        return boxes
+    for line in p.read_text(encoding="utf-8").splitlines():
+        parts = line.strip().split()
+        if len(parts) < 5:
+            continue
+        if int(parts[0]) != class_id:
+            continue
+        xc, yc, w, h = map(float, parts[1:5])
+        boxes.append((xc, yc, w, h))
+    return boxes
+
+
+def run(args):
+    from ultralytics import YOLO
+
+    images_dir = Path(args.images)
+    labels_dir = Path(args.labels)
+    out_dir = Path(args.out_dir)
+    vis_dir = out_dir / "_pred_visual"
+    if not images_dir.exists():
+        raise SystemExit(f"图片目录不存在：{images_dir}")
+    if not labels_dir.exists():
+        raise SystemExit(f"标签目录不存在：{labels_dir}")
+    out_dir.mkdir(parents=True, exist_ok=True)
+    vis_dir.mkdir(parents=True, exist_ok=True)
+
+    weights, _ = resolve_weights(args.weights,
+                                 weights_url=getattr(args, "weights_url", None))
+    device = pick_device(args.device)
+    model = YOLO(weights)
+    print(f"[审计] 模型 {weights} | 设备 {device}")
+    print(f"[审计] 类别 id={args.class_id} | 独立回检阈值 conf>={args.conf_pred_no_gt}")
+
+    stats = {"total": 0, "missing_gt": 0, "gt_unmatched": 0, "pred_unmatched": 0}
+    records = []
+
+    for img_path in sorted(images_dir.iterdir()):
+        if img_path.suffix.lower() not in IMG_EXTS:
+            continue
+        stats["total"] += 1
+        label_path = labels_dir / f"{img_path.stem}.txt"
+
+        r = model(str(img_path), conf=args.conf, verbose=False)[0]
+        pred_boxes = []
+        for i in range(len(r.boxes)):
+            if int(r.boxes.cls[i]) != args.class_id:
+                continue
+            conf = float(r.boxes.conf[i])
+            xc, yc, w, h = r.boxes.xywhn[i].tolist()
+            pred_boxes.append((conf, xc, yc, w, h))
+
+        gt_boxes = _read_gt(label_path, args.class_id)
+        reason = None
+
+        if len(gt_boxes) == 0:
+            if any(p[0] >= args.conf_pred_no_gt for p in pred_boxes):
+                reason = "missing_gt"
+                stats["missing_gt"] += 1
+        else:
+            for gt in gt_boxes:
+                max_iou = max((_compute_iou(gt, p[1:]) for p in pred_boxes), default=0)
+                if max_iou < args.iou_gt_no_pred:
+                    reason = "gt_unmatched"
+                    stats["gt_unmatched"] += 1
+                    break
+            if reason is None:
+                for conf, box in [ (p[0], p[1:]) for p in pred_boxes ]:
+                    if conf >= args.conf_pred_no_gt:
+                        max_iou = max((_compute_iou(box, gt) for gt in gt_boxes), default=0)
+                        if max_iou < args.match_iou:
+                            reason = "pred_unmatched"
+                            stats["pred_unmatched"] += 1
+                            break
+
+        if reason is not None:
+            records.append((img_path.name, reason))
+            shutil.copy2(img_path, out_dir / img_path.name)
+            if label_path.exists():
+                shutil.copy2(label_path, out_dir / label_path.name)
+            _draw_compare(img_path, gt_boxes, pred_boxes, vis_dir)
+
+    _write_summary(stats, records, out_dir)
+    print(f"\n[完成] 总图片 {stats['total']}，可疑 {len(records)} 个")
+    print(f"  漏标 {stats['missing_gt']} | GT无法匹配 {stats['gt_unmatched']} | 预测无对应 {stats['pred_unmatched']}")
+    print(f"  输出目录：{out_dir}")
+
+
+def _draw_compare(img_path, gt_boxes, pred_boxes, vis_dir):
+    import cv2
+    img = cv2.imread(str(img_path))
+    if img is None:
+        return
+    h, w = img.shape[:2]
+    for (xc, yc, bw, bh) in gt_boxes:
+        x1, y1 = int((xc - bw / 2) * w), int((yc - bh / 2) * h)
+        x2, y2 = int((xc + bw / 2) * w), int((yc + bh / 2) * h)
+        cv2.rectangle(img, (x1, y1), (x2, y2), (0, 255, 0), 2)
+    for (conf, xc, yc, bw, bh) in pred_boxes:
+        x1, y1 = int((xc - bw / 2) * w), int((yc - bh / 2) * h)
+        x2, y2 = int((xc + bw / 2) * w), int((yc + bh / 2) * h)
+        cv2.rectangle(img, (x1, y1), (x2, y2), (0, 0, 255), 2)
+        cv2.putText(img, f"{conf:.2f}", (x1, max(0, y1 - 5)),
+                    cv2.FONT_HERSHEY_SIMPLEX, 0.5, (0, 0, 255), 1)
+    cv2.imwrite(str(vis_dir / img_path.name), img)
+
+
+def _write_summary(stats, records, out_dir):
+    p = out_dir / "audit_report.txt"
+    with open(p, "w", encoding="utf-8") as f:
+        f.write("标签污染审计报告\n" + "=" * 40 + "\n")
+        f.write(f"总图片: {stats['total']}\n")
+        f.write(f"可疑总数: {len(records)}\n")
+        f.write(f"  - 缺失标注(漏标): {stats['missing_gt']}\n")
+        f.write(f"  - GT无法匹配(错框): {stats['gt_unmatched']}\n")
+        f.write(f"  - 预测无对应(漏标): {stats['pred_unmatched']}\n\n")
+        f.write("可疑图片列表:\n")
+        for name, reason in records:
+            f.write(f"{name}\t{reason}\n")
+    print(f"[报告] {p}")