藍圖製圖

Blueprint Maker

從以下來源生成最終的藍圖風格圖表（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 px/cm，在 15.6 吋筆記型電腦上約為 56 px/cm）。使用列高度（像素）+ ~12。
4. 樣式：blueprint（預設，藍色）、graphite（深色配橘色線條）、paper（淺色，可列印）。
5. 文字的語言（預設英文；請以該語言撰寫規格文字）。

不要盤問使用者：如果他們已經提供足夠資訊，請使用預設值並說明你的假設。

步驟 1 - 設定

pip install trimesh numpy scipy networkx pillow opencv-python-headless matplotlib --break-system-packages -q
# 可選，僅用於超過 700k 面的網格：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" 放入規格中。

inspect 也接受 --az、--el（預設 58 / 20）和 --k（候選數量，預設 16）。在規格中使用相同的 view az/el，否則候選編號將不匹配。

撰寫規格

建立 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 視圖，更寬）。

規格鎖定（規格和模型之間的綁定）

寫為 cand、pick 或 extreme 的錨點僅對其選定的模型、方向和視圖有意義。第一次構建會在規格旁邊寫入 <spec>.lock.json：每個錨點解析到的 3D 點、模型的幾何指紋，以及影響錨點的設定（up、front、視圖 az/el、candidates、max_faces）。每次後續構建都會重新解析錨點並進行比較：

• 錨點移動（不同的模型、方向或視圖）-> 構建失敗，顯示 error: spec is not bound to this model ...，列出每個標註及其變化。使用規格的設定重新執行 inspect，重新選擇錨點，然後使用 --relock 構建（或恢復原始模型/設定）；
• 模型不同但每個錨點仍然落在相同位置（例如無損重新導出）-> WARNING: binding: ...；檢查，然後 --relock；
• 你故意編輯了一個錨點（相同的模型/設定）-> 鎖定記錄會靜默更新。

--no-lock 跳過檢查（不建議）。將鎖定檔案與規格一起保存（提交它）。切勿透過忽略綁定錯誤來「修復」它：標籤會指向錯誤的部分。

步驟 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. 頂部安全區域是空的（桌布用途）。

如果有問題，請編輯規格（錨點、view.az/view.el、文字長度、feature_deg）並重新構建；使用快取只需幾秒鐘。典型總計：1 次檢查 + 1-2 次構建，2-3 次影像檢視。

步驟 4 - 交付

保存在 /mnt/user-data/outputs/ 下，呼叫 present_files，然後簡短回覆。在回覆中，務必說明：

• 你發明了哪些文字（描述、規格、備註、標註功能）與哪些是從檔案中測量出來的 - 使用者應替換他們關心的發明技術聲明；
• 單位/比例假設；
• 任何 WARNING 或可見的限制（密集線條、隱藏錨點、長寬比）。

保持低 Token 使用量

• 一張 inspect 影像，一次最終 view；依賴列印的審核，而不是在每次調整後重新檢視。
• 使用 cand 錨點並省略 label；不要手動調整像素座標。
• 一次性完整撰寫規格（錨點、文字），然後構建；只編輯審核或最終檢視標記的欄位。

撰寫註釋文字

• 只描述渲染結果中可見的內容；保持功能聲明合理且通用。如果物件來自特許經營權，不要陳述你不確定的背景故事細節。
• 標註標題：2-4 個字。標註文字：一個簡短句子（約 70 個字元）。備註：3-5 個簡短項目。描述：約 600-700 個字元。規格行：值約 45 個字元以內。
• 保持措辭技術性和一致性：名稱、規格編號、修訂版、單位。

規格參考

常見鍵（兩個管線皆適用）：

鍵	意義	預設值
title	標題欄中的大字標題	"UNTITLED"
subtitle	標題下方的行	""
designation	描述框頂部的粗體行	""
description	描述框的段落	（省略框）
specs	[["Label","Value"], ...] 作為規格表	（省略）
notes	字串列表作為備註框（A, B, C...）	（省略）
notes_title	該框的標題	"DESIGN REMARKS" / "NOTES"
callouts	標註物件列表（如下）	無
spec_no, class, rev, sheet, scale	標題欄欄位（空白的會被跳過）	sheet "01 / 01", scale "AS SHOWN"
fields	標題欄欄位的完整覆蓋：[["KEY","value"], ...]	自動
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。
• 非常慢： 超過約 700k 面的網格如果安裝了 fast-simplification 會自動降低解析度；否則構建可能需要幾分鐘。
• 2D 遮罩錯誤或破碎： 主體顏色太接近背景。使用 "bg": "none"、crop，或提供一個 mask PNG（白色 = 主體）。
• 文字警告： 縮短文字；不要手動降低字型大小。
• 候選編號與圖片不匹配 / spec is not bound to this model： 模型檔案、up/front、規格 view az/el 或 candidates 與撰寫規格時的不同。使用規格的設定重新執行 inspect，重新選擇錨點，使用 --relock 構建。
• 自動標籤放置持續失敗（"no collision-free position"）： 面板的標註太多或太長；縮短描述、刪除標註，或使用 "layout": "single" 以獲得更大的面板。
• 編輯腳本後輸出看起來過時： 快取金鑰包含渲染器程式碼，但如果懷疑，請使用 --no-cache 執行一次。

檔案

• scripts/binding.py - 規格鎖定檔案（處理與驗證）

…（已為翻譯截斷）