CommunityImagegithub.com

poster

A pure Python library for creating promotional images and posters locally: single-page posters, infographics, covers, banners, knowledge cards, comparison sheets, certificates, and roll-up banners. Declarative 'skeleton + block + theme' or direct Canvas drawing; outputs PNG/SVG/PDF with zero third-party dependencies (only fontTools) for local rasterization.

What is poster?

This skill, named 'poster', is a pure Python toolkit designed for local generation of promotional graphics and posters, including single-page posters, long infographics, covers, banners, knowledge cards, comparison sheets, certificates, and roll-up banners. It operates entirely offline without requiring internet access, Office suites, or GPU hardware. Users can either use a declarative approach with a 'skeleton + block + theme' trio for standard layouts or directly call the Canvas API for custom vector art. The engine outputs PNG, SVG, or PDF formats using only fontTools as an external dependency. It emphasizes performance with C-level optimizations for pixel operations and provides built-in checks for layout boundaries, contrast, font glyph coverage, and more. The skill supports multiple templates, themes, and presets for different output formats (draft, preview, publish, print) and is suitable for developers needing automated, programmatic graphic generation in Python scripts or AI agent workflows.

Works with~Claude Code~Codex CLI~Cursor
npx skills add https://github.com/KongBai-lab/dsh-skill-poster/tree/main

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

Ask in your favorite AI

Open a new chat with this agent skill pre-loaded.

Documentation

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

Related Skills