jisui

Procesamiento Jisui (自炊)

Reglas para imágenes escaneadas → ZIP / CBZ / PDF. Aplica no solo a libros sino a cualquier cosa escaneada (revistas, documentos, apuntes, etc.). Este skill no decide el nombre ni la ubicación del archivo de salida. Sigue al llamante (el CLAUDE.md del proyecto o las instrucciones del usuario); si ninguno lo dice, pregúntale al usuario.

Rutas proporcionadas

Argumentos: $ARGUMENTS

Lee primero las rutas proporcionadas (carpetas de escaneos, archivos de imagen o PDFs); si no se proporcionó ninguna, usa el directorio actual (.) — a menos que la solicitud misma nombre los escaneos. Luego: lista cada una recursivamente (subcarpetas, nombres de archivo, extensiones, conteos, dimensiones de imagen/DPI de algunos archivos), y observa algunas imágenes (primera, última y un par intermedias). A partir de eso, deduce la estructura — por ejemplo, un volumen por carpeta o varios volúmenes en una carpeta, qué archivos parecen ser la portada / contraportada / sobrecubierta / páginas del cuerpo, divisiones de páginas pares/impares, duplicados o archivos extraños — y propón un plan concreto de jisui (volúmenes, orden de páginas, fuentes de portada/contraportada/sobrecubierta, opciones sugeridas). Integra ese plan en las preguntas siguientes para que el usuario lo confirme o lo corrija en un solo paso.

Antes de comenzar

Pregunta al usuario (una llamada AskUserQuestion) por lo que el llamante no haya decidido ya:

• Formato de salida: ZIP / CBZ / PDF.
• Portada (cubierta frontal): colocación — primera página de la salida / no usada / archivo separado junto a la salida; y fuente — un archivo que el usuario proporcione / el primer escaneo / la parte frontal de la sobrecubierta / una imagen encontrada en la web.
• Contraportada: colocación — última página antes de la sobrecubierta / no usada / archivo separado junto a la salida; y fuente — un archivo que el usuario proporcione / el último escaneo (antes de la sobrecubierta, si la sobrecubierta es el último escaneo) / la parte trasera de la sobrecubierta / una imagen encontrada en la web.
• Sobrecubierta (escaneo o imagen de la sobrecubierta): las mismas dos preguntas; fuente — un archivo que el usuario proporcione / el último escaneo / una imagen encontrada en la web.

Una fuente proveniente de los escaneos se extrae de las páginas del cuerpo incluso si su colocación es "no usada" (no se procesa ni se conserva). Si no hay fuente de portada/contraportada/sobrecubierta, cada escaneo es una página del cuerpo. Para una imagen web, busca la edición que coincida con los escaneos (título, editorial, ISBN si es visible), descarga la versión más grande en el área temporal, muéstrasela al usuario y obtén su confirmación antes de usarla.

Procesamiento de páginas

0. Portada / contraportada / sobrecubierta (según lo decidido en "Antes de comenzar"). Todos los pasos siguientes aplican solo a las páginas del cuerpo.
   • Portada: se usa tal cual, sin procesar (aún en color, dimensiones sin cambios). Incluida → la primera página. Desde la parte frontal de la sobrecubierta: mira la sobrecubierta en posición vertical y encuentra las columnas del panel frontal X0–X1 — entre el pliegue del lomo y el pliegue de la solapa frontal (a la derecha del lomo para un libro encuadernado a la izquierda, a la izquierda para uno encuadernado a la derecha / de escritura vertical) — y recorta solo eso, con toda la altura (aún en color).
   • Contraportada: igual que la portada. Incluida → la página después de la última página del cuerpo (antes de la sobrecubierta). Desde la parte trasera de la sobrecubierta: el panel trasero, entre el pliegue de la solapa trasera y el pliegue del lomo (al otro lado del lomo respecto al panel frontal).
   • Sobrecubierta: solo gírala a la orientación correcta (aún en color, dimensiones sin cambios). Gira con precisión de píxeles; si las dimensiones del JPEG no permiten una rotación sin pérdida, usa PNG. Incluida → la última página; en el PDF, haz que solo esa página tenga tamaño real (según su DPI).
   • Archivo separado: guárdalo junto a la salida como <nombre de salida>-portada.<ext> / <nombre de salida>-contraportada.<ext> / <nombre de salida>-sobrecubierta.png, sin cambios respecto a lo que escribió el script.
1. Corrección de inclinación: para cada página, detecta la inclinación dentro de ±3° en pasos de 0.1° y corrígela.
   • Detecta y corrige la rotación (las líneas están inclinadas) y el cizallamiento (las líneas están niveladas pero solo los bordes izquierdo/derecho del bloque de texto están sesgados — esto ocurre cuando el papel se desliza lateralmente en un alimentador de hojas) por separado.
   • Las páginas con poco texto (portadillas, medias portadas, páginas cortas) no se pueden verificar de manera confiable para detectar inclinación, así que no las corrijas.
2. Minimización de márgenes: recorta para dejar solo 2 mm (24 píxeles a 300 dpi) de margen en cada lado del bloque de texto.
   • No incluyas sombras del escáner, líneas finas en los bordes de la página ni pequeñas manchas en el bloque de texto. Blanquea sombras y líneas en los bordes de la página.
3. Dimensiones uniformes: todas las páginas del cuerpo de un volumen obtienen las mismas dimensiones.
   • Decide un tamaño de recuadro de recorte por volumen, y posiciona por página para ajustarse al bloque de texto de esa página (la posición del bloque de texto se desplaza unos mm de un escaneo a otro). Las páginas con poco texto (portadillas, aperturas de capítulo, páginas cortas) usan la posición de una página cercana del mismo lado (par/impar), para que conserven su diseño original.
   • Las páginas que desbordan el recuadro se escalan ligeramente para que quepan.
   • Solo cuando se indique: saca las páginas de imagen como ilustraciones a página completa y portadillas del recuadro del cuerpo y dales un recuadro de página de imagen compartido, con la misma altura que el cuerpo pero más ancho (--picture). Esto permite márgenes más pequeños en las páginas del cuerpo.
4. Páginas en blanco: no las omitas; consérvalas como páginas en blanco.
5. Conserva cada página: no elimines ninguna página, incluidos los anuncios.
6. B&N: binariza a blanco y negro solo cuando se indique (con pérdida, así que no por defecto).
   • Binariza el texto, pero no binarices las áreas de imagen como fotos e ilustraciones; conviértelas a escala de grises.
   • Usa un umbral de 200 (0–255; los píxeles más oscuros que esto se vuelven negros) como línea base. La selección automática (Otsu, alrededor de 160) hacía el texto demasiado tenue.
   • Después del trabajo, informa el umbral usado y pregúntale al usuario si ese valor le parece correcto.
7. OCR: solo cuando se indique, añade una capa de texto OCR al PDF (ocrmypdf -j 2 -l jpn+eng --output-type pdf, imágenes sin cambios; ajusta -l al idioma del contenido, ej. kor+eng para coreano). Apple OCR tiende a agotar el tiempo de espera en recuentos de páginas grandes, así que divide con qpdf en fragmentos de 50 páginas, aplica OCR a cada uno, rehaz solo los que fallaron y luego fusiona.
   • Cuando se usa repetidamente, Apple OCR (LiveText) puede comenzar a devolver silenciosamente capas de texto vacías en medio del proceso, sin ningún error. Antes de fusionar, verifica cada página con pdftotext para confirmar que se extrajo texto; para los fragmentos con páginas del cuerpo vacías, espera un poco y rehazlos. Si eso no lo soluciona, reinicia el Mac.
8. Marcadores (indexación): solo cuando se indique, añade marcadores de tabla de contenidos (esquema) al PDF.
   • Lee las páginas de la tabla de contenidos y añade partes/capítulos/secciones en la misma jerarquía que la TOC, con los encabezados exactamente como se imprimen (incluye el prólogo, epílogo, comentario, notas, índice, etc. si están en la TOC). Pon una entrada para la propia tabla de contenidos primero, apuntando a la página de la TOC. Las partes/capítulos sin número de página en la TOC apuntan a su portadilla o a la página con su encabezado.
   • Determina la correspondencia entre los números de página impresos y las páginas del PDF leyendo números de página en varios lugares. Puede cambiar (ej. debido a frontispicios), así que verifica que el encabezado realmente aparezca en la página de destino para cada entrada de nivel superior y algunas de nivel inferior.
   • Escríbelo con pikepdf usando el mismo procedimiento que la edición de metadatos (sin recompresión de imágenes), y establece /PageMode /UseOutlines. Vuelve a leerlo después de escribirlo para verificar. Si no hay tabla de contenidos, no añadas marcadores; informa al usuario.

Ejecución

uv run <carpeta de este skill>/scripts/jisui.py <carpeta de imágenes> <carpeta de salida> [--threshold N | --gray | --color] [--no-deskew 1,12,...] [--picture 3,24,...] [--dpi N] [--cover first|ARCHIVO|jacket:X0-X1] [--back last|ARCHIVO|jacket:X0-X1] [--jacket last|ARCHIVO] [--jacket-rotate 0|90|180|270] realiza el paso 0 (--cover: copia el primer escaneo o ARCHIVO tal cual como 0000.<ext>, o con jacket:X0-X1 recorta esas columnas de la sobrecubierta en posición vertical como 0000.png (necesita --jacket); --back: lo mismo para la contraportada, desde el último escaneo (tomado antes del de la sobrecubierta), escrito justo después de las páginas del cuerpo como NNNN.<ext> (.png cuando se recorta de la sobrecubierta); --jacket: toma el último escaneo o ARCHIVO, lo gira en el sentido de las agujas del reloj según --jacket-rotate, y lo escribe como el último NNNN.png; pásalos siempre que haya una fuente de portada/contraportada/sobrecubierta, sea cual sea su colocación), los pasos 1–3, y el paso 6 (B&N) (con --gray, sin B&N y las páginas permanecen en escala de grises; con --color, las páginas permanecen en color), y escribe las imágenes de las páginas (PNG) y un informe (<carpeta de salida>-report.json: umbral, dimensiones del recuadro, páginas en blanco/redimensionadas y páginas con áreas en escala de grises). Los números de página son los números de salida (NNNN.png; la portada es 0, la primera página del cuerpo es 1). Pasa números de página a los que no se debe corregir la inclinación a --no-deskew, y números de página de imagen a --picture (el informe también da las dimensiones del recuadro de página de imagen; la altura es la misma que la del cuerpo, así que un --imgsize es suficiente). Coloca la salida de trabajo en el área temporal; nunca escribas en los escaneos originales ni en las carpetas del usuario.

• No asumas un tamaño de recorte. Por defecto minimiza los márgenes y hace que las páginas del cuerpo tengan tamaño uniforme. La resolución para la conversión mm↔px proviene de la etiqueta DPI de la imagen; si no hay etiqueta o está por debajo de 150 (un marcador de posición como 72), asume 300 dpi (de lo contrario, pasa --dpi N).
• Al hacer un PDF, establece el tamaño con img2pdf --imgsize x<altura del recuadro en mm> (los PNG de salida no llevan información de DPI). Construye la página de portada/sobrecubierta por separado sin --imgsize (tamaño real según su etiqueta DPI) y añádela con pikepdf.
• Después del procesamiento, observa algunas páginas como imágenes (inclinación, recorte, binarización) y verifica que las páginas en blanco/redimensionadas en el informe tengan sentido antes de producir la salida.

Salida

Antes de empaquetar, extrae del conjunto de páginas las imágenes de portada/contraportada/sobrecubierta cuya colocación sea "no usada" o "archivo separado" (y guarda las separadas como en el paso 0).

• ZIP: coloca las imágenes de página procesadas en el nivel superior del archivo, con nombres de archivo en orden de página. No recompres las imágenes (zip -0). No incluyas .DS_Store ni similares.
• CBZ: igual que ZIP, con la extensión .cbz. Los lectores usan la primera imagen como miniatura. Añade ComicInfo.xml solo mediante edición de metadatos.
• PDF: coloca las mismas imágenes que el ZIP sin recompresión (img2pdf). El OCR sigue el paso 7, los marcadores el paso 8.
• Nombres de modo: determinados por las páginas del cuerpo — color / grayscale / bw (una portada en color por sí sola no lo convierte en color). Añade +ocr si hay capa OCR y +toc si hay marcadores (nunca en ZIP/CBZ). Si ponerlo en el nombre del archivo depende del llamante.

Edición de metadatos (Título / Autor)

Toma los valores del llamante (catálogo, usuario). Nunca adivines ni los completes.

• Solo los campos Título y Autor. No pongas traductores en Autor.
• PDF: escribe Título y Autor tanto en el diccionario Info como en XMP, sin recompresión de páginas (pikepdf).
• EPUB: cambia solo el dc:title principal del OPF y cada dc:creator (y los metadatos dcterms:* / file-as que los refines); no toques nada más. Reescribe el ZIP manteniendo el orden de entradas y métodos de compresión, con mimetype primero y sin comprimir. Las entradas de subtítulo / título largo de Standard Ebooks pueden dejarse como están.
• CBZ: escribe ComicInfo.xml (<Title>, <Writer>) al final del archivo, almacenado (zip -0), manteniendo las entradas de imagen sin cambios. Para libros de derecha a izquierda (texto vertical japonés, manga), añade también <Manga>YesAndRightToLeft</Manga> si el usuario lo confirma.
• ZIP (imágenes escaneadas): no tiene metadatos, así que omítelo.
• Trabaja en una copia en el área temporal, verifícala (conteo de páginas / entradas sin cambios, los metadatos leídos coinciden con los valores proporcionados) y luego reemplaza el archivo original. Reemplazar sobrescribe el archivo del usuario, así que confirma primero a menos que el llamante lo haya aprobado.