poster: Promotional Image / Poster
Boundaries (Read This First)
| Need | Use |
|---|
| Single data charts (bar/line/pie, flowchart, timeline) | diagram, do not use this skill |
| Single visual image: poster/long image/cover/banner/card/exhibition board | This skill |
| Multi-page presentation | make-ppt |
| Document with formulas | md2docx |
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
- 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".
- 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.
- 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]
- 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.
- 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
| Mode | Input | Use Case |
|---|
| A Templates | Copy templates/*/, edit only content.json | Standard promotional images (80% of scenarios) |
| B Assembly | Write layout.json (skeleton + block list + parameters) | Structure changes, standard elements |
| C Custom Drawing | engine.canvas.Canvas directly | Mimic 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
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
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
| Knob | Values | Description |
|---|
preset | xhs-3x4 / sq-1x1 / story-9x16 / wechat-cover / video-16x9 / info-long / a4-portrait / a3-portrait / rollup-85x200 | Dimensions and safe zones |
--for | draft / preview / publish / print | Resolution and output quality (see refs/workflow.md) |
--format | png / pdf / svg | Default: print→pdf, otherwise png |
--deco | 0/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)
| File | Content |
|---|
refs/workflow.md | Reference image dissection → gray model → coloring → text → validation; quality tiers and performance benchmarks |
refs/canvas-api.md | Canvas / Path / geometry quick reference, workarounds for missing capabilities |
refs/presets.md | All dimensions, safe zones, print bleed, and pt conversions |
refs/packs.md | Asset pack protocol and "pack on demand" workflow |
refs/styles.md | Style parameters, 6 built-in style fingerprints, theme_overrides, process to mimic a style |
refs/analyze.md | Reference image analysis: color extraction, light/dark, layout center, density → theme draft |