OCR変換ツール convert_ocr.py 技術ドキュメント

プログラムの動作

convert_ocr.py は、画像、PDF、およびOffice文書からテキストを抽出し、Markdown (.md) 形式で出力することに特化したコマンドラインツールです。このプログラムは、OCR (光学文字認識) エンジンとして Tesseract-OCR または Generative AI (Google Geminiなど) を利用できます。

主な機能は以下の通りです。

  • 多様な入力形式のサポート: PNG, JPEGなどの画像ファイル、PDF文書、PowerPoint, Word, ExcelなどのOffice文書、さらにはクリップボード上の画像も入力として受け付けます。

  • 複数のOCRエンジン: 高精度なローカルOCRエンジンである Tesseract-OCR と、柔軟なテキスト抽出能力を持つ Generative AI エンジンを選択できます。

  • Markdown形式での出力: 抽出されたテキストは、元の文書の構造（見出し、箇条書き、表など）を可能な限り保持したMarkdown形式で整形されます。

  • 中間ファイルの管理: PDFやOffice文書は内部で画像に変換されますが、これらの変換により生成された中間ファイルを必要に応じて保持するオプションも提供されます。

  • 依存関係の表示: 利用可能なOCRエンジンやレンダリングライブラリ、対応する入力形式といった依存関係のレポートを生成できます。

このツールは、様々な形式のドキュメントから情報を抽出し、編集や再利用が容易なMarkdown形式で集約する作業を効率化するために設計されています。

原理

convert_ocr.py は、以下の段階を経てドキュメントのOCR変換を実行します。

  1. 入力の正規化:

    • クリップボード: Pillow.ImageGrab を使用してクリップボード上の画像をキャプチャし、一時的なPNGファイルとして保存します。

    • 画像ファイル: 入力ファイルが画像形式の場合、直接OCR処理の対象となります。

    • PDFファイル: PyMuPDF (fitz) ライブラリを使用して、PDFの各ページを指定されたDPIで個別のPNG画像にレンダリングします。

    • Office文書: soffice (LibreOffice) コマンドラインツールを呼び出して、Office文書を一時的なPDFファイルに変換します。その後、PDFファイルと同様に PyMuPDF を用いて各ページをPNG画像にレンダリングします。

  2. OCR処理: 正規化された画像ファイルに対して、指定されたOCRエンジンが適用されます。

    • Tesseract-OCR: pytesseract ライブラリを介して、システムにインストールされている Tesseract-OCR エンジンを呼び出します。画像が入力として渡され、指定された言語 (--lang 引数、例: jpn+eng) に基づいてテキストが抽出されます。 原理的には、Tesseract は画像内の文字領域を検出し、トレーニングされたモデル（言語データ）に基づいて各文字を認識し、その結果をテキストデータとして出力します。

    • Generative AI (GenAI): tkai_lib または google.generativeai ライブラリを使用して、Google Gemini などの Generative AI モデルを利用します。 入力画像と、--ini 引数で指定された設定ファイルから読み込まれるか、デフォルトで定義されたプロンプトテキストがAIモデルに送信されます。プロンプトは、画像内のテキストを正確に抽出し、Markdown形式で出力するようAIに指示します。AIは与えられた画像とプロンプトに基づいてコンテンツを解析し、Markdown形式のテキストを生成して返します。APIキーなどの環境設定は --ai-env で指定されたファイルから読み込まれます。

  3. Markdownの構築: 各画像（元のドキュメントのページまたはスライド）から抽出されたテキストは、元の入力名、OCRエンジン、セグメント数などのメタデータと共に、Markdown形式に整形されます。各画像セグメントは --- で区切られ、## 見出しで各セグメントのラベル（例: Page 1 や Clipboard）が示されます。

これらの段階を通じて、様々な形式のドキュメントが統一されたMarkdown出力に変換されます。

必要な非標準ライブラリとインストール方法

convert_ocr.py を実行するには、以下のPython非標準ライブラリが必要です。使用するOCRエンジンや入力ファイルの種類に応じて、必要なライブラリが変わります。

ライブラリ名

用途

必須度

インストールコマンド (pip)

Pillow

画像処理、クリップボードからの画像取得

ほとんどのケースで必須 (画像入力、PDF/Officeからの変換、GenAI利用時)。クリップボード入力時やGenAI OCR時にも必要。

pip install Pillow

PyMuPDF

PDF文書の処理 (PDF/Office入力時)

PDFまたはOffice文書を入力とする場合に必須。

pip install PyMuPDF

pytesseract

Tesseract OCRエンジンへのインターフェース

Tesseractエンジンを使用する場合に必須。

pip install pytesseract

tkai_lib

Generative AI (Gemini) バックエンド

GenAIエンジンを使用する場合に、google-generativeai の代わりに利用可能。

pip install tkai_lib (※ PyPIに公開されているか要確認)

google-generativeai

Generative AI (Gemini) バックエンド

GenAIエンジンを使用する場合に必須。

pip install google-generativeai

追加の外部ツール (OSへのインストールが必要):

  • Tesseract-OCR エンジン: pytesseract を使用するには、Tesseract-OCR エンジン本体がOSにインストールされている必要があります。また、日本語を含む複数の言語をOCRする場合は、対応する言語データもインストールする必要があります。

    • Debian/Ubuntu: sudo apt install tesseract-ocr tesseract-ocr-jpn

    • macOS (Homebrew): brew install tesseract tesseract-langfiles

    • Windows: Tesseract-OCRのGitHubリポジトリ からインストーラーをダウンロードしてください。

  • LibreOffice (soffice): Office文書 (.pptx, .docx, .xlsx など) を入力として扱う場合、LibreOffice または OpenOffice の soffice コマンドがOSにインストールされている必要があります。

    • Debian/Ubuntu: sudo apt install libreoffice

    • macOS (Homebrew): brew install --cask libreoffice

    • Windows: LibreOffice公式サイト からインストーラーをダウンロードしてください。

必要な入力ファイル

convert_ocr.py が期待する入力ファイルとデータは以下の通りです。

  1. メイン入力 (input 引数): OCR処理の対象となる主要な入力。以下のいずれかを指定できます。

    • 画像ファイル: .png, .jpg, .jpeg, .bmp, .tif, .tiff, .webp などの画像形式。

    • PDFファイル: .pdf 形式の文書。

    • Office文書: .pptx, .ppt, .docx, .doc, .xlsx, .xls, .odp, .odt, .ods などのMicrosoft OfficeまたはLibreOfficeの文書形式。これらのファイルタイプを処理するには、LibreOffice (またはOpenOffice) の soffice コマンドがシステムにインストールされている必要があります。

    • クリップボード: clip という文字列を指定すると、プログラム実行時にクリップボードにコピーされている画像が入力として扱われます。この機能は Pillow.ImageGrab が利用可能な環境でのみ動作します。

  2. GenAI設定ファイル (--ini 引数): GenAIエンジンを使用する場合、プロンプトテキストを定義するための簡易INIファイルです。 ファイルは key=value 形式をサポートし、# や ; で始まる行はコメントとして無視されます。 キーとして PROMPT, PROMPT_TEMPLATE_JA, PROMPT_TEMPLATE_EN のいずれかが設定されている場合、その値がGenAIへのプロンプトとして使用されます。 また、値は「3重引用符」で囲むことで複数行にわたるテキストを表現できます。

    例 (ai_ocr2md.ini):

    PROMPT = """
以下の画像を解析し、テキストをMarkdown形式で抽出してください。
- 日本語を優先
- 見出し、箇条書き、表の構造を維持
- 数式は可能な限りLaTeX形式で表現
"""
API_KEY = your_api_key_if_not_in_env

  3. AI環境変数ファイル (--ai-env 引数): GenAIエンジンを使用する場合、AIサービスに必要なAPIキーなどの環境変数を定義するためのINIファイルです。 key=value 形式で記述され、プログラム実行時にこれらの変数が os.environ にロードされます。 既に環境変数として設定されているキーは上書きされません。 デフォルトは ai.env です。

    例 (ai.env):

    GOOGLE_API_KEY = your_google_api_key_here
gemini_model = gemini-1.5-pro

生成される出力ファイル

convert_ocr.py は、OCR処理の結果として以下のファイルを生成します。

  1. Markdown出力ファイル (.md):

    • ファイル名:

      • --output (または -o) 引数で出力ファイル名を指定した場合、その名前で保存されます。

      • 指定がない場合、入力ファイルのパスから拡張子を除いた名前に .md 拡張子を付与したものとなります（例: input.png -> input.md）。

      • 入力が clip の場合、デフォルトで clipboard_ocr.md となります。

    • 内容: OCR処理によって抽出されたテキストがMarkdown形式で記述されます。

      • ファイルの先頭には、ドキュメント全体の大見出しとして # OCR Result: <入力ソース名> が付加されます。

      • 使用されたOCRエンジンと処理されたセグメント数がメタ情報として含まれます。

      • 各入力セグメント（画像ファイル、PDFのページ、Officeのページなど）は、Markdownの水平線 (---) で区切られます。

      • 各セグメントのOCR結果は、## <ラベル> という見出しの下に配置されます（例: ## Page 1, ## Clipboard）。

      • テキストが抽出できなかったセグメントには、*(empty result)* と表示されます。

  2. 中間ファイル (オプション):

    • PDFやOffice文書が入力として与えられた場合、内部的に画像ファイルやPDFファイルが一時的に生成されます。通常、これらのファイルはプログラムの終了時に削除されます。

    • --keep-images オプションを指定した場合、これらの_中間画像_や_中間PDF_ファイルは作業ディレクトリ (--workdir で指定、または一時ディレクトリ) に残されます。これにより、OCR結果の検証やデバッグに役立てることができます。

    • これらのファイル名は、元の入力ファイル名に基づいて自動生成され、例えば page_0001.png や input_file_name.pdf のようになります。

コマンドラインでの使用例 (Usage)

convert_ocr.py の基本的なコマンドライン使用法は以下の通りです。

python convert_ocr.py input [--output OUTPUT] [--engine ENGINE] [--ini INI] [--api API] [--model MODEL] [--lang LANG] [--dpi DPI] [--keep-images] [--workdir WORKDIR] [--ai-env AI_ENV] [--list]

引数:

  • input: OCR処理を行う入力ファイル。画像、PDF、Office文書のパス、またはクリップボードの画像を指す clip を指定します。--list オプションが指定された場合は不要です。

  • --output, -o OUTPUT: 生成されるMarkdownファイルのパスと名前を指定します。省略された場合、入力ファイル名から推測されます。

  • --engine, -e ENGINE: 使用するOCRエンジンを指定します。tesseract (デフォルト) または genai を選択できます。

  • --ini, -i INI: genai エンジンを使用する際に、プロンプトなどの設定を含むINIファイルのパスを指定します。

  • --api, -a API: genai エンジンを使用する際に、利用するAPIの名前を指定します。デフォルトは gemini です。

  • --model, -m MODEL: genai エンジンを使用する際に、利用するAIモデル名を指定します。

  • --lang LANG: tesseract エンジンを使用する際に、OCRの言語を指定します（例: jpn+eng）。デフォルトは jpn+eng です。

  • --dpi DPI: PDFやOffice文書を画像に変換する際の解像度（DPI）を指定します。デフォルトは 300 です。

  • --keep-images: 中間的に生成される画像ファイルやPDFファイルを削除せずに残します。

  • --workdir WORKDIR: 一時ファイルや中間ファイルを保存する作業ディレクトリを指定します。指定しない場合、一時ディレクトリが使用されます。

  • --ai-env AI_ENV: AI用の環境変数（APIキーなど）を読み込むINIファイルのパスを指定します。デフォルトは ai.env です。

  • --list: 対応する形式、依存関係、および実行例を表示して終了します。

コマンドラインでの具体的な使用例

1. サポートされている形式と依存関係の表示

システムで利用可能なOCRエンジン、レンダラー、サポートされる入力形式を確認します。

python convert_ocr.py --list

実行結果の例:

convert_ocr.py : 利用可能な入力 / エンジン / 依存関係

[OCR engine]
- tesseract : OK (pytesseract import可)
- genai     : OK (tkai_lib)

[renderer]
- Pillow    : OK
- PyMuPDF   : OK
- soffice   : OK (/usr/bin/libreoffice)

[input type]
- image     : .bmp, .gif, .jpeg, .jpg, .png, .tif, .tiff, .webp
- pdf       : .pdf
- office    : .doc, .docx, .ods, .odt, .odp, .ppt, .pptx, .xls, .xlsx  ※ soffice が必要
- clipboard : clip  ※ Pillow.ImageGrab が使える環境のみ

[output]
- 常に .md

[examples]
- python convert_ocr.py input.png
- python convert_ocr.py input.pdf --engine tesseract --lang jpn+eng
- python convert_ocr.py input.png --engine genai --ini ai_ocr2md.ini
- python convert_ocr.py slides.pptx --engine tesseract --keep-images

2. 画像ファイル (PNG) をTesseractでOCRし、Markdownに出力

input.png という画像ファイルをTesseractエンジンでOCRし、結果を input.md として出力します。

python convert_ocr.py input.png

実行結果の例:

[tesseract] OCR: input.png -> /tmp/convert_ocr_xxxxxx/input.png
OK: wrote input.md

3. PDFファイルをTesseractでOCRし、日本語と英語を認識

document.pdf をTesseractエンジンでOCRし、日本語と英語の両方を認識させます。出力ファイルは document.md となります。

python convert_ocr.py document.pdf --engine tesseract --lang jpn+eng

実行結果の例:

[tesseract] OCR: Page 1 -> /tmp/convert_ocr_xxxxxx/document_images/page_0001.png
[tesseract] OCR: Page 2 -> /tmp/convert_ocr_xxxxxx/document_images/page_0002.png
...
OK: wrote document.md

4. クリップボードの画像をGenAIでOCRし、特定のINIファイルを使用

現在クリップボードにコピーされている画像をGenAIエンジンでOCRします。OCRプロンプトは my_ai_prompt.ini から読み込み、AIサービスの環境設定は my_ai.env から読み込みます。結果は clipboard_ocr.md に保存されます。

python convert_ocr.py clip --engine genai --ini my_ai_prompt.ini --ai-env my_ai.env

実行結果の例:

[genai] OCR: Clipboard -> /tmp/convert_ocr_xxxxxx/clipboard_input.png
OK: wrote clipboard_ocr.md

5. Office文書 (PowerPoint) をTesseractでOCRし、中間画像を保持

presentation.pptx をTesseractエンジンでOCRします。PDF変換後の中間画像ファイルは削除せずに、指定された作業ディレクトリ work_files に残します。出力ファイルは presentation.md となります。

python convert_ocr.py presentation.pptx --engine tesseract --keep-images --workdir work_files

実行結果の例:

[soffice] converting presentation.pptx to pdf...
[tesseract] OCR: Page 1 -> work_files/presentation_images/page_0001.png
[tesseract] OCR: Page 2 -> work_files/presentation_images/page_0002.png
...
OK: wrote presentation.md
work files kept in: work_files