macOS Vision OCR Local

Este skill te guía para convertir imágenes/PDFs proporcionados por el usuario a texto: utiliza el motor Vision nativo de macOS (el comando macocr) para realizar el reconocimiento localmente, sin subir ningún dato.

Verificación del entorno (imprescindible)

Antes de ejecutar cualquier comando OCR, primero realiza la siguiente comprobación. Si alguna falla, detente y responde según se indica:

[ "$(uname -s)" = "Darwin" ] && echo OK-macOS
command -v macocr || ls "$HOME/.local/bin/macocr"

Si uname no es Darwin: esta herramienta solo es compatible con macOS. No intentes instalarla ni compilarla, simplemente informa al usuario que este Skill solo está disponible en macOS y sugiere usar otra solución OCR.
Si macocr no existe: guía al usuario para que ejecute ./install.sh en el directorio del paquete (la compilación requiere Xcode Command Line Tools; en Apple Silicon sin entorno de compilación, retrocede automáticamente al binario precompilado incluido). Una vez instalado, ejecuta sh scripts/selftest.sh para una verificación integral de extremo a extremo, y solo continúa si pasa.

Una vez completadas la instalación y la autoverificación, no es necesario repetirlas en cada sesión.

Flujo estándar para ejecutar tareas

Sigue estos pasos para procesar las solicitudes OCR del usuario, sin saltarte ninguno:

Confirma el tipo de entrada. Si el usuario proporciona una imagen (png/jpg/jpeg/heic/tiff), ve directamente al paso 3. Si es un PDF escaneado (sin capa de texto), ve primero al paso 2 para convertirlo a imagen.
Convierte PDF a imagen (solo para PDFs escaneados). Usa el sips del sistema, comenzando con 144 ppp:
```
sips -s format png -s dpiHeight 144 -s dpiWidth 144 entrada.pdf --out /tmp/p1.png
```
Ten en cuenta que sips solo procesa una página; para PDFs de varias páginas, especifícalas una por una o, si tienes pymupdf, usa una matriz de 4x para renderizar (mejora notablemente en documentos con letra pequeña; consulta «Cómo usar con PDFs escaneados»).
Ejecuta el reconocimiento. El comando predeterminado cubre la mayoría de los casos:
```
macocr <ruta_de_imagen>            # Se pueden listar varias imágenes; las salidas se separan con ===
```
Agrega parámetros según el escenario (consulta la tabla de parámetros a continuación). El resultado es texto plano, ya ordenado por líneas visuales.
Entrega el resultado. Muestra el texto reconocido directamente al usuario; para resultados con tablas o números densos, advierte al usuario que debe verificar los números clave (consulta «Atención especial a datos tabulares»).

Referencia rápida de parámetros

Parámetro	Uso
`--fast`	Desactiva la corrección lingüística. Recomendado para tablas y números, evita que los números se «corrijan» a valores extraños
`--lang zh-Hans+en-US`	Predeterminado para mezcla chino-inglés. Para solo inglés, usa `en-US` para mayor velocidad; para chino tradicional, usa `zh-Hant`
`--rect x,y,w,h`	Reconoce solo un área rectangular (origen en esquina superior izquierda, en píxeles). Úsalo cuando solo quieras extraer una tabla de una imagen grande
`--upscale N`	Para imágenes pequeñas y borrosas (imágenes reenviadas con ancho <1000px, escaneos antiguos), primero amplía con Lanczos N veces (1.0–4.0). Solo pruébalo gradualmente 2 → 3 cuando la tasa de reconocimiento normal sea baja; ampliar imágenes nítidas y grandes sin necesidad puede causar trazos pegados
`--orientation up\|left\|right\|180`	Corrige la orientación manualmente si la foto está girada o al revés. Vision no corrige automáticamente según EXIF; las fotos tomadas de lado deben usar esto
`--list-langs`	Lista los idiomas de reconocimiento compatibles con la máquina (útil para verificar la instalación; la salida debe incluir zh-Hans)

Orden de actuación cuando la tasa de reconocimiento es baja

Intenta desde lo más simple a lo más complejo, sin saltar directamente a soluciones complicadas:

Busca la imagen original: las imágenes reenviadas por chat suelen tener muy baja resolución; pide al usuario el archivo original
--rect para delimitar el área objetivo, reduciendo ruido
--upscale 2 (para imágenes pequeñas y borrosas)
--fast (para escenarios con tablas y números)
Preprocesamiento de imagen (recorte + escala de grises + contraste automático + enfoque + binarización), ejemplo a continuación

from PIL import Image, ImageOps, ImageEnhance
im = Image.open("src.JPG")
im.crop((x0, y0, x1, y1)).resize((w*2, h*2), Image.LANCZOS)   # Recorte + ampliación
ImageOps.autocontrast(im.convert("L"))                         # Escala de grises + contraste automático
ImageEnhance.Sharpness(im).enhance(2.0)                        # Enfoque
im.convert("L").point(lambda p: 255 if p > 128 else 0)         # Binarización

Votación múltiple: para una misma tabla, ejecuta 2–3 preprocesamientos diferentes, toma las partes consistentes y revisa por separado los números inconsistentes. Verificación cruzada: si sumas filas/columnas enteras y coinciden, es confiable; si no, algún número está mal.

¿Por qué el «Texto en vivo» de la app Fotos parece más preciso que llamar a la API directamente?

Es el mismo motor Vision. La diferencia está en el pre y postprocesamiento, no en el modelo:

Orientación: «Fotos» corrige según EXIF antes de reconocer; la API directa procesa por defecto como .up → usa --orientation
Resolución: «Fotos» usa la imagen original a resolución completa; las que circulan en flujos de trabajo suelen ser vistas previas comprimidas → prioriza siempre el archivo original
Submuestreo implícito: NSImage genera según «puntos»; las capturas @2x/@3x y algunos HEIC pierden la mitad de los píxeles → esta herramienta recorre los rep para obtener el mapa de bits de mayor resolución
Texto vertical: «Texto en vivo» maneja texto vertical; la API directa lo fragmenta en líneas sueltas → esta herramienta detecta automáticamente y arbitra con confianza
Ventaja interactiva (no replicable completamente): «Texto en vivo» permite seleccionar partes, dando la sensación de «menos errores»; la línea de comandos muestra todo el texto de una vez, y cualquier error tipográfico resalta

Conclusión: mismo motor, el pipeline determina el límite.

Atención especial a datos tabulares

El OCR es más propenso a errores en tablas: puntos decimales que se pierden (. → ,), columnas adyacentes que se fusionan en una sola cadena, filas mezcladas. Los números clave deben verificarse dos veces: si hay un PDF original, extrae la capa de texto para comparar; si solo hay fotos, recurre a votación múltiple + validación lógica de filas y columnas.

Cuándo no usar esta herramienta

Escenario	Mejor alternativa
El modelo de IA usado ya soporta lectura de imágenes	Deja que la IA vea la imagen directamente, no pases por OCR
Se necesita reconstrucción compleja del diseño (múltiples columnas, fórmulas, estructura de tablas con líneas)	Servicios de análisis a nivel de diseño como MinerU (los datos subirán a la nube)
Convertir un lote completo de PDFs escaneados a texto y se puede usar la nube	Interfaces por lotes de servicios OCR en la nube

Regla: priorizar local, datos no se envían al exterior; si realmente se necesita mayor precisión, sube a la nube solo después de confirmar que los datos pueden enviarse.

Verificación y resolución de problemas

Autoverificación post-instalación: sh scripts/selftest.sh (usa la imagen de prueba incluida para una verificación integral; muestra PASS/FAIL)
La lista de idiomas no contiene zh-Hans: los datos de idioma del sistema están incompletos, es muy raro; comprueba si la versión de macOS es ≥ 13
La salida está vacía o completamente errónea: primero confirma que la imagen sea legible (sips -g pixelWidth -g pixelHeight imagen), luego sigue el «Orden de actuación cuando la tasa de reconocimiento es baja» paso a paso

Requisitos del sistema

macOS 13+ (automaticallyDetectsLanguage requiere 13.0)
La compilación requiere Xcode Command Line Tools (xcode-select --install); o usa el binario precompilado incluido para Apple Silicon (scripts/macocr-arm64, firma ad-hoc)

Descripción de archivos en el paquete

Archivo	Uso	Cuándo es necesario
`install.sh`	Instala macocr (prioriza compilación, retrocede a precompilado)	Cuando la verificación del entorno detecta que macocr no existe
`scripts/selftest.sh` + `scripts/selftest.png`	Autoverificación integral (script + imagen de prueba incluida)	Validación post-instalación; cuando se detectan anomalías en el reconocimiento, ejecútalo primero para confirmar que la herramienta funciona correctamente
`scripts/vision_ocr.swift`	Código fuente (~200 líneas, auditable)	Cuando se necesita compilar uno mismo o auditar
`scripts/macocr-arm64`	Binario precompilado para Apple Silicon	En máquinas Apple Silicon sin swiftc; `install.sh` lo usa automáticamente

GreenWich-art/agent-skills

¿Qué es agent-skills?

Preguntar en tu IA favorita

Documentación