# scratch-detect

**Repository Path**: trgtokai/scratch-detect

## Basic Information

- **Project Name**: scratch-detect
- **Description**: 基于yoloV5模型开发的一个识别产品外观伤痕 瑕疵的检测模型
A detection model for identifying product appearance scratches and defects developed based on the yoloV5 model. Pyqt, Pytorch
- **Primary Language**: Python
- **License**: GPL-3.0
- **Default Branch**: master
- **Homepage**: https://gitee.com/trgtokai/scratch-detect
- **GVP Project**: No

## Statistics

- **Stars**: 4
- **Forks**: 0
- **Created**: 2023-06-23
- **Last Updated**: 2026-06-22

## Categories & Tags

**Categories**: Uncategorized

**Tags**: None

## README

# Scratch-detect — Industrial scratch / defect inspection (YOLOv5 + PyQt5)

[![Python](https://img.shields.io/badge/Python-3.8-3776AB.svg?logo=python&logoColor=white)](https://www.python.org/)
[![PyQt5](https://img.shields.io/badge/PyQt5-GUI-41CD52.svg?logo=qt&logoColor=white)](https://www.riverbankcomputing.com/software/pyqt/)
[![YOLOv5](https://img.shields.io/badge/YOLOv5-v6.1-FFDD00.svg)](https://github.com/ultralytics/yolov5/tree/v6.1)

**Languages**: [简体中文（主文档）](./readme.md) · **English**  · [日本語](./readme-jp.md) 

Windows desktop app for production lines: **[YOLOv5 v6.1](https://github.com/ultralytics/yolov5/tree/v6.1)** inference with **PyQt5** UI; inputs include images, video, **multi-camera and RTSP**; optional **Modbus RTU/TCP**, PLC (e.g. Mitsubishi FX3S), Weinview HMI, stack lights, SQL, and auto-save folders. PLC / HMI projects live under `./plc/`.

**Current codebase**: `main.py` drives a refactored **`app/` pipeline** (`MultiSource` capture, `DetectorThread` inference, `UiBridge` UI fan-out, `AsyncWriter` for disk/SQL, `ModbusWorker` for periodic TCP writes). The previous monolith is kept as **`main_legacy.py`** for rollback. **STOP** behaviour is still a **P0** checkout item — see **`doc/refactor-regression.md`**.

---

## 1. Directory layout (current)

```
scratch-detect/
├── readme.md / readme-en.md / readme-jp.md
├── LICENSE
├── main.py                         # Entry: wires app/ pipeline to legacy PyQt UI
├── main_legacy.py                  # Pre-refactor single-file backup (rollback by copy-over)
├── train.py / detect.py / val.py / export.py
├── modbus_rtu.py / modbus_tcp.py   # Modbus helpers (TCP worker lives in app/sinks)
├── restart.py
├── win_run_app.bat / win_restart.bat / win_autorun_main.bat
├── requirements.txt
├── requirement-torch Local Installation.txt
├── streams.txt                     # Multi-channel streams / camera indices
├── app/
│   ├── config.py                   # ConfigStore, setting.json / setting2.json
│   ├── logger.py
│   ├── whiteboard.py
│   ├── capture/                    # MultiSource, OpenCV / MVS-related paths
│   ├── detector/                   # DetectorThread, YoloDetector, LoopResult
│   └── sinks/                      # UiBridge, AsyncWriter, ModbusWorker
├── tools/bench_loop.py             # Headless capture/inference benchmark
├── doc/refactor-regression.md      # Level 1–3 smoke, STOP checklist, bench commands
├── testing_script/                 # Experiments (multi-thread/process, YOLOv12, image2video, …)
├── config/                         # JSON templates (*.example.json) and live setting*.json
├── models/ / utils/                # YOLOv5 core
├── ui_files/                       # .ui / .py for main window, settings, RTSP dialog
├── pt/ / plc/ / runs/ / sql_folder/ / auto_save/ / imgs/ / backupfile/ / wandb/
└── debug_log.txt* (rotating), log, …
```

Training still expects a standard YOLO **`data/*.yaml`** layout; add it locally if missing.

---

## 2. Features (summary)

| Area | What it does |
| ---- | -------------- |
| **Inputs** | Images, video, multiple cameras / RTSP (`streams.txt`, OpenCV; Hikvision via MVS + `utils.capnums` as deployed) |
| **Inference** | YOLOv5 v6.1 in `DetectorThread`; NMS / plotting via `models/` + `utils/` |
| **`app/capture`** | `MultiSource` aggregates channels without the old fixed 30 FPS sleep cap |
| **`app/sinks`** | `UiBridge` throttles previews/statistics; `AsyncWriter` writes NG jpg/txt/SQL off the hot path; `ModbusWorker` writes holding registers (~100 ms cadence) |
| **UI** | `ui_files/main_win` — model dropdown, IoU/conf/rate sliders, **RUN / PAUSE / STOP** |
| **Line integration** | Modbus TCP DO0–DO7 pulses, NG/loop counters — register map must match `./plc/` (details in Chinese [readme §3.5](./readme.md)) |
| **Bench** | `python tools/bench_loop.py --help` for FPS / latency splits |

Full Modbus register table and DO/class mapping: see **section 3.5** in [readme.md](./readme.md) (Chinese master doc).

---

## 3. Hardware & software (typical)

- **OS**: Windows 10/11 x64; **GPU**: NVIDIA + CUDA recommended.
- **Stack**: Python 3.8, PyTorch, OpenCV, PyQt5, pymodbus (see `requirements.txt`).
- **Field devices** (example): Hikvision MV-CU050-90UC + MVS; Mitsubishi FX3S + Modbus; Weinview MT8072IP; ring light + controller — adjust per site.

---

## 4. Demo videos

| Region | Link |
| ------ | ---- |
| China (Bilibili) | [BV1nz421S7KR](https://www.bilibili.com/video/BV1nz421S7KR) |
| Overseas (YouTube) | [youtu.be/mEYHFr3ZQhM](https://youtu.be/mEYHFr3ZQhM) |

**UI screenshot** (same asset as Chinese readme):

![Production UI](imgs/%E7%BA%BF%E4%B8%8A%E6%A3%80%E6%9F%A5%5B00_10_57%5D%5B20240605-174147%5D.png)

---

## 5. Install & run

```bash
git clone https://gitee.com/trgtokai/scratch-detect.git
cd scratch-detect
conda create -n yolov5_pyqt5 python=3.8
conda activate yolov5_pyqt5
pip install -r requirements.txt
```

Optional offline Torch wheels: edit and use `requirement-torch Local Installation.txt`. If `pycocotools` fails to build, install **Visual Studio C++ Build Tools**.

```bash
conda activate yolov5_pyqt5
python main.py
```

Optional Windows launcher: `win_run_app.bat` (edit paths inside for your machine).

Copy `config/*.example.json` to `config/setting.json` / `config/setting2.json` if missing; the app can also materialize them on first run.

---

## 6. Training & weights

1. Label with [labelImg](https://blog.csdn.net/klaus_x/article/details/106854136) (or your tool).
2. Point `data/*.yaml` at your dataset ([example walkthrough](https://blog.csdn.net/qq_45945548/article/details/121701492)).
3. `python train.py` → copy the best `.pt` into `./pt/` and select it in the UI.

---

## 7. Testing & regression

There is no single `npm test` style command. Use:

- **`doc/refactor-regression.md`** — Level 1–3 smoke, UI checks, long-run camera notes, Modbus TCP checks.
- **`tools/bench_loop.py`** — e.g. `python tools/bench_loop.py --weights .\pt\yolov5s.pt --source streams.txt --duration 30`

**STOP (P0)**: verify on a safe bench before relying on software stop for production safety; use **PAUSE** and hardwired e-stop as required by your plant.

---

## 8. References & license

- YOLOv5 v6.1: https://github.com/ultralytics/yolov5/tree/v6.1  
- Mirror: https://github.com/bigcheng123/scratch-detect  
- License: [GPL-3.0](./LICENSE)

**Contact / feedback**: message maintainers as in the original project readme (e.g. @li-chey / @Alex_Kwan on the host platform).

> Doc sync: aligned with Chinese `readme.md` · 2026-05-14