Community画像github.com

poster

ローカル環境の純Pythonで宣伝画像やポスターを描画します。単一ページのポスター、情報長尺画像、カバー、バナー、知識カード、比較ページ、証明書、展示用バナーなどに対応。宣言的な「スケルトン+ブロック+テーマ」の3点セット、またはCanvasを直接呼び出して自由描画。出力はPNG/SVG/PDF、サードパーティ依存はfontToolsのみでローカルラスタライズを実現。

poster とは?

posterは、AIエージェント(Claude Code, Cursor, Codexなど)がローカル環境で純Pythonを使用して宣伝画像やポスターを生成するためのスキルです。このスキルは、単一ページのポスター、情報長尺画像、カバー、バナー、知識カード、比較用単一ページ、証明書、展示用バナー(易拉宝)など、多様な形式のビジュアルコンテンツを作成するために設計されています。主な特徴は、宣言的な「スケルトン(レイアウト構造)+ブロック(要素)+テーマ(スタイル)」の3点セットによるテンプレートベースの高速生成(A・Bモード)と、Canvasオブジェクトを直接操作してゼロから自由に描画するカスタムモード(Cモード)の2つのアプローチを提供することです。出力形式はPNG、SVG、PDFをサポートし、すべてのラスタライズ処理はPythonとfontToolsのみで行われ、外部のGUIやOfficeは不要です。AIエージェントは、このスキルを使用する際、幾何・ベクタースタイルの画像生成に最適化されている点に注意する必要があります。写真や写実的なイラスト、3Dレンダリングはサポートしていません。パフォーマンス面では、半透明合成にLUT(ルックアップテーブル)を活用するなど、効率的な実装が施されており、プレビュー品質で約1.6秒、公開品質で約2.7秒(1080×1440ベース)でレンダリングが完了します。また、高度な機能として、23種類のパラメトリックな幾何図形、21種類の宣言的ブロック、9種類のスケルトン、6種類の組み込みテーマを備え、文字の自動改行、縦書き、約物のぶら下げなど、タイポグラフィ機能も充実しています。開発者は、コード変更後のモジュールキャッシュクリアや、Checkモジュールによる自動検証など、堅牢なワークフローをサポートするツールも利用できます。

対応~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に質問する

このエージェントスキルを事前に読み込んだ状態で新しいチャットを開きます。

ドキュメント

poster:宣伝画像 / ポスター

境界(最初に読むこと)

要件使用するもの
単一データ図(棒・折れ線・円グラフ/フローチャート/タイムライン)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 層に任せ、まずプロファイルしてから変更する
    • 半透明オーバーレイが単色(黒/白/灰)の場合、3チャンネルは同じマッピング → 256エントリのLUT + bytes.translate。 実測では、画素ごとのピクセル混合が 71%(6.6秒)を占めていましたが、変更後は 0.05秒で、数学的に完全に同等です。
    • 行全体の塗りつぶしはスライス代入を使用し、1バイトずつ書き込まないでください。
    • zlib はレベル 6 を使用し、レベル 9 は避けてください(2倍速く、ファイルサイズはわずか 15%増加)。
    • 実装前には必ず cProfile を使用してください:このプロジェクトの最大のボトルネックは alpha 混合であり、幾何アルゴリズムではありません。

3つのアクセスモード

モード入力適用
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 のスケルトン(左右2段組み含む)
  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 の3つのバックエンドはすべて純Python実装です。

クイックスタート

# 画像出力(デフォルトプレビュー品質)
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")

外部向けは4つのコントロールのみ

コントロール値説明
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(テーマ内)装飾密度。見た目とファイルサイズにのみ影響し、速度にはほとんど影響しません

quality パラメータはありません:品質の下限は図形の適応的細分化 + サブピクセルカバレッジ + check.py で保証されます。

制限(正直にお伝えします)

  • 写真、写実イラスト、3D は作成しません。半写実的な器物は可能(1点あたり約100–200行、6層描画)、人物は推奨しません。
  • PDF 初版は文字がパス化されます:見た目は正しいですが、選択不可、検索不可です。
  • PDF は RGB のみ、CMYK/スポットカラー非対応。印刷前には別途変換が必要です。
  • 大きな見出し/細い線は ss=2 の場合、--for publish(ss=3)の使用を推奨します。
  • 稀な文字は字形が欠落する可能性があります。check.py が欠字を報告します。フォントは POSTER_FONT_DIR で指定できます。
  • 初回レンダリングには約 6 秒追加(フォントファイルの解析)、同じプロセス内の後続レンダリングでは再利用されます。繰り返し処理の場合は連続して呼び出し、頻繁に再起動しないでください。
  • ウォーム状態の所要時間目安:preview ≒1.6秒、publish ≒2.7秒(1080×1440 ベースの 3240×4320 出力)。
  • 縦書き約物は平行移動のみで回転しません。数字/英字の縦書きは回転しません。マルチエンドフォントの適合は未対応です。

注意事項(踏んだ罠)

パフォーマンス

  • 半透明オーバーレイ:任意の色でもチャンネルごとのLUTを使用(実測 13秒→2.5秒)。新たに「広範囲ピクセル単位」機能を追加する前に、まずテーブル参照が可能か検討してください。
  • 大きなPNGデコード:5760×3240 のフルデコードに 10秒以上。背景素材は 1500px 以下にするか、JPEG(DC成分のみデコード、一桁高速)を使用してください。
  • print 品質は強制 ss=1:A4@ss3 で実測 52秒。
  • 静的レイヤーキャッシュは実測で割に合わない(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 ドラフト

関連スキル