PixelBead-Codex-Skill：图片转 MARD 拼豆图纸

本项目是一个基于 Codex Skill 的拼豆图纸生成工具。用户输入一张图片后，Skill 会通过部署在沐曦 GPU 算力环境上的 Moark / Gitee.AI Serverless 大模型完成抠图、图像类型判断和尺寸规划，再使用 Skill 内置确定性算法生成可打印的 MARD 拼豆图纸、预览图、用豆清单和真实调用日志。

GitLink 仓库：

https://www.gitlink.org.cn/xy111/pixelbead-codex-skill

项目特点

• 支持卡通图、人像、Logo、物体照片和复杂照片。
• 使用 RMBG-2.0 自动抠图，去除背景。
• 使用 Qwen3-VL-8B-Instruct 判断图片类型、复杂度、推荐图纸尺寸和是否需要 Q 版化。
• 人像或复杂照片可使用 Qwen-Image-Edit 做轻 Q 版 / 像素友好化转换。
• 使用 MARD 221 色卡进行拼豆色号匹配，其中 H1 为透明色、H2 为白色、H7 为黑色。
• 支持 52、78、104 规格豆板；超过 104 时可按多板尺寸导出。
• 图纸主体按原图比例缩放，居中放入方形豆板画布，避免强行拉伸变形。
• 输出图纸带四边坐标、5/10 格参考线、格内色号、颜色图例和每色数量。
• 生成 pattern_grid.png、pattern_preview.png、pattern.pdf、beads.csv、pattern.json、moark_call_log.jsonl

Skill 功能流程

输入图片
  ↓
RMBG-2.0 抠图
  ↓
Qwen3-VL-8B-Instruct 图像规划
  - 判断 cartoon / portrait / object / logo / complex_photo
  - 推荐 52 / 78 / 104 / 多板规格
  - 判断是否需要 Qwen-Image-Edit
  ↓
可选：Qwen-Image-Edit 轻 Q 版 / 像素友好化
  ↓
Skill 内置确定性算法
  - Alpha 裁剪
  - 等比例缩放并居中留白
  - 场景化采样
  - MARD 字母大类预匹配
  - CIEDE2000 色差匹配
  - 孤岛清理与低用量颜色合并
  - 背景透明格处理
  ↓
导出图纸、预览图、用豆清单、JSON、调用日志和性能记录

使用模型与算力环境

本项目只调用 Moark / Gitee.AI 平台上的沐曦 GPU 算力模型，不调用其它大模型。

环节	模型	接口
背景抠除	RMBG-2.0	/images/mattings
图片规划	Qwen3-VL-8B-Instruct	/chat/completions
可选图片编辑	Qwen-Image-Edit	/images/edits

模型接口封装代码位于：

scripts/moark_client.py

配置模板位于：

.env.example

Codex Skill 接入与使用

本仓库本身就是一个 Codex Skill 文件夹，核心入口为 SKILL.md。Codex 读取该文件后，会按 Skill 工作流保存用户输入图片、调用 scripts/ 中的处理脚本，并产出图纸、预览图、用豆清单、JSON、真实调用日志和性能记录。

1. 接入 Skill

可将本仓库作为一个 Skill 目录提供给 Codex 使用。目录中至少保留以下文件和资源：

pixelbead-codex-skill/
  SKILL.md
  scripts/
  assets/
  mard_221_colors.csv
  requirements.txt
  .env.example

Codex 可通过 Skill 名称 pixelbead-pattern 显式调用，也可在用户需求匹配 SKILL.md 描述时自动选择该 Skill。

2. 配置模型调用

在 Skill 运行环境中根据 .env.example 配置 Moark / Gitee.AI Access Token。.env 只用于运行环境，不提交到仓库。

MOARK_BASE_URL=https://api.moark.com/v1
MOARK_API_KEY=your_access_token
MOARK_MODEL_RMBG=RMBG-2.0
MOARK_MODEL_IMAGE_EDIT=Qwen-Image-Edit
MOARK_MODEL_PLANNER=Qwen3-VL-8B-Instruct
MOARK_RMBG_PATH=/images/mattings
MOARK_IMAGE_EDIT_PATH=/images/edits
MOARK_CHAT_COMPLETIONS_PATH=/chat/completions

演示和真实验证均使用真实 Moark / 沐曦模型调用，并在输出目录中生成 moark_call_log.jsonl 作为调用凭证。

3. 在 Codex 中调用

在 Codex 中上传或指定图片后，可直接使用 Skill 名称发起任务：

Use $pixelbead-pattern to turn this image into a printable MARD bead chart.

Codex 会按照 SKILL.md 中的工作流执行：保存输入图片，调用 Moark / Gitee.AI 模型完成抠图与规划，必要时进行 Qwen-Image-Edit 图片优化，再由 Skill 内置算法生成最终拼豆图纸。

输出文件说明

文件	说明
pattern_grid.png	可打印图纸，包含四边坐标、格内色号、5/10 格参考线、颜色图例和每色数量。
pattern_preview.png	无坐标和色号的纯效果预览图。
pattern.pdf	可打印 PDF 图纸。
beads.csv	MARD 色号、RGB、Hex 和每色用豆数量。
pattern.json	图纸矩阵、元数据、颜色统计、模型规划结果。
moark_call_log.jsonl	模型真实调用日志，包含接口、模型、状态码、延迟和 token 用量。
performance.md	调用次数、总延迟、总豆数、按模型延迟估算的吞吐量。

示例输入输出

仓库内包含示例输入图片与真实调用生成的输出材料：

demo/cartoon/
demo/portrait/

卡通示例：

• 输入图片：demo/cartoon/5.png
• 输出图纸：demo/cartoon/pattern_grid.png
• 输出预览：demo/cartoon/pattern_preview.png
• 用豆清单：demo/cartoon/beads.csv
• 真实调用日志：demo/cartoon/moark_call_log.jsonl
• 性能记录：demo/cartoon/performance.md

人像示例：

• 输入图片：demo/portrait/1.jpg
• 输出图纸：demo/portrait/pattern_grid.png
• 输出预览：demo/portrait/pattern_preview.png
• 用豆清单：demo/portrait/beads.csv
• 真实调用日志：demo/portrait/moark_call_log.jsonl
• 性能记录：demo/portrait/performance.md

已记录的示例性能：

示例	模型调用次数	模型总延迟	输出豆数	吞吐量
卡通示例	2	3.592 s	1433	398.942 beads/s
人像示例	4	98.547 s	5071	51.458 beads/s

Skill 内置确定性算法

大模型只负责抠图、规划和可选图片编辑，最终拼豆图纸由 Skill 内置确定性算法生成：

• 卡通 / Logo 使用硬边主导色采样，照片 / 人像使用更平滑的采样配置。
• 模型推荐尺寸按“最长边档位”理解，主体按原始比例缩放并居中放入豆板画布。
• 对卡通 / Logo / 物体图，先根据原始采样色选择最接近的 MARD 字母大类，再在该大类内用 CIEDE2000 匹配具体色号。
• 色彩匹配使用色相、明度、彩度和中性白约束，避免浅色区域被错误匹配成过暗、过饱和或纯白。
• 对被深色轮廓包围的透明内部区域，可恢复为 H2 白豆。
• 对孤立小色块和极低用量颜色做合并，降低实际制作难度。

演示材料

• 示例输入图：demo/cartoon/5.png、demo/portrait/1.jpg
• 应用效果图：demo/cartoon/pattern_grid.png、demo/cartoon/pattern_preview.png、demo/portrait/pattern_grid.png、demo/portrait/pattern_preview.png
• 真实调用日志：demo/cartoon/moark_call_log.jsonl、demo/portrait/moark_call_log.jsonl
• 性能记录：demo/cartoon/performance.md、demo/portrait/performance.md
• Demo 演示视频链接：【demo】 https://www.bilibili.com/video/BV1vENJ68EDU/?share_source=copy_web&vd_source=0ced6568cf9111d4ebd4ecc72a33a4cb

开发记录

• Git 提交历史已保留在 GitLink 仓库。
• 主要功能开发记录已体现在 README、SKILL.md、scripts/ 和 demo 产物中。
• 当前核心提交：Initial PixelBead Codex skill。
• GitLink Issue 中的记录： Issue 1：项目初始化与 Moark API 接入。 Issue 2：RMBG 抠图、Qwen3-VL 规划、Qwen-Image-Edit 分支。 Issue 3：MARD 色卡整理与 H1/H2/H7 规则修正。

后续优化

当前skill主要处理 卡通图片–>拼豆图纸。由于大模型对人像的Q版/像素化处理结果不太贴合原图，最终拼豆图纸效果并不理想。后续会对人像图片–>拼豆图纸做进一步优化。