Plasmoid77/photo-to-pdf

Foto a PDF

El objetivo es obtener páginas individuales en el orden correcto, con bordes ajustados y trazos conservados en los extremos. Trabaja localmente con fotografías. No se requiere un plugin o MCP especial para este proceso.

Método probado

1. Inspecciona las fuentes. Ten en cuenta EXIF. Verifica el orden por nombre/hora y contenido; la hora de captura por sí sola no demuestra la secuencia. Encuentra la portada, pliegos, duplicados vueltos a fotografiar, hojas en blanco. El brillo no permite distinguir de forma fiable un dibujo pálido de una página vacía. Si el papel está sobre un fondo claro (mesa blanca, hoja, pantalla cercana) y los contornos no se detectan, pide que se vuelva a fotografiar sobre una superficie mate oscura.
2. Etiqueta las hojas. Para hojas individuales (documentos, A4, incluido apaisado) ejecuta prepare --layout pages. auto divide un contorno ancho solo si hay indicios de pliegue (sombra de lomo o línea de pliegue), pero en hojas inusuales puede equivocarse. scan.py prepare crea un manifest preliminar y contact sheets con contornos. El detector encuentra el papel como una zona clara y poco saturada, atrae los bordes a la transición nítida «papel → fondo oscuro» y busca el pliegue para el pliego. El pliegue es el lugar donde se quiebran las líneas de pauta. La sombra del lomo cae sobre una página, por lo que en una sombra profunda el pliegue se sitúa en la base del cambio de brillo del lado oscuro. En cuadernos de referencia el error mediano del pliegue es de 2–3 px. Sigue siendo una hipótesis. Las páginas con flags no vacíos (gutter-*, partner-mismatch, touches-frame, aspect-outlier, one-side-unruled, margin-ink, contour, full-frame-fallback, duplicate) márcalas manualmente primero. Las demás verifícalas con la foto: el detector puede tomar un monitor, un ticket o una mitad de pliego. scan.py inspect proporciona recortes grandes de cada esquina con divisiones en fracciones del cuadro – con ellos corrige las esquinas en el manifest. Cada hoja recibe sus cuatro esquinas TL, TR, BR, BL en coordenadas después de la rotación EXIF.
3. Corrige la perspectiva. Por defecto, una matriz proyectiva por página. No muevas filas/columnas individuales siguiendo el borde encontrado automáticamente: la cuadrícula, el texto, los dedos y las sombras pueden confundirse con el borde y crear ondas en toda la página. Para una corrección completa explícitamente solicitada de una página de libro curvada se necesita un algoritmo probado aparte y una verificación adicional de la geometría.
4. Ajusta los bordes. Se prefiere un recorte ajustado, no un margen grande uniforme en todas partes. bleed_px por defecto es 0. Añade un pequeño margen individual solo si realmente queda escritura más allá de la recta entre esquinas o un borde curvado con información. Revisa las puntas de las letras, los puntos sobre la eñe, las fechas a la izquierda, el texto junto al pliegue y las líneas inferiores de los dibujos. La línea inferior a menudo llega hasta el borde mismo – allí el límite se sitúa en la mediana del borde, no ajustado. Si entre el borde ajustado y el extremo del papel hay trazos de pluma, prepare desplaza el borde hacia ellos (campo margin_ink, no más del 4 % del ancho). El lápiz no se protege así, por lo que las fechas y firmas a lápiz cerca del borde revísalas visualmente. El borde curvado se aproxima con una recta, por lo que las esquinas de una hoja curvada pueden quedar ligeramente fuera del límite. El recorte adicional del PDF se hace con el comando crop, sin volver a estirar ni re-comprimir en JPEG.
5. Conserva los trazos pálidos. Se permite una corrección suave de la iluminación; una binarización agresiva puede borrar el lápiz. Para portadas, fotografías y colores importantes desactiva enhance. No dibujes letras, esquemas o partes faltantes del cuadro con un modelo generativo. Añade OCR solo cuando sea necesario o se solicite.
6. Revisa el PDF final. Usa el skill PDF disponible para crear/verificar, incluyendo el marcador de operación que este proporciona. review renderiza todas las páginas, hace contact sheets y enumera las páginas con fondo o escritura cerca del borde (edges.json). compare muestra cada página de la foto con un margen del 4 % y un marco rojo de recorte – se ve qué queda fuera. Revisa todo el documento, no solo las primeras páginas. Un esquema económico para grandes volúmenes: ejecuta compare en todas las páginas, repártelas en lotes de no más de 16 a agentes paralelos en un modelo barato con imágenes (en Claude Code — Sonnet, en Codex — gpt-5.6-luna) con la tarea de references/screening.md sin cambios. Abre tú solo las páginas donde el revisor indique defect y las páginas con banderas de prepare; corrige solo lo confirmado. En 32 páginas de borrador con 8 errores de esquina conocidos > 3 %, este esquema encontró los 8 (Sonnet — 7, banderas — la restante) con 4 falsas alarmas; Haiku encontró 4 y solo añadió falsas alarmas, por lo que Haiku solo no es suficiente. En el segundo cuaderno (32 páginas, tarea no ajustada) Sonnet y gpt-5.6-luna encontraron franjas de fondo visibles sin falsas alarmas, pero omitieron páginas con error de esquina del 1,5–2 %; gpt-6.1-terra señaló casi todo, incluyendo 12 de 19 páginas limpias – con él no hay ahorro. El esquema se probó en un solo cuaderno y la tarea se redactó sobre las mismas páginas: para documentos importantes o dudas, revisa tú mismo todas las páginas. Los números de página en las respuestas de los revisores verifican además el orden. Tras un recorte, vuelve a comprobar las páginas afectadas; tras cambiar el algoritmo geométrico, revisa todo el documento. El número de páginas y un config correcto no sustituyen la inspección visual.

Para esta digitalización, el usuario prefiere eliminar las hojas vacías confirmadas; la solicitud explícita de conservarlas tiene prioridad. Los duplicados se excluyen tras inspección visual, no por similitud de pauta/caligrafía. Conserva la portada si no hay otra instrucción. Lee el pliego de izquierda a derecha cuando la fuente esté así dispuesta.

Comandos

La ruta al script se determina relativa a este skill. Esquema y parámetros: references/commands.md. No traslades esquinas, rutas, números de página ni proporciones del cuaderno anterior.

python3 <skill>/scripts/scan.py prepare <fotos> --work <trabajo> --layout auto
python3 <skill>/scripts/scan.py inspect <trabajo>/manifest.json --work <trabajo>/inspect --ids 0006-L,0006-R
python3 <skill>/scripts/scan.py build <trabajo>/manifest.json --output <trabajo>/draft.pdf
python3 <skill>/scripts/scan.py measure <trabajo>/draft-pages --work <trabajo>/measure
python3 <skill>/scripts/scan.py review <trabajo>/draft.pdf --work <trabajo>/review
python3 <skill>/scripts/scan.py compare <trabajo>/draft.scan.json --work <trabajo>/compare

Dependencias: Pillow, NumPy, OpenCV, ReportLab para fotos; pypdfium2 para crop; Poppler pdftoppm para review y measure sobre PDF. Las importaciones están separadas por comandos. Comprueba los intérpretes/entornos disponibles; si es necesario, usa un venv aparte sin modificar el Python global. Si OpenCV/NumPy están instalados como paquetes del sistema, crea el venv sobre el mismo intérprete con --system-site-packages (python3 -m venv; uv venv toma por defecto su propio Python y no verá el cv2 del sistema). No se asume que la red sea obligatoria. No incrustes rutas de la caché de una máquina concreta en el skill.

Proporciones y tamaño de la hoja. aspect: null se estima a partir de los lados del contorno y bajo ángulo puede estar desplazado un 1–2 %. Para papel cuadriculado, genera un borrador y ejecuta measure. Encuentra el paso de la cuadrícula, calcula el tamaño físico de las páginas y propone un único aspect para todo el cuaderno y un --width-mm. Toma los valores de la salida, no del cuaderno anterior. Con el mismo --width-mm todas las páginas del PDF tienen un tamaño físico idéntico. De lo contrario, el tamaño se calcula a partir de los píxeles y --dpi y varía según la distancia de captura.

build requiere reviewed: true en las páginas incluidas: es una marca de verificación del etiquetado por parte del agente, no una consulta adicional al usuario. No pidas permiso para el procesamiento rutinario de las fotos ya entregadas.

Regresiones del detector. El manifest verificado de un cuaderno es la referencia. Tras modificar scan.py, ejecuta prepare sobre las mismas fotos y eval <manifest nuevo> --reference <referencia>. El comando mostrará el error de esquinas en % del ancho de la página, la proporción de páginas marcadas y los errores «silenciosos» – páginas no marcadas con un error mayor que --tolerance (por defecto 3 %). Código de retorno 1 si hay más errores silenciosos que --max-silent. No guardes referencias con fotos personales en el repositorio del skill.

Finalización

• No modifiques las fotos originales. Reemplaza el PDF existente solo tras verificar la nueva versión. Conserva el etiquetado y los parámetros para correcciones puntuales.
• Al rehacer, primero comprueba la vigencia del archivo. No permitas la recompresión JPEG acumulativa.
• Informa del resultado, el número de páginas y las limitaciones significativas de las fuentes. Si parte de la escritura ya está fuera del encuadre, indícalo en lugar de afirmar que se ha restaurado.
• El skill ahorra preparación y reescritura de código; no promete reconocimiento de bordes totalmente automático ni eliminación de la inspección visual.