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…

194 ·GitHub
Bead-grid-studio
这是什么？Bead Grid Studio 是一个本地优先的工具，把图片转换成可编辑、可打印的拼豆图纸，支持自动配色匹配、网格坐标和用料统计。
这是桌面应用、网站，还是需要安装的东西？它是一个完全在浏览器中运行的 Web 应用和 PWA；另有单文件离线 HTML 版本，可在没有网络的环境下使用。
怎么开始把图片变成拼豆图纸？打开在线版，点击示例图片或上传你自己的 PNG/JPG/WebP/GIF，选择网格尺寸或真实底板，调整颜色或用画笔修点，然后把图纸导出为 PNG，或把项目保存为 JSON。
使用它需要安装什么吗？普通用户无需安装任何东西，打开网页应用或下载离线 HTML 文件即可。只有想从源码构建的开发者才需要 Node.js 22.12 或更高版本。
小网格尺寸能完美还原我的图片吗？不能——16x16 网格只有 256 个格子，比一颗珠子还小的细节（细线、小字、反光）无法全部呈现；这个工具会尽量保住能保留的结构，并如实报告装不下的部分，而不是假装完美。
它能完全离线使用吗？可以，你可以从 Releases 下载一个自包含的单 HTML 文件，在任何现代浏览器中离线运行；也可以联网加载一次后，把 PWA 安装到主屏幕。
它用什么色卡来匹配珠子？它使用一个固定的 MIT 许可数据源，包含 221 色的基础子集（A-H、M 类），与 MARD 兼容；其中 220 种不透明颜色用于量化，透明的 H1 色保留给手动放置。
我可以 fork 它做自己的品牌版本吗？可以，项目明确支持 fork，用于部署自己的站点、更换品牌、添加经过验证的色卡、改进转换算法或新增语言，并提供到 GitHub Pages 或 Cloudflare Pages 的引导式部署流程。
除了生成图纸，它还提供哪些拼豆辅助功能？它包含一个逐色聚焦助手，一次只突出一种珠子颜色，并跟踪按颜色统计的完成进度（保存在本地），还能导出带色号、数量和完成状态的 UTF-8 CSV 用料清单。
它支持哪些图片格式和底板布局？它接受 PNG、JPG、WebP 和 GIF 图片，支持 2.6mm 和 5mm 等常见真实底板尺寸，图纸居中显示且不会拉伸变形。
What are similar projects?VibeOffice, beadrelief, PCB_lightgraph_Portable, squoosh, piskel, rubrictrail, palette-from-image-ai, reelmimic
Which topics is it in?pixel-art, pwa, canvas, offline-first, image-processing, local-first, web-app, privacy, tool, apache-2.0, javascript, open-source
Creator
zwhy149
Size
2.4 MB
Stars
194
Updated
CommitSep 20Releasev1.3.0Sep 19
Age
2mo
Commits · 90 Days