# 拼豆底稿生成器 (Perler Beads Generator)

因为市面上的拼豆软件差强人意（可能是我没用到好的），所以花了大概两个小时，写了一个专门生成拼豆图纸的网站：

[perlerbeads.zippland.com](perlerbeads.zippland.com)

❓
想解决的（市场上拼豆软件的）问题：
1. 颜色识别，
2. 灰色毛状边界线，
3. 无法自适应合并同色系的颜色，
4. 手动着色困难，无法精准选择颜色
4. 无法给出采购清单，
5. 限制图片的导出和打印。

💯
目前（网站上的）功能：
1.  生成底稿，
2.  对应Mard颜色，
3.  解析风格选择（池化逻辑）
4.  自动合并邻近相似颜色
5.  统计每个颜色/一共有多少粒，
6.  半自动去除杂色，
7.  细节部分的手动着色（或修改）
7.  导出图纸，
8.  导出采购清单。

❤️ 如果有需求可以直接提，我集成在网站里。

✅
对于商家，我把算法的改进思路放在这里，
希望你们可以越做越好。
如果有其他想二开的同学，可以直接在项目提交pr，
这个思路也可以直接使用̋(ˊ•͈ꇴ•͈ˋ)

### 1️⃣ 初始颜色映射
黑色毛边是因为池化过程中对RGB 采用了 mean 操作，改为局部  max pooling ，每个单元，找到像素频率最高的 RGB 值，用欧氏距离查找最近的颜色就行

### 2️⃣ 区域颜色合并
杂色问题的产生，是因为没有进行颜色合并操作，需要从未访问单元格开始，使用BFS 查找欧氏距离小于阈值的邻近单元格，形成区域。将整个区域统一设置为该区域内出现次数最多的色号对应的颜色即可。

### 3️⃣ 背景移除
无法进行拼豆数量统计的原因，是没有进行背景移除操作：先定义背景色号列表。从图像所有边界单元格开始执行洪水填充。将所有与边界连通且颜色属于背景色号列表的单元格标记为"外部"。统计和下载时将忽略这些"外部"单元格即可。

### 4️⃣ 颜色排除与重映射
这是杂色自动去除仍不干净的情况下的附加功能，首先确定图像处理后最初包含的所有已存在颜色。重映射时，仅在已存在颜色中排除和其他已排除颜色的子集里寻找替换色。

## 功能特点

*   **图片上传**: 支持拖放或点击选择 JPG/PNG 图片。
*   **智能像素化**:
    *   **可调粒度**: 通过滑块控制像素画的横向格子数量。
    *   **颜色合并**: 通过滑块调整相似颜色的合并阈值，平滑色块区域。
*   **多色板支持**:
    *   提供多种预设拼豆色板 (如 168色, 144色, 96色等) 可供选择。
    *   根据所选色板进行颜色映射。
*   **颜色排除与管理**:
    *   在颜色统计列表中点击可**排除/恢复**特定颜色。
    *   排除颜色后，原使用该颜色的区域将智能重映射到邻近的可用颜色。
    *   提供一键恢复所有排除颜色的功能。
*   **实时预览**:
    *   即时显示处理后的像素画预览。
    *   **悬停/长按交互**: 在预览图上悬停（桌面）或长按（移动）可查看对应单元格的颜色编码 (Key) 和颜色。
    *   自动识别并标记外部背景区域（预览时显示为浅灰色）。
*   **下载成品**:
    *   **带 Key 图纸**: 下载带有清晰颜色编码 (Key) 和网格线的 PNG 图纸，忽略外部背景。
    *   **颜色统计图**: 下载包含各颜色 Key、色块、所需数量的 PNG 统计图。

## 技术实现

*   **框架**: [Next.js](https://nextjs.org/) (React) 与 TypeScript
*   **样式**: [Tailwind CSS](https://tailwindcss.com/) 用于响应式布局和样式。
*   **核心逻辑**: 浏览器端 [Canvas API](https://developer.mozilla.org/en-US/docs/Web/API/Canvas_API) 用于图像处理、颜色分析和绘制。
*   **状态管理**: React Hooks (`useState`, `useRef`, `useEffect`, `useMemo`)。

### 核心算法：像素化、颜色映射与优化

应用程序的核心是将图像转换为像素网格，并将颜色精确映射到有限的拼豆调色板，同时进行平滑和背景处理。

1.  **图像加载与网格划分**:
    *   加载用户上传的图片。
    *   根据用户选择的"粒度"(`granularity`, N) 和原图宽高比确定 `N x M` 的网格尺寸。

2.  **初始颜色映射 (基于主导色)**:
    *   遍历 `N x M` 网格。
    *   对每个单元格，在原图对应区域内找出出现频率最高的**像素 RGB 值 (Dominant Color)**（忽略透明/半透明像素）。
    *   使用**欧氏距离**在 RGB 空间中，将该主导色映射到**当前选定且未被排除**的调色板 (`activeBeadPalette`) 中最接近的颜色。
    *   记录每个单元格的初始映射色号和颜色 (`initialMappedData`)。

3.  **区域颜色合并 (基于相似度)**:
    *   使用**广度优先搜索 (BFS)** 遍历 `initialMappedData`。
    *   识别颜色相似（欧氏距离小于 `similarityThreshold`）的**连通区域**。
    *   找出每个区域内出现次数最多的**珠子色号**。
    *   将该区域内所有单元格统一设置为这个主导色号对应的颜色，得到初步平滑结果 (`mergedData`)。

4.  **背景移除 (基于边界填充)**:
    *   定义一组背景色号 (`BACKGROUND_COLOR_KEYS`, 如 T1, H1)。
    *   从 `mergedData` 的**所有边界单元格**开始，使用**洪水填充 (Flood Fill)** 算法。
    *   标记所有从边界开始、颜色属于 `BACKGROUND_COLOR_KEYS` 且相互连通的单元格为"外部背景" (`isExternal = true`)。

5.  **颜色排除与重映射**:
    *   当用户排除某个颜色 `key` 时：
        *   确定一个**重映射目标调色板**：包含网格中**最初存在**的、且**当前未被排除**的所有颜色。
        *   如果目标调色板为空（表示排除此颜色会导致没有有效颜色可用），则阻止排除。
        *   否则，将 `mappedPixelData` 中所有使用 `key` 的非外部单元格，重新映射到目标调色板中的**最近似**颜色。
    *   当用户恢复颜色时，触发完整的图像重新处理流程（步骤 1-4）。

6.  **生成预览图与下载文件**:
    *   **预览图**: 在 Canvas 上绘制 `mergedData`，根据 `isExternal` 状态区分内部颜色和外部背景（浅灰），并添加网格线。支持悬停/长按显示色号。
    *   **带 Key 图纸下载**: 创建临时 Canvas，绘制 `mergedData` 中非外部背景的单元格，填充颜色、绘制边框，并在中央标注颜色 Key。
    *   **统计图下载**: 统计 `mergedData` 中非外部背景单元格的各色号数量，生成包含色块、色号、数量的列表式 PNG 图片。

### 调色板数据

预设的拼豆调色板数据定义在 `src/app/colorSystemMapping.json` 文件中，该文件包含了所有颜色的hex值到各个色号系统（MARD、COCO、漫漫、盼盼、咪小窝）的映射关系。不同的色板组合 (如 168色、96色等) 在 `src/app/page.tsx` 的 `paletteOptions` 中定义。

## 许可证

Apache 2.0

# 拼豆图纸生成器微信小程序 PRD

## 1. 产品概述

### 1.1 产品定位
基于统一画布工作台理念的拼豆制作工具，为拼豆爱好者提供从图像处理到成品制作的一站式解决方案。

### 1.2 核心价值
- **一体化体验**：统一画布承载所有操作，无缝切换不同工作模式
- **智能色板**：自动适配不同店家色号体系，简化用户选择
- **渐进式引导**：从新手友好的预览模式到专业的编辑模式，再到专注的制作模式

### 1.3 目标用户
- 拼豆制作爱好者（初学者到专业玩家）
- 需要定制图案的用户
- 希望数字化管理拼豆项目的用户

## 2. 产品架构

### 2.1 整体流程
```
首页导入按钮 → 图像转像素画（预览模式） → 像素画编辑（编辑模式） → 专心拼豆（拼豆模式） → 完成分享
```

### 2.2 核心模块关系
- **统一色板模块**：为所有模块提供颜色数据和店家适配，以及通过勾选的自定义色板
- **统一画布模块**：承载所有视觉交互和模式切换
- **数据管理模块**：处理图像处理、存储和同步

## 3. 功能模块详述

### 3.1 首页模块

#### 3.1.1 功能概述
作为用户进入小程序的第一个接触点，提供简洁的功能入口和项目管理。

#### 3.1.2 主要功能（两个按钮）
- **快速开始**：一键创建新项目（图片上传/拍照）
- **色板设置**：全局店家色号体系选择

#### 3.1.3 界面布局
- 顶部（占据一半）：品牌标识
- 中部（大）：点击导入图片或者 csv 文件
- 下部（弱）：点击进入色板编辑（编辑后的色板储存在本地）

### 3.2 统一色板模块

#### 3.2.1 设计理念
基于 `colorSystemMapping.json` 构建的智能色板系统，对用户完全透明化 hex 值，只显示当前选择店家的色号命名。

#### 3.2.2 核心功能

**3.2.2.1 色板数据管理**
- 维护 291 个标准 hex 颜色
- 支持 5 个店家色号体系：MARD、COCO、漫漫、盼盼、咪小窝
- 动态映射：同一颜色在不同店家显示不同色号
- 全局色号体系切换：用户选择店家后，整个小程序所有颜色显示自动更新

**3.2.2.2 自定义色板机制**
- 用户可以自定义自己想要的色板（自己的拼豆颜色种类）

**3.2.2.3 交互设计**
- **预览模式**：色板仅用于信息展示，点击颜色显示详细信息
- **编辑模式**：色板作为画笔工具，支持颜色选择、自定义色板
- **拼豆模式**：色板按使用顺序和重要性排序，突出当前需要的颜色

#### 3.2.3 技术实现要点
- 建立 hex 到店家色号的单向映射索引
- 实现响应式色板组件，支持不同尺寸屏幕
- 色彩空间转换算法，确保颜色显示一致性

### 3.3 统一画布模块

#### 3.3.1 设计理念
单一画布承载所有视觉交互，通过模式切换实现不同功能状态，提供连贯的用户体验。

#### 3.3.2 核心功能

**3.3.2.1 基础画布能力**
- **自适应尺寸**：根据像素网格自动计算画布大小，初始化的时候最长边占满屏幕
- **手势支持**：双指捏合缩放、单指拖拽平移
- **性能优化**：大尺寸网格的虚拟化渲染，保证流畅性
- **坐标系统**：统一的网格坐标系，支持精确的像素级操作

**3.3.2.2 多模式状态管理**

**预览模式（Mode 1）**
- **视觉状态**：显示完整像素化结果，网格线清晰可见
- **交互行为**：
  - 点击：显示该位置颜色信息弹窗（店家色号 + 颜色预览）
  - 长按：显示周围区域的颜色分布热力图
  - 双击：快速放大到该区域
- **UI 覆盖层**：网格坐标标识、色彩统计信息

**编辑模式（Mode 2）**
- **视觉状态**：突出显示可编辑区域，当前工具状态指示
- **交互行为**：
  - 单击：使用当前画笔颜色填充像素
  - 长按：激活连续绘制模式
  - 双指点击：吸管工具，获取该位置颜色
- **工具栏集成**：画笔选择、橡皮擦、填充工具、撤销重做
- **实时预览**：编辑操作的即时视觉反馈

**拼豆模式（Mode 3）**
- **视觉状态**：游戏化界面，突出显示当前任务区域
- **交互行为**：
  - 点击：标记完成该像素
  - 长按：查看该区域的详细制作指导
- **进度系统**：完成度可视化、区域引导、成就反馈
- **辅助功能**：放大镜工具、颜色高亮、完成动画

**3.3.2.3 模式切换机制**
- **无缝转换**：保持画布视口位置和缩放比例
- **状态持久化**：每个模式的操作历史独立保存
- **上下文保护**：切换模式时保护用户当前操作进度

#### 3.3.3 技术架构

**3.3.3.1 渲染引擎**
- 基于微信小程序 Canvas 2D API
- 分层渲染：背景层、像素层、交互层、UI 层
- 局部刷新策略，仅重绘变化区域

**3.3.3.2 状态管理**
```typescript
interface CanvasState {
  mode: 'preview' | 'edit' | 'create'
  viewport: { x: number, y: number, scale: number }
  pixelData: MappedPixel[][]
  currentTool: ToolType
  operationHistory: Operation[]
}
```

### 3.4 图像转像素画模块（预览模式）

#### 3.4.1 功能概述
将用户上传的图像智能转换为适合拼豆制作的像素画，并提供预览和调整功能。

#### 3.4.2 图像处理流程

**3.4.2.1 图像预处理**
- **尺寸标准化**：自动调整为横轴 100 像素，纵轴按比例计算
- **色彩优化**：色彩空间转换、对比度增强、降噪处理
- **边缘处理**：智能识别和保护重要边缘信息

**3.4.2.2 像素化算法**
- **卡通模式**：基于主导色的像素化（保持色块纯净）
- **真实模式**：基于平均色的像素化（保持色彩过渡）
- **智能色彩映射**：将像素色彩映射到最接近的拼豆颜色

**3.4.2.3 后处理优化**
- **色彩合并**：相似颜色自动合并，减少色彩数量
- **区域优化**：小面积杂色自动清理
- **边缘锐化**：重要边缘的对比度增强

#### 3.4.3 交互功能
- **参数调节**：实时调整像素化精度、色彩合并阈值
- **区域预览**：支持局部放大查看细节效果
- **色彩统计**：显示使用的颜色数量和分布

### 3.5 像素画编辑模块

#### 3.5.1 功能概述
提供专业的像素画编辑能力，允许用户精细调整转换结果。

#### 3.5.2 编辑工具集

**3.5.2.1 基础绘制工具**
- **画笔工具**：支持不同大小的方形画笔
- **橡皮擦**：删除指定区域的像素
- **填充工具**：快速填充连通区域
- **吸管工具**：快速获取画布上的颜色

**3.5.2.2 高级编辑功能**
- **区域选择**：矩形、自由形状选择工具
- **批量替换**：将特定颜色批量替换为另一种颜色
- **图层管理**：支持多图层编辑（背景层、前景层等）
- **对称绘制**：支持水平、垂直对称绘制模式

**3.5.2.3 辅助功能**
- **网格对齐**：自动对齐到像素网格
- **颜色建议**：基于周围颜色推荐最适合的颜色
- **撤销重做**：支持多步操作的撤销和重做
- **实时预览**：编辑过程中的实时效果预览

#### 3.5.3 用户体验优化
- **手势识别**：支持常用编辑手势（缩放、拖拽、点击）
- **工具切换**：快速访问常用工具的浮动工具栏
- **操作反馈**：每个操作都有清晰的视觉反馈

### 3.6 专心拼豆模块

#### 3.6.1 功能概述
游戏化的拼豆制作指导系统，帮助用户有序完成拼豆作品。

#### 3.6.2 核心功能

**3.6.2.1 智能引导系统**
- **制作顺序优化**：基于颜色分布和难易度推荐制作顺序
- **区域推荐**：
  - 最近优先：推荐距离当前位置最近的未完成区域
  - 大块优先：优先推荐大色块区域，提高效率
  - 边缘优先：从外围向内部制作，符合拼豆制作习惯

**3.6.2.2 进度管理**
- **颜色进度跟踪**：每种颜色的完成进度可视化
- **区域完成标记**：点击标记已完成的像素区域
- **总体进度展示**：整体完成百分比和剩余工作量

**3.6.2.3 辅助工具**
- **放大镜功能**：支持选择特定区域进行放大操作
- **颜色高亮**：突出显示当前工作颜色的所有位置
- **完成动画**：颜色完成时的庆祝动效

#### 3.6.3 用户体验设计

**3.6.3.1 游戏化元素**
- **成就系统**：设置里程碑奖励（完成第一个颜色、完成 50% 等）
- **进度条动画**：平滑的进度变化动画
- **完成庆祝**：作品完成时的特殊庆祝效果

**3.6.3.2 实用功能**
- **时间记录**：记录制作时间，支持暂停和继续
- **拍照记录**：支持拍照记录制作进度
- **分享功能**：生成完成图片，支持分享到社交平台

### 3.7 数据管理模块

#### 3.7.1 本地存储
- **项目文件**：完整的像素画数据、编辑历史、进度信息
- **用户设置**：色板偏好、操作习惯、界面配置
- **缓存管理**：图像处理结果缓存、色板数据缓存