macOS Vision OCR Local

Esta skill orienta você a converter imagens/PDFs fornecidos pelo usuário em texto: usando o mecanismo Vision nativo do macOS (o comando macocr) para reconhecimento local, sem enviar nenhum dado.

Verificação de Ambiente (Obrigatória)

Antes de executar qualquer comando de OCR, execute a verificação a seguir. Se qualquer condição não for atendida, pare e responda conforme indicado:

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

uname não retorna Darwin: esta ferramenta funciona apenas no macOS. Não tente instalar ou compilar; informe diretamente ao usuário que esta skill só está disponível no macOS e sugira alternativas de OCR.
macocr não encontrado: oriente o usuário a executar ./install.sh no diretório do pacote (a compilação requer Xcode Command Line Tools; no Apple Silicon, sem ambiente de compilação, o instalador cai automaticamente no binário pré-compilado incluso). Após a instalação, execute sh scripts/selftest.sh para um teste de ponta a ponta. Só prossiga após aprovação.

Após a instalação e autoteste, não é necessário repeti-los a cada sessão.

Fluxo Padrão de Execução de Tarefas

Siga estas etapas para processar solicitações de OCR do usuário, sem pular nenhuma:

Identificar o tipo de entrada. Se o usuário fornecer uma imagem (png/jpg/jpeg/heic/tiff), vá direto para o passo 3; se for um PDF escaneado (sem camada de texto), primeiro vá para o passo 2 para converter em imagem.
Converter PDF para imagem (apenas para PDFs escaneados). Use o sips nativo do sistema, com resolução inicial de 144 dpi:
```
sips -s format png -s dpiHeight 144 -s dpiWidth 144 entrada.pdf --out /tmp/p1.png
```
Observe que sips processa apenas uma página; para PDFs com várias páginas, é necessário especificar cada página ou usar o pymupdf com matriz 4x para renderizar (resultados significativamente melhores em slides com fontes pequenas, consulte "Como usar com PDF escaneado").
Executar o reconhecimento. O comando padrão cobre a maioria dos cenários:
```
macocr <caminho_da_imagem>            # Para múltiplas imagens, liste-as sequencialmente; a saída é separada por ===
```
Adicione parâmetros conforme o cenário (tabela de parâmetros abaixo). O resultado é texto puro, já ordenado por linhas visuais.
Entregar o resultado. Exiba o texto reconhecido diretamente ao usuário; para resultados com tabelas ou números densos, alerte o usuário de que os números críticos devem ser verificados novamente (consulte "Atenção especial para dados tabulares").

Referência Rápida de Parâmetros

Parâmetro	Uso
`--fast`	Desativa a correção de idioma. Recomendado para tabelas e números, para evitar que números sejam "corrigidos" para valores estranhos
`--lang zh-Hans+en-US`	Padrão para texto misto chinês/inglês. Defina `en-US` para apenas inglês (mais rápido); `zh-Hant` para chinês tradicional
`--rect x,y,w,h`	Reconhecer apenas uma região retangular (origem no canto superior esquerdo, em pixels). Use quando quiser extrair apenas uma tabela de uma imagem grande
`--upscale N`	Amplia imagens pequenas e borradas (largura < 1000px, imagens encaminhadas, digitalizações antigas) usando Lanczos por um fator N (1.0–4.0). Use apenas quando a precisão do modo normal for baixa, testando progressivamente 2 → 3; ampliar imagens grandes e nítidas cegamente pode causar fusão de traços
`--orientation up\|left\|right\|180`	Corrige rotação/inversão manualmente. O Vision não corrige automaticamente com base no EXIF; fotos laterais devem usar este parâmetro
`--list-langs`	Lista os idiomas de reconhecimento suportados pela máquina (use para verificar a instalação; a saída deve conter zh-Hans)

Ordem de Ação para Baixa Precisão

Tente do mais simples ao mais complexo, sem pular para soluções complicadas logo de início:

Obter a imagem original: imagens encaminhadas em chat têm precisão muito baixa; peça ao usuário o arquivo original
Usar --rect para delimitar a área alvo, reduzindo ruído
--upscale 2 (para imagens pequenas e borradas)
--fast (para tabelas e números)
Pré-processamento de imagem (recorte + escala de cinza + contraste automático + nitidez + binarização), exemplo abaixo

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 + ampliação
ImageOps.autocontrast(im.convert("L"))                         # escala de cinza + contraste automático
ImageEnhance.Sharpness(im).enhance(2.0)                        # nitidez
im.convert("L").point(lambda p: 255 if p > 128 else 0)         # binarização

Votação entre versões: para uma mesma tabela, gere 2–3 pré-processamentos diferentes, mantenha as partes consistentes e verifique individualmente os números divergentes. Validação cruzada: somar linhas/colunas completas e conferir; se bater, é provável que esteja correto; se não bater, algum número está errado.

Por que o Texto Vivo do aplicativo Fotos parece mais preciso do que a API pura?

O mesmo mecanismo Vision, a diferença está no pré e pós-processamento, não no modelo:

Orientação: o Fotos corrige a orientação pelo EXIF antes de reconhecer; a API pura processa como .up por padrão → use --orientation para compensar
Resolução: o Fotos usa a imagem original em resolução total; as imagens que circulam em fluxos de trabalho costumam ser versões compactadas → sempre prefira o arquivo original
Downsampling implícito: NSImage renderiza por "pontos", e capturas de tela @2x/@3x junto com alguns HEIC podem perder metade dos pixels → esta ferramenta percorre os representantes e pega o bitmap de maior resolução
Texto vertical: o Texto Vivo consegue processar texto vertical; a API pura fragmenta texto vertical em linhas quebradas → esta ferramenta detecta automaticamente e faz arbitragem de confiança
Bônus de interatividade (não replicável completamente): o Texto Vivo permite selecionar partes, dando a sensação de "menos erros"; a linha de comando exibe o texto completo de uma vez, e qualquer caractere errado fica evidente

Conclusão: mesmo motor, o pipeline define o limite superior.

Atenção Especial para Dados Tabulares

OCR erra com mais frequência em tabelas: ponto decimal é engolido (. → ,), colunas adjacentes se fundem em uma sequência, linhas se misturam. Números críticos devem ser verificados novamente: se houver PDF original, extraia a camada de texto para comparar; se houver apenas foto, use votação entre versões + validação lógica de linhas e colunas.

Quando Não Usar Esta Ferramenta

Cenário	Escolha mais adequada
O modelo de IA usado já suporta leitura de imagens	Deixe o modelo ver a imagem diretamente, sem passar por OCR
Necessidade de reconstrução complexa de layout (multicolunas, fórmulas, estrutura de bordas de tabela)	MinerU e outros serviços de análise de layout (os dados vão para a nuvem)
Lote de PDFs escaneados para converter em texto e pode enviar para a nuvem	Interface de lote de serviços de OCR em nuvem

Regra: local primeiro, dados não são enviados para fora; só use a nuvem se precisar de maior precisão e após confirmar que os dados podem ser enviados.

Verificação e Solução de Problemas

Autoteste pós-instalação: sh scripts/selftest.sh (usa imagens de teste do pacote para validação de ponta a ponta, saída PASS/FAIL)
Lista de idiomas não contém zh-Hans: dados de idioma do sistema incompletos, muito raro; verifique se a versão do macOS é ≥ 13
Saída vazia ou totalmente errada: primeiro confirme que a imagem em si é legível (sips -g pixelWidth -g pixelHeight imagem), depois siga a "Ordem de Ação para Baixa Precisão" gradualmente

Requisitos de Sistema

macOS 13+ (automaticallyDetectsLanguage requer 13.0)
Compilação requer Xcode Command Line Tools (xcode-select --install); ou use o binário pré-compilado para Apple Silicon incluso (scripts/macocr-arm64, assinatura ad-hoc)

Descrição dos Arquivos do Pacote

Arquivo	Uso	Quando é necessário
`install.sh`	Instalar o macocr (compilação prioritária, fallback para pré-compilado)	Quando a verificação de ambiente mostrar que macocr não existe
`scripts/selftest.sh` + `scripts/selftest.png`	Autoteste de ponta a ponta (script + imagem de teste inclusa)	Verificação pós-instalação; ao investigar "reconhecimento anormal", execute primeiro para confirmar que a ferramenta em si está normal
`scripts/vision_ocr.swift`	Código-fonte (cerca de 200 linhas, auditável)	Quando precisar compilar manualmente ou auditar
`scripts/macocr-arm64`	Binário pré-compilado para Apple Silicon	Máquinas Apple Silicon sem swiftc, usado automaticamente pelo install.sh

GreenWich-art/agent-skills

O que é agent-skills?

Perguntar na sua IA favorita

Documentação