本地优先的拼豆像素创作工作台
Biz-BeadCraft 把照片、插画和角色图像转换成真正可以制作的拼豆图纸：你可以调整构图、控制尺寸和颜色、移除背景、编辑单颗豆，并在生成前看到清晰的材料统计。
English — Biz-BeadCraft is a local-first pixel bead pattern studio for turning images into editable, material-aware bead plans in the browser.
- 完成实时图片转换工作台：裁切、缩放、完整显示和像素预览都在同一操作层完成。
- 新增区域平均采样、OKLab/CIEDE2000 色差、多种抖动和孤立豆清理策略。
- 新增本地 AI 去背景、手动遮罩、透明/纯色背景合成和原尺寸 PNG 导出。
- 新增辅助线、制作起点、移动端参数抽屉和桌面/移动定向测试。
- 加入工作台示例图，展示遮罩编辑与像素预览的并行工作流。
- 完成 GitHub 开源发布文档、Apache-2.0 许可证和第三方模型说明。
完整历史见 发布记录。
拼豆图纸不只是把图片缩小成马赛克。有限的色卡、固定的网格、真实的材料数量和制作难度，都会影响最终作品是否“像”和“能拼”。Biz-BeadCraft 将这些约束放进同一条本地工作流，让你从灵感图片直接走到可编辑、可制作的图纸。
| 能力 | 说明 |
|---|---|
| 图片转换 | 支持 PNG、JPG、WebP；最多约 100 万源像素，转换在 Worker 中执行 |
| 构图控制 | 居中裁切铺满、完整显示留白、拖动定位、滚轮/双指缩放和比例锁定 |
| 高质量采样 | 最近邻或区域平均采样；预乘 Alpha；支持透明边缘 |
| 感知色差 | RGB、OKLab、CIEDE2000；可选相似色合并 |
| 抖动与清理 | Floyd–Steinberg、Atkinson、Bayer、Clustered；孤立豆和小区域清理 |
| 本地去背景 | 按需加载 Transformers.js 模型；AI 遮罩、背景吸管、保留/擦除画笔 |
| 遮罩处理 | 阈值、扩缩、羽化、去边缘杂色、撤销/重做和 AI 结果重置 |
| 图纸编辑 | PixiJS 主渲染、Canvas 降级、画笔、填充、橡皮擦、撤销/重做 |
| 制作辅助 | 构图九宫格、像素豆格线、任意制作起点与相对坐标方向 |
| 材料统计 | 按色卡统计颜色使用量、单色数量和总豆数 |
| 输出 | 透明/纯色抠图 PNG；图纸生成结果可继续进入编辑工作流 |
| 响应式工作台 | 桌面端双预览与右侧参数；移动端标签切换和底部参数抽屉 |
示例：本地遮罩编辑、透明背景合成与实时像素预览。
工作台的核心路径是：
选择图片 → 调整构图 → 可选去除背景 → 实时像素预览 → 应用为图纸 → 编辑与统计
当前 3D 预览入口已保留在工作台流程中，真实拼豆材质与熨烫渲染属于后续里程碑；2D 图纸、转换算法和材料统计是当前可用闭环。
- Node.js 22 或更高兼容版本
- pnpm 10
- Chromium（仅运行 Playwright 测试时需要）
pnpm install
pnpm dev打开 http://localhost:4173/workspace。所有命令都从仓库根目录执行。
pnpm format:check
pnpm lint
pnpm typecheck
pnpm test --run
pnpm build
pnpm exec playwright test -c playwright.config.ts普通图片解码、像素转换、图纸生成和编辑均在浏览器本地完成，原图不会上传到应用服务器。
背景移除模型只有在用户主动点击“移除背景”后才会下载。模型文件由浏览器缓存，推理、遮罩编辑和 PNG 导出仍在本地执行。详细模型来源、版本和许可证见 第三方组件与模型说明。
- React 19 + TypeScript + Vite
- Zustand：转换会话、编辑历史和工作台状态
- PixiJS：高性能图纸纹理渲染
- Web Worker：图片转换与本地背景移除
@bead/pattern-core：采样、色差、抖动、清理和 Pattern 领域算法- Transformers.js + ONNX Runtime：按需加载的浏览器端背景移除
- Vitest、Testing Library、Playwright：单元、组件和桌面/移动端流程测试
核心数据流：
原始图片
→ PreparedImage
→ 构图/背景遮罩
→ 采样与色差匹配
→ 抖动/清理
→ Pattern
→ 编辑、统计和导出
apps/web/ 浏览器工作台、转换状态、Worker 和 E2E
packages/pattern-core/ Pattern 类型与图片转换算法
packages/palette/ 内置色卡与颜色查询
packages/design-system/ 共享 UI 组件与 Storybook
packages/rendering/ 2D/3D 渲染公共契约
docs/ 产品、架构、规划、发布与协作文档
- 图片导入、构图、像素转换和实时预览
- 高质量采样、感知色差、抖动与图案清理
- 本地 AI 去背景与手动遮罩编辑
- 2D 图纸编辑、材料统计和制作起点
- 真实拼豆材质、熨烫和 3D 成品渲染
- PNG/PDF 图纸、材料清单和成品效果图完整导出
- 浏览器草稿持久化与项目分享
欢迎通过 Issue 或 Pull Request 参与后续迭代。
项目代码使用 Apache License 2.0。背景移除模型和 Transformers.js 依赖分别遵循其上游许可证；请阅读 第三方组件与模型说明。