蓝图制图

蓝图生成器

从以下内容生成完整的蓝图风格图纸（PNG格式，默认1920x1080）：

• 3D模型 -> 真实的隐藏线正交投影视图：一个大的3/4视图加上侧视图、顶视图和前视图，带有测量的尺寸标注（3D流程），或
• 2D图像 -> 线条提取，包含轮廓线、边界框尺寸和标注（2D流程）。

两个流程共享一个布局引擎（框架、面板、标题栏、文本自适应），因此最终结果看起来风格一致。

能做什么和不能做什么（在相关时告知用户）

• 没有文件，就没有蓝图。 仅用文字描述的物体无法生成精确的图纸。请用户提供3D模型或图像。不要凭空捏造几何形状。
• 3D模型能生成真正的正交投影视图；2D图像则不能。 单张照片只有一个视角，因此2D流程只能生成单幅线稿图，而非前/侧/顶视图。
• 线条质量取决于网格/图像。 从游戏中提取的网格可能包含数十万个三角形，导致线条密集；这是一个良好的自动基础，但无法达到手工插画的质量。
• 除非用户提供了尺寸参照，否则比例是未知的。 除非提供了scale_ref（真实测量值），否则尺寸单位为模型单位（u）或像素（px）。切勿将猜测的真实世界尺寸作为事实呈现。
• 字体： 内置文本渲染使用DejaVu字体（支持拉丁语、希腊语、西里尔字母）。中日韩（CJK）/阿拉伯语/希伯来语文本将无法正确渲染。
• 布局专为16:9设计（经过1920x1080、2560x1440和1920x1200的测试）。其他宽高比会拉伸面板布局；请检查输出。
• 从游戏/电影中提取的资源是他人的知识产权。 适合用于个人壁纸；建议用户不要重新分发。

步骤0 - 收集输入（只询问一次缺失的信息）

1. 文件（模型或图像）。
2. 物体的名称和描述——或者主动提出草拟。描述必须与实际渲染中的内容一致（先检查渲染图）。描述一个轮式车辆但配上了四条腿的生物的描述会破坏图纸的可信度；如果用户的文本与几何形状不符，请指出并重写。
3. 输出分辨率和顶部安全区域（如果是壁纸，顶部可能被桌面任务栏遮挡）。默认top_safe = 76（框架从1080p分辨率下距顶部76像素处开始，为笔记本电脑上约1厘米的任务栏留出空间）。如果用户给定厘米，则进行转换：px_per_cm = screen_width_px / screen_width_cm（在24英寸1080p显示器上约为36像素/厘米，在15.6英寸笔记本电脑上约为56像素/厘米）。使用任务栏高度（像素）+ ~12。
4. 样式：blueprint（默认，蓝色）、graphite（石墨色，深色背景配橙色线条）、paper（纸质，浅色，可打印）。
5. 文本语言（默认英语；请用该语言编写规格文本）。

不要对用户进行盘问：如果他们已提供足够信息，则使用默认值继续，并说明您的假设。

步骤1 - 设置

pip install trimesh numpy scipy networkx pillow opencv-python-headless matplotlib --break-system-packages -q
# 可选，仅用于超过70万面的网格：pip install fast-simplification --break-system-packages

所有脚本都位于此文件旁边的scripts/目录中。将SKILL_DIR替换为技能文件夹的路径。

步骤2A - 3D模型

检查（始终先执行此操作 - 一张图片，一条命令）

python3 SKILL_DIR/scripts/blueprint3d.py inspect MODEL.glb --out /home/claude/insp

使用view打开inspect.png（它是一张接触印相照片）并阅读打印的文本：

• 顶部行 = 原始轴投影：找出哪个原始轴是向上以及物体面向哪个方向。
• 底部 = 3/4视图，带有编号的锚点候选（黄色）。控制台会列出每个候选cand N及其像素和规范坐标。淡色网格使用1500x860参考像素（可用作pick）。

方向标志（规范坐标系：y轴向上，物体正面朝向-x轴）： --up +Y（GLB/glTF格式默认；其他格式为+Z）和--front -X|+X|+Z|-Z|...。打印的提示会命名最长的水平轴；正面必须在侧视图的左侧，因此如果头部/正面在另一侧，则翻转符号。如果方向错误，使用其他值重新运行inspect一次。将最终值作为"up"和"front"放入spec中。

inspect还接受--az、--el（默认58 / 20）和--k（候选数量，默认16）。在spec中使用相同的view az/el，否则候选编号将不匹配。

编写spec

创建spec.json（架构如下，工作示例见assets/example_spec_3d.json）。为每个标注提供一个标题、一个简短描述和一个锚点：

• "cand": N - 来自inspect.png的编号候选（最经济：无需猜测像素）。候选点分布在可见表面上，因此请检查该点确实位于您所命名的部件上；如果没有足够接近的候选点，请使用pick。
• "pick": [px, py] - 在1500x860参考视图中的像素坐标（即inspect.png中的网格）
• "extreme": "+x" | "-x" | "+y" | "-y" | "+z" | "-z" - 规范坐标系中的极值点（正面是-x；可能被几何体遮挡）
• "point": [x, y, z] - 精确的规范坐标

除非必要，否则不要设置"label"：标签位置会自动选择（文字避开模型轮廓和其他标签，在面板侧边排列整齐的列，短引线不交叉）。"label": [x, y]（1920x1080参考坐标，主面板x范围为40-1290，y范围为96-826）会强制手动设置位置，并将在下面的审核中进行检查。

构建

python3 SKILL_DIR/scripts/blueprint3d.py build MODEL.glb spec.json --out /mnt/user-data/outputs/blueprint.png

绘制的视图会缓存在磁盘上（~/.cache/blueprint-maker或$BP_CACHE），以模型+视图+样式为键。更改文本、标签、标注或不依赖于调色板的内容时，重建大约需要2秒，而不是重新绘制；使用--no-cache或"cache": false禁用缓存。

布局："layout": "multi"（默认：大3/4视图 + 侧/顶/前视图 + 尺寸标注）或"single"（仅3/4视图，更宽）。

规格锁定（spec与模型之间的绑定）

使用cand、pick或extreme编写的锚点仅对它们所选择的模型、方向和视图有意义。首次构建会在spec旁边写入<spec>.lock.json：每个锚点解析到的3D点、模型的几何指纹以及影响锚点的设置（up、front、view的az/el、candidates、max_faces）。随后的每次构建都会重新解析锚点并进行比较：

• 锚点移动（不同的模型、方向或视图）-> 构建失败，并显示error: spec is not bound to this model ...，列出每个标注及其变化。使用spec的设置重新运行inspect，重新拾取锚点，然后使用--relock构建（或恢复原始模型/设置）；
• 模型不同但每个锚点仍落在相同位置（例如，无损重新导出）-> WARNING: binding: ...；检查，然后使用--relock；
• 您有意编辑了锚点（相同模型/设置）-> 锁定条目会静默更新。

--no-lock跳过检查（不推荐）。将锁定文件与spec一起保存（提交它）。切勿通过忽略绑定错误来“修复”它：标签会指向错误的部分。

步骤2B - 2D图像

python3 SKILL_DIR/scripts/blueprint2d.py inspect IMAGE.png --out /home/claude/insp

读取打印的遮罩覆盖率（背景移除适用于纯色背景或透明PNG；否则会报告“none”），然后使用view查看inspect.png：左侧是带有标签网格的源图像（使用源像素坐标的point_px），右侧是线条提取器看到的内容。这里也会自动放置标注标签（省略"label"）。

编写spec.json（参见assets/example_spec_2d.json）并进行构建：

python3 SKILL_DIR/scripts/blueprint2d.py build IMAGE.png spec.json --out /mnt/user-data/outputs/blueprint.png

调优参数："detail" 0.3（清晰、粗线条）到 0.8（密集）；"mode": "edges"（Canny边缘检测，适用于照片/渲染图）或 "sketch"（XDoG，适用于柔和/低对比度艺术图）；"bg": "none" 保留整个画布，或 "mask": "path.png" 用于手工制作的轮廓；"crop": [x0,y0,x1,y1] 用于隔离主体；"fill" 0-1 控制主体的半透明颜色填充。

步骤3 - 检查结果（不要跳过，但保持简洁）

构建器会打印WARNING:行。首先阅读它们——这是一个自动审核，因此您通常只需在最后view PNG一次：

• error: spec is not bound to this model - 请参见上面的“规格锁定”；这是一个硬性错误，而非警告。
• layout: ... - 标注文本与模型重叠、两个标签重叠、一条引线与另一个标签的文本/另一条引线/其自身文本交叉、文本超出面板、文本落在轴三角上。通过移除手动设置的"label"（让放置器决定）、更改锚点或缩短文本来解决。
• description / specs / notes: shrunk to Npx 或 does NOT fit - 缩短文本或删除行，而不是接受不可读的文本。

然后view最终的PNG一次，并验证审核无法知道的内容：

1. 模型在所有视图中都正确直立并面向预期方向；尺寸标注合理。
2. 每个标注点确实落在其文本命名的部件上。
3. 顶部安全区域为空（壁纸使用）。

如果出现问题，编辑spec（锚点、view.az/view.el、文本长度、feature_deg）并重建；由于缓存的存在，这只需几秒钟。典型操作流程：1次检查 + 1-2次构建，2-3次图片查看。

步骤4 - 交付

保存到/mnt/user-data/outputs/，调用present_files，然后简要回复。在回复中，始终说明：

• 哪些文本是您虚构的（描述、规格、备注、标注功能说明），哪些是从文件中测量得出的——用户应替换他们关心的虚构技术声明；
• 单位/比例假设；
• 任何WARNING或可见的限制（密集线条、隐藏锚点、宽高比）。

降低Token消耗

• 一次inspect图片，一次最终view；依赖打印的审核，而不是在每次调整后重新查看。
• 使用cand锚点并省略label；不要手动调整像素坐标。
• 一次性完整编写spec（锚点、文本），然后构建；仅编辑审核或最终视图标记的字段。

编写标注文本

• 仅描述渲染图中可见的内容；保持功能描述合理且通用。如果物体来自某个系列，不要陈述您不确定的背景细节。
• 标注标题：2-4个单词。标注文本：一个短句（约70个字符）。备注：3-5个简短条目。描述：约600-700个字符。规格行：值不超过45个字符。
• 保持措辞技术性和一致性：名称、规格编号、修订版本、单位。

Spec参考

通用键（两个流程通用）：

键	含义	默认值
title	标题栏中的大标题	"UNTITLED"
subtitle	标题下方的一行文字	""
designation	描述框顶部的粗体行	""
description	描述框的段落	（省略文本框）
specs	[["标签","值"], ...] 用于规格表	（省略）
notes	字符串列表，用于备注框（A, B, C...）	（省略）
notes_title	备注框的标题	"设计备注" / "备注"
callouts	标注对象列表	无
spec_no, class, rev, sheet, scale	标题栏字段（空白字段将被跳过）	sheet "01 / 01", scale "如所示"
fields	标题栏字段的完全覆盖：[["键","值"], ...]	自动
width, height	输出尺寸（像素）	1920, 1080
top_safe	框架开始的y坐标（在1080p分辨率下）；保持桌面任务栏清晰	76
palette	blueprint, graphite, paper	blueprint
scale_ref	`{"axis": "length	height

3D模型专用：up、front、layout（multi/single）、view {"az": 58, "el": 20, "margin": 0.045}、candidates（cand使用的k值，默认16；必须与inspect的--k相同）、feature_deg（边缘角度阈值，默认38；提高到50-60可减少线条）、feature_deg_small（默认44，用于侧/顶/前视图）、max_faces（默认700000）、cache（默认true）。

2D图像专用：mode、detail、bg、mask、crop、fill、fit_subject（裁剪到主体，默认true）、view_title、view_sub。

标注对象：{"title": "...", "desc": "..."} 加上锚点 - 3D：cand / pick / extreme / point；2D：point_px: [x, y] （以源图像像素为单位） - 以及可选的 "label": [x, y] 用于强制手动位置。

故障排除

• 模型侧翻 / 颠倒 / 背对视线： 使用--up / --front重新运行inspect；检查inspect.png的顶部行。
• 仅看到灰色模糊线条团： 提高feature_deg（50-65）；对于非常密集的网格，同时降低max_faces（需要fast-simplification）。
• 缺失部分或出现透视孔洞： 网格不防水或有反向面；画家算法渲染器可以容忍此问题，但游戏资产的内部部分可能会透过显示。降低view.margin，或尝试不同的az。
• 非常慢： 如果安装了fast-simplification，超过约70万面的网格会自动简化；否则，构建可能需要数分钟。
• 2D遮罩错误或破碎： 主体颜色与背景太接近。使用"bg": "none"、crop或提供mask PNG（白色 = 主体）。
• 文本警告： 缩短文本；不要手动降低字体大小。
• 候选编号与图片不匹配 / spec is not bound to this model： 模型文件、up/front、spec中的view az/el或candidates与编写spec时所用的值不同。使用spec的设置重新运行inspect，重新拾取锚点，使用--relock构建。
• 自动标签放置持续失败（“未找到无碰撞位置”）： 面板上的标注太多或太长；缩短描述、删除标注，或使用"layout": "single"获得更宽的面板。
• 编辑脚本后输出看起来陈旧： 缓存键包含渲染器代码，但如有疑问，可使用--no-cache运行一次。

文件

• scripts/binding.py - spec锁定文件