Anotações de Imagem

Adicione chamadas visuais a qualquer imagem — capturas de tela, diagramas, documentos de arquitetura, quadros de demonstração — usando PIL/Pillow. Destaque o que mudou ou o que olhar, para que os revisores não precisem adivinhar.

Quando Usar Esta Habilidade

Use esta habilidade quando precisar:

• Destacar uma área específica em uma captura de tela para uma descrição de PR
• Anotar imagens de antes/depois para mostrar o que mudou
• Adicionar rótulos e chamadas a diagramas ou imagens de arquitetura
• Criar quadros anotados para demonstrações em GIF animado

Pré-requisitos

pip install Pillow -q

Regras de Cores

• Vermelho (#E63946) — apenas para coisas "ruins" / "removidas" (por exemplo, circular um bug que está sendo corrigido)
• Amarelado-laranja (#FF9F1C) — para destaques neutros ("olhe aqui", "novo recurso", etc.)
• Nunca use vermelho apenas porque chama a atenção — vermelho = ruim/removido

Fonte

• Use Ink Free (C:/Windows/Fonts/Inkfree.ttf) para um visual de escrita à mão no Windows
• No Linux/macOS, use ImageFont.load_default() como alternativa
• Tamanho 36 para anotações em imagens de ~1400px de largura
• stroke_width=1 com stroke_fill=<same color as fill> — dá corpo sem ser muito grosso
• NÃO use contorno branco — parece um efeito de brilho ruim

Formas

• Prefira retângulos arredondados em vez de círculos/elipses — menos pixelização nas bordas
• draw.rounded_rectangle([x1, y1, x2, y2], radius=14, outline=color, width=5)
• Preenchimento de 18px ao redor do conteúdo alvo

Snippet de Referência

from PIL import Image, ImageDraw, ImageFont

# Setup
font = ImageFont.truetype('C:/Windows/Fonts/Inkfree.ttf', 36)  # or load_default()
color = '#FF9F1C'  # orange for highlights
stroke = 5
pad = 18

img = Image.open('screenshot.png')
draw = ImageDraw.Draw(img)

# Rounded rect with padding
draw.rounded_rectangle(
    [x1 - pad, y1 - pad, x2 + pad, y2 + pad],
    radius=14, outline=color, width=stroke
)

# Leader line (same thickness as rect)
draw.line([x2 + pad, cy, x2 + pad + 40, cy - 30], fill=color, width=stroke)

# Label — same-color stroke for body, NO white stroke
draw.text(
    (x2 + pad + 45, cy - 60), 'label text',
    fill=color, font=font, stroke_width=1, stroke_fill=color
)

img.save('annotated.png')

Anotação Algorítmica — annotate.py

Para imagens com múltiplos elementos para anotar, use o módulo annotate.py abaixo. Salve-o ao lado do seu script e importe dele. Ele lida com o posicionamento automático de rótulos sem sobreposição.

Início rápido

from annotate import annotate_image

result = annotate_image(
    'screenshot.png',
    [
        {'elem': (560, 275, 635, 390), 'label': 'button', 'draw_box': True},
        {'elem': (105, 453, 236, 470), 'label': 'status text'},
    ],
    debug=True,
)
result.save('annotated.png')

• elem: (x1, y1, x2, y2) caixa delimitadora justa — deve ser coordenadas de pixel exatas
• label: rótulo de texto (suporta \n para várias linhas)
• draw_box: se True, desenha um retângulo arredondado ao redor do elemento. Se False (padrão), desenha uma ponta de seta em V apontando para o elemento
• debug: mostra retângulos de destino e mapa de calor de candidatos para validação de posicionamento

Auxiliar de grade de coordenadas

Sempre use grid_image() antes de anotar uma imagem desconhecida. Pré-visualizações redimensionadas exibem imagens menores que as dimensões reais em pixels — o erro se acumula à medida que você se afasta de (0,0).

from annotate import grid_image

grid = grid_image('screenshot.png', step=100)
grid.save('grid.png')

Em seguida, verifique com pequenos cortes:

from PIL import Image
img = Image.open('screenshot.png')
crop = img.crop((x1 - 20, y1 - 20, x2 + 20, y2 + 20))
crop.save('verify.png')

Visão geral do algoritmo

1. Busca em anel: candidatos entre MIN_ARROW (25px) e MAX_ARROW (120px) da borda do elemento
2. Pontuação de contraste: prefere posicionamentos onde o texto do rótulo é legível — abs(avg_brightness - 147) - std * 0.3 - dist * 0.02
3. Resolução conjunta: candidatos calculados independentemente, posicionados de forma gananciosa (melhor pontuação primeiro)
4. Bloqueios rígidos: rótulos não podem sobrepor o elemento ou a caixa de respiro de nenhuma outra anotação
5. Penalidade de proximidade: rótulos a menos de 40px de outras caixas posicionadas recebem uma penalidade de pontuação
6. Penalidade de cruzamento de setas: -50 para setas cruzando setas já posicionadas

Cores do modo de depuração

Estilos de seta

…