bead-grid-studio README

The project's README from github.com/zwhy149/bead-grid-studio. As one markdown file: README.md.

拼豆图纸生成器|豆格工坊(图片转拼豆 / 拼豆像素画)

把图片变成可编辑、可打印的拼豆施工图。
Bead Grid Studio 支持图片转拼豆、拼豆像素画编辑、自动配色、逐格色号、辅助线与用料统计,全程在你的浏览器本地完成。

简体中文 · English

🚀 在线体验 · ⬇ 离线版 / GitHub Release · 30 秒上手 · ⭐ GitHub Star

CI License: Apache-2.0 Release

示例 / Examples

Simple Graphic / 简洁图形:原图 → 拼豆图纸

两侧都使用仓库自有的火箭素材。右侧是应用真实运行后生成的界面截图,不是 AI 绘制的产品假图。

原始图片 自动生成并可继续编辑的拼豆图纸
仓库自有火箭原图 中文桌面版生成火箭拼豆图纸

截图会由 npm run capture:docs 使用同一张火箭素材自动更新。完整的中文桌面与手机截图见界面预览。

它能帮你完成什么

30 秒快速开始

  1. 打开在线版。
  2. 点击 试试示例,不需要先准备图片,几秒钟即可看到真实火箭图纸。
  3. 选择图案长边格数或真实底板;不确定时保留自动推荐。
  4. 根据需要调整颜色或用画笔修正一两格。
  5. 点击 开始制作,按颜色逐项摆豆;也可直接点击 导出图纸 保存施工图。
  6. 需要备料或记录进度时,从用料统计导出 CSV,并保存 JSON 工程。

也可以直接点击 选择图片,使用 PNG、JPG、WebP 或 GIF。图片只在当前浏览器内解码和转换。

选择适合你的使用方式

你想做什么 最省事的入口 是否需要安装
立即把图片转成拼豆图 打开在线版 不需要
断网使用或保存到 U 盘 从 Releases 下载单 HTML 不需要
部署成自己的公开网页 Fork 与部署教程 需要 GitHub 账号;Cloudflare 可选
修改代码或参与开发 开发者本地运行 需要 Node.js

下载离线版

普通使用者不需要下载源码,也不需要安装 Node.js。离线版是一个完整 HTML 文件,适用于 Windows、macOS 和 Linux 的现代浏览器:

  1. 打开最新 Release。
  2. 展开页面底部的 Assets。
  3. 下载名字类似 bead-grid-studio-vX.Y.Z.html 的文件,其中 X.Y.Z 是版本号。
  4. 不要把 GitHub 自动生成的 Source code ZIP 当作离线应用。
  5. 双击 HTML 并选择 Chrome、Edge、Firefox 或 Safari 打开。

单 HTML 已内嵌代码、样式、Apache-2.0 许可证和第三方许可,不依赖外部 CDN。Release 还提供 ZIP 和 SHA256SUMS.txt;校验时只与同一个 Release 中的文件比较:

# Windows PowerShell:先进入下载目录
Get-FileHash .\bead-grid-studio-vX.Y.Z.html -Algorithm SHA256
Get-Content .\SHA256SUMS.txt
# Linux
sha256sum --check SHA256SUMS.txt

# macOS
shasum -a 256 bead-grid-studio-vX.Y.Z.html

手机用户优先使用在线 PWA,并通过浏览器“添加到主屏幕”。PWA 必须先在 HTTPS 网页中完整加载一次,之后才能用缓存断网打开。草稿保存在当前浏览器站点数据中;更换浏览器或清理缓存前,请导出 JSON 工程。

Fork 后做成自己的版本

Fork 不只是复制代码。你可以用它:

最短流程:

Fork → 启用 GitHub Actions → Settings → Pages → Deploy

仓库已经包含构建、完整 QA 和 Pages 工作流,不需要手工提交 dist。按中文 Fork 与部署教程操作,通常几分钟即可得到自己的 GitHub Pages 地址;需要自定义域名和安全响应头时,可继续使用同一教程中的 Cloudflare Pages 方案。

界面预览

中文桌面工作台 中文手机工作台
中文桌面工作台 中文手机工作台

截图里的火箭位于 tests/fixtures/,由仓库自行制作,可按本项目许可证使用。

如果第一次结果不理想

本项目不会承诺把任意图片在 16 或 24 格内“无损还原”。它会尽量保护轮廓、开口和彼此分离的小部件;如果细节已经小于一颗豆,会明确提示,而不是静默声称完美。

开发者本地运行

需要 Node.js 22.12 或更高版本:

git clone https://github.com/zwhy149/bead-grid-studio.git
cd bead-grid-studio
npm ci
npm run dev

完整测试:

npm run setup
npm run qa

npm run qa 会执行源码、许可和色板门禁,纯函数测试,Chromium/Firefox/WebKit E2E,以及应用内转换回归。

当前重点

完整计划见 ROADMAP.md。

帮助项目成长

第一次参与可先查看 good first issue。

维护者可以运行 npm run metrics 查看 GitHub 官方公开 API 返回的 Stars、Forks、Open Issues 和真实 Release asset 下载量。该脚本不在网页中运行,也不会追踪应用访问者。

需要核验项目活跃度、社区处理记录、发布安全和公开数据边界时,请查看项目健康度与公开影响证据。

主要能力与工程边界

小网格为什么不可能“一模一样”

豆格数量就是信息容量:16×16 只有 256 个位置,源图中小于一格的鼻点、细字或反光不可能全部独立表示。转换器会保护可表达的结构,并报告无法容纳的细节。详见算法说明和已知限制。

色号与实物色差

默认色板为固定 MIT 数据源中的基础 221 子集(A/B/C/D/E/F/G/H/M)。屏幕 HEX 只能近似表示实物;显示器、环境光、打印、品牌配方和生产批次都会产生差异。大量采购前,请用实际购买品牌与批次的实物色卡复核。完整来源见色板来源。

MARD、Artkal、Hama、Perler 等是第三方标识,本项目与这些品牌不存在隶属或官方背书关系。见商标说明。

隐私与安全

安全问题请按 SECURITY.md 私下报告。公开 Issue 不要附带隐私图片、客户图片或无权公开的作品。GitHub Pages 不会应用仓库里的可选 _headers 文件;具体托管安全边界见部署说明。

仓库结构

src/                      浏览器应用、核心 Module、i18n 和色板数据
public/                   PWA、离线缓存、SEO、隐私与许可页
tests/unit/               纯函数不变量测试
tests/e2e/                桌面、移动端和浏览器测试
tests/fixtures/           自制或明确授权的测试图
scripts/                  源码检查、截图、指标和单 HTML 构建
docs/                     架构、算法、部署、色板来源和 ADR

许可证

代码采用 Apache-2.0。第三方数据和构建工具归属见 NOTICE。许可证允许商业复用,但不授予“豆格工坊”名称、Logo 或第三方品牌标识的使用权。

如果项目确实帮你省去了一次手工描图,可以 Star 仓库、分享给其他拼豆爱好者,或提交可复现的改进建议。Star 不会解锁任何功能。

bead-grid-studio (zwhy149/bead-grid-studio)

Searching Database…

What is this?Bead Grid Studio is a local-first tool that turns an image into an editable, printable fuse-bead (pindou) pattern, with auto color matching, grid coordinates, and material usage stats.
Is this a desktop app, a website, or something I install?It is a web app and PWA that runs entirely in your browser; there is also a single-file offline HTML build for use without internet access.
How do I start turning a picture into a bead pattern?Open the online version, click the sample image or upload your own PNG/JPG/WebP/GIF, pick a grid size or real baseplate, tweak colors or touch up with the brush, then export the pattern as PNG or save the project as JSON.
Do I need to install anything to use it?Regular users need nothing installed; just open the web app or download the offline HTML file. Only developers who want to build from source need Node.js 22.12 or higher.
Will small grid sizes reproduce my image perfectly?No — a 16x16 grid only has 256 cells, so details smaller than one bead (fine lines, small text, reflections) can't all be represented; the tool protects what structure it can and reports what it can't fit instead of faking perfection.
Can I use it completely offline?Yes, you can download a single self-contained HTML file from Releases that runs offline in any modern browser, or install the PWA to your home screen after one online load.
What color palette does it use for matching beads?It uses a fixed MIT-licensed data source with a basic 221-color subset (categories A-H, M), MARD-compatible, with 220 opaque colors used for quantization and a transparent H1 color reserved for manual placement.
Can I fork this and make my own branded version?Yes, forking is explicitly supported for deploying your own site, changing branding, adding verified palettes, improving the conversion algorithm, or adding new languages, with a guided deploy flow to GitHub Pages or Cloudflare Pages.
What kind of bead-making assistance does it offer beyond generating the pattern?It includes a color-by-color focus assistant that highlights one bead color at a time, tracks per-color completion progress saved locally, and exports a UTF-8 CSV materials list with color codes, quantities, and completion status.
What image formats and baseplate layouts does it support?It accepts PNG, JPG, WebP, and GIF images, and supports common real baseplate sizes like 2.6mm and 5mm with the pattern centered and not stretched out of proportion.
Creator
zwhy149
Size
2.4 MB
Stars
194
Age
2mo
Commits · 90 Days