macOS Vision ローカル OCR

このスキルは、ユーザーが提供する画像/PDFをテキストに変換します。macOS 標準の Vision エンジン（macocr コマンド）をローカルで使用し、データを一切アップロードしません。

環境チェック（必須）

OCR コマンドを呼び出す前に、必ず以下のチェックを実行してください。いずれかが満たされない場合は停止し、指示に従って応答します。

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

uname が Darwin でない場合：このツールは macOS のみで動作します。インストールやコンパイルを試みず、ユーザーにこのスキルは 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（表や数字のシナリオ）
画像の前処理（トリミング + グレースケール + 自動コントラスト + シャープ化 + 2値化）。例は下記を参照

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値化

マルチバージョン投票：同じ表に対して2～3種類の前処理を実行し、一致する部分を採用。異なる数字は個別に再確認します。 クロスバリデーション：行全体/列全体の合計が合えばおおよそ信頼できます。合わない場合は、どこかの数字が間違っています。

なぜ「写真」アプリのライブテキストは、生のAPI呼び出しよりも正確に見えるのか？

同じ Vision エンジンです。違いは前処理と後処理にあり、モデル自体の差ではありません。

向き：「写真」は EXIF に従って正しい向きにしてから認識します。生のAPIはデフォルトで .up として処理する → --orientation で補正します
解像度：「写真」はフル解像度の元画像を使用します。ワークフローでやり取りされる画像は、圧縮されたプレビュー画像であることが多い → 常に元のファイルを優先します
暗黙のダウンサンプリング：NSImage は「ポイント」単位で画像を出力するため、@2x/@3x のスクリーンショットや一部の HEIC はピクセル数が半分に削られることがあります → このツールは rep を反復処理し、最大ピクセルのビットマップを取得します
縦書きテキスト：ライブテキストは縦書きを処理できます。生の呼び出しは縦書きをバラバラの行に分割してしまいます → このツールは自動的に検出し、信頼度に基づいて調停します
インタラクションのメリット（完全には再現不可）：ライブテキストは部分選択が可能で、「間違いが少ない」と認識されます。コマンドラインは全文を一度に出力するため、どんな誤字も目立ちます

結論：エンジンは同じで、パイプラインが上限を決める。

表データの特別な注意

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