# tool

**Repository Path**: pageone/tool

## Basic Information

- **Project Name**: tool
- **Description**: No description available
- **Primary Language**: Unknown
- **License**: Not specified
- **Default Branch**: master
- **Homepage**: None
- **GVP Project**: No

## Statistics

- **Stars**: 0
- **Forks**: 0
- **Created**: 2026-10-22
- **Last Updated**: 2026-10-22

## Categories & Tags

**Categories**: Uncategorized

**Tags**: None

## README

# 拼豆图纸生成器

把一张图片转换成拼豆（Perler / fuse bead）图纸：效果预览、每颗豆的 MARD 色号编号、颜色用量统计，以及 PNG / PDF / CSV / JSON 下载。纯本地运行，图片不会上传到任何服务器。

## 快速开始

微信小程序版源码位于 [`miniprogram/`](miniprogram/README.md)，与 Web 共用 Python 算法和全部转换、导出接口。小程序将图片发送到配置的服务处理；开发联调和上线配置见该目录说明。

```bash
./run.sh
```

首次运行会自动下载 NumPy 到 `vendor/`，然后打开 <http://127.0.0.1:8765>。

手动启动：

```bash
./setup.sh          # 安装/检查依赖
python3 app.py      # 或 ./run.sh --port 9000 --no-browser
```

依赖：

- Python 3.10+
- Pillow 10+（系统包或 `pip install pillow`）
- NumPy（由 `setup.sh` 下载到 `vendor/`，不需要 pip）

## 功能

- 上传 PNG / JPEG / WebP / GIF / BMP，支持拖拽、粘贴。
- 自定义成品宽度、高度（8–300 颗；高度留空按原图比例）。
- 限制最大颜色数（0 = 不限），可选 Floyd–Steinberg 抖动。
- 从图片边缘识别纯色背景并去除，容差可调。
- 清理孤立单颗豆，减少噪点。
- 效果图可显示网格；编号图纸每格显示 MARD 色号，带 5/10 格辅助线与行列坐标。
- 三栏结果：效果图 / 编号图纸 / 用量清单。
- 下载编号图纸 PNG、可打印 A4 PDF、CSV 用量表、JSON 图案数据。
- 点击结果图可在新标签页查看大图。

## 使用说明

1. 选择或拖入图片。
2. 设置成品尺寸、最大颜色数、是否抖动/去背景/清理孤立豆。
3. 点击「生成图纸」（修改参数后也会自动重新生成）。
4. 在「效果图 / 编号图纸 / 用量清单」之间切换，或下载文件。

编号图纸中每格文字就是对应豆子的 MARD 色号，可直接按格摆放。PDF 按 A4 分页：摘要页、用量清单页，以及每页 50×50 格的编号图纸。

## 输出文件

每次生成会在 `outputs/<job_id>/` 下写入：

| 文件 | 内容 |
| --- | --- |
| `preview.png` | 立体豆子效果图 |
| `chart.png` | 带色号、网格、坐标的编号图纸 |
| `counts.csv` | 每种颜色的色号、名称、数量、占比 |
| `pattern.json` | 尺寸、参数、完整色号矩阵 |
| `pattern.pdf` | 按需生成的 A4 打印版 |

`outputs/` 会在启动时清理 7 天前的任务目录。

## 参数与 API

主要接口：

```text
GET  /api/health
GET  /api/palette
POST /api/convert        请求体为图片原始字节（application/octet-stream）
GET  /api/pdf/<job_id>   首次请求时生成 PDF
GET  /outputs/<job_id>/<file>
```

`/api/convert` 参数：

| 参数 | 默认 | 说明 |
| --- | --- | --- |
| `width` | 50 | 成品宽度（颗） |
| `height` | 自动 | 成品高度（颗） |
| `max_colors` | 24 | 最大颜色数，0 为不限 |
| `dither` | 0 | 1 启用抖动 |
| `remove_bg` | 0 | 1 去除边缘纯色背景 |
| `bg_tolerance` | 40 | 背景颜色容差（0–120） |
| `cleanup` | 0 | 1 清理孤立豆 |
| `show_grid` | 0 | 1 在效果图上画网格 |

示例：

```bash
curl --data-binary @samples/landscape.png \
  -H 'Content-Type: application/octet-stream' \
  'http://127.0.0.1:8765/api/convert?width=50&max_colors=24'
```

## 色卡

内置 MARD（咪嗒/漫漫）291 色，数据在 `palettes/mard.json`，每项包含：

```json
{"code": "A1", "name": "白色", "series": "A", "hex": "#FFFFFF", "rgb": [255, 255, 255]}
```

色号与屏幕 RGB 仅为参考，实际豆子颜色可能因批次和显示器存在差异。色卡数据整理自 [pixelbead.art 的 MARD 色卡](https://www.pixelbead.art/zh/guides/mard-bead-color-chart)。

替换色卡时保持同样的字段结构即可，应用启动时会自动加载。

## 还原度与细节

网页默认显示原色像素预览，避免模拟豆孔和间隙影响颜色与文字辨识；可开启「立体豆子预览」查看摆豆效果。

网页默认使用 150 颗宽、最多 48 色；包含文字、Logo 的图片可选择「高还原」预设（225 颗宽、最多 64 色）。高度自动保持比例，最长边仍限制为 300 颗；高还原会显著增加用豆数量。API 不传尺寸时仍默认 50 颗宽、24 色。

「保留细节」默认开启，使用 Lanczos 缩图和适度锐化，减少细线与文字的模糊。限色时按整体感知色差选取代表色，避免只保留大面积颜色；抖动在最终选定的色卡内进行。处理透明图片时先预乘透明度，避免透明像素中的隐藏颜色污染边缘。

文字图建议关闭「抖动」和「清理孤立豆」，避免噪点或清理操作破坏笔画。50 颗宽的图无法容纳小字的全部细节；提高尺寸比单纯增加颜色更有效。API 可传 `preserve_detail=0` 关闭细节增强。

## 算法简述

1. 读取图片并应用 EXIF 方向，限制超大图片。
2. 在线性光空间进行透明度预乘缩放，默认使用 Lanczos 并适度增强细节。
3. 按透明度/边缘连通区域处理背景。
4. 每个格子取平均颜色，转换到 CIELAB。
5. 用 CIE76 先筛出 16 个候选色，再用 CIEDE2000 精确匹配（与全量 CIEDE2000 结果一致，但快很多）。
6. 按加权感知误差选择限色色卡，重新匹配原始格子颜色；可选在限色色卡内抖动及孤立豆清理。
7. 渲染效果图与编号图纸；PDF 在用户点击下载时才生成。

## 项目结构

```text
app.py                 HTTP 服务与 API
beadify/
  colorspace.py        Lab、CIEDE2000、最近色
  palette.py           色卡加载
  quantize.py          图片 -> 豆子网格
  render.py            效果图 / 编号图纸
  export.py            CSV / JSON / PDF
static/                前端页面
palettes/mard.json     MARD 291 色
samples/               示例图片
vendor/                本地 NumPy（setup.sh 生成）
outputs/               生成结果（自动清理）
```

## 测试

测试结果保存在独立目录 `test-results/`，直接打开 `test-results/report.html` 查看带截图的完整报告：

- 14 个 API 功能用例（当前测试脚本）
- 6 个边界/错误用例
- 15 项浏览器 UI 检查（当前测试脚本）
- 历史报告为 326/326 项检查通过；当前验证结果见 `test-results/quality/README.md`

无需网络套接字的算法与 API 检查：

```bash
python3 test-results/test_quantize.py
python3 test-results/test_api_inprocess.py
```

重新运行全部测试：

```bash
./test-results/run_all.sh
```

## 常见问题

- **启动时报 `ModuleNotFoundError: numpy`**：运行 `./setup.sh`，或 `python3 -m pip install --target vendor numpy`。
- **缺少 Pillow**：`python3 -m pip install --user pillow`，或用系统包管理器安装 `python3-pil`。
- **端口被占用**：`./run.sh --port 9000`。
- **不想自动打开浏览器**：`./run.sh --no-browser`。
- **图纸太大**：成品尺寸上限为 300×300；建议先控制在 50–150 颗宽，PDF 会按 50×50 分页。