Metadata-Version: 2.4
Name: ydl2
Version: 0.2.0
Summary: OpenCV 轻量扩展(Unicode 路径/HALCON 缩放/形状匹配)，可选 UNet 分割训练与推理
Author-email: 无敌的杨 <ydl779762225@gmail.com>
License-Expression: MIT
Project-URL: Homepage, https://github.com/CiweiWenruo/ydl2
Keywords: opencv,cv2,image,halcon,scale_image,segmentation,unet,pytorch
Classifier: Development Status :: 4 - Beta
Classifier: Intended Audience :: Developers
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3.8
Classifier: Programming Language :: Python :: 3.9
Classifier: Programming Language :: Python :: 3.10
Classifier: Programming Language :: Python :: 3.11
Classifier: Programming Language :: Python :: 3.12
Classifier: Topic :: Scientific/Engineering :: Image Processing
Requires-Python: >=3.8
Description-Content-Type: text/markdown
License-File: LICENSE
Requires-Dist: numpy>=1.21
Requires-Dist: opencv-python>=4.6
Provides-Extra: cnn
Requires-Dist: torch>=2.0; extra == "cnn"
Requires-Dist: torchvision; extra == "cnn"
Requires-Dist: segmentation-models-pytorch; extra == "cnn"
Requires-Dist: pyyaml; extra == "cnn"
Requires-Dist: addict; extra == "cnn"
Requires-Dist: tqdm; extra == "cnn"
Requires-Dist: pillow; extra == "cnn"
Provides-Extra: cnn-onnx
Requires-Dist: onnx; extra == "cnn-onnx"
Requires-Dist: onnxruntime; extra == "cnn-onnx"
Dynamic: license-file

# ydl2

`ydl2` 是对 OpenCV 的轻量补充：解决 **Windows 中文路径** 读写问题，提供与 **HALCON** 语义一致的灰度缩放算子，以及基于 HALCON 的**形状模板匹配**封装。

## 安装

```bash
# 核心(轻量，仅 numpy + opencv)：中文路径、HALCON 缩放、形状匹配
pip install ydl2

# 额外解锁 UNet 分割训练与推理(会安装 torch 等)
pip install ydl2[cnn]

# 再额外需要 ONNX 导出/推理时
pip install "ydl2[cnn,cnn-onnx]"
```

`pip install ydl2` 与现在一致，只有 HALCON / OpenCV 相关功能；只有
`pip install ydl2[cnn]` 之后，下方的 `ydl2.cnn`(UNet 训练/推理)才可用。

## 快速使用

### Unicode 路径 & 灰度缩放

```python
import ydl2

# Unicode 路径读写（Windows 中文路径）
img = ydl2.imread(r"D:\图片\测试.png")
ydl2.imwrite(r"D:\图片\输出.png", img)

# HALCON 等价算子
stretched = ydl2.scale_image_max(img)
inverted  = ydl2.scale_image(img, -1.0, 255.0)
mapped    = ydl2.scale_image_range(img, 100, 200)
```

### 形状模板匹配

```python
import ydl2
import cv2

# 加载模板（只需一次）
model = ydl2.read_shape_model(r"model.yyds")

# 读图并创建图像句柄（首次）
mat = cv2.imread(r"image.jpg")
b, g, r = cv2.split(mat)
handle = ydl2.any_to_tiyoo(r, g, b)

# 匹配
results = ydl2.find_shape_model(handle, model)
for res in results:
    print(res['row'], res['col'], res['score'])

# 后续帧原地更新（零内存分配）
handle = ydl2.any_to_tiyoo(r, g, b, handle=handle)

# 释放
ydl2.clear_image(handle)
ydl2.clear_shape_model(model)
```

## API

| 函数 | 说明 |
|------|------|
| `imread` / `imwrite` / `imshow` | 支持中文路径的读写与显示 |
| `scale_image_max` | 每通道 min/max 拉伸到 0–255 |
| `scale_image` | `g' = g * Mult + Add` |
| `scale_image_range` | 区间线性映射 |
| `any_to_tiyoo` | numpy 数组 → Halcon 图像句柄（创建或原地更新） |
| `tiyoo_to_any` | Halcon 图像句柄 → numpy 数组 |
| `read_image` / `write_image` / `clear_image` | Halcon 图像文件读写与释放 |
| `read_shape_model` / `clear_shape_model` | 加载 / 释放 Halcon 模板文件 |
| `find_shape_model` | 形状模板匹配，返回 `[{'row', 'col', 'angle', 'score'}]` |

## 分割(CNN)：UNet 训练与推理

`ydl2.cnn` 提供 YOLO 风格的极简分割接口（基于 PyTorch + segmentation-models-pytorch 的 UNet）。
需先安装 `pip install ydl2[cnn]`；未安装时导入会给出中文安装提示，不影响核心包。

### 训练

```python
from ydl2.cnn import Seg

# 用配置文件训练(配置写法见 train-x 的 configs/segmentation/*.yaml)
Seg("smp_unet_xray_defect_fast.yaml").train()

# 断点续训
Seg("cfg.yaml").train(resume="work_dir/checkpoints/last.pth")
```

训练已内置深度优化：AMP(bf16/fp16)、channels_last、梯度累积、LR 预热、
权重 EMA、CUDA 预取、内存缓存、GPU 端流式验证指标等(可在配置的 `runner`/`hooks` 中开关)。

### 推理

```python
from ydl2.cnn import Seg

m = Seg("best.pth", config="cfg.yaml", device="cuda")
m.warmup()                              # 预热，消除首图冷启动

mask = m.predict("a.png")               # 传路径或 numpy 数组，返回 mask
vis, mask = m.predict("a.png", visualize=True)   # 叠加可视化
masks = m.predict_batch(["a.png", "b.png"])      # 批量推理

m.release()                             # 释放显存/上下文
```

推理已启用 channels_last、`inference_mode`、autocast(可选 FP16)、GPU 端最近邻还原尺寸等优化。

### 预热 / 保温 / 释放

针对“进程常驻但久未推理后，第一张图明显变慢(GPU 空闲自动降频)”的工业场景：

```python
m.warmup(n=3)                # 预热：用真实输入尺寸预跑，触发 cudnn 自整定与显存预热

# 保温：低功耗脉冲(默认)
m.keep_warm(True, mode="pulse", interval=30)
# 保温：锁频(首图最快、功耗较高，需要管理员权限锁 GPU 时钟)
m.keep_warm(True, mode="lock")
m.keep_warm(False)           # 关闭保温

m.release()                  # 停止保温线程并释放资源；也支持 with Seg(...) as m:
```

保温设计要点：

- 保温线程与推理共享同一把锁，脉冲用“非阻塞拿锁”，真实推理在跑时直接跳过本次脉冲，
  绝不阻塞或拖慢正常工业检测推理；
- 刚推理过的活跃期内不脉冲，省电；
- 功耗权衡：
  - `pulse`(默认)：每 `interval` 秒一次极短前向，平均增量功耗很小；极长空闲后首图可能仍略慢；
  - `lock`：用 `nvidia-smi` 把 GPU 时钟钉在高位，首图最快，但空闲功耗明显上升；锁频失败(无权限/不支持)会自动回退为高频脉冲。

## 依赖

- Python >= 3.8
- numpy >= 1.21
- opencv-python >= 4.6
- 分割功能(可选 `[cnn]`)：torch >= 2.0、torchvision、segmentation-models-pytorch、pyyaml、addict、tqdm、pillow
- ONNX(可选 `[cnn-onnx]`)：onnx、onnxruntime

## 链接

- 仓库：<https://github.com/CiweiWenruo/ydl2>
