ML Paper Figure 1
以手寫 SVG 在四個關卡階段中建構圖表:計劃 → 草稿 → 渲染與評論(最多 3 輪)→ 匯出。 在藍圖存在之前,請勿開始撰寫 SVG。隨意選擇的座標是導致標籤溢出和箭頭穿過方塊的主要原因,而且 lint 和視覺審查只有在有計劃的情況下才能良好運作。
下方的 SKILL_DIR 代表此技能的基本目錄。腳本是離線執行的;每個階段檢查一次渲染器:
python3 "$SKILL_DIR/scripts/render_svg.py" --list-backends
腳本會依序嘗試使用 Chromium (Playwright)、rsvg-convert、inkscape、cairosvg 或 resvg 中已安裝的任一項。精確的幾何 lint 需要 Chromium。沒有它的情況下檢查會是近似值,因此需要更加依賴視覺審查。
參考檔案(在指定階段讀取)
| 檔案 | 何時讀取 |
|---|---|
references/design-system.md | 階段 1。內容涵蓋每個會議的畫布大小、佈局間距、色板角色、字型層級、形狀隱喻、連接器樣式。這些是預設值;當內容需要時可以調整它們。 |
references/svg-primitives.md | 階段 2。包含可複製貼上的 <defs>(標記、徽章、縮圖)、文字置中和連接器公式,以及 ML 形狀模板。 |
assets/primitives-gallery.png | 可選。每個基本元素的渲染視圖,對於選擇隱喻很有用。 |
assets/example-figure1.svg (+ .png) | 可選。一個完整、無 lint 錯誤的 Figure 1(凍結編碼器 → 提出的模組 → 解碼器 + 虛線損失)作為結構參考。 |
scripts/svg_geom.py | 任何需要確切座標時使用。它會輸出連接器路徑、梯形、堆疊、網格和置中標籤,並附帶適應性檢查。 |
scripts/tex_math.py | 由 render_svg.py 用於處理 $…$ 數學公式。執行 --paper main.tex --show 查看數學設定和從論文提取的巨集,--test 'c_{FA}' --pt 6 用於排版一個片段。 |
階段 1:計劃(任何 SVG 之前的藍圖)
- 提取結構,根據使用者提供的任何內容(散文、方法 LaTeX/Markdown、PyTorch
nn.Module程式碼):- 階段(2-4 個群組,變成卡片 (a)、(b)、(c)),以及每個階段內部的模組;
- 哪些模組是論文的貢獻(使用強調色),哪些是凍結/預訓練的,哪些是可訓練的;
- 主路徑上的張量及其形狀,例如
(B, 3, H, W) → (B, N, D),使用論文自己的符號; - 流程:前向資料(實線)、損失/監督(虛線)、梯度/反饋、跳躍連接、僅推理 vs. 僅訓練路徑。
從程式碼:
__init__列出模組,forward()給出順序和形狀,requires_grad_(False)/.eval()/torch.no_grad()標記凍結部分,損失項來自訓練步驟。 如果來源沒有說明什麼是新的或什麼是凍結的,請提出一個簡短的問題。否則,做出合理的假設並說明它們。
- 固定畫布:目標會議和寬度,以及來自
design-system.md§2 表格的viewBox。預設為每個印刷 pt 2 個單位,例如 NeurIPS800 × ~300。 - 撰寫藍圖到圖表旁邊的
<name>.blueprint.md,並用幾行文字向使用者總結。檔案放置在使用者存放論文圖表的地方(預設:他們專案中的figures/):
figure: figure1_overview # 檔案主體名稱
target: neurips # render_svg.py --target 值;viewBox 800 x 300 (2u = 1pt)
flow: left-to-right # 或 top-to-bottom / two-row snake
stages: # 卡片 x 範圍平鋪寬度並留有間隙;卡片共享一個 y 範圍
- id: a
title: "(a) Frozen Encoder"
box: [12, 12, 186, 240] # x, y, w, h
modules:
- {id: img, kind: thumb-patches, box: [28, 120, 40, 40], label: "x", dims: "3×H×W"}
- {id: enc, kind: trapezoid-encoder, role: frozen, badge: frozen, box: [96, 90, 88, 100], inset: 18, label: "Vision|Encoder"}
- id: b
# ...
edges:
- {from: img.right, to: enc.left, style: forward, role: data}
- {from: dec.bottom, to: loss.top, style: loss, label: "ŷ"}
colors: {enc: frozen, uam: proposed, dec: train, loss: loss} # 來自 design-system.md §4 的色板角色
legend: [forward, loss, frozen, trainable] # 僅需解釋的編碼
notes: "proposed card ~45% of width; spine at y = 140"
在繼續之前檢查藍圖:每個模組都有一個 box;卡片內部的 box 至少保留 14u 的卡片內邊距;有箭頭連接的相鄰元素至少相距 28u(如果箭頭帶有標籤則為 40u);標籤寬度適合其 box(svg_geom.py label … 會報告內邊距);且主軸(主要路徑)應盡可能為一條直線。
階段 2:草稿(一個獨立的 SVG)
閱讀 references/svg-primitives.md,然後撰寫 <name>.svg:
- 從那裡的骨架和核心
<defs>開始(字型堆疊、排版類別、每個色板角色一個箭頭、向量徽章)。僅在使用時才加入可選的縮圖 def。 - 自包含:無外部圖片、無網路字型或
@import、無<foreignObject>、無腳本、無表情符號。使用向量徽章代替 ❄️/🔥,因為表情符號在 PDF 中會變成點陣圖或 tofu。 - 繪製順序:背景 → 卡片 → 邊緣 → 模組 → 標籤 → 徽章 → 圖例。邊緣位於模組下方,這樣它們的末端會藏在邊框下方。
- 為模組加上 id(
id="enc"),連接器加上class="edge"和fill="none",迷你視覺元素加上data-lint="ignore"。這樣 lint 訊息就可以指名道姓地指出元素。 - 使用公式或
svg_geom.py計算座標,不要用目測。文字置中的基準線是cy + 0.35 × font-size。路徑在到達目標邊框前 2u 處結束,因為標準箭頭尖端會超出 2u。 - 數學公式使用 LaTeX:在
<text>標籤內將符號寫在$…$之間(scores $S[i,v,p]$,$\mathcal{L}_{\text{KL}}$),使用論文中的符號。渲染腳本會使用論文的數學字型和巨集(--paper main.tex)來排版這些公式,並將結果寫入 SVG。僅編輯原始<text>;絕不要使用斜體襯線字型或<tspan dy>下標來偽造數學公式(參閱 svg-primitives.md §2)。
階段 3:渲染與評論(循環,最多 3 輪)
每輪:
- 渲染與 lint:
加上python3 "$SKILL_DIR/scripts/render_svg.py" <name>.svg --target <venue> [--paper main.tex] # venue: neurips (default), icml, cvpr, …-col, or 5.5in--paper(只需一次;設定會儲存在 SVG 中)後,$…$數學公式會使用論文的數學字型和巨集。 這會產生<name>.png、<name>.debug.png(座標網格,並在每個問題E#/W#周圍加上編號方框)和<name>.preview.png(印刷尺寸的圖表),並印出錯誤和警告及其座標。 - 自己查看圖片。 先讀取
<name>.debug.png,然後是<name>.preview.png。Lint 無法判斷構圖,因此視覺檢查是必須的。 - 瀏覽檢查清單並撰寫簡短的評論:每個缺陷一行,附帶座標修正。
- 文字適應:沒有標籤觸碰或跨越其 box 邊界;模組標籤至少保留 8u 的側邊內邊距。
- 箭頭:沒有箭頭穿過模組或標籤;箭頭尖端接觸目標邊框(無間隙,無刺穿);沒有可避免的交叉;流向很明確。
- 間距與對齊:同級元素之間等距,行共享中心線,相同類型的 box 共享大小,卡片內邊距均勻,沒有角落擁擠而另一個角落空置的情況。
- 印刷可讀性(
preview.png):最小的文字仍然可讀;腳本報告目標寬度下最小 ≥ 6pt;筆畫可見;角色可區分。 - 層次結構:提出的模組是視線首先停留的地方;階段標題 (a)/(b)/(c) 易於掃視;使用一個強調色。
- 語義:所有藍圖中的模組和邊緣都存在且正確;實線 = 前向,虛線 = 損失;徽章和圖例與繪製的內容匹配;標記法與論文匹配。
- 修正,然後重新渲染。當有 0 個錯誤 且檢查清單每個項目都通過時停止,或者當剩餘的警告是一個你可以證明的刻意選擇時(說明是哪個以及為什麼)。Lint 警告是指標,不是最終判決:一個你已經檢查過並判斷無誤的警告不需要修改。
在第 3 輪之後,即使有輕微問題也停止迭代,並在報告中列出它們。
階段 4:匯出
python3 "$SKILL_DIR/scripts/render_svg.py" <name>.svg --target <venue> --export
這會產生 <name>.pdf(向量格式,頁面大小等於印刷寬度,因此其文字大小是真實的印刷大小)、高解析度 <name>.png(3 px/u,或 --dpi 300),以及 PDF 檢查:單頁、字型已嵌入、僅包含 Type 1 / TrueType 字型(Type 3 為錯誤)、無點陣化內容,以及 PDF 與 PNG 匹配。如果渲染器會為無襯線文字嵌入 Type 3 字型(Chromium 會為 CFF 字型,例如 Inter .otf 或 TeX Gyre .otf 這樣做,而 NeurIPS/ICML 風格的檢查器會拒絕它們),則該文字會自動轉換為向量輪廓(--pdf-text auto|fonts|outline)。$…$ 數學公式隨後會從 pdflatex 的輸出中蓋印上去,因此 PDF 會攜帶真實的 Type 1 數學字型(例如帶有 CMMI5 上下標的 CMMI6);報告會列出這些字型及其印刷大小。它也會移除審查圖片。然後提供給使用者:
- 檔案(
.svg原始檔、適用於 LaTeX 的.pdf、適用於簡報/預覽的.png); - 一個符合目標寬度的 LaTeX 片段:
\begin{figure*}[t] % 對於單欄會議(NeurIPS/ICLR)或欄寬圖表,使用 figure + \linewidth \centering \includegraphics[width=\textwidth]{figures/<name>.pdf} \caption{...}\label{fig:overview} \end{figure*} - 一份簡短報告:目標和最小的印刷字體大小(以及數學基礎/腳本大小,如果有)、執行的評論輪次以及變更的內容,以及任何被接受的警告。
品質標準(何謂「完成」)
- 在印刷寬度下可讀:文字 ≥ 6pt,最多 4 種字體大小,線條粗細 ≥ 0.5pt。
- 零 lint 錯誤。無文字溢出、重疊、畫布外元素、損壞的引用或表情符號。
- 每個箭頭都在邊框上開始和結束,從不穿過模組或標籤,並遵循圓角正交路徑。
- 一個清晰的焦點(貢獻)、一致的顏色角色,以及僅用於非顯而易見編碼的圖例。
- 忠於論文:模組名稱、符號和張量形狀與文字或程式碼匹配。不發明任何東西。標記所有假設。
- 數學公式由 LaTeX 使用論文的數學字型和符號排版,使用 LaTeX 腳本大小(印刷 ≥ 5pt)。
- 交付物是一個獨立的 SVG、一個向量 PDF(Type 1/TrueType 或輪廓字型,絕非 Type 3)和一個 PNG,全部在本地渲染,無需雲端 API。