文／NODE｜JAN1 LAB 工作室工具筆記
「畫面想要六公尺寬，投影機放這裡可以嗎？」
規劃投影時，先確認畫面尺寸、可用距離與鏡頭投射比，才能判斷機器適合放在哪裡。
從展演空間到活動現場，這些條件往往會反覆調整。比起每次重新算公式、重畫配置圖，我們希望把需求整理成能直接比較的方案。
投影配置助手（projection-planner） 是 JAN1 LAB 整理的 Codex Skill。用日常語言描述條件，就能計算畫面尺寸與投射距離，並產生 SVG 配置圖、文字摘要與計算結果。
它適合單台投影機正對平面幕面的初步規劃，讓你在搬動設備前，先把尺寸與位置的關係看清楚。
它會幫我算什麼？
你可以從畫面寬度、投射距離、投射比這三個條件中，提供足夠的已知數值，求出缺少的那一個。
例如，知道寬度與投射比，就能求距離；知道距離與投射比，就能求畫面寬度。若有鏡頭投射比上下限，也能列出可用的幾何距離區間，檢查預定位置是否落在範圍內。
除了寬度與距離，它也會計算畫面高度、對角線尺寸及原生全幅像素間距。影片與原生畫面比例不同時，會列出有效影片尺寸和黑邊。
長度可用公尺、公分或毫米。原生比例支援 16:9、16:10、4:3 及自訂比例；原生解析度支援 Full HD、WUXGA、4K UHD 及自訂尺寸。輸入的原生比例需與解析度相符，影片比例則另外設定。
投射比，先看懂這個關係
核心關係只有幾行：
投射比 = 投射距離 ÷ 畫面寬度
投射距離 = 投射比 × 畫面寬度
畫面寬度 = 投射距離 ÷ 投射比這裡的寬度指原生全幅投影畫面的水平寬度。距離則要依原廠定義，從指定的鏡頭參考點量到幕面。
把「機器離牆大概七公尺」換成明確的鏡頭參考距離，計算才有共同基準。
大概可以拿來聊天。進到配置圖裡，還是要有單位。
安裝後，直接這樣問
範例一：畫面六公尺寬，需要退多遠？
使用 $projection-planner：我的畫面寬六公尺，比例16:9， 投影機原生解析度是Full HD，投射比1.2。
專案名稱是「展演A」，版本v1。 請計算需要的投射距離，並提供配置圖和結果摘要。
依這組條件，結果是：
| 項目 | 結果 |
|---|---|
| 投射距離 | 7.2 公尺 |
| 原生畫面尺寸 | 6 × 3.375 公尺 |
| 原生全幅像素間距 | 3.125 毫米 |
這個數值提供概念規劃依據。實際選位，仍需核對使用鏡頭的投射、對焦及安裝條件。
範例二：現場只有五公尺，能投多大？
用投影配置助手幫我計算：現場投射距離五公尺，投射比1.25， 原生解析度是WUXGA 1920×1200。
影片是16:9，請使用等比適配， 列出畫面尺寸、有效影片尺寸和黑邊，並附配置圖。
原生畫面寬度為 4 公尺，高度為 2.5 公尺。16:9 影片等比放入後，有效尺寸為 4 × 2.25 公尺，上下黑邊各 0.125 公尺。
影片維持原本比例。若要裁切填滿或拉伸，需要明確提出，結果也會說明裁切量或變形。
黑邊有尺寸。不能靠播放時假裝沒看到。
範例三：我想放的位置，在鏡頭範圍內嗎？
使用 $projection-planner：畫面要六公尺寬，原生解析度是4K UHD， 鏡頭投射比範圍是1.2到1.8。
我想把投影機放在六公尺遠的位置， 請檢查是否可行，列出允許的距離區間並附配置圖。
這組鏡頭的幾何允許距離為 7.2～10.8 公尺。指定的 6 公尺位置不在範圍內，結果會列出警告與不通過狀態。
投射比區間不是看起來差不多就能通融。畫面要六公尺寬，機器就得去合適的位置。
固定版型，讓不同方案放在一起比較
配置圖把數字整理成固定版型，讓不同方案能放在一起比較：
- 頂部放專案名稱、版本、日期與單位。
- 左側是俯視配置、投影機符號、幕面與距離標註。
- 右上是幕面正視圖，查看寬高與比例。
- 右下整理解析度、投射比、距離、尺寸與鏡頭區間。
俯視圖用來看投影機與幕面的位置關係，正視圖則呈現畫面寬高。調整距離或鏡頭條件後，仍能用相同版型比較差異。
想看完整配置圖，可以打開這三份範例：案例A配置圖、案例B配置圖、案例C配置圖。
每個方案都會輸出 SVG 配置圖、Markdown 摘要與 JSON 計算結果。 配置圖可放大查看或用於提案，文字摘要方便溝通，JSON 則保留完整數值。
不用讓每一次改版，都順便換一套排版。
從需求描述到配置圖
像上面的範例一樣，告訴 Codex 你已知的尺寸、距離與鏡頭條件，再提出想解決的問題。它會統一單位、計算數值，並整理成同一套配置圖與摘要。
如果缺少必要條件，或提供的數值彼此矛盾，它會先請你補充或修正，讓下一步的討論有清楚的依據。
下載與安裝
下載 ZIP 並解壓，保留完整的 projection-planner 資料夾。使用環境需有 Python 3.10 以上；也可請 Codex 使用 $skill-installer，從 GitHub 專案安裝。
手動安裝時，將完整的 projection-planner 資料夾放到個人技能目錄：
~/.agents/skills/projection-planner/只想在某個專案使用，也可放到該專案的 .agents/skills/projection-planner/。計算腳本、參考文件及模板都有相對路徑關係，請保留整套資料夾。
安裝後，在技能選單確認是否出現「投影配置助手」，再以 $projection-planner 明確呼叫。若未出現，可重新啟動 Codex。技能位置與安裝方式可參考 OpenAI 官方 Build skills 文件。
