海報 是做什麼的?
邊界(先看這一節)
| 需求 | 用什麼 |
|---|
| 單張數據圖(柱線餅/流程/時間軸) | diagram,不要用本 skill 畫 |
| 單幅視覺圖:海報/長圖/封面/橫幅/卡片/展板 | 本 skill |
| 多頁簡報 | make-ppt |
| 帶公式的文件 | md2docx |
本機能力邊界:沒有擴散模型權重、沒有本地推理算力,不能生成照片與寫實插畫。
本 skill 只能做幾何/向量風格(可做到精細,但不是工筆寫實)。
鐵律
- 不要手寫點列。形狀一律用
engine.geometry 的參數化圖元(circle/leaf/cloud/wave/heart…),
它們內部自適應細分;手寫座標是「一眼看出多邊形湊數」的根源。
- 文字也走 Path。不要另寫一套文字繪製;
engine.typography 負責斷行/豎排/避首尾。
- 改完程式碼先清模組快取。
python 工具的解譯器跨請求共享:
for m in [k for k in sys.modules if k.startswith("engine")]: del sys.modules[m]
- 不要靠看圖驗收 1–2px 等級的缺陷。
read_image 預覽會縮放,產生假缺口;
用 engine.check.check_canvas() 的斷言,或做像素級統計。
- 效能:大面積像素操作交給 C 層,先剖析再改。
- 半透明疊加若是單色(黑/白/灰),三通道同映射 → 256 項 LUT +
bytes.translate。
實測暗角逐像素混合佔 71%(6.6s),改後 0.05s,且數學上完全等價。
- 整行平塗用切片賦值,不要逐像素寫 3 位元組。
- zlib 用 level 6,不是 9(快一倍,檔案只大 15%)。
- 動手前先
cProfile:本專案最大的坑是 alpha 混合,不是幾何演算法。
三種接入模式
| 模式 | 輸入 | 適用 |
|---|
| A 套模板 | 複製 templates/*/,只改 content.json | 常規宣傳圖(80% 場景) |
| B 組裝 | 寫 layout.json(骨架 + 區塊列表 + 參數) | 結構要變、元素標準 |
| C 自繪 | engine.canvas.Canvas 直接寫圖元 | 仿參考圖、版式獨一無二 |
目錄
engine/
canvas.py 顯示列表(Canvas.fill/stroke/clip,圖層 static/dynamic)
path.py Path(M/L/C/Q/Z)+ 自適應細分
geometry.py 23 個參數化圖元
fonts.py 字型註冊表 + 字形→Path + 缺字檢測
typography.py 斷行/避頭尾/標點擠壓/豎排/字距
theme.py 主題(6 套皮膚 + 風格參數)+ 9 個畫布預設
blocks.py 21 個宣告式區塊
layouts.py 9 個骨架(含左右分欄)
render.py 組裝 + CLI
check.py 越界/對比度/字型大小/色數/缺字/slot 斷言
cache.py 靜態層點陣圖快取(預設關閉,實測見 refs/workflow.md)
backends/ raster.py(PNG)、pdf.py(向量 PDF)、svg.py
packs/ 素材包(guofeng 國風、tea 茶器),按需載入
templates/ 成品配方(content + layout)
執行前提
- 裝依賴:
pip install -r requirements.txt(只有一個依賴:fontTools)。
- 字型:本倉庫不附帶字型檔案,引擎讀取系統已安裝字型——預設掃描
/system/fonts、/usr/share/fonts、~/.fonts 等常見目錄;字型裝在別處時用環境變數
POSTER_FONT_DIR 指到字型目錄。
- 無需聯網、無需 Office/GUI:光柵化、PDF、SVG 三個後端都是純 Python 實作。
快速開始
python -m engine.render templates/minimal-poster/layout.json -o out.png
python -m engine.render templates/minimal-poster/layout.json -o out.pdf \
--preset a4-portrait --for print
python -m engine.render ... --theme guofeng --preset xhs-3x4
python -m engine.render --list
Python 裡呼叫:
from engine.render import render, load_json
render(layout, content, theme="minimal", preset_name="xhs-3x4",
out="out.png", for_="publish")
對外只有四個旋鈕
| 旋鈕 | 取值 | 說明 |
|---|
preset | xhs-3x4 / sq-1x1 / story-9x16 / wechat-cover / video-16x9 / info-long / a4-portrait / a3-portrait / rollup-85x200 | 尺寸與安全區 |
--for | draft / preview / publish / print | 清晰度與輸出(見 refs/workflow.md) |
--format | png / pdf / svg | 預設:print→pdf,其餘 png |
--deco | 0/1/2(theme 內) | 裝飾密度;只影響觀感與檔案大小,幾乎不影響速度 |
沒有 quality 參數:品質下限由圖元自適應細分 + 亞像素覆蓋率 + check.py 保證。
限制(如實告知)
- 不做照片、寫實插畫、3D;半寫實器物可以(每件約 100–200 行六層繪製),人物不建議。
- PDF 首版文字路徑化:視覺正確但不可選、不可搜。
- PDF 僅 RGB,不支援 CMYK/專色;印前需自行轉換。
- 大字標題/細線在 ss=2 下建議改用
--for publish(ss=3)。
- 生僻字可能缺字形;
check.py 會報缺字,字型可用 POSTER_FONT_DIR 指定。
- 首次渲染另加約 6s(解析字型檔案),同程序後續渲染複用;迭代時應連續呼叫而不是頻繁重啟。
- 熱態耗時參考:preview ≈1.6s、publish ≈2.7s(1080×1440 的 3240×4320 輸出)。
- 豎排標點只平移不旋轉,數字/英文豎排不旋轉;多端字型適配未做。
注意事項(踩過的坑)
效能
- 半透明疊加:任意顏色都走逐通道 LUT(實測 13s→2.5s)。新增「大面積逐像素」功能前,先想能不能查表。
- 大 PNG 解碼:5760×3240 全解碼 10s+。背景素材建議 ≤1500px,或用 JPEG(只解 DC 係數,快一個數量級)。
- print 檔強制 ss=1:A4@ss3 實測 52s。
- 靜態層快取實測不划算(40MB 點陣圖 IO ≈ 渲染成本),
--cache 預設關閉。
字型
- 所有 FZ 字型都缺
∂ ħ ∇ 與上標數字 ⁻³⁵;缺字靜默跳過,不報錯(公式會變成 ψ/ t = i Hψ)。
- 寫公式/單位前先
fonts.missing(text, family);實測可用符號只有 ψ ∫ ≈ ∝ λ ∞ → ·。
版式
hero 多行需要區域高度 ≥ 行數 × 行高,否則壓到下一塊。
banner / card-grid / cover 的比例是經驗值,換內容可能要微調。
- 寬螢幕裡的 CTA 必須設
max_width,否則佔滿整行像進度條。
- 背景圖自帶的文字會和前景打架——選無文字素材(照片/紋理/插畫)。
圖片素材
- JPEG 的 PNG 輸出是 DC 版(8× 縮略、像素化);要清晰請出 PDF 或換 PNG 素材。
- PDF 直嵌 JPEG 零重編碼,品質最好。
- 素材沒有副檔名也能辨識(按檔案簽名判斷)。
工程習慣
python 工具的模組快取跨請求共享,每次測試開頭清 sys.modules 裡的 engine* / packs*。
- 開發目錄與安裝目錄分離,改完要
copytree 同步(忽略 __pycache__)。
scene 的 objects_pack 匯入失敗會靜默回退到簡筆版,不報錯。
細節文件(按需讀)
| 檔案 | 內容 |
|---|
refs/workflow.md | 參考圖解剖 → 灰模 → 上色 → 上字 → 驗收;清晰度檔位與效能實測 |
refs/canvas-api.md | Canvas / Path / geometry 速查,缺失能力的補法 |
refs/presets.md | 全部尺寸、安全區、印刷出血與 pt 換算 |
refs/packs.md | 素材包協議與「按需求打包」的收割流程 |
refs/styles.md | 風格參數、6 套內建風格指紋、theme_overrides、模仿一套風格的流程 |
refs/analyze.md | 參考圖分析:取色/明暗/版心/密度 → theme 草稿 |