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:
- Inicialização do Workspace: Configura um espaço de trabalho pessoal local (mantido fora do git via
.gitignore). - Pré-verificação de Cobertura: Escaneia um rascunho alvo (
pages.jsonou texto puro) contraglyphs/manifest.jsone produz a lista mínima exata (ou folha A4 para escrita) de caracteres ausentes. - Pré-processamento & Ingestão Guiada de Fotos: Decodifica fotos
.DNG/.HEIC/.JPG/.PNGcom 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. - 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+ compillowenumpy.scripts/handwrite.pyinclui metadados inline PEP 723, entãouv run scripts/handwrite.py ...provisiona automaticamente as dependências em macOS, Linux e Windows. - Opcional:
ffmpeg(oupillow-heif) para decodificar fotos.HEIC.swiftdo 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.jsonestruturado (veja references/page_schema.md) ou passe um rascunho.txtdiretamente paracheck. - 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–9e 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
- Execute
preprocesspara decodificar.DNG/.HEIC/.JPG/.PNGem<base>_clean.pnge<base>_ink.png(RGBA transparente). Use--crop x0,y0,x1,y1(normalizado0.0–1.0) se a foto incluir bordas da mesa ou sombras. - Crie um
rows_spec.jsonlistando os caracteres escritos em cada linha (use"□"ou"SKIP"para ignorar borrões riscados ou manchas soltas; vejaexamples/usst_lab_report/sample_rows_spec.json). - Sempre execute
ingestcom--dry-runprimeiro. 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. - Confirme zero desalinhamentos, borrões de tinta ou traços cortados. Só então execute novamente
ingestsem--dry-runpara confirmar os glifos emmanifest.jsonusando 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
- 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. - Inspecione visualmente cada
page_<N>.pngrenderizado:- Verifique a porcentagem de preenchimento vertical no stdout; se
[WARNING] ... overflowed bottom marginaparecer, reduza--font-size(faixa típica28–34), ajusteline_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.
- Verifique a porcentagem de preenchimento vertical no stdout; se
Referência de Scripts Utilitários
| Subcomando | Descrição | Flags Principais |
|---|---|---|
init | Cria um espaço de trabalho pessoal limpo | --workspace, --with-example |
check | Calcula a cobertura de glifos e grade opcional A4 de caracteres ausentes | --content, --manifest, --output, --grid-dir |
preprocess | Decodifica foto e extrai tinta RGBA sem sombras | --input, --output-dir, --crop, --hi, --lo |
ingest | Fatia mento guiado por linhas em glifos RGBA + folhas de auditoria | --input, --rows-spec, --manifest, --contact-dir, --dry-run, --source-id |
contact-sheet | Gera uma folha de contato rotulada a partir de manifest.json | --manifest, --output, --chars |
render | Renderiza pages.json em modelos e exporta PDF | --content, --manifest, --output-dir, --assets-dir, --pdf-name, --font-size, --messiness, --seed |
Erros Comuns
- Pular a auditoria visual
--dry-runduranteingest: Uma única mancha riscada ou par de traços adjacentes mesclados pode deslocar os rótulos de uma linha inteira. Sempre inspecione<base>_debug.pnge<base>_sheet.pngantes de confirmar. - 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. - Colisões de sistema de arquivos insensíveis a maiúsculas/minúsculas: No macOS (APFS) e Windows (NTFS),
A_0.pngea_0.pngse sobrescrevem. Sempre usehandwrite.py(que impõeupper_A_0.png/lower_a_0.png/sym_uXXXX_0.png). - Chamar
sipsdo macOS dentro de sandboxes:sipspode gerar silenciosamente imagens pretas sólidas em ambientes sandbox.handwrite.py preprocesslida com.DNGem Python puro e.HEICviapillow-heifouffmpeg. - 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.