atlasmarkz/handwriting-pdf

Caligrafia → PDF

Crie um .ttf real a partir de uma amostra de caligrafia e depois renderize texto com ele em um PDF que se pareça com a escrita da própria pessoa. Tudo é executado localmente; a amostra nunca sai da máquina.

Verdade dura a ser dita ao usuário antecipadamente: isso não é uma IA que inventa 3 000 glifos chineses a partir de uma foto. Uma fonte só pode conter os caracteres realmente escritos na amostra. Portanto: texto latino precisa de ~60–100 caracteres escritos; texto chinês precisa de cada caractere distinto do documento (algumas centenas é normal, milhares é impraticável). Caracteres ausentes são desenhados com uma caligrafia de fallback neutra e relatados — nunca inventados silenciosamente.

0. Localizar a ferramenta

O diretório da skill é a pasta que contém este SKILL.md. Chame a CLI através do seu lançador:

• Windows: <skill>\bin\hwpdf.cmd <comando> ...
• macOS/Linux: <skill>/bin/hwpdf <comando> ...

Se o lançador estiver faltando, instale primeiro (<skill>\install.ps1 no Windows, <skill>/install.sh nos outros), ou execute python <skill>/scripts/hwpdf.py <comando> ... quando as dependências já estiverem disponíveis. hwpdf doctor deve imprimir status ok antes de qualquer outra coisa; se não imprimir, execute o instalador e relate o erro de dependência em vez de improvisar.

1. Escolher o fluxo de entrada

Situação	Fluxo
Padrão: usuário quer um documento real em sua caligrafia	A. Folha de prática (melhor qualidade, mapeamento automático de células)
Usuário fornece um PDF que já mostra sua caligrafia	D. Entrada de PDF — tente a fonte embutida primeiro, senão colha glifos da camada de texto
Usuário já enviou uma foto de sua caligrafia e não quer escrever mais	B. Foto de forma livre (o agente rotula os glifos recortados)
Usuário já possui seu próprio .ttf/.otf	C. Apenas fonte — pule para o passo 4, depois salve um perfil

Peça o texto do documento antes de gerar qualquer coisa: a folha de prática só precisa dos caracteres que o documento usa, então um texto curto significa uma folha curta.

Fluxo A — folha de prática (recomendado)

1. Coloque o texto alvo em um arquivo UTF-8, por exemplo hw/doc.txt, então:

   hwpdf template --text-file hw/doc.txt -d hw
   

   Isso escreve hw/template.pdf (e hw/template.json). 30 células por página, uma página para cada 30 caracteres distintos. Informe exatamente isto ao usuário:
   • imprimir em 100% / Tamanho Real (nunca "ajustar à página");
   • traçar cada glifo cinza claro com uma caneta escura (0,5 mm ou mais grossa) — uma esferográfica é muito clara;
   • manter os quatro quadrados pretos dos cantos visíveis e sem marcações;
   • fotografar cada página de cima com luz uniforme, preencher o quadro e enviar os arquivos.
2. Digitalize as fotos na ordem das páginas:

   hwpdf scan hw/page1.jpg hw/page2.jpg -d hw
   

   A perspectiva e pequenas rotações são corrigidas a partir dos quadrados dos cantos. Saída hw/glyphs.json e hw/glyphs/*.png. Se uma célula retornar como "ausente", o glifo não foi escrito ou estava muito fraco — diga quais caracteres e ofereça uma refotografia apenas dessas células.
3. Construa a fonte:

   hwpdf font -d hw --family "Mão do Alex" -o hw/font.ttf
   

4. Verifique a cobertura antes de renderizar:

   hwpdf coverage --font hw/font.ttf --text-file hw/doc.txt
   

   Saída com código de erro / lista missing significa que esses caracteres não têm glifo. Corrija escrevendo uma segunda folha pequena apenas para esses caracteres e mesclando-a:

   hwpdf template --chars "<caracteres ausentes>" -d hw2
   hwpdf scan hw2/page1.jpg -d hw --append
   hwpdf font -d hw -o hw/font.ttf
   

   Caso contrário, aceite o fallback neutro e diga isso explicitamente.
5. Renderize:

   hwpdf render --font hw/font.ttf --text-file hw/doc.txt -o hw/carta.pdf --size 12 --paper ruled
   

6. Veja o resultado. Renderize páginas para PNG e inspecione-as com visão:

   hwpdf preview --pdf hw/carta.pdf -d hw/preview --dpi 150
   

   Julgue: os traços estão muito finos/grossos, as linhas estão muito apertadas, os caracteres estão colidindo ou saindo das margens, algo parece obviamente errado? Corrija com --size, --leading, --jitter, --weight (reconstrua a fonte), --paper none|ruled|grid.

Fluxo D — o usuário fornece um PDF com sua caligrafia

Esta é a rota mais rápida quando funciona, porque o PDF já contém as formas.

1. Tente o programa de extração de fonte embutida (melhor: conjunto completo de glifos, sem redigitalização):

   hwpdf extract-font --pdf usuario.pdf -d hw
   

   Boa saída = um .ttf/.otf em hw/fonts/ com um mapa de caracteres real (mapped > 20). Pule se o relatório disser "subset/cid".
2. Caso contrário, se o PDF tiver uma camada de texto (acontece quando você pode selecionar os caracteres), colha os glifos da página renderizada — a camada de texto fornece o rótulo, o raster fornece a tinta:

   hwpdf pdf-specimen --pdf usuario.pdf -d hw            # adicione --font-name "<família>" para manter apenas a fonte deles
   hwpdf font -d hw --family "Mão do Alex" -o hw/font.ttf
   

3. Caso contrário, é uma digitalização: hwpdf rasterize --pdf usuario.pdf -d hw/pages → Fluxo B nas imagens das páginas, ou peça uma folha de prática (Fluxo A).
4. Salve o resultado como um perfil (passo 5 abaixo), depois renderize.

Fluxo B — foto de forma livre

1. hwpdf segment hw/foto.jpg -d hw → hw/contact.png (miniaturas numeradas) + hw/crops/.
2. Abra hw/contact.png e leia os números. Escreva hw/labels.json como {"0":"A","1":"b",...}, ou use hwpdf label -d hw --pair "0=A 1=B 2=''" ("" descarta um blob: pontos, borrões, bordas de página ou um fragmento de uma letra desenhada em dois traços).
3. hwpdf font -d hw --labels hw/labels.json -o hw/font.ttf, depois passos 4–6 acima.

A escrita cursiva/conectada e caracteres CJK de múltiplos traços tornam este fluxo propenso a erros; se o resultado parecer ruim, mude para o Fluxo A e explique o motivo.

Fluxo C — usuário já tem uma fonte

Pule para hwpdf coverage e hwpdf render com --font <arquivo deles>, depois salve um perfil.

Perfis — a maneira estável e reutilizável

Um perfil congela tudo o que é necessário para reproduzir a aparência: o arquivo de fonte (copiado para o perfil, com SHA-256), seus padrões e um prompt pronto para colar.

hwpdf profile save --name alex --font hw/font.ttf --source "pdf da caligrafia do usuário"
hwpdf profile list
hwpdf render --profile alex --text-file carta.txt -o carta.pdf

• Os perfis ficam em ~/.handwriting-pdf/profiles/<nome>/ (profile.json, font.ttf, PROMPT.md); defina HWPDF_PROFILE_DIR para realocar.
• PROMPT.md é escrito para o usuário: cole-o em qualquer agente em qualquer máquina e ele chamará a mesma fonte com os mesmos padrões de layout.
• Iterando na aparência? Mude uma coisa de cada vez — renderize, preview, compare, depois hwpdf profile save --name alex --font hw/font.ttf --size ... --paper ... para torná-la o novo padrão. font --weight 1 reconstrói um traço mais ousado; salve o perfil novamente depois para que a alteração persista.
• Um perfil construído a partir de um PDF cobre apenas os caracteres que aparecem naquele PDF. Verifique com hwpdf coverage --font <fonte do perfil> --text-file <novo doc> antes de prometer um documento completo.

Síntese — caracteres que o usuário nunca escreveu (experimental)

Um documento quase sempre precisa de caracteres que o usuário nunca escreveu; em chinês, isso é a norma, não a exceção. Duas maneiras de preenchê-los, em ordem de honestidade:

1. Fallback neutro (padrão, previsível): render --fallback auto escolhe uma fonte de caligrafia do sistema; a página mistura a caligrafia do usuário com uma caligrafia impressa ou neutra, e render relata cada caractere desenhado dessa forma.
2. Inferência de síntese (hwpdf synth, ainda experimental): construa uma segunda fonte que cubra o conjunto completo de caracteres, pegando emprestadas as partes mensuráveis do estilo do usuário — inclinação, peso do traço, altura-x, largura do glifo — e estampando-as em um glifo esqueleto do sistema.

hwpdf synth doctor                              # quais mecanismos são utilizáveis, o que está faltando
hwpdf synth build --style hw/font.ttf --charset common3500 -o hw/synth.ttf
hwpdf synth specimen --font hw/synth.ttf --real hw/font.ttf -o hw/folha.png   # inspecione primeiro
hwpdf synth verify --font hw/synth.ttf --charset common3500                   # cobertura / ausentes
hwpdf synth eval --font hw/synth.ttf --real hw/font.ttf -o hw/relatorio.md      # números para o relatório
hwpdf profile save --name alex --font hw/font.ttf --synth-font hw/synth.ttf
hwpdf render --profile alex --text-file doc.txt -o saida.pdf                    # síntese preenche as lacunas

Mecanismos: stylefit (analítico — sem download, sem GPU, determinístico; glifos chineses mantêm um esqueleto sans do sistema e captam apenas a inclinação/peso do usuário) e stub (teste de fixture, não transferência de estilo). O mecanismo de difusão diff-font precisa de pesos cujas licenças não estão resolvidas (PLAN.md §8 S4) — synth doctor diz isso em vez de fingir.

Diga o que é: caracteres que eles escreveram são reproduzidos literalmente; caracteres inferidos são "sua inclinação e peso em um esqueleto impresso". Não diga ao usuário que a metade inferida "se parece com eles". Verifique meta.gate em <fonte>.json (rejected deve ser 0) e olhe a amostra antes de entregar.

Regras

1. Apenas local. Nunca envie a amostra, a fonte ou a saída; sem chamadas de API.
2. Apenas a caligrafia do próprio usuário. Recuse-se a imitar a caligrafia, assinatura ou papel timbrado de terceiros, e recuse a geração de assinatura / contrato / certificado / documento oficial — explique brevemente (falsificação, fraude, regras de evidência) e ofereça um documento digitado normal.
3. Nunca invente qualidade. Se a fonte tem 40 glifos, diga 40. Se o fallback desenhou metade da página, diga isso. Relate os caracteres ausentes literalmente.
4. Peça uma refotografia antes de culpar a ferramenta: fotos borradas, com sombras, cantos cortados ou linhas de grade cobertas são a causa mais comum de falha.
5. Mantenha o diretório de trabalho (hw/) — o usuário pode adicionar caracteres depois e reconstruir a fonte.

Referência de comandos

Comando	Propósito
hwpdf doctor	verificação de dependências + fontes do sistema
hwpdf template --chars "abc" / --text-file doc.txt -d DIR	folha de prática PDF + metadados
hwpdf scan IMG... [-d DIR] [--rotate 90] [--append]	folha fotografada → máscaras de glifo (append = mescla ao trabalho existente)
hwpdf extract-font --pdf in.pdf -d DIR	extrair fontes embutidas de um PDF (melhor caso: TTF completo)
hwpdf pdf-specimen --pdf in.pdf -d DIR [--font-name F]	colher glifos rotulados da camada de texto + raster de um PDF
hwpdf rasterize --pdf in.pdf -d DIR [--dpi 300]	PDF escaneado → PNGs de página
hwpdf segment IMG... [-d DIR] [--thresh N] [--deskew]	foto de forma livre → blobs + folha de contato
hwpdf label -d DIR --order "ABC" / --pair "0=A 1=B"	mapear blobs para caracteres
hwpdf font -d DIR [--labels f] [--family NAME] [--weight -2..2] [--smooth 0..2] -o saida.ttf	construir fonte
hwpdf coverage --font f --text-file doc.txt	quais caracteres estão ausentes
`hwpdf render --font f --text-file doc.txt -o saida.pdf [--size 12] [--leading 1.8] [--paper ruled] [--jitter 1] [--ink "#1a1c24"] [--fallback auto	none
hwpdf render --profile NOME --text-file doc.txt -o saida.pdf	PDF usando a fonte + padrões de um perfil salvo
hwpdf profile save/list/show/remove ...	congelar / inspecionar o perfil de caligrafia reutilizável (escreve PROMPT.md)
hwpdf preview --pdf saida.pdf -d DIR [--dpi 150]	páginas PDF → PNG para revisão visual
hwpdf synth doctor / build / specimen / verify / charsets	mecanismo de inferência opcional: fonte de conjunto completo a partir de um subconjunto escrito (veja a seção de Síntese)
hwpdf selftest -d DIR [--messy]	teste de fumaça sintético ponta a ponta

Limites (informe quando relevante)

• Um glifo por caractere: sem cursiva conectada, sem variação natural entre ocorrências, sem textura de pressão/tinta. O espaçamento irregular é simulado, as formas dos glifos não.
• CJK: a fonte contém apenas caracteres escritos. 30 células por página; uma carta de 300 caracteres precisa de uma folha de prática de 10 páginas. hwpdf synth build --charset common3500 é o atalho, mas CJK inferido é um esqueleto sans do sistema com a inclinação do usuário, não sua pincelada real.
• A camada de texto do PDF é texto real (pesquisável/copiável) na fonte gerada.
• As fotos devem mostrar todos os quatro quadrados pretos dos cantos da folha de prática.

Detalhes: references/workflow.md · references/troubleshooting.md