poster:宣伝画像 / ポスター
境界(最初に読むこと)
| 要件 | 使用するもの |
|---|
| 単一データ図(棒・折れ線・円グラフ/フローチャート/タイムライン) | 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 層に任せ、まずプロファイルしてから変更する
- 半透明オーバーレイが単色(黒/白/灰)の場合、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
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つのコントロールのみ
| コントロール | 値 | 説明 |
|---|
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(テーマ内) | 装飾密度。見た目とファイルサイズにのみ影響し、速度にはほとんど影響しません |
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.md | Canvas / Path / geometry クイックリファレンス、不足機能の補完方法 |
refs/presets.md | 全サイズ、セーフエリア、印刷塗り足しと pt 換算 |
refs/packs.md | 素材パックプロトコルと「要求に応じてパッケージング」する収穫フロー |
refs/styles.md | スタイルパラメータ、6つの組み込みスタイルフィンガープリント、theme_overrides、スタイルを模倣するフロー |
refs/analyze.md | 参照画像分析:色抽出/明暗/版面/密度 → theme ドラフト |