# PreProcessing_Common

这个目录用于处理复杂度更高、艺术性更强的篆文字图像。当前提供轻量 clean、平滑和 SVG 矢量化三部分能力。

## 一键处理

推荐使用统一入口脚本，从原图直接输出 clean+smoothed PNG 和 SVG：

```bash
.venv/bin/python PreProcessing_Common/scripts/run_preprocessing.py \
  --input-dir PreProcessing_Common/original_characters \
  --image-output-dir PreProcessing_Common/processed_characters \
  --svg-output-dir PreProcessing_Common/vector_characters
```

输出：

- `--image-output-dir`：`原文件名_cleaned_smoothed.png`
- `--svg-output-dir`：`原文件名.svg`

脚本内部会先做轻量 clean，再做平滑和矢量化。笔画密度高、线条复杂的字会自动使用更少平滑和更低轮廓简化比例，以保留更多细节和线条感。

可选参数：

```bash
.venv/bin/python PreProcessing_Common/scripts/run_preprocessing.py \
  --input-dir PreProcessing_Common/original_characters \
  --image-output-dir PreProcessing_Common/processed_characters \
  --svg-output-dir PreProcessing_Common/vector_characters \
  --max-isolated-speck-area 32 \
  --max-hole-area 40 \
  --vector-smooth-iterations 1 \
  --epsilon-ratio 0.001
```

`--epsilon-ratio` 越小，SVG 保留的轮廓点越多，细节越多，文件也越大。

## 分步 clean

从项目根目录运行：

```bash
.venv/bin/python PreProcessing_Common/scripts/clean_characters.py
```

默认输入：

```text
PreProcessing_Common/original_characters
```

默认输出：

```text
PreProcessing_Common/cleaned_characters
```

输出文件会保留原文件名，并追加 `_cleaned`：

```text
篆文字_page_001_text_00.png -> 篆文字_page_001_text_00_cleaned.png
```

## 清理策略

这套脚本不会做矩阵化或强形态学重构，只做：

- 去除极小黑色噪点
- 去除远离主体笔画的孤立黑色污点
- 填补笔画内部的小白色气泡
- 去除靠边的细长扫描/裁切线
- 一次轻量 3x3 边缘平滑

可选参数：

```bash
.venv/bin/python PreProcessing_Common/scripts/clean_characters.py \
  --input-dir PreProcessing_Common/original_characters \
  --output-dir PreProcessing_Common/cleaned_characters \
  --min-component-area 8 \
  --max-isolated-speck-area 32 \
  --max-hole-area 40
```

如果需要完全跳过边缘平滑，可以加 `--no-smooth`。

`--max-isolated-speck-area` 只影响孤立黑色污点清理；`--max-hole-area` 控制笔画内部白色气泡填补。

## 输出 clean 前后对比图

生成原图和 cleaned 图的左右并排对比：

```bash
.venv/bin/python PreProcessing_Common/scripts/make_clean_comparisons.py
```

默认读取：

```text
PreProcessing_Common/original_characters
PreProcessing_Common/cleaned_characters
```

默认输出：

```text
PreProcessing_Common/comparisons
```

也可以指定目录：

```bash
.venv/bin/python PreProcessing_Common/scripts/make_clean_comparisons.py \
  --original-dir PreProcessing_Common/original_characters \
  --cleaned-dir PreProcessing_Common/cleaned_characters \
  --output-dir PreProcessing_Common/comparisons
```

## 平滑和矢量化

对 cleaned 图进行轻度平滑，并输出 SVG：

```bash
.venv/bin/python PreProcessing_Common/scripts/vectorize_characters.py
```

默认读取：

```text
PreProcessing_Common/cleaned_characters
```

默认输出：

```text
PreProcessing_Common/smoothed_characters
PreProcessing_Common/svg_characters
```

脚本会根据轮廓复杂度自动调整参数：笔画密度高、线条复杂的字会使用更少平滑和更低轮廓简化比例，以保留更多细节和线条感。

可选参数：

```bash
.venv/bin/python PreProcessing_Common/scripts/vectorize_characters.py \
  --input-dir PreProcessing_Common/cleaned_characters \
  --smoothed-dir PreProcessing_Common/smoothed_characters \
  --svg-dir PreProcessing_Common/svg_characters \
  --smooth-iterations 1 \
  --epsilon-ratio 0.001
```

`--epsilon-ratio` 越小，SVG 保留的轮廓点越多，细节越多，文件也越大。