CommunityImagemgithub.com

poster

Crie cartazes e materiais promocionais em Python puro localmente: cartazes de página única, infográficos longos, capas, banners, cartões de conhecimento, páginas comparativas, certificados e banners de feira. Declarativo com 'esqueleto + blocos + tema' ou desenho livre com Canvas; saída em PNG / SVG / PDF, sem dependências externas (apenas fontTools) para rasterização local.

O que é poster?

O skill **poster** é uma ferramenta puramente Python para criar materiais visuais promocionais, como cartazes, banners, infográficos longos, capas, cartões de conhecimento e certificados, diretamente no terminal, sem necessidade de GUI, Office ou conexão com a internet. Ele oferece três modos de uso: **A. Template** (editar um arquivo `content.json` para 80% dos casos), **B. Montagem** (escrever um `layout.json` com esqueleto, blocos e parâmetros) e **C. Desenho Livre** (usar a classe `Canvas` para controle pixel a pixel). A saída pode ser em PNG, SVG ou PDF vetorial (sem texto selecionável na primeira versão), utilizando apenas a biblioteca `fontTools` como dependência. O skill é ideal para desenvolvedores e designers que precisam de automação de alta qualidade, com suporte a temas, verificação de layout (check.py) e otimizações de desempenho como LUT para blend alfa.

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

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

Perguntar na sua IA favorita

Abre um novo chat com esta habilidade de agente já pré-carregada.

Documentação

poster:Cartaz / Material Promocional

Limites (leia esta seção primeiro)

NecessidadeO 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/painelEste skill
Apresentação com vários slidesmake-ppt
Documento com fórmulasmd2docx

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

  1. 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".
  2. 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.
  3. 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]
  4. 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.
  5. 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

ModoEntradaAplicação
A TemplateCopie templates/*/, altere apenas content.jsonCartazes comuns (80% dos casos)
B MontagemEscreva layout.json (esqueleto + lista de blocos + parâmetros)Estrutura variável, elementos padrão
C Desenho Livreengine.canvas.Canvas para desenhar primitivas diretamenteImitar 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

# Gerar imagem (modo preview padrão)
python -m engine.render templates/minimal-poster/layout.json -o out.png

# Impressão: PDF vetorial A4 (texto não selecionável)
python -m engine.render templates/minimal-poster/layout.json -o out.pdf \
       --preset a4-portrait --for print

# Trocar tema / tamanho
python -m engine.render ... --theme guofeng --preset xhs-3x4

# Listar predefinições/esqueletos/blocos disponíveis
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

ControleValoresDescrição
presetxhs-3x4 / sq-1x1 / story-9x16 / wechat-cover / video-16x9 / info-long / a4-portrait / a3-portrait / rollup-85x200Tamanho e área segura
--fordraft / preview / publish / printNitidez e saída (consulte refs/workflow.md)
--formatpng / pdf / svgPadrão: print→pdf, outros png
--deco0/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)

ArquivoConteúdo
refs/workflow.mdDissecaçã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.mdReferência rápida de Canvas / Path / geometry, como implementar funcionalidades ausentes
refs/presets.mdTodos os tamanhos, áreas seguras, sangria de impressão e conversão de pt
refs/packs.mdProtocolo de pacotes de materiais e fluxo de "empacotamento sob demanda"
refs/styles.mdParâmetros de estilo, 6 impressões digitais de estilos integrados, theme_overrides, processo para imitar um estilo
refs/analyze.mdAnálise de imagem de referência: extração de cores/claridade/centro do layout/densidade → rascunho de theme

Habilidades Relacionadas