Community影像github.com

poster:宣傳圖 / 海報

在本地純 Python 繪製宣傳圖與海報:單頁海報、資訊長圖、封面、橫幅、知識卡、對比單頁、證書、易拉寶。聲明式「骨架 + 區塊 + 主題」三件套,或直接呼叫 Canvas 自由繪製;輸出 PNG / SVG / PDF,零第三方依賴(僅 fontTools)本地光柵化。

海報 是什麼?

這個 skill 提供一個純 Python 的向量圖形引擎,專為生成宣傳用視覺內容而設計,例如海報、橫幅、社交媒體貼文與長圖。它完全在本地運作,僅依賴 fontTools 處理字型,無需網路、GPU 或外部渲染服務。使用者可以透過三種模式操作:從預製模板進行替換、組合可宣告的區塊與骨架,或直接使用 Canvas API 進行程式化繪製。此引擎支援輸出 PNG、SVG 及向量 PDF,並包含內建的主題系統、排版引擎與檢查工具,以確保輸出品質。此 skill 特別適用於需要大量視覺內容生成且重視速度與本地隱私的團隊,但應避免用於照片級真實渲染或複雜的資料視覺化,這些情境應使用專用工具。

相容平台~Claude Code~Codex CLI~Cursor
npx skills add https://github.com/KongBai-lab/dsh-skill-poster/tree/main

Installed? Explore more 影像 skills: steipete/songsee, affaan-m/frontend-design, mattpocock/improve-codebase-architecture · View all 6 →

在你喜歡的 AI 中提問

開啟一個已預先載入此 Agent Skill 的新對話。

說明文件

海報 是做什麼的?

邊界(先看這一節)

需求用什麼
單張數據圖(柱線餅/流程/時間軸)diagram,不要用本 skill 畫
單幅視覺圖:海報/長圖/封面/橫幅/卡片/展板本 skill
多頁簡報make-ppt
帶公式的文件md2docx

本機能力邊界:沒有擴散模型權重、沒有本地推理算力,不能生成照片與寫實插畫。 本 skill 只能做幾何/向量風格(可做到精細,但不是工筆寫實)。

鐵律

  1. 不要手寫點列。形狀一律用 engine.geometry 的參數化圖元(circle/leaf/cloud/wave/heart…), 它們內部自適應細分;手寫座標是「一眼看出多邊形湊數」的根源。
  2. 文字也走 Path。不要另寫一套文字繪製;engine.typography 負責斷行/豎排/避首尾。
  3. 改完程式碼先清模組快取。python 工具的解譯器跨請求共享: for m in [k for k in sys.modules if k.startswith("engine")]: del sys.modules[m]
  4. 不要靠看圖驗收 1–2px 等級的缺陷。read_image 預覽會縮放,產生假缺口; 用 engine.check.check_canvas() 的斷言,或做像素級統計。
  5. 效能:大面積像素操作交給 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 實作。

快速開始

# 出圖(預設 preview 檔)
python -m engine.render templates/minimal-poster/layout.json -o out.png

# 印刷稿:A4 向量 PDF(文字不可選)
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")

對外只有四個旋鈕

旋鈕取值說明
presetxhs-3x4 / sq-1x1 / story-9x16 / wechat-cover / video-16x9 / info-long / a4-portrait / a3-portrait / rollup-85x200尺寸與安全區
--fordraft / preview / publish / print清晰度與輸出(見 refs/workflow.md)
--formatpng / pdf / svg預設:print→pdf,其餘 png
--deco0/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.mdCanvas / Path / geometry 速查,缺失能力的補法
refs/presets.md全部尺寸、安全區、印刷出血與 pt 換算
refs/packs.md素材包協議與「按需求打包」的收割流程
refs/styles.md風格參數、6 套內建風格指紋、theme_overrides、模仿一套風格的流程
refs/analyze.md參考圖分析:取色/明暗/版心/密度 → theme 草稿

相關技能