macOS Vision 로컬 OCR

이 Skill은 사용자가 제공한 이미지/PDF를 텍스트로 변환하는 방법을 안내합니다: macOS 시스템 내장 Vision 엔진 (macocr 명령어)을 사용하여 로컬에서 완료하며, 어떤 데이터도 업로드하지 않습니다.

환경 확인 (필수)

OCR 명령어를 호출하기 전에 먼저 다음 확인을 실행하세요. 어느 하나라도 충족되지 않으면 중단하고 설명에 따라 응답하세요:

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

uname이 Darwin이 아님: 이 도구는 macOS만 지원합니다. 설치나 컴파일을 시도하지 말고 사용자에게 이 Skill은 macOS에서만 사용 가능하다고 알리고, 다른 OCR 방식을 사용하도록 제안하세요.
macocr이 없음: 이 패키지 디렉토리에서 ./install.sh를 실행하도록 안내하세요 (컴파일에는 Xcode Command Line Tools 필요; Apple Silicon에서 컴파일 환경이 없으면 자동으로 포함된 사전 컴파일 바이너리로 대체됨). 설치가 완료되면 sh scripts/selftest.sh로 종단 간 자체 검사를 수행하고 통과한 후 계속하세요.

설치와 자체 검사가 완료되면 각 세션마다 반복할 필요가 없습니다.

작업 실행의 표준 절차

사용자의 OCR 요청을 처리할 때는 다음 단계를 순서대로 따르고 건너뛰지 마세요:

입력 유형 확인. 사용자가 제공한 것이 이미지(png/jpg/jpeg/heic/tiff)라면 바로 3단계로 이동; 스캔된 PDF(텍스트 레이어 없음)라면 먼저 2단계로 가서 이미지로 변환하세요.
PDF를 이미지로 변환 (스캔된 PDF만 필요). 시스템 내장 sips 사용, 144dpi 기본:
```
sips -s format png -s dpiHeight 144 -s dpiWidth 144 입력.pdf --out /tmp/p1.png
```
참고: sips는 단일 페이지만 처리합니다. 다중 페이지 PDF는 페이지별로 지정하거나, pymupdf가 있으면 4배 행렬 렌더링 사용 (작은 글씨 강의자료에 효과 더 좋음, '스캔된 PDF 사용 방법' 참조).
인식 실행. 기본 명령어로 대부분의 경우를 커버할 수 있습니다:
```
macocr <이미지_경로>          # 여러 이미지는 순서대로 나열, 출력은 ===로 구분
```
상황에 따라 매개변수 추가 (매개변수 표는 아래 참조). 인식 결과는 순수 텍스트이며 시각적 줄 순서로 정렬됩니다.
결과 전달. 사용자에게 인식된 텍스트를 직접 보여줍니다. 표/숫자가 밀집된 결과는 반드시 사용자에게 주요 숫자는 재확인이 필요하다고 알리세요 ('표 데이터 특별 주의' 참조).

매개변수 참조

매개변수	용도
`--fast`	언어 교정 끄기. 표 및 숫자 상황에서 추천, 숫자가 이상한 값으로 '교정'되는 것을 방지
`--lang zh-Hans+en-US`	기본 중영 혼합. 순수 영어는 `en-US`로 설정하여 속도 향상; 번체는 `zh-Hant` 사용
`--rect x,y,w,h`	사각형 영역만 인식 (왼쪽 위 원점, 픽셀). 큰 이미지에서 특정 표만 추출할 때 사용
`--upscale N`	흐릿한 작은 이미지(폭 <1000px의 전송 이미지, 오래된 스캔본)를 먼저 Lanczos로 N배 확대 (1.0–4.0). 일반 모드에서 인식률이 낮을 때만 2 → 3 순서로 시도, 선명한 큰 이미지에 무분별한 확대는 획 연결을 초래
`--orientation up\|left\|right\|180`	사진 회전/뒤집힘 시 수동으로 바로잡기. Vision은 EXIF를 기준으로 자동 회전하지 않으므로, 옆으로 찍은 사진은 반드시 이 매개변수 사용
`--list-langs`	이 기기에서 지원하는 인식 언어 목록 출력 (설치 자체 검사용, 출력에 zh-Hans가 포함되어야 함)

인식률 낮을 때 처리 순서

비용이 낮은 순서부터 시도하고, 처음부터 복잡한 방안을 적용하지 마세요:

원본 이미지 찾기: 채팅 전송 이미지 인식률이 매우 낮음. 먼저 사용자에게 원본 파일을 요청
--rect로 목표 영역을 지정하여 노이즈 줄이기
--upscale 2 (흐릿한 작은 이미지)
--fast (표 숫자 상황)
이미지 전처리 (자르기 + 그레이스케일 + 자동 대비 + 선명화 + 이진화), 예시는 아래 참조

from PIL import Image, ImageOps, ImageEnhance
im = Image.open("src.JPG")
im.crop((x0, y0, x1, y1)).resize((w*2, h*2), Image.LANCZOS)   # 자르기 + 확대
ImageOps.autocontrast(im.convert("L"))                         # 그레이스케일 + 자동 대비
ImageEnhance.Sharpness(im).enhance(2.0)                        # 선명화
im.convert("L").point(lambda p: 255 if p > 128 else 0)         # 이진화

다중 버전 투표: 동일한 표에 대해 2–3가지 전처리를 실행하고 일치하는 부분을 취하며, 일치하지 않는 숫자는 개별적으로 재확인. 교차 검증: 전체 행/열 합계가 맞으면 대체로 신뢰 가능; 맞지 않으면 특정 숫자가 잘못된 것임.

왜 '사진' 앱의 라이브 텍스트가 순수 API 호출보다 정확한가?

동일한 Vision 엔진이며, 차이는 전후 처리에서 옵니다. 모델 자체의 문제가 아닙니다:

방향: '사진' 앱은 EXIF에 따라 회전을 보정한 후 인식; 순수 API 호출은 기본적으로 .up 방향으로 처리 → --orientation으로 보완
해상도: '사진' 앱은 전체 해상도 원본을 사용; 워크플로우에서 전달되는 것은 종종 압축된 미리보기 이미지 → 항상 원본 파일을 우선 사용
암시적 다운샘플링: NSImage는 '포인트' 단위로 이미지를 출력, @2x/@3x 스크린샷과 일부 HEIC는 절반의 픽셀이 제거됨 → 이 도구는 rep을 순회하여 최대 픽셀 비트맵을 사용
세로 텍스트: 라이브 텍스트는 세로 텍스트를 처리 가능; 순수 API 호출은 세로 텍스트를 조각으로 나누어 버림 → 이 도구는 자동 감지 후 신뢰도 중재 수행
상호작용 이점 (완전히 복제 불가): 라이브 텍스트는 부분 선택을 허용하여 '오류가 적다'는 인식을 줌; 명령줄은 전체 텍스트를 한 번에 출력하므로 모든 오타가 눈에 띔

결론: 엔진은 동일, 파이프라인이 상한을 결정한다.

표 데이터의 특별 주의

OCR은 표에서 가장 오류가 발생하기 쉽습니다: 소수점이 사라짐(. → ,), 인접 열이 하나의 문자열로 합쳐짐, 행 혼동. 주요 숫자는 반드시 재확인: PDF 원본이 있으면 텍스트 레이어를 추출하여 대조; 사진만 있다면 다중 버전 투표 + 행-열 논리 검증에 의존.

이 도구를 사용하지 말아야 할 경우

상황	더 적합한 선택
사용 중인 AI 모델 자체가 이미지 읽기 가능	OCR을 거치지 않고 모델에게 직접 이미지를 보여주세요
복잡한 레이아웃 복원 필요 (다중 열, 수식, 표 테두리 구조)	MinerU 등 레이아웃 수준 분석 서비스 (데이터는 클라우드로 전송됨)
전체 스캔 PDF를 일괄 텍스트 변환하고 클라우드 사용 가능	클라우드 OCR 서비스의 일괄 인터페이스

규칙: 로컬 우선, 데이터 외부 전송 금지; 더 높은 정밀도가 정말 필요하면 클라우드를 사용하되 데이터를 외부로 보내도 되는지 먼저 확인하세요.

검증 및 문제 해결

설치 후 자체 검사: sh scripts/selftest.sh (패키지 내 테스트 이미지로 종단 간 검증, PASS/FAIL 출력)
언어 목록에 zh-Hans가 없음: 시스템 언어 데이터 불완전, 매우 드물음; macOS 버전이 ≥ 13인지 확인
출력이 비었거나 전부 오류: 먼저 이미지 자체를 읽을 수 있는지 확인 (sips -g pixelWidth -g pixelHeight 이미지), 그런 다음 '인식률 낮을 때 처리 순서'에 따라 단계별 시도

시스템 요구 사항

macOS 13+ (automaticallyDetectsLanguage는 13.0 필요)
컴파일에는 Xcode Command Line Tools 필요 (xcode-select --install); 또는 포함된 Apple Silicon 사전 컴파일 바이너리 사용 (scripts/macocr-arm64, ad-hoc 서명)

패키지 내 파일 설명

파일	용도	필요한 경우
`install.sh`	macocr 설치 (컴파일 우선, 사전 컴파일 대비)	환경 확인에서 macocr이 없음을 발견했을 때
`scripts/selftest.sh` + `scripts/selftest.png`	종단 간 자체 검사 (스크립트 + 자체 테스트 이미지)	설치 후 검증; '인식 이상' 문제 해결 시 먼저 실행하여 도구 자체가 정상인지 확인
`scripts/vision_ocr.swift`	소스 코드 (약 200줄, 감사 가능)	직접 컴파일하거나 감사가 필요할 때
`scripts/macocr-arm64`	Apple Silicon 사전 컴파일 바이너리	swiftc가 없는 Apple Silicon 기기에서 install.sh가 자동으로 사용

macOS Vision 本地 OCR