atlasmarkz/handwriting-pdf

Manuscrito → PDF

Crea una fuente .ttf real a partir de una muestra de escritura a mano, luego renderiza texto con ella en un PDF que se parece a la caligrafía del propio escritor. Todo se ejecuta localmente; la muestra nunca sale de la máquina.

Verdad incómoda que debes contarle al usuario de inmediato: esto no es una IA que inventa 3.000 glifos chinos a partir de una foto. Una fuente solo puede contener los caracteres realmente escritos en la muestra. Por lo tanto: el texto latino necesita entre ~60 y 100 caracteres escritos; el texto chino necesita cada carácter distinto del documento (unos cientos es normal, miles es inviable). Los caracteres faltantes se dibujan con un defecto de escritura a mano neutro y se notifican; nunca se inventan en silencio.

0. Localizar la herramienta

El directorio del skill es la carpeta que contiene este SKILL.md. Invoca la CLI a través de su lanzador:

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

Si falta el lanzador, instala primero (<skill>\install.ps1 en Windows, <skill>/install.sh en otros), o ejecuta python <skill>/scripts/hwpdf.py <comando> ... cuando las dependencias ya estén disponibles. hwpdf doctor debe imprimir status ok antes de cualquier otra cosa; si no lo hace, ejecuta el instalador e informa del error de dependencia en lugar de improvisar.

1. Elegir el flujo de entrada

Situación	Flujo
Por defecto: el usuario quiere un documento real escrito a mano	A. Hoja de práctica (mejor calidad, mapeo de celdas totalmente automático)
El usuario entrega un PDF que ya muestra su escritura a mano	D. Entrada PDF: prueba primero la fuente incrustada, si no, cosecha glifos de la capa de texto
El usuario ya envió una foto de su escritura a mano y no quiere escribir más	B. Foto libre (el agente etiqueta los glifos recortados)
El usuario ya tiene su propia fuente .ttf/.otf	C. Solo fuente: salta al paso 4, luego guarda un perfil

Pide el texto del documento antes de generar nada: la hoja de práctica solo necesita los caracteres que usa el documento, así que un texto corto significa una hoja corta.

Flujo A: hoja de práctica (recomendado)

1. Coloca el texto de destino en un archivo UTF-8, p. ej., hw/doc.txt, luego:

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

   Esto escribe hw/template.pdf (y hw/template.json). 30 celdas por página, una página por cada 30 caracteres distintos. Dile exactamente esto al usuario:
   • imprimir al 100% / Tamaño real (nunca "ajustar a la página");
   • trazar cada glifo gris claro con un bolígrafo oscuro (0,5 mm o más grueso): un bolígrafo normal es demasiado claro;
   • mantener visibles y sin marcar las cuatro esquinas negras cuadradas;
   • fotografiar cada página desde arriba con luz uniforme, llenando el encuadre, y enviar los archivos.
2. Escanea las fotos en orden de página:

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

   La perspectiva y las pequeñas rotaciones se corrigen a partir de los cuadrados de las esquinas. Genera hw/glyphs.json y hw/glyphs/*.png. Si una celda aparece como "perdida", el glifo no se escribió o era demasiado tenue: indica qué caracteres y ofrece volver a fotografiar solo esas celdas.
3. Construye la fuente:

   hwpdf font -d hw --family "Alex Hand" -o hw/font.ttf
   

4. Verifica la cobertura antes de renderizar:

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

   Código de salida distinto de cero / lista de missing significa que esos caracteres no tienen glifo. Solución: escribe una segunda hoja pequeña solo para esos caracteres y combínala:

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

   De lo contrario, acepta el fallback neutro y dilo explícitamente.
5. Renderiza:

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

6. Mira el resultado. Renderiza las páginas a PNG e inspecciónalas con visión:

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

   Evalúa: ¿los trazos son demasiado finos/gruesos, las líneas demasiado juntas, los caracteres chocan o se salen de los márgenes, algo parece claramente incorrecto? Corrige con --size, --leading, --jitter, --weight (reconstruye la fuente), --paper none|ruled|grid.

Flujo D: el usuario entrega un PDF con su escritura a mano

Esta es la ruta más rápida cuando funciona, porque el PDF ya contiene las formas.

1. Prueba el programa de fuente incrustada (lo mejor: conjunto completo de glifos, sin necesidad de volver a trazar):

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

   Buena salida = un .ttf/.otf en hw/fonts/ con un mapa de caracteres real (mapped > 20). Omítelo si el informe dice "subset/cid".
2. De lo contrario, si el PDF tiene una capa de texto (la tiene cuando puedes seleccionar los caracteres), cosecha los glifos de la página renderizada: la capa de texto da la etiqueta, el ráster da la tinta:

   hwpdf pdf-specimen --pdf user.pdf -d hw            # añade --font-name "<familia>" para conservar solo su fuente
   hwpdf font -d hw --family "Alex Hand" -o hw/font.ttf
   

3. De lo contrario, es un escaneo: hwpdf rasterize --pdf user.pdf -d hw/pages → Flujo B sobre las imágenes de página, o pide una hoja de práctica (Flujo A).
4. Guarda el resultado como perfil (paso 5 a continuación), luego renderiza.

Flujo B: foto libre

1. hwpdf segment hw/photo.jpg -d hw → hw/contact.png (miniaturas numeradas) + hw/crops/.
2. Abre hw/contact.png y lee los números. Escribe hw/labels.json como {"0":"A","1":"b",...}, o usa hwpdf label -d hw --pair "0=A 1=B 2=''" ("" descarta una mancha: puntos, borrones, bordes de página o un fragmento de letra dibujada en dos trazos).
3. hwpdf font -d hw --labels hw/labels.json -o hw/font.ttf, luego pasos 4–6 anteriores.

La escritura conectada/cursiva y los caracteres CJK de trazo múltiple hacen que este flujo sea propenso a errores; si el resultado se ve mal, cambia al Flujo A y explica por qué.

Flujo C: el usuario ya tiene una fuente

Salta a hwpdf coverage y hwpdf render con --font <su archivo>, luego guarda un perfil.

Perfiles: la forma estable y reutilizable

Un perfil congela todo lo necesario para reproducir el aspecto: el archivo de fuente (copiado en el perfil, con SHA-256), sus valores predeterminados y un prompt listo para pegar.

hwpdf profile save --name alex --font hw/font.ttf --source "escritura a mano del usuario pdf"
hwpdf profile list
hwpdf render --profile alex --text-file letter.txt -o letter.pdf

• Los perfiles residen en ~/.handwriting-pdf/profiles/<nombre>/ (profile.json, font.ttf, PROMPT.md); establece HWPDF_PROFILE_DIR para reubicarlos.
• PROMPT.md está escrito para el usuario: pégalo en cualquier agente en cualquier máquina y este llamará a la misma fuente con los mismos valores predeterminados de diseño.
• ¿Iterando sobre el aspecto? Cambia una cosa a la vez: renderiza, preview, compara, luego hwpdf profile save --name alex --font hw/font.ttf --size ... --paper ... para convertirlo en el nuevo valor predeterminado. font --weight 1 reconstruye un trazo más grueso; vuelve a guardar el perfil después para que el cambio persista.
• Un perfil creado a partir de un PDF solo cubre los caracteres que aparecen en ese PDF. Verifica con hwpdf coverage --font <fuente del perfil> --text-file <nuevo doc> antes de prometer un documento completo.

Síntesis: caracteres que el usuario nunca escribió (experimental)

Un documento casi siempre necesita caracteres que el usuario nunca escribió; en chino esto es la norma, no una excepción. Dos formas de rellenarlos, en orden de honestidad:

1. Fallback neutro (predeterminado, predecible): render --fallback auto elige una fuente de escritura a mano del sistema; la página mezcla su letra con una letra impresa o neutra, y render notifica cada carácter dibujado de esa forma.
2. Inferencia de síntesis (hwpdf synth, aún experimental): construye una segunda fuente que cubre el conjunto de caracteres completo tomando prestadas las partes medibles de su estilo: inclinación, grosor del trazo, altura x, ancho del glifo, y estampándolas sobre un glifo esqueleto del sistema.

hwpdf synth doctor                              # qué motores son utilizables, qué falta
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/sheet.png   # inspeccionar primero
hwpdf synth verify --font hw/synth.ttf --charset common3500                   # cobertura / faltantes
hwpdf synth eval --font hw/synth.ttf --real hw/font.ttf -o hw/report.md      # números para el informe
hwpdf profile save --name alex --font hw/font.ttf --synth-font hw/synth.ttf
hwpdf render --profile alex --text-file doc.txt -o out.pdf                    # la síntesis rellena los huecos

Motores: stylefit (analítico: sin descarga, sin GPU, determinista; los glifos chinos mantienen un esqueleto sans-serif del sistema y solo toman la inclinación/grosor del usuario) y stub (banco de pruebas, no es transferencia de estilo). El motor de difusión diff-font necesita pesos cuyas licencias no están resueltas (PLAN.md §8 S4) – synth doctor lo dice en lugar de fingir.

Di lo que es: los caracteres que escribió se reproducen textualmente; los caracteres inferidos son "su inclinación y grosor sobre un esqueleto impreso". No le digas al usuario que la mitad inferida "se parece a él". Verifica meta.gate en <fuente>.json (rejected debe ser 0) y mira la muestra antes de enviar.

Reglas

1. Solo local. Nunca subas la muestra, la fuente ni la salida; nada de llamadas API.
2. Solo la propia escritura a mano del usuario. Rehúsate a imitar la escritura a mano, firma o membrete de un tercero, y rehúsa la generación de firmas / contratos / certificados / documentos oficiales. Explica brevemente (falsificación, fraude, reglas de prueba) y ofrece un documento mecanografiado normal.
3. Nunca inventes calidad. Si la fuente tiene 40 glifos, di 40. Si el fallback dibujó la mitad de la página, dilo. Notifica los caracteres faltantes textualmente.
4. Pide volver a fotografiar antes de culpar a la herramienta: las fotos borrosas, con sombras, esquinas recortadas o líneas de cuadrícula cubiertas son la causa de fallo más común.
5. Mantén el directorio de trabajo (hw/): el usuario puede añadir caracteres más tarde y reconstruir la fuente.

Referencia de comandos

Comando	Propósito
hwpdf doctor	verificación de dependencias + fuentes del sistema
hwpdf template --chars "abc" / --text-file doc.txt -d DIR	PDF de hoja de práctica + metadatos
hwpdf scan IMG... [-d DIR] [--rotate 90] [--append]	hoja fotografiada → máscaras de glifos (append = fusiona con trabajo existente)
hwpdf extract-font --pdf in.pdf -d DIR	extraer fuentes incrustadas de un PDF (mejor caso: TTF completo)
hwpdf pdf-specimen --pdf in.pdf -d DIR [--font-name F]	cosechar glifos etiquetados de la capa de texto + ráster de un PDF
hwpdf rasterize --pdf in.pdf -d DIR [--dpi 300]	PDF escaneado → PNG de páginas
hwpdf segment IMG... [-d DIR] [--thresh N] [--deskew]	foto libre → manchas + hoja de contactos
hwpdf label -d DIR --order "ABC" / --pair "0=A 1=B"	mapear manchas a caracteres
hwpdf font -d DIR [--labels f] [--family NAME] [--weight -2..2] [--smooth 0..2] -o out.ttf	construir fuente
hwpdf coverage --font f --text-file doc.txt	qué caracteres faltan
`hwpdf render --font f --text-file doc.txt -o out.pdf [--size 12] [--leading 1.8] [--paper ruled] [--jitter 1] [--ink "#1a1c24"] [--fallback auto	none
hwpdf render --profile NOMBRE --text-file doc.txt -o out.pdf	PDF usando la fuente y valores predeterminados de un perfil guardado
hwpdf profile save/list/show/remove ...	congelar / inspeccionar el perfil de escritura a mano reutilizable (escribe PROMPT.md)
hwpdf preview --pdf out.pdf -d DIR [--dpi 150]	páginas PDF → PNG para revisión visual
hwpdf synth doctor / build / specimen / verify / charsets	motor de inferencia opcional: fuente de conjunto de caracteres completo a partir de un subconjunto escrito (ver la sección de Síntesis)
hwpdf selftest -d DIR [--messy]	prueba de humo sintética de extremo a extremo

Límites (menciónalos cuando sean relevantes)

• Un glifo por carácter: no hay cursiva conectada, ni variación natural entre apariciones, ni textura de presión/tinta. La fluctuación del espaciado se simula, las formas de los glifos no.
• CJK: la fuente contiene solo los caracteres escritos. 30 celdas por página; una carta de 300 caracteres necesita una hoja de práctica de 10 páginas. hwpdf synth build --charset common3500 es el atajo, pero el CJK inferido es un esqueleto sans-serif del sistema con la inclinación del usuario, no su trazo real.
• La capa de texto del PDF es texto real (buscable/copiable) en la fuente generada.
• Las fotos deben mostrar las cuatro esquinas negras cuadradas de la hoja de práctica.

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