Community图像github.com

poster

在本地纯 Python 绘制宣传图与海报:单页海报、信息长图、封面、横幅、知识卡、对比单页、证书、易拉宝。声明式「骨架 + 区块 + 主题」三件套,或直接调用 Canvas 自由绘制;输出 PNG / SVG / PDF,零第三方依赖(仅 fontTools)本地光栅化。

poster 是什么?

poster is a Claude Code agent skill that 在本地纯 Python 绘制宣传图与海报:单页海报、信息长图、封面、横幅、知识卡、对比单页、证书、易拉宝。声明式「骨架 + 区块 + 主题」三件套,或直接调用 Canvas 自由绘制;输出 PNG / SVG / PDF,零第三方依赖(仅 fontTools)本地光栅化。.

兼容平台~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 的新对话。

文档

poster: Promotional Image / Poster

Boundaries (Read This First)

NeedUse
Single data charts (bar/line/pie, flowchart, timeline)diagram, do not use this skill
Single visual image: poster/long image/cover/banner/card/exhibition boardThis skill
Multi-page presentationmake-ppt
Document with formulasmd2docx

Local capability boundary: No diffusion model weights, no local inference compute, cannot generate photos or realistic illustrations. This skill can only produce geometric/vector styles (can be detailed, but not realistic).

Hard Rules

  1. Do not hand-write point lists. Shapes must use parameterized primitives from engine.geometry (circle/leaf/cloud/wave/heart…), they internally adapt subdivision; hand-written coordinates are the root cause of "obvious polygon approximations".
  2. Text also uses Path. Do not write a separate text drawing system; engine.typography handles line breaking, vertical writing, and line-start/end character avoidance.
  3. After modifying code, clear module cache first. The python tool's interpreter is shared across requests: for m in [k for k in sys.modules if k.startswith("engine")]: del sys.modules[m]
  4. Do not rely on visual inspection for 1–2px defects. read_image preview scales down, creating false gaps; use assertions from engine.check.check_canvas() or pixel-level statistics.
  5. Performance: large-area pixel operations go to C layer, profile before optimizing.
    • For translucent overlays of a single color (black/white/gray), three channels have the same mapping → 256-entry LUT + bytes.translate. Measured: per-pixel blending consumed 71% (6.6s), after optimization 0.05s, mathematically equivalent.
    • For uniform row fills, use slice assignment, not per-pixel 3-byte writes.
    • zlib uses level 6, not 9 (twice as fast, only 15% larger file).
    • Before starting, use cProfile: the biggest bottleneck in this project is alpha blending, not geometric algorithms.

Three Access Modes

ModeInputUse Case
A TemplatesCopy templates/*/, edit only content.jsonStandard promotional images (80% of scenarios)
B AssemblyWrite layout.json (skeleton + block list + parameters)Structure changes, standard elements
C Custom Drawingengine.canvas.Canvas directlyMimic a reference image, unique layout

Directory Structure

engine/
  canvas.py       Display list (Canvas.fill/stroke/clip, layers static/dynamic)
  path.py         Path (M/L/C/Q/Z) + adaptive subdivision
  geometry.py     23 parameterized primitives
  fonts.py        Font registry + glyph→Path + missing character detection
  typography.py   Line breaking, line-start/end avoidance, punctuation squeezing, vertical writing, kerning
  theme.py        Themes (6 skins + style parameters) + 9 canvas presets
  blocks.py       21 declarative blocks
  layouts.py      9 skeletons (including left-right split columns)
  render.py       Assembly + CLI
  check.py        Bounds, contrast, font size, color count, missing glyphs, slot assertions
  cache.py        Static layer bitmap cache (disabled by default, see refs/workflow.md for tests)
  backends/       raster.py (PNG), pdf.py (vector PDF), svg.py
packs/            Asset packs (guofeng Chinese style, tea teaware), loaded on demand
templates/        Finished recipes (content + layout)

Prerequisites

  • Install dependencies: pip install -r requirements.txt (only one dependency: fontTools).
  • Fonts: This repository does not bundle font files; the engine reads system-installed fonts — by default it scans /system/fonts, /usr/share/fonts, ~/.fonts and other common directories; if fonts are elsewhere, use the environment variable POSTER_FONT_DIR to point to the font directory.
  • No internet, no Office/GUI needed: rasterization, PDF, and SVG backends are all pure Python implementations.

Quick Start

# Generate image (default preview quality)
python -m engine.render templates/minimal-poster/layout.json -o out.png

# Print-ready: A4 vector PDF (text not selectable)
python -m engine.render templates/minimal-poster/layout.json -o out.pdf \
       --preset a4-portrait --for print

# Change theme / change size
python -m engine.render ... --theme guofeng --preset xhs-3x4

# List available presets / skeletons / blocks
python -m engine.render --list

Using in Python:

from engine.render import render, load_json
render(layout, content, theme="minimal", preset_name="xhs-3x4",
       out="out.png", for_="publish")

Only Four Knobs to Adjust

KnobValuesDescription
presetxhs-3x4 / sq-1x1 / story-9x16 / wechat-cover / video-16x9 / info-long / a4-portrait / a3-portrait / rollup-85x200Dimensions and safe zones
--fordraft / preview / publish / printResolution and output quality (see refs/workflow.md)
--formatpng / pdf / svgDefault: print→pdf, otherwise png
--deco0/1/2 (within theme)Decoration density; only affects appearance and file size, barely affects speed

There is no quality parameter: quality floor is guaranteed by adaptive subdivision of primitives + sub-pixel coverage + check.py.

Limitations (Honestly Admitted)

  • Does not do photos, realistic illustrations, or 3D; semi-realistic objects are possible (each about 100–200 lines, six layers of drawing), people are not recommended.
  • PDF first version text is path-based: visually correct but not selectable or searchable.
  • PDF is RGB only, does not support CMYK/spot colors; preprocessing is needed before printing.
  • Large titles / thin lines at ss=2 should use --for publish (ss=3) instead.
  • Rare characters may lack glyphs; check.py will report missing glyphs; fonts can be specified via POSTER_FONT_DIR.
  • First render adds about 6s (font file parsing), subsequent renders in the same process reuse; iterate with continuous calls, not frequent restarts.
  • Warm-state time estimates: preview ≈1.6s, publish ≈2.7s (for 1080×1440 output at 3240×4320).
  • Vertical punctuation only translates, does not rotate; numbers/English in vertical text do not rotate; multi-font adaptation is not implemented.

Notes (Common Pitfalls)

Performance

  • Translucent overlays: any color uses per-channel LUT (measured 13s→2.5s). Before adding new "large-area per-pixel" functions, think whether a table lookup works.
  • Large PNG decoding: full decode of 5760×3240 takes 10s+. Background assets should be ≤1500px, or use JPEG (only decode DC coefficients, an order of magnitude faster).
  • print mode forces ss=1: A4@ss3 measured 52s.
  • Static layer cache is not worth it (40MB bitmap IO ≈ render cost), --cache is disabled by default.

Fonts

  • All FZ fonts lack ∂ ħ ∇ and superscript numbers ⁻³⁵; missing glyphs are silently skipped, no error (formulas become ψ/ t = i Hψ).
  • Before writing formulas/units, check fonts.missing(text, family); verified available symbols: ψ ∫ ≈ ∝ λ ∞ → ·.

Layout

  • hero multi-line requires area height ≥ number of lines × line height, otherwise it overflows to the next block.
  • banner / card-grid / cover proportions are empirical; content changes may require fine-tuning.
  • CTA in wide layouts must set max_width, otherwise it fills the entire line like a progress bar.
  • Text inherent in background images will clash with foreground — choose text-free assets (photos/textures/illustrations).

Image Assets

  • JPEG output for PNG is DC version (8× thumbnail, pixelated); for sharp output, use PDF or switch to PNG assets.
  • PDF embeds JPEG directly with zero re-encoding, best quality.
  • Assets without extensions are recognized (by file signature).

Engineering Habits

  • The python tool's module cache is shared across requests; at the start of each test, clear sys.modules entries for engine* / packs*.
  • Keep development and installation directories separate; after changes, use copytree to sync (ignoring __pycache__).
  • If scene's objects_pack import fails, it silently falls back to a simplified version, no error.

Detailed Documentation (Read on Demand)

FileContent
refs/workflow.mdReference image dissection → gray model → coloring → text → validation; quality tiers and performance benchmarks
refs/canvas-api.mdCanvas / Path / geometry quick reference, workarounds for missing capabilities
refs/presets.mdAll dimensions, safe zones, print bleed, and pt conversions
refs/packs.mdAsset pack protocol and "pack on demand" workflow
refs/styles.mdStyle parameters, 6 built-in style fingerprints, theme_overrides, process to mimic a style
refs/analyze.mdReference image analysis: color extraction, light/dark, layout center, density → theme draft

相关技能