CommunityImagemgithub.com

personal-handwriting

Habilidade de imagem. Construa uma biblioteca pessoal de glifos manuscritos a partir de fotos reais de caneta no papel, verifique a cobertura de caracteres em relação a rascunhos alvo, oriente a captura mínima de caracteres ausentes e renderize programaticamente documentos manuscritos realistas de várias páginas e PDFs (com tabelas, equações e modelos personalizados) sem artefatos de geração de imagens por IA. Use quando o usuário quiser digitalizar sua própria caligrafia, criar ou expandir uma biblioteca pessoal de glifos, ou renderizar tarefas manuscritas, anotações ou relatórios de laboratório.

O que é personal-handwriting?

O Personal Handwriting Studio é uma skill especializada para agentes de IA que permite a digitalização e reprodução realista da caligrafia pessoal de um usuário. Ao processar fotos reais de caneta no papel, ela constrói uma biblioteca de glifos reutilizável e renderiza documentos manuscritos de múltiplas páginas em PDF, sem os artefatos típicos da geração de fontes por IA. A skill oferece um pipeline completo: verificação de cobertura de caracteres contra um rascunho alvo, pré-processamento de fotos com normalização de iluminação, segmentação guiada por linhas para extração de glifos, e renderização realista com suporte a tabelas, equações e modelos personalizados. É especialmente útil para estudantes, pesquisadores ou profissionais que precisam criar relatórios, anotações ou trabalhos manuscritos de forma programática, mantendo a autenticidade visual da própria caligrafia. Suporta imagens nos formatos DNG, HEIC, JPG e PNG, e opera em macOS, Linux e Windows com Python 3.10+ e as bibliotecas pillow e numpy.

Funciona com~Claude Code~Codex CLI~Cursor
npx skills add https://github.com/Elizhng/personal-handwriting/tree/HEAD

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

Personal Handwriting Studio

Transforme fotos reais de sua caligrafia em uma biblioteca pessoal de glifos reutilizável e renderize programaticamente documentos manuscritos realistas de várias páginas e PDFs — sem artefatos de fontes geradas por IA.

Visão Geral

Esta skill orquestra um pipeline de caligrafia 100% programático e em circuito fechado:

  1. Inicialização do Workspace: Configura um espaço de trabalho pessoal local (mantido fora do git via .gitignore).
  2. Pré-verificação de Cobertura: Escaneia um rascunho alvo (pages.json ou texto puro) contra glyphs/manifest.json e produz a lista mínima exata (ou folha A4 para escrita) de caracteres ausentes.
  3. Pré-processamento & Ingestão Guiada de Fotos: Decodifica fotos .DNG / .HEIC / .JPG / .PNG com normalização de iluminação (removendo sombras e transparência do papel), fatia caracteres via agrupamento de componentes conectados guiado por linhas multiplataforma, e executa uma auditoria visual obrigatória de folha de contato antes de confirmar os glifos.
  4. Renderização Realista & PDF: Compõe páginas em papel em branco ou modelos personalizados usando normalização de largura de traço com supersampling 2× (~0,6 mm de consistência de caneta gel), deduplicação multi-variante por janela deslizante, linha de base natural ondulada, tabelas/equações desenhadas à mão trêmula e verificação de 100% de cobertura de caracteres.

Dependências

  • Runtime: uv (recomendado) ou Python 3.10+ com pillow e numpy. scripts/handwrite.py inclui metadados inline PEP 723, então uv run scripts/handwrite.py ... provisiona automaticamente as dependências em macOS, Linux e Windows.
  • Opcional:
    • ffmpeg (ou pillow-heif) para decodificar fotos .HEIC.
    • swift do macOS apenas se estiver usando o extrator OCR opcional Apple Vision (veja references/macos_vision_ocr.md).

Início Rápido

# 1. Inicialize um espaço de trabalho pessoal (com o exemplo opcional de relatório de laboratório USST)
uv run scripts/handwrite.py init --workspace ./my_handwriting --with-example

# 2. Verifique quais caracteres de um rascunho estão faltando na sua biblioteca de glifos
uv run scripts/handwrite.py check \
  --content ./my_handwriting/content/sample_pages.json \
  --manifest ./my_handwriting/glyphs/manifest.json \
  --output ./my_handwriting/coverage_report.json \
  --grid-dir ./my_handwriting/missing_grid

# 3. Pré-processe uma foto da sua folha manuscrita (DNG / HEIC / JPG / PNG)
uv run scripts/handwrite.py preprocess \
  --input ./my_handwriting/photos/sheet1.jpg \
  --output-dir ./my_handwriting/preprocessed

# 4. Simule o fatia mento e audite visualmente antes de confirmar no manifest.json
uv run scripts/handwrite.py ingest \
  --input ./my_handwriting/preprocessed/sheet1_ink.png \
  --rows-spec ./my_handwriting/content/rows_spec.json \
  --manifest ./my_handwriting/glyphs/manifest.json \
  --contact-dir ./my_handwriting/contact_sheets \
  --dry-run

# 5. Após inspecionar visualmente a sobreposição de depuração e a folha de contato, confirme os glifos (omita --dry-run)
uv run scripts/handwrite.py ingest \
  --input ./my_handwriting/preprocessed/sheet1_ink.png \
  --rows-spec ./my_handwriting/content/rows_spec.json \
  --manifest ./my_handwriting/glyphs/manifest.json \
  --contact-dir ./my_handwriting/contact_sheets

# 6. Renderize PNGs manuscritos realistas de várias páginas + PDF combinado
uv run scripts/handwrite.py render \
  --content ./my_handwriting/content/sample_pages.json \
  --manifest ./my_handwriting/glyphs/manifest.json \
  --assets-dir ./my_handwriting \
  --output-dir ./my_handwriting/output \
  --pdf-name report.pdf

Fluxo de Trabalho Padrão do Agente

Etapa 1: Pré-verificação de Cobertura Antes de Pedir ao Usuário para Escrever

  • Converta o rascunho do usuário em um pages.json estruturado (veja references/page_schema.md) ou passe um rascunho .txt diretamente para check.
  • Execute uv run scripts/handwrite.py check ... para calcular os caracteres ausentes exatos ordenados por frequência.
  • Peça ao usuário para escrever à mão apenas os caracteres ausentes em papel branco em branco com uma caneta gel preta (recomende escrever 2–4 variantes para caracteres de alta frequência, dígitos 0–9 e pontuação para que as páginas renderizadas pareçam naturais), e tire uma foto plana e uniformemente iluminada.

Etapa 2: Pré-processamento, Ingestão Guiada por Linhas e Auditoria Visual Obrigatória

  1. Execute preprocess para decodificar .DNG / .HEIC / .JPG / .PNG em <base>_clean.png e <base>_ink.png (RGBA transparente). Use --crop x0,y0,x1,y1 (normalizado 0.0–1.0) se a foto incluir bordas da mesa ou sombras.
  2. Crie um rows_spec.json listando os caracteres escritos em cada linha (use "□" ou "SKIP" para ignorar borrões riscados ou manchas soltas; veja examples/usst_lab_report/sample_rows_spec.json).
  3. Sempre execute ingest com --dry-run primeiro. Inspecione tanto <base>_debug.png (caixas delimitadoras sobre a tinta) quanto <base>_sheet.png (folha de contato de caracteres individuais rotulados) usando sua ferramenta de leitura/visão.
  4. Confirme zero desalinhamentos, borrões de tinta ou traços cortados. Só então execute novamente ingest sem --dry-run para confirmar os glifos em manifest.json usando nomes de arquivo seguros para maiúsculas/minúsculas multiplataforma (upper_<X>_k.png, lower_<x>_k.png, sym_u<4hex>_k.png, <ch>_k.png).

Etapa 3: Renderização e QA Página por Página

  1. Execute render. O script aplica uma verificação de pré-voo de 100% de cobertura de caracteres (verify_all_chars_covered) e falha rapidamente se algum caractere estiver ausente.
  2. Inspecione visualmente cada page_<N>.png renderizado:
    • Verifique a porcentagem de preenchimento vertical no stdout; se [WARNING] ... overflowed bottom margin aparecer, reduza --font-size (faixa típica 28–34), ajuste line_h_ratio (1.38–1.50), ou divida o conteúdo em uma página de continuação adicional.
    • Verifique se os campos da capa se alinham limpa mente nos sublinhados, se as tabelas não cortam o texto das células e se as larguras dos traços parecem uniformes.

Referência de Scripts Utilitários

SubcomandoDescriçãoFlags Principais
initCria um espaço de trabalho pessoal limpo--workspace, --with-example
checkCalcula a cobertura de glifos e grade opcional A4 de caracteres ausentes--content, --manifest, --output, --grid-dir
preprocessDecodifica foto e extrai tinta RGBA sem sombras--input, --output-dir, --crop, --hi, --lo
ingestFatia mento guiado por linhas em glifos RGBA + folhas de auditoria--input, --rows-spec, --manifest, --contact-dir, --dry-run, --source-id
contact-sheetGera uma folha de contato rotulada a partir de manifest.json--manifest, --output, --chars
renderRenderiza pages.json em modelos e exporta PDF--content, --manifest, --output-dir, --assets-dir, --pdf-name, --font-size, --messiness, --seed

Erros Comuns

  1. Pular a auditoria visual --dry-run durante ingest: Uma única mancha riscada ou par de traços adjacentes mesclados pode deslocar os rótulos de uma linha inteira. Sempre inspecione <base>_debug.png e <base>_sheet.png antes de confirmar.
  2. Usar geração de imagens por IA ou fontes alternativas do sistema: Nunca gere páginas manuscritas com modelos de difusão ou substitua caracteres ausentes por fontes do sistema. Sempre capture glifos genuínos ausentes via check → ingest.
  3. Colisões de sistema de arquivos insensíveis a maiúsculas/minúsculas: No macOS (APFS) e Windows (NTFS), A_0.png e a_0.png se sobrescrevem. Sempre use handwrite.py (que impõe upper_A_0.png / lower_a_0.png / sym_uXXXX_0.png).
  4. Chamar sips do macOS dentro de sandboxes: sips pode gerar silenciosamente imagens pretas sólidas em ambientes sandbox. handwrite.py preprocess lida com .DNG em Python puro e .HEIC via pillow-heif ou ffmpeg.
  5. Confirmar caligrafia pessoal no Git: Mantenha espaços de trabalho pessoais (glyphs/, photos/, output/) fora do repositório da skill ou dentro de caminhos ignorados pelo git.

Habilidades Relacionadas