ai_ocr2md.py 技術ドキュメント
プログラムの動作
ai_ocr2md.py は、指定された画像ファイルまたはクリップボード上の画像からテキストを抽出し、その内容をMarkdown形式に整形して出力するAI OCRツールです。ユーザーは、使用するAI API（Geminiがデフォルト）やモデル、プロンプトの内容を細かく設定できます。
主な機能は以下の通りです。
画像入力: ローカルの画像ファイル (
.png,.jpgなど) を指定するか、Windowsのクリップボードから直接画像を読み込むことができます。AI OCR処理: Google Gemini API (デフォルト) を使用して、画像内のテキストを認識し、指定されたプロンプトに基づいてMarkdown形式に整形します。
プロンプトのカスタマイズ:
ai_ocr2md.iniファイルを通じて、OCR処理に渡すプロンプトを自由に設定できます。これにより、出力されるMarkdownの形式や詳細度を制御可能です。出力: 処理結果は、指定されたファイル名、または入力ファイル名に基づく自動生成ファイル名でMarkdown形式 (
.md) として保存されます。
このプログラムは、紙のドキュメント、スクリーンショット、手書きメモなどの画像データから、編集可能な構造化されたテキストを効率的に生成する課題を解決します。
原理
ai_ocr2md.py は、主に以下のステップで動作します。
引数の解析と設定の読み込み:
コマンドライン引数 (
argparseモジュール使用) を解析し、入力画像パス、出力ファイル名、プロンプトファイルパス、AI API、AIモデル名などを取得します。ai.envファイルからAPIキーなどのAI設定を読み込みます。
プロンプトの準備:
--iniオプションで指定されたINIファイル（デフォルトはai_ocr2md.ini）が存在する場合、そのファイルから[PROMPT]セクションのPROMPTキーに対応するテキストを読み込みます。INIファイルが存在しない、またはプロンプトが指定されていない場合は、デフォルトのプロンプト「画像のテキストを正確に抽出し、Markdown形式で整えてください。数式はLaTeXを使用してください。」を使用します。
入力画像の取得:
コマンドライン引数で画像ファイルパスが指定された場合、そのファイルを直接使用します。
引数に
"clip"が指定された場合、PIL.ImageGrab.grabclipboard()を使用してWindowsクリップボードから画像データを取得します。取得した画像は一時的にclipboard_ocr_input.pngとして保存され、OCR処理に使用されます。
AI OCR処理:
call_ai_ocr関数がAI APIを呼び出します。デフォルトのAPIであるGeminiを使用する場合、環境変数
GOOGLE_API_KEYからAPIキーを取得し、tkai_lib.genai.configure()で設定します。tkai_lib.genai.GenerativeModel()を使用して指定されたモデル（例:gemini-3.1-pro-preview）のインスタンスを作成します。生成されたモデルに対して
generate_content([prompt, img])を呼び出し、準備されたプロンプトと画像データを送信してテキスト生成をリクエストします。AIは画像内のテキストを認識し、プロンプトの指示に従ってMarkdown形式のテキストを生成します。
結果の保存:
AIから返された結果テキストは、
Path(args.output).write_text()を使用して、指定された出力ファイル名 (デフォルトは入力ファイル名に基づく) のMarkdownファイルとしてUTF-8エンコーディングで保存されます。
このプロセスを通じて、AIの高度な画像認識能力と自然言語処理能力を活用し、画像データを構造化されたMarkdownテキストに変換します。
必要な非標準ライブラリとインストール方法
本プログラムは、以下の非標準ライブラリに依存しています。
Pillow (PIL): 画像ファイルの読み込み、保存、クリップボードからの画像取得に使用されます。
google-generativeai: Gemini APIとの通信に使用されます。
tkai_lib内部でラップされている可能性がありますが、直接的な依存関係として必要です。
これらのライブラリは pip コマンドでインストールできます。
pip install Pillow google-generativeai
なお、プログラム内で import tkai_lib があり、これは添付ライブラリまたはプロジェクト固有のユーティリティライブラリと推測されます。このライブラリのインストール方法については、本プログラムの配布元を参照してください。
必要な入力ファイル
ai_ocr2md.py は以下の種類の入力ファイルを必要とする場合があります。
画像ファイル:
形式:
Pillowがサポートする一般的な画像形式（PNG, JPEG, GIF, BMPなど）。内容: OCRの対象となる画像データ。テキスト、図、数式などが含まれていることが期待されます。
指定方法: コマンドライン引数でファイルパスを指定します。例:
sample.png備考: クリップボードから入力する場合は、このファイルは不要です。
AI設定ファイル (
ai.env):形式: テキストファイル。環境変数を
KEY=VALUE形式で記述します。内容: AI APIを利用するためのAPIキーなど、機密情報が含まれます。
例 (Gemini APIの場合):
GOOGLE_API_KEY=YOUR_GEMINI_API_KEY_HERE
場所:
ai_ocr2md.pyと同じディレクトリ、またはtkai_lib.read_ai_configが探索するパスに配置します。備考: AI APIを利用するために必須です。
プロンプト設定ファイル (
ai_ocr2md.ini):形式: INIファイル形式。
内容: AI OCRに指示する具体的なプロンプトテキストを記述します。
例:
[PROMPT] PROMPT = 画像の内容を詳細に分析し、Markdown形式で構造化してください。数式はLaTeX形式で記述し、コードは適切なシンタックスハイライトを使用してください。
指定方法:
--iniまたは-iオプションでパスを指定します。備考: 省略可能です。省略された場合は、デフォルトのプロンプトが使用されます。
生成される出力ファイル
ai_ocr2md.py は、OCR処理の後に以下のファイルを生成します。
Markdownファイル (.md):
ファイル名:
--outputまたは-oオプションで指定されたファイル名。オプションが指定されていない場合、入力画像ファイル名（拡張子を除く）に
.mdを付加した名前。クリップボード入力 (
clip) の場合、デフォルトでclipboard_ocr_input.md。
内容: AI OCRが画像から抽出し、指定されたプロンプトに基づいてMarkdown形式に整形されたテキスト。見出し、箇条書き、コードブロック、LaTeX形式の数式などが含まれる場合があります。
エンコーディング: UTF-8。
一時画像ファイル (
clipboard_ocr_input.png):ファイル名:
clipboard_ocr_input.png。内容: コマンドライン引数に
"clip"を指定してクリップボードから画像が読み込まれた際に、OCR処理のために一時的に保存されるPNG画像ファイル。備考: プログラム実行後も自動的には削除されません。
コマンドラインでの使用例 (Usage)
基本的なコマンドライン引数とオプションは以下の通りです。
ai_ocr2md.py [-h] [--output OUTPUT] [--ini INI] [--api {gemini,openai,openai5}] [--model MODEL] input
input: 必須。OCR対象の画像ファイルパス、またはクリップボードからの入力の場合は"clip"を指定します。--output OUTPUT,-o OUTPUT: 出力するMarkdownファイルのパスとファイル名を指定します。省略した場合、入力ファイル名（またはclipboard_ocr_input）に.md拡張子が付加されます。--ini INI,-i INI: プロンプト設定ファイル（INI形式）のパスを指定します。デフォルトはai_ocr2md.iniです。--api {gemini,openai,openai5},-a {gemini,openai,openai5}: 使用するAI APIを指定します。現在のデフォルトはgeminiです。--model MODEL,-m MODEL: 使用するAIモデルの名前を指定します。デフォルトはgemini-3.1-pro-previewです。
コマンドラインでの具体的な使用例
1. 画像ファイルを指定してOCRを実行し、結果をデフォルトのファイル名で保存する例
ai.env に GOOGLE_API_KEY=YOUR_API_KEY が設定されており、ai_ocr2md.ini に以下の内容が記述されていると仮定します。
[PROMPT]
PROMPT = 画像のテキストをMarkdown形式で正確に抽出し、箇条書きや見出しも適切に表現してください。
sample.png という画像ファイルが存在する場合の実行例です。
python ai_ocr2md.py sample.png
実行結果の説明:
sample.pngがAI OCRによって解析され、ai_ocr2md.iniで定義されたプロンプトに従って処理されます。結果のMarkdownテキストは、自動生成されたファイル名sample.mdとして保存されます。
2. クリップボードから画像をOCRし、出力ファイル名を指定する例
事前にWindowsの Win + Shift + S などを使って画面の一部をキャプチャし、クリップボードに画像をコピーしておきます。
python ai_ocr2md.py clip -o my_screenshot_notes.md
実行結果の説明: クリップボードにコピーされた画像データが一時的に
clipboard_ocr_input.pngとして保存され、その画像に対してAI OCRが実行されます。--iniオプションが指定されていないため、デフォルトのプロンプト「画像のテキストを正確に抽出し、Markdown形式で整えてください。数式はLaTeXを使用してください。」が使用されます。OCR結果はmy_screenshot_notes.mdというファイルに保存されます。
3. 特定のGeminiモデルを指定してOCRを実行する例
document.jpg という画像ファイルが存在すると仮定します。
python ai_ocr2md.py document.jpg --model gemini-1.5-pro
実行結果の説明:
document.jpgがOCRされ、document.mdに結果が保存されます。この際、デフォルトのgemini-3.1-pro-previewではなく、明示的に指定されたAIモデルgemini-1.5-proが使用されます。プロンプトはデフォルトのものが適用されます。