uglymie/real-offline-ocr

Offline OCR — オフライン画像文字抽出

RapidOCR + PP-OCRv6 ベースのローカル画像文字抽出機能。完全オフライン動作、中国語・英語対応。ネット接続不要、API登録不要、GPU不要。

いつ使うか

• ユーザーが画像ファイル（スクリーンショット、写真、領収書、スキャン文書、ドキュメント画像、キャプチャ等）を提供し、画像内の文字を読み取りたい場合
• 画像からテキスト内容を抽出したい場合（領収書情報のコピー、スクリーンショット内のコード/文字認識、表内テキストの抽出など）
• 現在のモデルがマルチモーダル能力を持たない場合、「画像を見て文字を読む」代替として
• DeepSeek-V4 などマルチモーダル能力がない大規模モデルとの連携：モデルの会話インターフェースが「画像を見られない」場合、本スキルで先に画像から文字を抽出し、その後モデルが理解・回答・処理する

初回インストール（1回のみ）

スクリプト実行には独立した Python 仮想環境が必要です。初めて本スキルを使用する際は、環境が整っているか確認してください:

# <SKILL_DIR>/.venv が存在しない、または rapidocr を import できない場合、以下を実行:
python <SKILL_DIR>/scripts/setup.py

# Intel CPU ユーザーでより高いパフォーマンス（約1.8倍）を希望する場合、追加で OpenVINO をインストール:
python <SKILL_DIR>/scripts/setup.py --with-openvino

コマンドはクロスプラットフォームで一貫しています（Windows/macOS/Linux で使用可能、bash不要）。python が見つからない場合、Linux/macOS では python3 に置き換えてください。

setup.py は冪等であり、繰り返し実行可能です。既にインストール済みの場合はスキップされます。このスクリプトは:

• Python バージョンが 3.9 以上かを確認（不足する場合は各プラットフォーム向けのインストール手順を表示）
• <SKILL_DIR>/.venv を作成し、rapidocr + onnxruntime（デフォルト）または + openvino（オプション）をインストール
• Intel CPU を検出し、OpenVINO 未インストールの場合は約1.8倍高速化のオプションインストール方法を提案（自動インストールはしない）

<SKILL_DIR> は本スキルのディレクトリを指します。モデルは rapidocr パッケージに内蔵（PP-OCRv6 の3段階 det/rec）されており、別途ダウンロードは不要です。

初回実行から利用可能になるまでの完全な流れ: python <SKILL_DIR>/scripts/setup.py → 自動インストールを待つ（約1〜3分）→ 以下のコマンドで画像認識が可能。

使用方法

# 単一画像
python <SKILL_DIR>/scripts/ocr.py <画像パス>

# 複数画像
python <SKILL_DIR>/scripts/ocr.py <画像1> <画像2> ...

# よく使うパラメータ
--model tiny|small|medium      モデル段階（デフォルト small）
--engine onnxruntime|openvino  推論エンジン（デフォルト onnxruntime）
--use_cls                      テキスト行方向分類を有効化（回転・縦書きテキストに有用、やや遅い）
--save_vis                     可視化結果を output/ に保存

例:

python <SKILL_DIR>/scripts/ocr.py /path/to/screenshot.png
python <SKILL_DIR>/scripts/ocr.py --model tiny --save_vis /path/to/invoice.jpg
python <SKILL_DIR>/scripts/ocr.py --engine openvino /path/to/photo.png

説明：ocr.py は自動的に .venv 内の依存関係を使用して実行されます（Windows では .venv\Scripts\python.exe）。インタープリターのパスを気にする必要はありません。

出力形式

スクリプトは stdout に認識結果を以下の形式で出力します：

===== ファイル名.png =====
合計 N 個のテキストボックスを認識:
[1] 認識された最初の行のテキスト  (信頼度: 0.98)
[2] 認識された2行目のテキスト  (信頼度: 0.95)

認識終了後、[番号] 以降のプレーンテキスト内容を整理してユーザーに返し、信頼度が低い場合（例：<0.6）は認識が不正確である可能性があることを注意喚起します。

推論エンジンの選択

エンジン	サイズ	特徴
onnxruntime（デフォルト）	小 (~52M)	クロスプラットフォームで一貫、クリーンなインストール、汎用推奨
openvino	大 (~+123M)	Intel CPU でのみ高速（約1.8倍）; AMD/Apple Silicon では利点なし

モデル段階の選択

段階	det/rec モデルサイズ	速度	精度	適用シーン
tiny	1.8M / 4.5M	最速	低め	単純なシーン、クイックプレビュー
small（デフォルト）	9.9M / 21M	バランス良	良好	一般的なシーン
medium	62M / 77M	最遅	最高	複雑・ぼやけ・密集テキスト

画像が鮮明で文字が整っている場合は small を優先。認識が不正確な場合は medium にアップグレード。

注意事項

• 画像が鮮明で文字が整っているほど認識精度が高い。斜体、装飾文字、複雑な背景は精度を低下させる
• 方向が逆または縦書きのテキストには --use_cls パラメータを追加可能
• 1画像あたり約0.1〜1秒（CPU）、画像サイズ、段階、エンジンにより変動
• 必要なのは Python 3.9+ のみ。Python 環境がない場合、setup.py が各プラットフォーム向けのインストール手順を表示