convert_ocr プログラム仕様

convert_ocr.py

OCR専用の独立変換ツール。 - 出力は常に Markdown (.md) - OCRエンジンは tesseract / genai - 入力は画像, PDF, および (LibreOffice/soffice があれば) Office 文書 - --list で利用可能な形式と依存関係を表示

主な使い方:: 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 python convert_ocr.py --list

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

class ai.convert_ocr.ImageItem(path: Path, label: str)[ソース]

ベースクラス: object

OCR処理対象の画像情報を保持するデータクラスです。

パラメータ:

path (Path) -- 画像ファイルへのパス。
label (str) -- 画像を識別するためのラベル (例: ファイル名、ページ番号)。

label: str

path: Path

ai.convert_ocr.availability_report() → str[ソース]

本ツールのOCRエンジン、レンダラー、対応入力タイプなどの利用可能性レポートを生成します。

各OCRエンジン (Tesseract, GenAI) およびレンダリングに必要なライブラリ (Pillow, PyMuPDF) や外部コマンド (soffice) の利用可能性をチェックし、その結果と対応する入力タイプ、簡単な使用例を含むレポートテキストを返します。

戻り値:: 利用可能性レポートの文字列。
戻り値の型:: str

ai.convert_ocr.build_markdown(items: List[ImageItem], texts: List[str], engine: str, source_name: str) → str[ソース]

複数のOCR結果と画像情報からMarkdown形式のレポートを作成します。

入力された画像アイテムのリストとそれに対応するOCR結果のテキストリストを結合し、ソース名とOCRエンジン情報をヘッダーに含むMarkdown形式の文字列を生成します。各画像アイテムは、## ページ名の形式でセクション化されます。

パラメータ:

items (List[ImageItem]) -- 処理された各画像に関する ImageItem オブジェクトのリスト。
texts (List[str]) -- 各画像から抽出されたテキストのリスト。items と同じ順序で対応します。
engine (str) -- OCRに使用されたエンジン名 (例: "tesseract", "genai")。
source_name (str) -- 元の入力源の名前 (例: "input.pdf", "clipboard")。

戻り値:

生成されたMarkdown文字列。

戻り値の型:

str

ai.convert_ocr.call_genai_ocr(prompt: str, image_path: Path, api: str = 'gemini', model: str | None = None, ai_env: str | None = None) → str[ソース]

GenAIサービスを呼び出して画像OCRを実行します。

tkai_lib または google.generativeai のいずれかのバックエンドを使用して、指定されたプロンプトと画像でOCRを実行します。 ai_env が指定されている場合、そこから環境変数をロードします。現在、GenAI APIは gemini のみサポートしています。

パラメータ:

prompt (str) -- GenAIに渡すプロンプト文字列。
image_path (Path) -- OCR対象の画像ファイルへのパス。
api (str) -- 使用するGenAI APIの名前 (既定: "gemini")。
model (Optional[str]) -- 使用するGenAIモデルの名前。None の場合、環境変数 gemini_model または "gemini-1.5-pro" を使用。
ai_env (Optional[str]) -- AI用環境変数が定義されているINIファイルへのパス。

戻り値:

GenAIによって抽出されたテキスト。

戻り値の型:

str

例外:

RuntimeError -- Pillowが利用できない、APIキーが設定されていない、GenAIバックエンドが利用できない、またはGenAIからの応答が空の場合。

ai.convert_ocr.collect_images(input_value: str, work_dir: Path, dpi: int) → List[ImageItem][ソース]

指定された入力（画像、PDF、Office文書、クリップボード）からOCR処理用の画像を収集します。

入力タイプに応じて以下の処理を行います: - "clip": クリップボードから画像を直接取得。 - 画像ファイル: そのまま ImageItem としてリストに追加。 - PDFファイル: 各ページを画像にレンダリング。 - Office文書: LibreOffice (soffice) を使用してPDFに変換後、各ページを画像にレンダリング。すべての中間ファイルは work_dir に作成されます。

パラメータ:

input_value (str) -- 入力源。画像/PDF/Office文書のパス、または "clip"。
work_dir (Path) -- 中間ファイルを保存する作業ディレクトリへのパス。
dpi (int) -- PDF/Office文書を画像化する際のDPI。

戻り値:

収集された各画像の ImageItem オブジェクトのリスト。

戻り値の型:

List[ImageItem]

例外:

FileNotFoundError -- 入力ファイルが見つからない場合。
RuntimeError -- サポートされていない入力タイプ、または必要な依存関係が不足している場合。

ai.convert_ocr.command_exists_any(names: Sequence[str]) → str | None[ソース]

指定されたコマンド名のいずれかがシステムPATH上に存在するかを確認します。

与えられたシーケンス内の各コマンド名を順番に検索し、最初に見つかったコマンドの絶対パスを返します。

パラメータ:: names (Sequence[str]) -- 検索するコマンド名のシーケンス。
戻り値:: 最初に見つかったコマンドの絶対パス、またはすべて見つからなかった場合は None。
戻り値の型:: Optional[str]

ai.convert_ocr.convert_office_to_pdf(input_path: Path, out_dir: Path) → Path[ソース]

Office文書をPDF形式に変換します。

LibreOfficeの soffice コマンドラインツールを使用して、指定されたOffice文書 (PPTX, DOCX, XLSX など) をPDFに変換します。変換されたPDFファイルは out_dir に保存されます。

パラメータ:

input_path (Path) -- 変換するOffice文書へのパス。
out_dir (Path) -- 変換されたPDFを保存するディレクトリへのパス。

戻り値:

変換されたPDFファイルへのパス。

戻り値の型:

Path

例外:

RuntimeError -- LibreOffice/sofficeが見つからない場合、またはsofficeでの変換に失敗した場合。

ai.convert_ocr.default_output_path(input_value: str, output: str | None) → Path[ソース]

出力ファイルパスが指定されていない場合に、既定の出力パスを生成します。

output 引数が指定されている場合はそれを優先します。 input_value が "clip" の場合、既定で clipboard_ocr.md を返します。それ以外の場合、input_value の拡張子を .md に変更したパスを返します。

パラメータ:

input_value (str) -- 入力ファイルのパス、または "clip"。
output (Optional[str]) -- ユーザーが指定した出力パス。

戻り値:

生成された出力ファイルのパス。

戻り値の型:

Path

ai.convert_ocr.ensure_clipboard_image(work_dir: Path) → Path[ソース]

クリップボードに画像が存在する場合、それを一時ファイルとして保存します。

Pillowの ImageGrab を使用してクリップボードから画像データを取得し、指定された作業ディレクトリ内に clipboard_input.png として保存します。

パラメータ:: work_dir (Path) -- 画像を保存する作業ディレクトリへのパス。
戻り値:: 保存された画像ファイルへのパス。
戻り値の型:: Path
例外:: RuntimeError -- Pillow.ImageGrabが利用できない場合、またはクリップボードに画像が含まれていない場合。

ai.convert_ocr.eprint(*args: object, **kwargs: object) → None[ソース]

標準エラー出力にメッセージを出力します。

print 関数と同じ引数を受け取りますが、出力先は sys.stderr です。デバッグ情報やエラーメッセージの表示に便利です。

パラメータ:

args (object) -- print 関数に渡される位置引数。
kwargs (object) -- print 関数に渡されるキーワード引数。特に file=sys.stderr が設定されます。

戻り値:

なし

戻り値の型:

None

ai.convert_ocr.init_genai_environment(ai_env: str | None) → None[ソース]

指定された環境変数ファイルからGenAI関連の環境変数を読み込み、設定します。

ファイルが存在する場合、その中の key=value 形式の各行を環境変数として設定します。ただし、すでに同じキーの環境変数が存在する場合は上書きしません。

パラメータ:: ai_env (Optional[str]) -- 環境変数が定義されているファイルへのパス。None の場合、何もしません。
戻り値:: なし
戻り値の型:: None

ai.convert_ocr.load_genai_prompt(ini_path: str | None) → str[ソース]

指定されたINIファイルからGenAIプロンプトを読み込みます。

INIファイルが見つからない、またはプロンプトキースが存在しない場合、既定のプロンプト (DEFAULT_GENAI_PROMPT) を使用します。プロンプトは PROMPT, PROMPT_TEMPLATE_JA, PROMPT_TEMPLATE_EN の順で検索されます。

パラメータ:: ini_path (Optional[str]) -- プロンプトが定義されているINIファイルへのパス。None の場合、既定のプロンプトを使用。
戻り値:: 読み込まれた、または既定のプロンプト文字列。
戻り値の型:: str

ai.convert_ocr.main(argv: Sequence[str] | None = None) → int[ソース]

スクリプトのメインエントリポイントです。

コマンドライン引数を解析し、OCR処理のフロー全体を管理します。具体的には、以下の処理を実行します: 1. 引数解析。 2. --list オプションが指定された場合、利用可能性レポートを表示して終了。 3. 入力値のチェックと出力パスの決定。 4. 作業ディレクトリの準備（一時ディレクトリまたは指定されたディレクトリ）。 5. 入力タイプに応じて画像を収集 (クリップボード、画像ファイル、PDF、Office文書)。 6. 選択されたOCRエンジン (TesseractまたはGenAI) で画像からテキストを抽出。 7. 抽出されたテキストと画像情報からMarkdownファイルを構築。 8. Markdownファイルを作業ディレクトリに出力パスに書き込み。 9. エラー処理と、必要に応じて一時ディレクトリのクリーンアップ。

パラメータ:: argv (Optional[Sequence[str]]) -- コマンドライン引数のリスト。None の場合、sys.argv を使用します。
戻り値:: 成功時は 0、エラー時は 1 (一般的なエラー) または 2 (引数エラー) の終了コード。
戻り値の型:: int

ai.convert_ocr.parse_args(argv: Sequence[str] | None = None) → Namespace[ソース]

コマンドライン引数を解析します。

入力ファイル、出力ファイル、OCRエンジン、言語、DPI、一時ファイル保持設定などの各種コマンドラインオプションを解析し、argparse.Namespace オブジェクトとして返します。

パラメータ:: argv (Optional[Sequence[str]]) -- コマンドライン引数のリスト。None の場合、sys.argv を使用します。
戻り値:: 解析された引数を格納する argparse.Namespace オブジェクト。
戻り値の型:: argparse.Namespace

ai.convert_ocr.probe_genai_backend() → Tuple[bool, str][ソース]

利用可能なGenAIバックエンドをプローブ（調査）します。

tkai_lib または google.generativeai のいずれかが現在の環境でインポート可能かを確認します。

戻り値:: 利用可能かどうかの真偽値と、利用可能なバックエンドを示す文字列のタプル。いずれも利用できない場合は (False, "tkai_lib または google-generativeai が必要") を返します。
戻り値の型:: Tuple[bool, str]

ai.convert_ocr.read_simple_ini(path: Path) → Dict[str, str][ソース]

key=value 形式の簡易 INI ファイルを読み込み、辞書として返します。

# または ; で始まるコメント行、および空行をスキップします。三連引用符（''' または """）で囲まれた複数行の値に対応しています。値に含まれる $VAR 形式の環境変数参照は、その環境変数の値に展開されます。

パラメータ:: path (Path) -- 読み込むINIファイルへのパス。
戻り値:: INIファイルから読み込んだキーと値の辞書。
戻り値の型:: Dict[str, str]

ai.convert_ocr.render_pdf_to_images(pdf_path: Path, out_dir: Path, dpi: int) → List[ImageItem][ソース]

PDFファイル内の各ページを画像としてレンダリングします。

PyMuPDF (fitz) を使用してPDFの各ページを指定されたDPIでPNG画像に変換し、指定された出力ディレクトリに保存します。

パラメータ:

pdf_path (Path) -- レンダリングするPDFファイルへのパス。
out_dir (Path) -- レンダリングされた画像を保存するディレクトリへのパス。
dpi (int) -- 画像の解像度 (dots per inch)。

戻り値:

レンダリングされた各画像の ImageItem オブジェクトのリスト。

戻り値の型:

List[ImageItem]

例外:

RuntimeError -- PyMuPDF (fitz) が利用できない場合。

ai.convert_ocr.slugify_filename(name: str) → str[ソース]

ファイル名をURLフレンドリーな形式（スラッグ）に変換します。

ファイル名として適さない文字（英数字、ピリオド、アンダースコア、ハイフン以外の文字）をアンダースコアに置換します。

パラメータ:: name (str) -- 変換するファイル名または文字列。
戻り値:: 変換されたスラッグ形式のファイル名。
戻り値の型:: str

ai.convert_ocr.tesseract_ocr_image(image_path: Path, lang: str = 'jpn+eng') → str[ソース]

Tesseract OCRエンジンを使用して画像からテキストを抽出します。

pytesseract ライブラリを介して、指定された画像ファイルから指定された言語でテキストを抽出します。

パラメータ:

image_path (Path) -- OCRを実行する画像ファイルへのパス。
lang (str) -- OCRに使用する言語コード (例: "jpn", "eng", "jpn+eng")。

戻り値:

画像から抽出されたテキスト。

戻り値の型:

str

例外:

RuntimeError -- pytesseractまたはPillowが利用できない場合。

ai.convert_ocr.which(cmd: str) → str | None[ソース]

指定されたコマンドがシステムPATH上に存在するかを確認し、そのパスを返します。

shutil.which のラッパー関数です。

パラメータ:: cmd (str) -- 検索するコマンド名。
戻り値:: コマンドの絶対パス、または見つからなかった場合は None。
戻り値の型:: Optional[str]