poster:Cartaz / Material Promocional
Limites (leia esta seção primeiro)
| Necessidade | O que usar |
|---|
| Gráfico de dados único (barras/linhas/pizza/fluxo/linha do tempo) | diagram, não use este skill |
| Imagem visual única: cartaz/infográfico/capa/banner/cartão/painel | Este skill |
| Apresentação com vários slides | make-ppt |
| Documento com fórmulas | md2docx |
Limitações da máquina local: sem pesos de modelos de difusão, sem poder computacional local para inferência, não é possível gerar fotos ou ilustrações realistas.
Este skill só pode criar estilos geométricos/vetoriais (pode ser detalhado, mas não fotorrealista).
Regras de Ouro
- Não escreva pontos manualmente. Use sempre primitivas paramétricas de
engine.geometry (circle/leaf/cloud/wave/heart…),
elas subdividem-se internamente de forma adaptativa; coordenadas escritas à mão são a fonte de "polígonos improvisados".
- Texto também usa Path. Não crie um sistema de desenho de texto separado;
engine.typography cuida de quebra de linha/texto vertical/evitação de pontuação no início/fim.
- Limpe o cache de módulos após modificar o código. O interpretador da ferramenta
python é compartilhado entre requisições:
for m in [k for k in sys.modules if k.startswith("engine")]: del sys.modules[m]
- Não confie na visualização para detectar defeitos de 1–2 px. A pré-visualização
read_image reduz a escala, criando falsas lacunas;
use asserções de engine.check.check_canvas() ou estatísticas em nível de pixel.
- Desempenho: operações em grandes áreas de pixels devem ser delegadas à camada C; analise antes de modificar.
- Blends semi-transparentes com cor única (preto/branco/cinza), mapeamento de três canais idêntico → LUT de 256 entradas +
bytes.translate.
Na prática, o blend de pixels escuros consumia 71% (6,6s), após a mudança 0,05s, e matematicamente equivalente.
- Preenchimento de linhas inteiras com fatias, não escreva 3 bytes por pixel.
- Use zlib level 6, não 9 (duas vezes mais rápido, arquivo apenas 15% maior).
- Antes de agir, use
cProfile: o maior gargalo deste projeto é o blend alfa, não os algoritmos geométricos.
Três Modos de Uso
| Modo | Entrada | Aplicação |
|---|
| A Template | Copie templates/*/, altere apenas content.json | Cartazes comuns (80% dos casos) |
| B Montagem | Escreva layout.json (esqueleto + lista de blocos + parâmetros) | Estrutura variável, elementos padrão |
| C Desenho Livre | engine.canvas.Canvas para desenhar primitivas diretamente | Imitar imagem de referência, layout único |
Diretório
engine/
canvas.py Lista de exibição (Canvas.fill/stroke/clip, camadas static/dynamic)
path.py Path (M/L/C/Q/Z) + subdivisão adaptativa
geometry.py 23 primitivas paramétricas
fonts.py Registro de fontes + Glyph→Path + detecção de caracteres ausentes
typography.py Quebra de linha/evitação de pontuação no início e fim/compressão de pontuação/texto vertical/ espaçamento entre caracteres
theme.py Tema (6 skins + parâmetros de estilo) + 9 predefinições de tela
blocks.py 21 blocos declarativos
layouts.py 9 esqueletos (incluindo coluna dupla)
render.py Montagem + CLI
check.py Asserções de estouro de limites/contraste/tamanho da fonte/número de cores/caracteres ausentes/slot
cache.py Cache de bitmap de camada estática (desligado por padrão, consulte refs/workflow.md para testes)
backends/ raster.py (PNG), pdf.py (PDF vetorial), svg.py
packs/ Pacotes de materiais (guofeng estilo chinês, chá), carregados sob demanda
templates/ Receitas prontas (content + layout)
Pré-requisitos
- Instalar dependências:
pip install -r requirements.txt (apenas uma dependência: fontTools).
- Fontes: este repositório não inclui arquivos de fonte; o motor lê as fontes instaladas no sistema — por padrão, escaneia
/system/fonts, /usr/share/fonts, ~/.fonts e outros diretórios comuns; se as fontes estiverem em outro local, use a variável de ambiente
POSTER_FONT_DIR para apontar para o diretório de fontes.
- Sem necessidade de internet, Office ou GUI: os três backends (rasterização, PDF, SVG) são implementados em Python puro.
Início 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
Uso em Python:
from engine.render import render, load_json
render(layout, content, theme="minimal", preset_name="xhs-3x4",
out="out.png", for_="publish")
Apenas Quatro Controles Externos
| Controle | Valores | Descrição |
|---|
preset | xhs-3x4 / sq-1x1 / story-9x16 / wechat-cover / video-16x9 / info-long / a4-portrait / a3-portrait / rollup-85x200 | Tamanho e área segura |
--for | draft / preview / publish / print | Nitidez e saída (consulte refs/workflow.md) |
--format | png / pdf / svg | Padrão: print→pdf, outros png |
--deco | 0/1/2 (dentro do tema) | Densidade decorativa; afeta apenas a aparência e o tamanho do arquivo, quase sem impacto na velocidade |
Não há parâmetro quality: o limite inferior de qualidade é garantido pela subdivisão adaptativa de primitivas + cobertura subpixel + check.py.
Limitações (declaradas honestamente)
- Não faz fotos, ilustrações realistas ou 3D; objetos semirrealistas podem (cada um ~100–200 linhas com seis camadas de desenho), pessoas não são recomendadas.
- A primeira versão do PDF converte texto em caminhos: visualmente correto, mas não selecionável ou pesquisável.
- PDF apenas RGB, não suporta CMYK ou cores especiais; é necessário converter antes da impressão.
- Títulos grandes / linhas finas com ss=2: recomenda-se usar
--for publish (ss=3).
- Caracteres raros podem estar ausentes;
check.py reportará caracteres faltantes; fontes podem ser especificadas com POSTER_FONT_DIR.
- Primeira renderização leva ~6s extras (para analisar arquivos de fonte); renderizações subsequentes no mesmo processo reutilizam; iterações devem ser chamadas continuamente, não reiniciando com frequência.
- Referência de tempo a quente: preview ≈1,6s, publish ≈2,7s (para saída de 3240×4320 a partir de 1080×1440).
- Pontuação vertical é apenas transladada, não rotacionada; números/inglês vertical não são rotacionados; adaptação de fontes para múltiplos sistemas não foi feita.
Notas de Atenção (Armadilhas Conhecidas)
Desempenho
- Blend semi-transparente: qualquer cor usa LUT por canal (na prática, 13s→2,5s). Antes de adicionar funcionalidade de "pixel a pixel em grande área", pense se pode usar tabela de consulta.
- Decodificação de PNG grande: 5760×3240 leva 10s+ para decodificar completamente. Materiais de fundo devem ter ≤1500px, ou usar JPEG (decodifica apenas coeficientes DC, uma ordem de magnitude mais rápido).
- Modo print força ss=1: A4@ss3 leva 52s na prática.
- Cache de camada estática não compensa na prática (IO de bitmap de 40MB ≈ custo de renderização),
--cache desligado por padrão.
Fontes
- Todas as fontes FZ carecem de
∂ ħ ∇ e sobrescritos numéricos ⁻³⁵; caracteres ausentes são ignorados silenciosamente, sem erro (fórmulas podem se tornar ψ/ t = i Hψ).
- Antes de escrever fórmulas/unidades, use
fonts.missing(text, family); símbolos disponíveis na prática: apenas ψ ∫ ≈ ∝ λ ∞ → ·.
Layout
hero com várias linhas precisa que a altura da área seja ≥ número de linhas × altura da linha, senão comprime para o próximo bloco.
- As proporções de
banner / card-grid / cover são empíricas; podem precisar de ajustes ao trocar conteúdo.
- CTA em telas largas deve ter
max_width definido, senão ocupa a linha inteira como uma barra de progresso.
- Texto embutido na imagem de fundo conflita com o texto do primeiro plano — escolha materiais sem texto (fotos/texturas/ilustrações).
Materiais de Imagem
- A saída PNG de JPEG é a versão DC (miniatura 8×, pixelizada); para nitidez, gere PDF ou troque para materiais PNG.
- PDF incorpora JPEG diretamente sem recodificação, melhor qualidade.
- Materiais sem extensão também são reconhecidos (pela assinatura do arquivo).
Hábitos de Engenharia
- O cache de módulos da ferramenta
python é compartilhado entre requisições; limpe sys.modules de engine* / packs* no início de cada teste.
- Diretório de desenvolvimento separado do diretório de instalação; após modificar, use
copytree para sincronizar (ignorando __pycache__).
- Se a importação de
objects_pack em scene falhar, cai silenciosamente para uma versão simplificada, sem erro.
Documentação Detalhada (Leia Conforme Necessário)
| Arquivo | Conteúdo |
|---|
refs/workflow.md | Dissecação de imagem de referência → wireframe → coloração → adição de texto → verificação; níveis de nitidez e benchmarks de desempenho |
refs/canvas-api.md | Referência rápida de Canvas / Path / geometry, como implementar funcionalidades ausentes |
refs/presets.md | Todos os tamanhos, áreas seguras, sangria de impressão e conversão de pt |
refs/packs.md | Protocolo de pacotes de materiais e fluxo de "empacotamento sob demanda" |
refs/styles.md | Parâmetros de estilo, 6 impressões digitais de estilos integrados, theme_overrides, processo para imitar um estilo |
refs/analyze.md | Análise de imagem de referência: extração de cores/claridade/centro do layout/densidade → rascunho de theme |