poster: Cartel / Imagen promocional
Límites (lea esta sección primero)
| Necesidad | Qué usar |
|---|
| Gráfico de datos simple (barras/líneas/tarta/flujo/línea temporal) | diagram, no use este skill |
| Imagen visual única: cartel/infografía larga/portada/banner/tarjeta/póster | Este skill |
| Presentación de varias diapositivas | make-ppt |
| Documento con fórmulas | md2docx |
Límites del equipo local: no tiene pesos de modelos de difusión ni capacidad de inferencia local, no puede generar fotografías ni ilustraciones realistas.
Este skill solo puede hacer estilo geométrico/vectorial (puede llegar a ser detallado, pero no realista).
Reglas de hierro
- No escriba listas de puntos manualmente. Use siempre primitivas parametrizadas de
engine.geometry (circle/leaf/cloud/wave/heart…),
que se subdividen internamente de forma adaptativa; las coordenadas escritas a mano son la raíz de "parece un polígono improvisado".
- El texto también va por Path. No escriba otro sistema de renderizado de texto;
engine.typography se encarga del ajuste de líneas/texto vertical/evitar caracteres prohibidos al inicio/final.
- Limpie el caché de módulos después de modificar código. El intérprete de la herramienta
python comparte módulos entre solicitudes:
for m in [k for k in sys.modules if k.startswith("engine")]: del sys.modules[m]
- No confíe en la revisión visual para defectos de 1–2 px. La vista previa
read_image escala, produciendo falsos cortes;
use las aserciones de engine.check.check_canvas() o estadísticas a nivel de píxel.
- Rendimiento: operaciones de grandes áreas de píxeles deben delegarse a la capa C; analice antes de modificar.
- Si la superposición semitransparente es de un solo color (negro/blanco/gris), los tres canales mapean igual → LUT de 256 entradas +
bytes.translate.
Se midió que la mezcla píxel a píxel consumía el 71% (6.6 s), después del cambio 0.05 s, y matemáticamente equivalente.
- Para rellenar filas completas, use asignación por segmentos, no escriba 3 bytes píxel a píxel.
- Use zlib nivel 6, no 9 (el doble de rápido, archivo solo 15% más grande).
- Antes de modificar, ejecute
cProfile: el mayor cuello de botella de este proyecto es la mezcla alfa, no los algoritmos geométricos.
Tres modos de uso
| Modo | Entrada | Aplicación |
|---|
| A: Plantillas | Copiar templates/*/, solo modificar content.json | Carteles habituales (80% de los casos) |
| B: Ensamblaje | Escribir layout.json (esqueleto + lista de bloques + parámetros) | Cuando la estructura cambia, elementos estándar |
| C: Dibujo libre | engine.canvas.Canvas escribir primitivas directamente | Imitar imágenes de referencia, diseño único |
Directorio
engine/
canvas.py Lista de visualización (Canvas.fill/stroke/clip, capas static/dynamic)
path.py Path (M/L/C/Q/Z) + subdivisión adaptativa
geometry.py 23 primitivas parametrizadas
fonts.py Registro de fuentes + glifo→Path + detección de glifos faltantes
typography.py Ajuste de líneas/evitar caracteres prohibidos/compresión de puntuación/texto vertical/espaciado
theme.py Tema (6 conjuntos de piel + parámetros de estilo) + 9 preajustes de lienzo
blocks.py 21 bloques declarativos
layouts.py 9 esqueletos (incluyendo columnas izquierda/derecha)
render.py Ensamblaje + CLI
check.py Aserciones de desbordamiento/contraste/tamaño de fuente/número de colores/glifos faltantes/slot
cache.py Caché de mapa de bits de capas estáticas (desactivado por defecto, ver refs/workflow.md para pruebas)
backends/ raster.py (PNG), pdf.py (PDF vectorial), svg.py
packs/ Paquetes de recursos (guofeng 国风, tea 茶器), cargados bajo demanda
templates/ Recetas listas (content + layout)
Requisitos previos
- Instalar dependencias:
pip install -r requirements.txt (solo una dependencia: fontTools).
- Fuentes: Este repositorio no incluye archivos de fuentes; el motor lee las fuentes del sistema instaladas — por defecto escanea
/system/fonts, /usr/share/fonts, ~/.fonts y otros directorios comunes; si las fuentes están en otro lugar, use la variable de entorno
POSTER_FONT_DIR para apuntar al directorio de fuentes.
- Sin necesidad de Internet, Office ni GUI: Los tres backends (rasterización, PDF, SVG) son implementaciones puras en Python.
Inicio rápido
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
Llamada desde Python:
from engine.render import render, load_json
render(layout, content, theme="minimal", preset_name="xhs-3x4",
out="out.png", for_="publish")
Solo cuatro parámetros externos
| Parámetro | Valores | Descripción |
|---|
preset | xhs-3x4 / sq-1x1 / story-9x16 / wechat-cover / video-16x9 / info-long / a4-portrait / a3-portrait / rollup-85x200 | Tamaño y zona segura |
--for | draft / preview / publish / print | Calidad y salida (ver refs/workflow.md) |
--format | png / pdf / svg | Por defecto: print→pdf, resto png |
--deco | 0/1/2 (dentro del tema) | Densidad decorativa; solo afecta apariencia y tamaño de archivo, casi no afecta velocidad |
No hay parámetro quality: La calidad mínima está garantizada por la subdivisión adaptativa de primitivas + cobertura de subpíxeles + check.py.
Limitaciones (información honesta)
- No hace fotografías, ilustraciones realistas ni 3D; objetos semirrealistas pueden funcionar (cada uno aproximadamente 100–200 líneas, seis capas de dibujo), no se recomiendan personas.
- La primera versión de PDF convierte texto a trazados: visualmente correcto pero no seleccionable ni buscable.
- PDF solo RGB, no admite CMYK ni colores planos; necesita conversión previa a la impresión.
- Títulos grandes/líneas finas con ss=2, se recomienda usar
--for publish (ss=3).
- Los caracteres poco comunes pueden faltar;
check.py informará de glifos faltantes, las fuentes se pueden especificar con POSTER_FONT_DIR.
- Primera renderización añade unos 6 s (análisis de archivos de fuentes), las renderizaciones posteriores en el mismo proceso reutilizan; en iteraciones se debe llamar de forma continua en lugar de reiniciar con frecuencia.
- Tiempo estimado en caliente: preview ≈1.6 s, publish ≈2.7 s (salida 3240×4320 desde 1080×1440).
- La puntuación vertical solo se desplaza, no se rota; los números/inglés vertical no se rotan; no se ha adaptado para múltiples fuentes.
Notas importantes (errores ya experimentados)
Rendimiento
- Superposición semitransparente: cualquier color pasa por LUT por canal (medido 13s → 2.5s). Antes de agregar una función "píxel a píxel en área grande", piense si se puede hacer con una tabla de búsqueda.
- Decodificación de PNG grandes: 5760×3240 completamente decodificado 10s+. Los recursos de fondo deben ser ≤1500px, o usar JPEG (solo decodifica coeficientes DC, un orden de magnitud más rápido).
- Modo print fuerza ss=1: A4@ss3 medido 52s.
- El caché de capas estáticas no es rentable en la práctica (40 MB de mapa de bits IO ≈ costo de renderización),
--cache desactivado por defecto.
Fuentes
- Todas las fuentes FZ carecen de
∂ ħ ∇ y superíndices numéricos ⁻³⁵; los glifos faltantes se omiten en silencio, no se reportan (las fórmulas se convierten en ψ/ t = i Hψ).
- Antes de escribir fórmulas/unidades, use
fonts.missing(text, family); los símbolos disponibles en la práctica son solo ψ ∫ ≈ ∝ λ ∞ → ·.
Maquetación
hero multilínea necesita altura de área ≥ número de líneas × altura de línea, de lo contrario se comprime al siguiente bloque.
- Las proporciones de
banner / card-grid / cover son empíricas; puede necesitar ajustes al cambiar contenido.
- El CTA en pantalla ancha debe tener
max_width, de lo contrario ocupa toda la línea como una barra de progreso.
- El texto incluido en la imagen de fondo choca con el primer plano — seleccione recursos sin texto (fotos/texturas/ilustraciones).
Recursos de imagen
- La salida PNG de JPEG es la versión DC (miniatura 8×, pixelada); para nitidez, genere PDF o use recursos PNG.
- PDF incrusta JPEG sin recodificación, con la mejor calidad.
- Los recursos sin extensión también se reconocen (por la firma del archivo).
Hábitos de ingeniería
- El caché de módulos de la herramienta
python se comparte entre solicitudes, al inicio de cada prueba limpie sys.modules de engine* / packs*.
- Separe el directorio de desarrollo del directorio de instalación; después de modificar, use
copytree para sincronizar (ignorando __pycache__).
- Si la importación de
objects_pack de scene falla, vuelve silenciosamente a la versión simplificada, sin error.
Documentación detallada (lea según necesidad)
| Archivo | Contenido |
|---|
refs/workflow.md | Disección de imagen de referencia → boceto en gris → coloreado → texto → verificación; niveles de nitidez y rendimiento medido |
refs/canvas-api.md | Referencia rápida de Canvas/Path/Geometry, cómo suplir capacidades faltantes |
refs/presets.md | Todos los tamaños, zonas seguras, sangrado de impresión y conversión pt |
refs/packs.md | Protocolo de paquetes de recursos y flujo de "empaquetado bajo demanda" |
refs/styles.md | Parámetros de estilo, huellas de 6 temas integrados, anulaciones de tema, flujo para imitar un estilo |
refs/analyze.md | Análisis de imagen de referencia: extracción de colores/claroscuro/caja de texto/densidad → borrador de tema |