Estudio de escritura a mano personal
Convierte fotos reales de escritura a mano en una biblioteca de glifos personales reutilizable y renderiza de forma programática documentos manuscritos realistas de varias páginas y PDFs, sin artefactos de fuentes generadas por IA.
Resumen
Esta habilidad orquesta un pipeline de escritura a mano 100% programático de bucle cerrado:
- Inicialización del workspace: Crea un workspace personal local (fuera de git mediante
.gitignore). - Verificación previa de cobertura: Escanea un borrador objetivo (
pages.jsono texto plano) contraglyphs/manifest.jsony produce la lista mínima exacta (o una hoja de escritura A4 imprimible) de caracteres faltantes. - Preprocesado de fotos e ingesta guiada: Decodifica fotos
.DNG/.HEIC/.JPG/.PNGcon normalización de iluminación (eliminando sombras y traspaso de tinta del papel), segmenta caracteres mediante agrupación de componentes conectados guiada por filas (multiplataforma), y ejecuta una auditoría visual obligatoria con hoja de contacto antes de confirmar los glifos. - Renderizado realista de páginas y PDF: Compone páginas en papel en blanco o plantillas personalizadas usando normalización del grosor de trazo con sobremuestreo 2× (consistencia de bolígrafo de gel de ~0.6 mm), deduplicación multi-variante por ventana deslizante, línea base ondulada natural, tablas/ecuaciones dibujadas a mano temblorosas, y verificación del 100% de cobertura de caracteres.
Dependencias
- Ejecución:
uv(recomendado) o Python 3.10+ conpillowynumpy.scripts/handwrite.pyincluye metadatos en línea PEP 723, por lo queuv run scripts/handwrite.py ...aprovisiona automáticamente las dependencias en macOS, Linux y Windows. - Opcional:
ffmpeg(opillow-heif) para decodificar fotos.HEIC.swiftde macOS solo si se usa el extractor OCR opcional de Apple Vision (ver references/macos_vision_ocr.md).
Inicio rápido
# 1. Inicializar un workspace personal (con el ejemplo opcional de informe de laboratorio USST)
uv run scripts/handwrite.py init --workspace ./mi_letra --with-example
# 2. Verificar qué caracteres de un borrador faltan en tu biblioteca de glifos
uv run scripts/handwrite.py check \
--content ./mi_letra/content/sample_pages.json \
--manifest ./mi_letra/glyphs/manifest.json \
--output ./mi_letra/coverage_report.json \
--grid-dir ./mi_letra/missing_grid
# 3. Preprocesar una foto de tu hoja manuscrita (DNG / HEIC / JPG / PNG)
uv run scripts/handwrite.py preprocess \
--input ./mi_letra/photos/hoja1.jpg \
--output-dir ./mi_letra/preprocessed
# 4. Segmentación en seco y auditoría visual antes de confirmar en manifest.json
uv run scripts/handwrite.py ingest \
--input ./mi_letra/preprocessed/hoja1_ink.png \
--rows-spec ./mi_letra/content/rows_spec.json \
--manifest ./mi_letra/glyphs/manifest.json \
--contact-dir ./mi_letra/contact_sheets \
--dry-run
# 5. Después de inspeccionar visualmente la superposición de depuración y la hoja de contacto, confirmar los glifos (omitir --dry-run)
uv run scripts/handwrite.py ingest \
--input ./mi_letra/preprocessed/hoja1_ink.png \
--rows-spec ./mi_letra/content/rows_spec.json \
--manifest ./mi_letra/glyphs/manifest.json \
--contact-dir ./mi_letra/contact_sheets
# 6. Renderizar PNGs manuscritos realistas de varias páginas + PDF combinado
uv run scripts/handwrite.py render \
--content ./mi_letra/content/sample_pages.json \
--manifest ./mi_letra/glyphs/manifest.json \
--assets-dir ./mi_letra \
--output-dir ./mi_letra/output \
--pdf-name reporte.pdf
Flujo de trabajo estándar del agente
Etapa 1: Verificación previa de cobertura antes de pedir al usuario que escriba
- Convierte el borrador del usuario en un
pages.jsonestructurado (ver references/page_schema.md) o pasa un borrador.txtdirectamente acheck. - Ejecuta
uv run scripts/handwrite.py check ...para calcular los caracteres faltantes exactos ordenados por frecuencia. - Pide al usuario que escriba a mano solo los caracteres faltantes en papel blanco con un bolígrafo de gel negro (se recomienda escribir 2–4 variantes para caracteres de alta frecuencia, dígitos
0–9y signos de puntuación para que las páginas renderizadas se vean naturales), y que tome una foto plana y uniformemente iluminada.
Etapa 2: Preprocesado, segmentación guiada por filas y auditoría visual obligatoria
- Ejecuta
preprocesspara decodificar.DNG/.HEIC/.JPG/.PNGen<base>_clean.pngy<base>_ink.png(RGBA transparente). Usa--crop x0,y0,x1,y1(normalizado0.0–1.0) si la foto incluye bordes de escritorio o sombras. - Crea un
rows_spec.jsonque enumere los caracteres escritos en cada fila (usa"□"o"SKIP"para ignorar errores tachados o manchas sueltas; verexamples/usst_lab_report/sample_rows_spec.json). - Ejecuta siempre
ingestcon--dry-runprimero. Inspecciona tanto<base>_debug.png(cajas delimitadoras sobre la tinta) como<base>_sheet.png(hoja de contacto de un solo carácter etiquetado) usando tu herramienta de lectura de archivos/visión. - Confirma que no haya desalineaciones, manchas de tinta o trazos recortados. Solo entonces vuelve a ejecutar
ingestsin--dry-runpara confirmar los glifos enmanifest.jsonusando nombres de archivo seguros para mayúsculas/minúsculas multiplataforma (upper_<X>_k.png,lower_<x>_k.png,sym_u<4hex>_k.png,<ch>_k.png).
Etapa 3: Renderizado y control de calidad página por página
- Ejecuta
render. El script aplica una verificación previa del 100% de cobertura de caracteres (verify_all_chars_covered) y falla rápidamente si falta algún carácter. - Inspecciona visualmente cada
page_<N>.pngrenderizado:- Verifica el porcentaje de llenado vertical en la salida estándar; si aparece
[WARNING] ... overflowed bottom margin, reduce--font-size(rango típico28–34), ajustaline_h_ratio(1.38–1.50), o divide el contenido en una página de continuación adicional. - Verifica que los campos de la portada se alineen limpiamente sobre las líneas, que las tablas no recorten el texto de las celdas y que los grosores de trazo sean uniformes.
- Verifica el porcentaje de llenado vertical en la salida estándar; si aparece
Referencia de scripts de utilidad
| Subcomando | Descripción | Opciones clave |
|---|---|---|
init | Crear un workspace personal limpio | --workspace, --with-example |
check | Calcular la cobertura de glifos y cuadrícula A4 de caracteres faltantes opcional | --content, --manifest, --output, --grid-dir |
preprocess | Decodificar foto y extraer tinta RGBA sin sombras | --input, --output-dir, --crop, --hi, --lo |
ingest | Segmentación guiada por filas en glifos RGBA + hojas de auditoría | --input, --rows-spec, --manifest, --contact-dir, --dry-run, --source-id |
contact-sheet | Generar una hoja de contacto etiquetada desde manifest.json | --manifest, --output, --chars |
render | Renderizar pages.json en plantillas y exportar PDF | --content, --manifest, --output-dir, --assets-dir, --pdf-name, --font-size, --messiness, --seed |
Errores comunes
- Omitir la auditoría visual con
--dry-runduranteingest: Un solo borrón tachado o un par de trazos adyacentes fusionados puede desplazar las etiquetas de una fila completa. Siempre inspecciona<base>_debug.pngy<base>_sheet.pngantes de confirmar. - Usar generación de imágenes IA o fuentes del sistema como respaldo: Nunca generes páginas manuscritas con modelos de difusión ni sustituyas fuentes del sistema por caracteres faltantes. Siempre captura los glifos faltantes reales mediante
check→ingest. - Colisiones de sistema de archivos que no distingue mayúsculas/minúsculas: En macOS (APFS) y Windows (NTFS),
A_0.pngya_0.pngse sobrescriben entre sí. Usa siemprehandwrite.py(que imponeupper_A_0.png/lower_a_0.png/sym_uXXXX_0.png). - Usar
sipsde macOS dentro de sandboxes:sipspuede generar imágenes negras sólidas en entornos sandboxeados.handwrite.py preprocessmaneja.DNGen Python puro y.HEICmediantepillow-heifoffmpeg. - Confirmar escritura a mano personal en Git: Mantén los workspaces personales (
glyphs/,photos/,output/) fuera del repositorio de la habilidad o dentro de rutas ignoradas por git.