diff --git a/docs/images/layout-ocr-flow.png b/docs/images/layout-ocr-flow.png new file mode 100644 index 000000000..3b9a2e1ec Binary files /dev/null and b/docs/images/layout-ocr-flow.png differ diff --git a/docs/installation.rst b/docs/installation.rst index 512545701..03b8e5031 100644 --- a/docs/installation.rst +++ b/docs/installation.rst @@ -330,4 +330,9 @@ So for a working OCR functionality, make sure to complete this checklist: * Windows: `setx TESSDATA_PREFIX "C:/Program Files/Tesseract-OCR/tessdata"` * Unix systems: `declare -x TESSDATA_PREFIX=/usr/share/tesseract-ocr/4.00/tessdata` + +.. note:: + + Find out more on the `official documentation for installing Tesseract website `_. + .. include:: footer.rst diff --git a/docs/locales/ja/LC_MESSAGES/pymupdf-layout/index.mo b/docs/locales/ja/LC_MESSAGES/pymupdf-layout/index.mo index a0fdfd1d1..3adc97408 100644 Binary files a/docs/locales/ja/LC_MESSAGES/pymupdf-layout/index.mo and b/docs/locales/ja/LC_MESSAGES/pymupdf-layout/index.mo differ diff --git a/docs/locales/ja/LC_MESSAGES/pymupdf-layout/index.po b/docs/locales/ja/LC_MESSAGES/pymupdf-layout/index.po index ce350964f..31efbb49e 100644 --- a/docs/locales/ja/LC_MESSAGES/pymupdf-layout/index.po +++ b/docs/locales/ja/LC_MESSAGES/pymupdf-layout/index.po @@ -193,11 +193,11 @@ msgstr "OCR サポート" #: ../../pymupdf-layout/index.rst:124 99eb4f65329d45c7bb6eaf035c255259 msgid "" -"The new layout-sensitive PyMuPDF4LLM version also evaluates whether a " +"The new layout-sensitive |PyMuPDF4LLM| version also evaluates whether a " "page would benefit from applying OCR to it. If its heuristics come to " "this conclusion, the built-in Tesseract-OCR module is automatically " "invoked. Its results are then handled like normal page content." -msgstr "新しいレイアウト対応の PyMuPDF4LLM バージョンは、ページに OCR を適用することが有益かどうかも評価します。ヒューリスティックがこの結論に達した場合、組み込みの **Tesseract-OCR** モジュールが自動的に呼び出されます。その結果は、通常のページコンテンツと同様に処理されます。" +msgstr "新しいレイアウト対応の |PyMuPDF4LLM| バージョンは、ページに OCR を適用することが有益かどうかも評価します。ヒューリスティックがこの結論に達した場合、組み込みの **Tesseract-OCR** モジュールが自動的に呼び出されます。その結果は、通常のページコンテンツと同様に処理されます。" #: ../../pymupdf-layout/index.rst:126 cdbf9a9f1f5341cc96aaaa1a6a74434f msgid "" @@ -205,7 +205,7 @@ msgid "" "or many character-sized vectors, a check is made using `OpenCV " "`_ whether text is *probably* " "detectable on the page at all. This is done to tell apart image-based " -"text from ordinary pictures (like photographies)." +"text from ordinary pictures (like photographs)." msgstr "ページにテキストがほとんど含まれていないが、画像や多数の文字サイズのベクターで覆われている場合、`OpenCV `_ を使用して、ページ上でテキストが検出可能かどうかをチェックします。これは、画像ベースのテキストを通常の写真などの画像と区別するために行われます。" #: ../../pymupdf-layout/index.rst:128 8c8ba1c1b2bc4875b04cc60b98293a08 @@ -218,10 +218,24 @@ msgstr "ページにテキストが含まれているものの、読み取り不 #: ../../pymupdf-layout/index.rst:130 225a390ebce94321a090f94ab2165c16 msgid "" -"For these heuristics to work we need both, an existing Tesseract " -"installation and the availability of OpenCV in the Python environment. If" +"For these heuristics to work we need both, an existing :ref:`Tesseract installation ` and the availability of `OpenCV `_ in the Python environment. If" " either is missing, no OCR is attempted at all." -msgstr "これらのヒューリスティックが機能するには、Tesseract のインストールと Python 環境での OpenCV の利用可能性の両方が必要です。どちらか一方が欠けている場合、OCR はまったく試行されません。" +msgstr "これらのヒューリスティックが機能するには、 :ref:`Tesseract installation ` のインストールと Python 環境での `OpenCV `_ の利用可能性の両方が必要です。どちらか一方が欠けている場合、OCR はまったく試行されません。" + +msgid "The decision tree for whether OCR is actually used or not depends on the following:" +msgstr "OCRが実際に使用されるかどうかの決定木は、以下に依存します" + +msgid ":ref:`PyMuPDF Layout is imported `" +msgstr "PyMuPDF Layoutがインポートされている" + +msgid "In the :ref:`PyMuPDF4LLM API ` you have `use_ocr` enabled (this is set to `True` by default)" +msgstr ":ref:`PyMuPDF4LLM API ` で ``use_ocr`` が有効になっている（これはデフォルトで ``True`` に設定されています）" + +msgid ":ref:`Tesseract is correctly installed `" +msgstr ":ref:`Tesseractが正しくインストールされている `" + +msgid "`OpenCV `_ is available in your Python environment" +msgstr "`OpenCV `_ がPython環境で利用可能である" #: ../../pymupdf-layout/index.rst:137 fddcc1ea96e64c658554704bb141490b msgid "|PyMuPDF Layout| and |PyMuPDF4LLM| parameter caveats" diff --git a/docs/locales/ja/LC_MESSAGES/pymupdf4llm/api.mo b/docs/locales/ja/LC_MESSAGES/pymupdf4llm/api.mo index 302237f84..3a1abbd60 100644 Binary files a/docs/locales/ja/LC_MESSAGES/pymupdf4llm/api.mo and b/docs/locales/ja/LC_MESSAGES/pymupdf4llm/api.mo differ diff --git a/docs/locales/ja/LC_MESSAGES/pymupdf4llm/api.po b/docs/locales/ja/LC_MESSAGES/pymupdf4llm/api.po index fbd5689ab..bd4a5ed3f 100644 --- a/docs/locales/ja/LC_MESSAGES/pymupdf4llm/api.po +++ b/docs/locales/ja/LC_MESSAGES/pymupdf4llm/api.po @@ -56,53 +56,56 @@ msgstr "ファイルのページを読み取り、各ページのテキストを msgid "the file, to be specified either as a file path string, or as a |PyMuPDF| :class:`Document` (created via `pymupdf.open`). In order to use `pathlib.Path` specifications, Python file-like objects, documents in memory etc. you **must** use a |PyMuPDF| :class:`Document`." msgstr "ファイルは、ファイルパス文字列、または |PyMuPDF| :class:`Document` (``pymupdf.open`` で作成) のいずれかで指定します。``pathlib.Path`` 指定、Pythonファイル風オブジェクト、メモリ内ドキュメントなどを使用する場合は、|PyMuPDF| :class:`Document` を **必ず** 使用してください。" -msgid "does a simple check for the general background color of the pages (default is ``True``). If any text or vector has this color it will be ignored. May increase detection accuracy. **Ignored in "layout mode".**" -msgstr "ページの全体的な背景色を簡易的にチェックします（デフォルトは ``True``）。テキストやベクターがこの色の場合、無視されます。検出精度が向上する可能性があります。**「レイアウトモード」では無視されます。**" +msgid "|PyMuPDFLayoutMode_Ignored| does a simple check for the general background color of the pages (default is ``True``). If any text or vector has this color it will be ignored. May increase detection accuracy." +msgstr "|PyMuPDFLayoutMode_Ignored| ページの全体的な背景色を簡易的にチェックします（デフォルトは ``True``）。テキストやベクターがこの色の場合、無視されます。検出精度が向上する可能性があります。" msgid "specify the desired image resolution in dots per inch. Relevant only if `write_images=True` or `embed_images=True`. Default value is 150." msgstr "希望する画像解像度をドット・パー・インチ（DPI）で指定します。``write_images=True`` または ``embed_images=True`` の場合のみ有効です。デフォルト値は150です。" -msgid "specify the desired image resolution in dots per inch for applying OCR to the intermediate image of the page. Default value is 400. Only relevant if the page has been determined to profit from OCR (no or few text, most of the page covered by images or character-like vectors, etc.). Large values may increase the OCR precision but increase memory requirements and processing time. There also is a risk of over-sharpening the image which may decrease OCR precision. So the default value should probably be sufficiently high. **Only valid in "layout mode".**" -msgstr "ページの中間画像にOCRを適用する際の希望する画像解像度をドット・パー・インチ（DPI）で指定します。デフォルト値は400です。ページがOCRの恩恵を受けると判断された場合（テキストが無いまたは少ない、ページの大部分が画像または文字のようなベクターで覆われているなど）のみ有効です。大きな値を指定するとOCRの精度が向上する可能性がありますが、メモリ要件と処理時間が増加します。また、画像が過度にシャープ化されてOCRの精度が低下するリスクもあります。そのため、デフォルト値はおそらく十分に高い値となっています。**「レイアウトモード」でのみ有効です。**" +msgid "|PyMuPDFLayoutMode_Valid| use :ref:`OCR capability ` to help analyse the page." +msgstr "|PyMuPDFLayoutMode_Valid| :ref:`OCR機能 ` を使用してページの分析を支援します。" + +msgid "|PyMuPDFLayoutMode_Valid| specify the desired image resolution in dots per inch for applying OCR to the intermediate image of the page. Default value is 400. Only relevant if the page has been determined to profit from OCR (no or few text, most of the page covered by images or character-like vectors, etc.). Large values may increase the OCR precision but increase memory requirements and processing time. There also is a risk of over-sharpening the image which may decrease OCR precision. So the default value should probably be sufficiently high." +msgstr "|PyMuPDFLayoutMode_Valid| ページの中間画像にOCRを適用する際の希望する画像解像度をドット・パー・インチ（DPI）で指定します。デフォルト値は400です。ページがOCRの恩恵を受けると判断された場合（テキストが無いまたは少ない、ページの大部分が画像または文字のようなベクターで覆われているなど）のみ有効です。大きな値を指定するとOCRの精度が向上する可能性がありますが、メモリ要件と処理時間が増加します。また、画像が過度にシャープ化されてOCRの精度が低下するリスクもあります。そのため、デフォルト値はおそらく十分に高い値となっています。" msgid "like `write_images`, but images will be included in the markdown text as base64-encoded strings. Mutually exclusive with `write_images` and ignores `image_path`. This may drastically increase the size of your markdown text." msgstr "``write_images`` と同様ですが、画像はbase64エンコードされた文字列としてマークダウンテキストに含まれます。``write_images`` とは相互排他的であり、``image_path`` は無視されます。これによりマークダウンテキストのサイズが大幅に増加する可能性があります。" -msgid "a value of `True` enforces `page_chunks=True` and adds key "words" to each page dictionary. Its value is a list of words as delivered by PyMuPDF's `Page` method `get_text("words")`. The sequence of the words in this list is the same as the extracted text. **Ignored in "layout mode".**" -msgstr "``True`` を指定すると ``page_chunks=True`` が強制され、各ページの辞書にキー「words」が追加されます。その値は、PyMuPDFの ``Page`` メソッド ``get_text("words")`` によって提供される単語のリストです。このリスト内の単語の順序は、抽出されたテキストと同じです。**「レイアウトモード」では無視されます。**" +msgid "|PyMuPDFLayoutMode_Ignored| a value of `True` enforces `page_chunks=True` and adds key "words" to each page dictionary. Its value is a list of words as delivered by PyMuPDF's `Page` method `get_text("words")`. The sequence of the words in this list is the same as the extracted text." +msgstr "|PyMuPDFLayoutMode_Ignored| ``True`` を指定すると ``page_chunks=True`` が強制され、各ページの辞書にキー「words」が追加されます。その値は、PyMuPDFの ``Page`` メソッド ``get_text("words")`` によって提供される単語のリストです。このリスト内の単語の順序は、抽出されたテキストと同じです。**「レイアウトモード」では無視されます。**" msgid "Overwrites or sets the desired image file name of written images. Useful when the document is provided as a memory object (which has no inherent file name)." msgstr "書き込まれる画像の希望するファイル名を上書きまたは設定します。ドキュメントがメモリオブジェクト（固有のファイル名を持たない）として提供される場合に便利です。" -msgid "limit the font size to consider for text extraction. If the font size is lower than what is set then the text won't be considered for extraction. Default is `3`, meaning only text with a font size `>= 3` will be considered for extraction. **Ignored in "layout mode".**" -msgstr "テキスト抽出時に考慮するフォントサイズの下限を設定します。フォントサイズが設定値より小さい場合、そのテキストは抽出対象として考慮されません。デフォルトは ``3`` で、フォントサイズが ``>= 3`` のテキストのみが抽出対象として考慮されます。**「レイアウトモード」では無視されます。**" +msgid "|PyMuPDFLayoutMode_Ignored| limit the font size to consider for text extraction. If the font size is lower than what is set then the text won't be considered for extraction. Default is `3`, meaning only text with a font size `>= 3` will be considered for extraction." +msgstr "|PyMuPDFLayoutMode_Ignored| テキスト抽出時に考慮するフォントサイズの下限を設定します。フォントサイズが設定値より小さい場合、そのテキストは抽出対象として考慮されません。デフォルトは ``3`` で、フォントサイズが ``>= 3`` のテキストのみが抽出対象として考慮されます。" -msgid "boolean to switch on/off page footer content. This parameter controls whether to include or omit footer text from all the document pages. Useful if the document has repetitive footer content which doesn't add any value to the overall extraction data. Default is `True` meaning that footer content will be considered. **Only valid in "layout mode".**" -msgstr "ページフッターの内容を含めるか除外するかを切り替えるブール値です。このパラメータは、ドキュメント全ページのフッターテキストを含めるか省略するかを制御します。ドキュメントに繰り返しのフッター内容があり、全体的な抽出データに価値を追加しない場合に便利です。デフォルトは ``True`` で、フッターの内容が考慮されることを意味します。**「レイアウトモード」でのみ有効です。**" +msgid "|PyMuPDFLayoutMode_Valid| boolean to switch on/off page footer content. This parameter controls whether to include or omit footer text from all the document pages. Useful if the document has repetitive footer content which doesn't add any value to the overall extraction data. Default is `True` meaning that footer content will be considered." +msgstr "|PyMuPDFLayoutMode_Valid| ページフッターの内容を含めるか除外するかを切り替えるブール値です。このパラメータは、ドキュメント全ページのフッターテキストを含めるか省略するかを制御します。ドキュメントに繰り返しのフッター内容があり、全体的な抽出データに価値を追加しない場合に便利です。デフォルトは ``True`` で、フッターの内容が考慮されることを意味します。" msgid "generate text output even when overlapping images / graphics. This text then appears after the respective image." msgstr "画像やグラフィックが重なっている場合でもテキスト出力を生成します。このテキストは該当する画像の後に表示されます。" -msgid "use this to limit dealing with excess amounts of vector graphics elements. Scientific documents, or pages simulating text via graphics commands may contain tens of thousands of these objects. As vector graphics are analyzed for multiple purposes, runtime may quickly become intolerable. With this parameter, all vector graphics will be ignored if their count exceeds the threshold. **Ignored in "layout mode".**" -msgstr "過剰な量のベクターグラフィック要素への対処を制限するために使用します。科学文書や、グラフィックコマンドでテキストをシミュレートするページには、これらのオブジェクトが数万個含まれている場合があります。ベクターグラフィックは複数の目的で分析されるため、実行時間がすぐに許容できないレベルになる可能性があります。このパラメータを使用すると、ベクターグラフィックの数が閾値を超えた場合、すべてのベクターグラフィックが無視されます。**「レイアウトモード」では無視されます。**" +msgid "|PyMuPDFLayoutMode_Ignored| use this to limit dealing with excess amounts of vector graphics elements. Scientific documents, or pages simulating text via graphics commands may contain tens of thousands of these objects. As vector graphics are analyzed for multiple purposes, runtime may quickly become intolerable. With this parameter, all vector graphics will be ignored if their count exceeds the threshold." +msgstr "|PyMuPDFLayoutMode_Ignored| 過剰な量のベクターグラフィック要素への対処を制限するために使用します。科学文書や、グラフィックコマンドでテキストをシミュレートするページには、これらのオブジェクトが数万個含まれている場合があります。ベクターグラフィックは複数の目的で分析されるため、実行時間がすぐに許容できないレベルになる可能性があります。このパラメータを使用すると、ベクターグラフィックの数が閾値を超えた場合、すべてのベクターグラフィックが無視されます。" -msgid "use this if you want to provide your own header detection logic. This may be a callable or an object having a method named `get_header_id`. It must accept a text span (a span dictionary as contained in :meth:`~.extractDICT`) and a keyword parameter "page" (which is the owning :ref:`Page ` object). It must return a string "" or up to 6 "#" characters followed by 1 space. If omitted (`None`), a full document scan will be performed to find the most popular font sizes and derive header levels based on them. To completely avoid this behavior specify `hdr_info=lambda s, page=None: ""` or `hdr_info=False`. **Ignored in "layout mode".**" -msgstr "独自のヘッダー検出ロジックを提供したい場合に使用します。これは、呼び出し可能オブジェクト、または ``get_header_id`` という名前のメソッドを持つオブジェクトです。テキストスパン（:meth:`~.extractDICT` に含まれるスパン辞書）とキーワードパラメータ「page」（所有する :ref:`Page ` オブジェクト）を受け入れる必要があります。空文字列 "" または最大6個の "#" 文字とその後に続く1つのスペースを返す必要があります。省略した場合（``None``）、ドキュメント全体がスキャンされ、最も一般的なフォントサイズを見つけ、それに基づいてヘッダーレベルが導出されます。この動作を完全に回避するには、``hdr_info=lambda s, page=None: ""`` または ``hdr_info=False`` を指定してください。**「レイアウトモード」では無視されます。**" +msgid "|PyMuPDFLayoutMode_Ignored| use this if you want to provide your own header detection logic. This may be a callable or an object having a method named `get_header_id`. It must accept a text span (a span dictionary as contained in :meth:`~.extractDICT`) and a keyword parameter "page" (which is the owning :ref:`Page ` object). It must return a string "" or up to 6 "#" characters followed by 1 space. If omitted (`None`), a full document scan will be performed to find the most popular font sizes and derive header levels based on them. To completely avoid this behavior specify `hdr_info=lambda s, page=None: ""` or `hdr_info=False`." +msgstr "|PyMuPDFLayoutMode_Ignored| 独自のヘッダー検出ロジックを提供したい場合に使用します。これは、呼び出し可能オブジェクト、または ``get_header_id`` という名前のメソッドを持つオブジェクトです。テキストスパン（:meth:`~.extractDICT` に含まれるスパン辞書）とキーワードパラメータ「page」（所有する :ref:`Page ` オブジェクト）を受け入れる必要があります。空文字列 "" または最大6個の "#" 文字とその後に続く1つのスペースを返す必要があります。省略した場合（``None``）、ドキュメント全体がスキャンされ、最も一般的なフォントサイズを見つけ、それに基づいてヘッダーレベルが導出されます。この動作を完全に回避するには、``hdr_info=lambda s, page=None: ""`` または ``hdr_info=False`` を指定してください。" -msgid "boolean to switch on/off page header content. This parameter controls whether we want to include or omit the header content from all the document pages. Useful if the document has repetitive header content which doesn't add any value to the overall extraction data. Default is `True` meaning that header content will be considered. **Only valid in \"layout mode\".**" -msgstr "ページヘッダーの内容を含めるか除外するかを切り替えるブール値です。このパラメータは、ドキュメント全ページのヘッダー内容を含めるか省略するかを制御します。ドキュメントに繰り返しのヘッダー内容があり、全体的な抽出データに価値を追加しない場合に便利です。デフォルトは ``True`` で、ヘッダーの内容が考慮されることを意味します。**「レイアウトモード」でのみ有効です。**" +msgid "|PyMuPDFLayoutMode_Valid| boolean to switch on/off page header content. This parameter controls whether we want to include or omit the header content from all the document pages. Useful if the document has repetitive header content which doesn't add any value to the overall extraction data. Default is `True` meaning that header content will be considered." +msgstr "|PyMuPDFLayoutMode_Valid| ページヘッダーの内容を含めるか除外するかを切り替えるブール値です。このパラメータは、ドキュメント全ページのヘッダー内容を含めるか省略するかを制御します。ドキュメントに繰り返しのヘッダー内容があり、全体的な抽出データに価値を追加しない場合に便利です。デフォルトは ``True`` で、ヘッダーの内容が考慮されることを意味します。" -msgid "if ``True`` includes text even when completely transparent. Default is ``False``: transparent text will be ignored which usually increases detection accuracy. **Ignored in \"layout mode\".**" -msgstr "``True`` の場合、完全に透明なテキストも含めます。デフォルトは ``False`` で、透明なテキストは無視され、通常は検出精度が向上します。**「レイアウトモード」では無視されます。**" +msgid "|PyMuPDFLayoutMode_Ignored| if ``True`` includes text even when completely transparent. Default is ``False``: transparent text will be ignored which usually increases detection accuracy." +msgstr "|PyMuPDFLayoutMode_Ignored| ``True`` の場合、完全に透明なテキストも含めます。デフォルトは ``False`` で、透明なテキストは無視され、通常は検出精度が向上します。**「レイアウトモード」では無視されます。**" msgid "if `True` then mono-spaced text lines do not receive special formatting. Code blocks will no longer be generated. This value is set to `True` if `extract_words=True` is used." msgstr "``True`` の場合、等幅テキスト行は特別なフォーマットを受けません。コードブロックは生成されなくなります。``extract_words=True`` が使用される場合、この値は ``True`` に設定されます。" -msgid "(New in v.0.0.20) Disregard vector graphics on the page. This may help detecting text correctly when pages are very crowded (often the case for documents representing presentation slides). Also speeds up processing time. This automatically prevents table detection. **Ignored in \"layout mode\".**" -msgstr "(v.0.0.20の新機能) ページ上のベクターグラフィックを無視します。ページが非常に混雑している場合（プレゼンテーションスライドを表すドキュメントでよくあるケース）、テキストを正しく検出するのに役立つ可能性があります。また、処理時間も短縮されます。これにより、テーブル検出が自動的に無効になります。**「レイアウトモード」では無視されます。**" +msgid "|PyMuPDFLayoutMode_Ignored| (New in v.0.0.20) Disregard vector graphics on the page. This may help detecting text correctly when pages are very crowded (often the case for documents representing presentation slides). Also speeds up processing time. This automatically prevents table detection." +msgstr "|PyMuPDFLayoutMode_Ignored| (v.0.0.20の新機能) ページ上のベクターグラフィックを無視します。ページが非常に混雑している場合（プレゼンテーションスライドを表すドキュメントでよくあるケース）、テキストを正しく検出するのに役立つ可能性があります。また、処理時間も短縮されます。これにより、テーブル検出が自動的に無効になります。" -msgid "(New in v.0.0.20) Disregard images on the page. This may help detecting text correctly when pages are very crowded (often the case for documents representing presentation slides). Also speeds up processing time. **Ignored in \"layout mode\".**" -msgstr "(v.0.0.20の新機能) ページ上の画像を無視します。ページが非常に混雑している場合（プレゼンテーションスライドを表すドキュメントでよくあるケース）、テキストを正しく検出するのに役立つ可能性があります。また、処理時間も短縮されます。**「レイアウトモード」では無視されます。**" +msgid "|PyMuPDFLayoutMode_Ignored| (New in v.0.0.20) Disregard images on the page. This may help detecting text correctly when pages are very crowded (often the case for documents representing presentation slides). Also speeds up processing time." +msgstr "|PyMuPDFLayoutMode_Ignored| (v.0.0.20の新機能) ページ上の画像を無視します。ページが非常に混雑している場合（プレゼンテーションスライドを表すドキュメントでよくあるケース）、テキストを正しく検出するのに役立つ可能性があります。また、処理時間も短縮されます。" msgid "specify the desired image format via its extension. Default is "png" (portable network graphics). Another popular format may be "jpg". Possible values are all :ref:`supported output formats `." msgstr "拡張子を使用して希望する画像形式を指定します。デフォルトは「png」（ポータブルネットワークグラフィックス）です。他の一般的な形式としては「jpg」があります。使用可能な値は、すべての :ref:`サポートされている出力形式 ` です。" @@ -110,11 +113,11 @@ msgstr "拡張子を使用して希望する画像形式を指定します。デ msgid "store images in this folder. Relevant if `write_images=True`. Default is the path of the script directory." msgstr "このフォルダに画像を保存します。``write_images=True`` の場合に有効です。デフォルトはスクリプトディレクトリのパスです。" -msgid "this must be a ``0 <= value < 1``. Images are ignored if `width / page.rect.width <= image_size_limit` or `height / page.rect.height <= image_size_limit`. For instance, the default value 0.05 means that to be considered for inclusion, an image's width and height must be larger than 5% of the page's width and height, respectively. **Ignored in "layout mode".**" -msgstr "``0 <= value < 1`` の値である必要があります。``width / page.rect.width <= image_size_limit`` または ``height / page.rect.height <= image_size_limit`` の場合、画像は無視されます。たとえば、デフォルト値の0.05は、画像が含まれる対象として考慮されるには、画像の幅と高さがそれぞれページの幅と高さの5%より大きくなければならないことを意味します。**「レイアウトモード」では無視されます。**" +msgid "|PyMuPDFLayoutMode_Ignored| this must be a ``0 <= value < 1``. Images are ignored if `width / page.rect.width <= image_size_limit` or `height / page.rect.height <= image_size_limit`. For instance, the default value 0.05 means that to be considered for inclusion, an image's width and height must be larger than 5% of the page's width and height, respectively." +msgstr "|PyMuPDFLayoutMode_Ignored| ``0 <= value < 1`` の値である必要があります。``width / page.rect.width <= image_size_limit`` または ``height / page.rect.height <= image_size_limit`` の場合、画像は無視されます。たとえば、デフォルト値の0.05は、画像が含まれる対象として考慮されるには、画像の幅と高さがそれぞれページの幅と高さの5%より大きくなければならないことを意味します。" -msgid "a float or a sequence of 2 or 4 floats specifying page borders. Only objects inside the margins will be considered for output. **Ignored in "layout mode".**" -msgstr "ページの境界を指定する浮動小数点数、または2個もしくは4個の浮動小数点数のシーケンスです。マージン内のオブジェクトのみが出力対象として考慮されます。**「レイアウトモード」では無視されます。**" +msgid "|PyMuPDFLayoutMode_Ignored| a float or a sequence of 2 or 4 floats specifying page borders. Only objects inside the margins will be considered for output." +msgstr "|PyMuPDFLayoutMode_Ignored| ページの境界を指定する浮動小数点数、または2個もしくは4個の浮動小数点数のシーケンスです。マージン内のオブジェクトのみが出力対象として考慮されます。" msgid "`margin=f` yields `(f, f, f, f)` for `(left, top, right, bottom)`." msgstr "``margin=f`` は ``(left, top, right, bottom)`` に対して ``(f, f, f, f)`` を生成します。" @@ -137,17 +140,17 @@ msgstr "**"toc_items"** - このページを指す目次項目のリストです msgid "**\"tables\"** - a list of tables on this page. Each item is a dictionary with keys \"bbox\", \"row_count\" and \"col_count\". Key \"bbox\" is a `pymupdf.Rect` in tuple format of the table's position on the page." msgstr "**"tables"** - このページ上のテーブルのリストです。各項目は、キー「bbox」、「row_count」、「col_count」を持つ辞書です。キー「bbox」は、ページ上のテーブルの位置を示すタプル形式の ``pymupdf.Rect`` です。" -msgid "**\"images\"** - a list of images on the page. This a copy of page method :meth:`Page.get_image_info`. **Empty list in \"layout mode\".**" -msgstr "**\"images\"** - ページ上の画像のリストです。これは、ページメソッド :meth:`Page.get_image_info` のコピーです。**「レイアウトモード」では空のリストです。**" +msgid "**\"images\"** - |PyMuPDFLayoutMode_EmptyList| a list of images on the page. This a copy of page method :meth:`Page.get_image_info`." +msgstr "**\"images\"** - |PyMuPDFLayoutMode_EmptyList| ページ上の画像のリストです。これは、ページメソッド :meth:`Page.get_image_info` のコピーです。" -msgid "**\"graphics\"** - a list of vector graphics rectangles on the page. This is a list of boundary boxes of clustered vector graphics as delivered by method :meth:`Page.cluster_drawings`. **Empty list in \"layout mode\".**" -msgstr "**\"graphics\"** - ページ上のベクターグラフィック矩形のリストです。これは、メソッド :meth:`Page.cluster_drawings` によって提供されるクラスタ化されたベクターグラフィックのバウンディングボックスのリストです。**「レイアウトモード」では空のリストです。**" +msgid "**\"graphics\"** - |PyMuPDFLayoutMode_EmptyList| a list of vector graphics rectangles on the page. This is a list of boundary boxes of clustered vector graphics as delivered by method :meth:`Page.cluster_drawings`." +msgstr "**\"graphics\"** - |PyMuPDFLayoutMode_EmptyList| ページ上のベクターグラフィック矩形のリストです。これは、メソッド :meth:`Page.cluster_drawings` によって提供されるクラスタ化されたベクターグラフィックのバウンディングボックスのリストです。" msgid "**\"text\"** - page content as |Markdown| text." msgstr "**\"text\"** - |Markdown| テキストとしてのページ内容です。" -msgid "**\"words\"** - if `extract_words=True` was used. This is a list of tuples `(x0, y0, x1, y1, \"wordstring\", bno, lno, wno)` as delivered by `page.get_text(\"words\")`. The **sequence** of these tuples however is the same as produced in the markdown text string and thus honors multi-column text. This is also true for text in tables: words are extracted in the sequence of table row cells. **Empty list in \"layout mode\".**" -msgstr "**\"words\"** - ``extract_words=True`` が使用された場合に含まれます。これは、``page.get_text("words")`` によって提供されるタプル ``(x0, y0, x1, y1, "wordstring", bno, lno, wno)`` のリストです。ただし、これらのタプルの **順序** はマークダウンテキスト文字列で生成される順序と同じであり、したがってマルチカラムテキストを尊重します。これはテーブル内のテキストにも当てはまります。単語はテーブル行のセルの順序で抽出されます。**「レイアウトモード」では空のリストです。**" +msgid "**\"words\"** - |PyMuPDFLayoutMode_EmptyList| if `extract_words=True` was used. This is a list of tuples `(x0, y0, x1, y1, \"wordstring\", bno, lno, wno)` as delivered by `page.get_text(\"words\")`. The **sequence** of these tuples however is the same as produced in the markdown text string and thus honors multi-column text. This is also true for text in tables: words are extracted in the sequence of table row cells." +msgstr "**\"words\"** - |PyMuPDFLayoutMode_EmptyList| ``extract_words=True`` が使用された場合に含まれます。これは、``page.get_text("words")`` によって提供されるタプル ``(x0, y0, x1, y1, "wordstring", bno, lno, wno)`` のリストです。ただし、これらのタプルの **順序** はマークダウンテキスト文字列で生成される順序と同じであり、したがってマルチカラムテキストを尊重します。これはテーブル内のテキストにも当てはまります。単語はテーブル行のセルの順序で抽出されます。" msgid "specify a desired page height. For relevance see the `page_width` parameter. If using the default `None`, the document will appear as one large page with a width of `page_width`. Consequently in this case, no markdown page separators will occur (except the final one), respectively only one page chunk will be returned." msgstr "希望するページの高さを指定します。関連性については ``page_width`` パラメータを参照してください。デフォルトの ``None`` を使用する場合、ドキュメントは ``page_width`` の幅を持つ1つの大きなページとして表示されます。したがって、この場合、マークダウンページ区切り文字は発生せず（最後のものを除く）、それぞれ1つのページチャンクのみが返されます。" @@ -165,17 +168,17 @@ msgstr "オプションで、出力対象として考慮するページを指定 msgid "Default is `False`. A value of `True` displays a progress bar as pages are being converted. Package `tqdm `_ is used if installed, otherwise the built-in text based progress bar is used." msgstr "デフォルトは ``False`` です。``True`` を指定すると、ページが変換される際に進捗バーが表示されます。インストールされている場合はパッケージ `tqdm `_ が使用され、それ以外の場合は組み込みのテキストベースの進捗バーが使用されます。" -msgid "see: :meth:`table detection strategy `. Default is `"lines_strict"` which ignores background colors. In some occasions, other strategies may be more successful, for example `"lines"` which uses all vector graphics objects for detection. **Ignored in \"layout mode\".**" -msgstr "参照: :meth:`テーブル検出戦略 `。デフォルトは ``"lines_strict"`` で、背景色を無視します。状況によっては、他の戦略がより成功する場合があります。たとえば、すべてのベクターグラフィックオブジェクトを検出に使用する ``"lines"`` などです。**「レイアウトモード」では無視されます。**" +msgid "|PyMuPDFLayoutMode_Ignored| see: :meth:`table detection strategy `. Default is `"lines_strict"` which ignores background colors. In some occasions, other strategies may be more successful, for example `"lines"` which uses all vector graphics objects for detection." +msgstr "|PyMuPDFLayoutMode_Ignored| 参照: :meth:`テーブル検出戦略 `。デフォルトは ``"lines_strict"`` で、背景色を無視します。状況によっては、他の戦略がより成功する場合があります。たとえば、すべてのベクターグラフィックオブジェクトを検出に使用する ``"lines"`` などです。" -msgid "(New in v.0.0.19) Default is `False`. A value of `True` will use the glyph number of the characters instead of the character itself if the font does not store the Unicode value. **Ignored in \"layout mode\".**" -msgstr "(v.0.0.19の新機能) デフォルトは ``False`` です。``True`` を指定すると、フォントがUnicode値を保存していない場合、文字自体の代わりに文字のグリフ番号が使用されます。**「レイアウトモード」では無視されます。**" +msgid "|PyMuPDFLayoutMode_Ignored| (New in v.0.0.19) Default is `False`. A value of `True` will use the glyph number of the characters instead of the character itself if the font does not store the Unicode value." +msgstr "|PyMuPDFLayoutMode_Ignored| (v.0.0.19の新機能) デフォルトは ``False`` です。``True`` を指定すると、フォントがUnicode値を保存していない場合、文字自体の代わりに文字のグリフ番号が使用されます。" msgid "when encountering images or vector graphics, images will be created from the respective page area and stored in the specified folder. |Markdown| references will be generated pointing to these images. Any text contained in these areas will not be included in the text output (but appear as part of the images). Therefore, if for instance your document has text written on full page images, make sure to set this parameter to `False`." msgstr "画像またはベクターグラフィックに遭遇した場合、該当するページ領域から画像が作成され、指定されたフォルダに保存されます。これらの画像を指す |Markdown| 参照が生成されます。これらの領域に含まれるテキストは、テキスト出力には含まれません（ただし、画像の一部として表示されます）。したがって、たとえば、ドキュメントにフルページ画像上に書かれたテキストがある場合は、このパラメータを ``False`` に設定してください。" -msgid "In \"layout mode\", boundary boxes that are classified as \"picture\" by the layout module will be treated as images - independent from the mixture of text, images or vector graphics they may be covering. If `force_text=True` is used, text will still be extracted from these areas and included in the output after the respective image reference." -msgstr "「レイアウトモード」では、レイアウトモジュールによって「picture」として分類されたバウンディングボックスは、テキスト、画像、またはベクターグラフィックの混在に関係なく、画像として扱われます。``force_text=True`` が使用された場合、これらの領域からテキストが抽出され、該当する画像参照の後に出力に含まれます。" +msgid "If using :ref:`PyMuPDF Layout `, boundary boxes that are classified as "picture" by the layout module will be treated as images - independent from the mixture of text, images or vector graphics they may be covering. If `force_text=True` is used, text will still be extracted from these areas and included in the output after the respective image reference." +msgstr ":ref:`PyMuPDF Layout ` を使用する場合、レイアウトモジュールによって「picture」として分類されたバウンディングボックスは、テキスト、画像、またはベクターグラフィックの混在に関係なく、画像として扱われます。``force_text=True`` が使用された場合、これらの領域からテキストが抽出され、該当する画像参照の後に出力に含まれます。" msgid "Either a string of the combined text of all selected document pages, or a list of dictionaries if `page_chunks=True`." msgstr "選択されたすべてのドキュメントページの結合されたテキストの文字列、または ``page_chunks=True`` の場合は辞書のリストです。" @@ -183,8 +186,8 @@ msgstr "選択されたすべてのドキュメントページの結合された msgid "Reads the pages of the file and outputs the text of its pages in |TXT| format." msgstr "ファイルのページを読み取り、各ページのテキストを |TXT| 形式で出力します。" -msgid "This method is only available in \"layout mode\", i.e. if the import of pymupdf4llm has happened **after** the statement ``import pymupdf.layout``" -msgstr "このメソッドは「レイアウトモード」でのみ利用可能です。つまり、pymupdf4llmのインポートが ``import pymupdf.layout`` ステートメントの **後に** 行われた場合のみです。" +msgid "|PyMuPDFLayoutMode_Valid|. This method is only available with PyMuPDF Layout." +msgstr "|PyMuPDFLayoutMode_Valid| このメソッドは「レイアウトモード」でのみ利用可能です。つまり、pymupdf4llmのインポートが ``import pymupdf.layout`` ステートメントの **後に** 行われた場合のみです。" msgid "the file, to be specified either as a file path string, or as a |PyMuPDF| :class:`Document` (created via `pymupdf.open`). In order to use `pathlib.Path` specifications, Python file-like objects, documents in memory etc. you **must** use a |PyMuPDF| :class:`Document`." msgstr "ファイルは、ファイルパス文字列、または |PyMuPDF| :class:`Document` (``pymupdf.open`` で作成) のいずれかで指定します。``pathlib.Path`` 指定、Pythonファイル風オブジェクト、メモリ内ドキュメントなどを使用する場合は、|PyMuPDF| :class:`Document` を **必ず** 使用してください。" @@ -210,8 +213,6 @@ msgstr "デフォルトは ``False`` です。``True`` を指定すると、ペ msgid "Parses the document and the specified pages and converts the result into a |JSON|-formatted string." msgstr "ドキュメントと指定されたページを解析し、結果を |JSON| 形式の文字列に変換します。" -msgid "This method is only available in \"layout mode\", i.e. if the import of pymupdf4llm has happened **after** the statement ``import pymupdf.layout`` " -msgstr "このメソッドは「レイアウトモード」でのみ利用可能です。つまり、pymupdf4llmのインポートが ``import pymupdf.layout`` ステートメントの **後に** 行われた場合のみです。" msgid "the file, to be specified either as a file path string, or as a |PyMuPDF| :class:`Document` (created via `pymupdf.open`). In order to use `pathlib.Path` specifications, Python file-like objects, documents in memory etc. you **must** use a |PyMuPDF| :class:`Document`." msgstr "ファイルは、ファイルパス文字列、または |PyMuPDF| :class:`Document` (``pymupdf.open`` で作成) のいずれかで指定します。``pathlib.Path`` 指定、Pythonファイル風オブジェクト、メモリ内ドキュメントなどを使用する場合は、|PyMuPDF| :class:`Document` を **必ず** 使用してください。" @@ -240,7 +241,7 @@ msgstr "「picture」バウンディングボックスの画像ファイルを msgid "optional, the pages to consider for output (caution: specify 0-based page numbers). If omitted (`None`) all pages are processed. Specify any valid Python sequence containing integers between `0` and `page_count - 1`." msgstr "オプションで、出力対象として考慮するページを指定します（注意:0ベースのページ番号を指定してください）。省略した場合（``None``）、すべてのページが処理されます。``0`` から ``page_count - 1`` の間の整数を含む任意の有効なPythonシーケンスを指定してください。" -msgid "Please see `this site `_ for more background and the current status of further improvements regarding layout mode." +msgid "Please see `this site `_ for more background and the current status of further improvements regarding usage with :ref:`PyMuPDF Layout `." msgstr "レイアウトモードに関する更なる改善の背景と現状については、`このサイト `_ をご覧ください。" msgid "Create a `pdf_markdown_reader.PDFMarkdownReader` using the `LlamaIndex`_ package. Please note that this package will **not automatically be installed** when installing **pymupdf4llm**." diff --git a/docs/pymupdf-layout/index.rst b/docs/pymupdf-layout/index.rst index a63bb7577..2168940e5 100644 --- a/docs/pymupdf-layout/index.rst +++ b/docs/pymupdf-layout/index.rst @@ -1,7 +1,7 @@ .. include:: ../header.rst -.. _pymupdf-layout +.. _pymupdf-layout: PyMuPDF Layout @@ -22,6 +22,8 @@ Install from |PyPI| with:: pip install pymupdf-layout +.. _pymupdf_layout_using: + Using ---------------------------------- @@ -118,16 +120,31 @@ Now we can happily load Office files and convert them as follows:: md = pymupdf4llm.to_markdown("sample.docx") +.. _pymupdf_layout_ocr_support: + OCR support ~~~~~~~~~~~~~~~~~ -The new layout-sensitive PyMuPDF4LLM version also evaluates whether a page would benefit from applying OCR to it. If its heuristics come to this conclusion, the built-in Tesseract-OCR module is automatically invoked. Its results are then handled like normal page content. +The new layout-sensitive |PyMuPDF4LLM| version also evaluates whether a page would benefit from applying OCR to it. If its heuristics come to this conclusion, the built-in Tesseract-OCR module is automatically invoked. Its results are then handled like normal page content. -If a page contains (roughly) no text at all, but is covered with images or many character-sized vectors, a check is made using `OpenCV `_ whether text is *probably* detectable on the page at all. This is done to tell apart image-based text from ordinary pictures (like photographies). +If a page contains (roughly) no text at all, but is covered with images or many character-sized vectors, a check is made using `OpenCV `_ whether text is *probably* detectable on the page at all. This is done to tell apart image-based text from ordinary pictures (like photographs). If the page does contain text but too many characters are unreadable (like "�����"), OCR is also executed, but **for the affected text areas only** -- not the full page. This way, we avoid losing already existing text and other content like images and vectors. -For these heuristics to work we need both, an existing Tesseract installation and the availability of OpenCV in the Python environment. If either is missing, no OCR is attempted at all. +For these heuristics to work we need both, an existing :ref:`Tesseract installation ` and the availability of `OpenCV `_ in the Python environment. If either is missing, no OCR is attempted at all. + +The decision tree for whether OCR is actually used or not depends on the following: + +1. :ref:`PyMuPDF Layout is imported ` + +2. In the :ref:`PyMuPDF4LLM API ` you have `use_ocr` enabled (this is set to `True` by default) + +3. :ref:`Tesseract is correctly installed ` + +4. `OpenCV `_ is available in your Python environment + + +.. image:: ../images/layout-ocr-flow.png ---- diff --git a/docs/pymupdf-pro/index.rst b/docs/pymupdf-pro/index.rst index 223e74755..8fb9102c2 100644 --- a/docs/pymupdf-pro/index.rst +++ b/docs/pymupdf-pro/index.rst @@ -2,7 +2,7 @@ .. include:: ../header.rst -.. _pymupdf-pro +.. _pymupdf-pro: PyMuPDF Pro ============= diff --git a/docs/pymupdf4llm/api.rst b/docs/pymupdf4llm/api.rst index c2dddcc49..e857132f2 100644 --- a/docs/pymupdf4llm/api.rst +++ b/docs/pymupdf4llm/api.rst @@ -1,10 +1,28 @@ .. include:: ../header.rst +.. |PyMuPDFLayoutMode_Ignored| raw:: html + + Ignored by PyMuPDF Layout + +.. |PyMuPDFLayoutMode_Valid| raw:: html + + Only valid with PyMuPDF Layout + +.. |PyMuPDFLayoutMode_EmptyList| raw:: html + + Empty list with PyMuPDF Layout + + +.. |PyMuPDFLayoutMode_Unavailable| raw:: html + + Unavailable in PyMuPDF Layout .. _pymupdf4llm-api: + + API =========================================================================== @@ -19,6 +37,7 @@ The |PyMuPDF4LLM| API .. method:: to_markdown(doc: pymupdf.Document | str, *, \ detect_bg_color: bool = True, \ dpi: int = 150, \ + use_ocr: bool = True, \ ocr_dpi: int = 400, \ embed_images: bool = False, \ extract_words: bool = False, \ @@ -51,45 +70,47 @@ The |PyMuPDF4LLM| API :arg Document,str doc: the file, to be specified either as a file path string, or as a |PyMuPDF| :class:`Document` (created via `pymupdf.open`). In order to use `pathlib.Path` specifications, Python file-like objects, documents in memory etc. you **must** use a |PyMuPDF| :class:`Document`. - :arg bool detect_bg_color: does a simple check for the general background color of the pages (default is ``True``). If any text or vector has this color it will be ignored. May increase detection accuracy. **Ignored in "layout mode".** + :arg bool detect_bg_color: |PyMuPDFLayoutMode_Ignored| does a simple check for the general background color of the pages (default is ``True``). If any text or vector has this color it will be ignored. May increase detection accuracy. :arg int dpi: specify the desired image resolution in dots per inch. Relevant only if `write_images=True` or `embed_images=True`. Default value is 150. - :arg int ocr_dpi: specify the desired image resolution in dots per inch for applying OCR to the intermediate image of the page. Default value is 400. Only relevant if the page has been determined to profit from OCR (no or few text, most of the page covered by images or character-like vectors, etc.). Large values may increase the OCR precision but increase memory requirements and processing time. There also is a risk of over-sharpening the image which may decrease OCR precision. So the default value should probably be sufficiently high. **Only valid in "layout mode".** + :arg bool use_ocr: |PyMuPDFLayoutMode_Valid| use :ref:`OCR capability ` to help analyse the page. + + :arg int ocr_dpi: |PyMuPDFLayoutMode_Valid| specify the desired image resolution in dots per inch for applying OCR to the intermediate image of the page. Default value is 400. Only relevant if the page has been determined to profit from OCR (no or few text, most of the page covered by images or character-like vectors, etc.). Large values may increase the OCR precision but increase memory requirements and processing time. There also is a risk of over-sharpening the image which may decrease OCR precision. So the default value should probably be sufficiently high. :arg bool embed_images: like `write_images`, but images will be included in the markdown text as base64-encoded strings. Mutually exclusive with `write_images` and ignores `image_path`. This may drastically increase the size of your markdown text. - :arg bool extract_words: a value of `True` enforces `page_chunks=True` and adds key "words" to each page dictionary. Its value is a list of words as delivered by PyMuPDF's `Page` method `get_text("words")`. The sequence of the words in this list is the same as the extracted text. **Ignored in "layout mode".** + :arg bool extract_words: |PyMuPDFLayoutMode_Ignored| a value of `True` enforces `page_chunks=True` and adds key "words" to each page dictionary. Its value is a list of words as delivered by PyMuPDF's `Page` method `get_text("words")`. The sequence of the words in this list is the same as the extracted text. :arg str filename: Overwrites or sets the desired image file name of written images. Useful when the document is provided as a memory object (which has no inherent file name). - :arg float fontsize_limit: limit the font size to consider for text extraction. If the font size is lower than what is set then the text won't be considered for extraction. Default is `3`, meaning only text with a font size `>= 3` will be considered for extraction. **Ignored in "layout mode".** + :arg float fontsize_limit: |PyMuPDFLayoutMode_Ignored| limit the font size to consider for text extraction. If the font size is lower than what is set then the text won't be considered for extraction. Default is `3`, meaning only text with a font size `>= 3` will be considered for extraction. - :arg bool footer: boolean to switch on/off page footer content. This parameter controls whether to include or omit footer text from all the document pages. Useful if the document has repetitive footer content which doesn't add any value to the overall extraction data. Default is `True` meaning that footer content will be considered. **Only valid in "layout mode".** + :arg bool footer: |PyMuPDFLayoutMode_Valid| boolean to switch on/off page footer content. This parameter controls whether to include or omit footer text from all the document pages. Useful if the document has repetitive footer content which doesn't add any value to the overall extraction data. Default is `True` meaning that footer content will be considered. :arg bool force_text: generate text output even when overlapping images / graphics. This text then appears after the respective image. - :arg int graphics_limit: use this to limit dealing with excess amounts of vector graphics elements. Scientific documents, or pages simulating text via graphics commands may contain tens of thousands of these objects. As vector graphics are analyzed for multiple purposes, runtime may quickly become intolerable. With this parameter, all vector graphics will be ignored if their count exceeds the threshold. **Ignored in "layout mode".** + :arg int graphics_limit: |PyMuPDFLayoutMode_Ignored| use this to limit dealing with excess amounts of vector graphics elements. Scientific documents, or pages simulating text via graphics commands may contain tens of thousands of these objects. As vector graphics are analyzed for multiple purposes, runtime may quickly become intolerable. With this parameter, all vector graphics will be ignored if their count exceeds the threshold. - :arg hdr_info: use this if you want to provide your own header detection logic. This may be a callable or an object having a method named `get_header_id`. It must accept a text span (a span dictionary as contained in :meth:`~.extractDICT`) and a keyword parameter "page" (which is the owning :ref:`Page ` object). It must return a string "" or up to 6 "#" characters followed by 1 space. If omitted (`None`), a full document scan will be performed to find the most popular font sizes and derive header levels based on them. To completely avoid this behavior specify `hdr_info=lambda s, page=None: ""` or `hdr_info=False`. **Ignored in "layout mode".** + :arg hdr_info: |PyMuPDFLayoutMode_Ignored| use this if you want to provide your own header detection logic. This may be a callable or an object having a method named `get_header_id`. It must accept a text span (a span dictionary as contained in :meth:`~.extractDICT`) and a keyword parameter "page" (which is the owning :ref:`Page ` object). It must return a string "" or up to 6 "#" characters followed by 1 space. If omitted (`None`), a full document scan will be performed to find the most popular font sizes and derive header levels based on them. To completely avoid this behavior specify `hdr_info=lambda s, page=None: ""` or `hdr_info=False`. - :arg bool header: boolean to switch on/off page header content. This parameter controls whether we want to include or omit the header content from all the document pages. Useful if the document has repetitive header content which doesn't add any value to the overall extraction data. Default is `True` meaning that header content will be considered. **Only valid in "layout mode".** + :arg bool header: |PyMuPDFLayoutMode_Valid| boolean to switch on/off page header content. This parameter controls whether we want to include or omit the header content from all the document pages. Useful if the document has repetitive header content which doesn't add any value to the overall extraction data. Default is `True` meaning that header content will be considered. - :arg bool ignore_alpha: if ``True`` includes text even when completely transparent. Default is ``False``: transparent text will be ignored which usually increases detection accuracy. **Ignored in "layout mode".** + :arg bool ignore_alpha: |PyMuPDFLayoutMode_Ignored| if ``True`` includes text even when completely transparent. Default is ``False``: transparent text will be ignored which usually increases detection accuracy. :arg bool ignore_code: if `True` then mono-spaced text lines do not receive special formatting. Code blocks will no longer be generated. This value is set to `True` if `extract_words=True` is used. - :arg bool ignore_graphics: (New in v.0.0.20) Disregard vector graphics on the page. This may help detecting text correctly when pages are very crowded (often the case for documents representing presentation slides). Also speeds up processing time. This automatically prevents table detection. **Ignored in "layout mode".** + :arg bool ignore_graphics: |PyMuPDFLayoutMode_Ignored| (New in v.0.0.20) Disregard vector graphics on the page. This may help detecting text correctly when pages are very crowded (often the case for documents representing presentation slides). Also speeds up processing time. This automatically prevents table detection. - :arg bool ignore_images: (New in v.0.0.20) Disregard images on the page. This may help detecting text correctly when pages are very crowded (often the case for documents representing presentation slides). Also speeds up processing time. **Ignored in "layout mode".** + :arg bool ignore_images: |PyMuPDFLayoutMode_Ignored| (New in v.0.0.20) Disregard images on the page. This may help detecting text correctly when pages are very crowded (often the case for documents representing presentation slides). Also speeds up processing time. :arg str image_format: specify the desired image format via its extension. Default is "png" (portable network graphics). Another popular format may be "jpg". Possible values are all :ref:`supported output formats `. :arg str image_path: store images in this folder. Relevant if `write_images=True`. Default is the path of the script directory. - :arg float image_size_limit: this must be a ``0 <= value < 1``. Images are ignored if `width / page.rect.width <= image_size_limit` or `height / page.rect.height <= image_size_limit`. For instance, the default value 0.05 means that to be considered for inclusion, an image's width and height must be larger than 5% of the page's width and height, respectively. **Ignored in "layout mode".** + :arg float image_size_limit: |PyMuPDFLayoutMode_Ignored| this must be a ``0 <= value < 1``. Images are ignored if `width / page.rect.width <= image_size_limit` or `height / page.rect.height <= image_size_limit`. For instance, the default value 0.05 means that to be considered for inclusion, an image's width and height must be larger than 5% of the page's width and height, respectively. - :arg float,list margins: a float or a sequence of 2 or 4 floats specifying page borders. Only objects inside the margins will be considered for output. **Ignored in "layout mode".** + :arg float,list margins: |PyMuPDFLayoutMode_Ignored| a float or a sequence of 2 or 4 floats specifying page borders. Only objects inside the margins will be considered for output. * `margin=f` yields `(f, f, f, f)` for `(left, top, right, bottom)`. * `(top, bottom)` yields `(0, top, 0, bottom)`. @@ -103,13 +124,13 @@ The |PyMuPDF4LLM| API - **"tables"** - a list of tables on this page. Each item is a dictionary with keys "bbox", "row_count" and "col_count". Key "bbox" is a `pymupdf.Rect` in tuple format of the table's position on the page. - - **"images"** - a list of images on the page. This a copy of page method :meth:`Page.get_image_info`. **Empty list in "layout mode".** + - **"images"** - |PyMuPDFLayoutMode_EmptyList| a list of images on the page. This a copy of page method :meth:`Page.get_image_info`. - - **"graphics"** - a list of vector graphics rectangles on the page. This is a list of boundary boxes of clustered vector graphics as delivered by method :meth:`Page.cluster_drawings`. **Empty list in "layout mode".** + - **"graphics"** - |PyMuPDFLayoutMode_EmptyList| a list of vector graphics rectangles on the page. This is a list of boundary boxes of clustered vector graphics as delivered by method :meth:`Page.cluster_drawings`. - **"text"** - page content as |Markdown| text. - - **"words"** - if `extract_words=True` was used. This is a list of tuples `(x0, y0, x1, y1, "wordstring", bno, lno, wno)` as delivered by `page.get_text("words")`. The **sequence** of these tuples however is the same as produced in the markdown text string and thus honors multi-column text. This is also true for text in tables: words are extracted in the sequence of table row cells. **Empty list in "layout mode".** + - **"words"** - |PyMuPDFLayoutMode_EmptyList| if `extract_words=True` was used. This is a list of tuples `(x0, y0, x1, y1, "wordstring", bno, lno, wno)` as delivered by `page.get_text("words")`. The **sequence** of these tuples however is the same as produced in the markdown text string and thus honors multi-column text. This is also true for text in tables: words are extracted in the sequence of table row cells. :arg float page_height: specify a desired page height. For relevance see the `page_width` parameter. If using the default `None`, the document will appear as one large page with a width of `page_width`. Consequently in this case, no markdown page separators will occur (except the final one), respectively only one page chunk will be returned. @@ -121,13 +142,13 @@ The |PyMuPDF4LLM| API :arg bool show_progress: Default is `False`. A value of `True` displays a progress bar as pages are being converted. Package `tqdm `_ is used if installed, otherwise the built-in text based progress bar is used. - :arg str table_strategy: see: :meth:`table detection strategy `. Default is `"lines_strict"` which ignores background colors. In some occasions, other strategies may be more successful, for example `"lines"` which uses all vector graphics objects for detection. **Ignored in "layout mode".** + :arg str table_strategy: |PyMuPDFLayoutMode_Ignored| see: :meth:`table detection strategy `. Default is `"lines_strict"` which ignores background colors. In some occasions, other strategies may be more successful, for example `"lines"` which uses all vector graphics objects for detection. - :arg bool use_glyphs: (New in v.0.0.19) Default is `False`. A value of `True` will use the glyph number of the characters instead of the character itself if the font does not store the Unicode value. **Ignored in "layout mode".** + :arg bool use_glyphs: |PyMuPDFLayoutMode_Ignored| (New in v.0.0.19) Default is `False`. A value of `True` will use the glyph number of the characters instead of the character itself if the font does not store the Unicode value. :arg bool write_images: when encountering images or vector graphics, images will be created from the respective page area and stored in the specified folder. |Markdown| references will be generated pointing to these images. Any text contained in these areas will not be included in the text output (but appear as part of the images). Therefore, if for instance your document has text written on full page images, make sure to set this parameter to `False`. - In "layout mode", boundary boxes that are classified as "picture" by the layout module will be treated as images - independent from the mixture of text, images or vector graphics they may be covering. If `force_text=True` is used, text will still be extracted from these areas and included in the output after the respective image reference. + If using :ref:`PyMuPDF Layout `, boundary boxes that are classified as "picture" by the layout module will be treated as images - independent from the mixture of text, images or vector graphics they may be covering. If `force_text=True` is used, text will still be extracted from these areas and included in the output after the respective image reference. :returns: Either a string of the combined text of all selected document pages, or a list of dictionaries if `page_chunks=True`. @@ -137,7 +158,7 @@ The |PyMuPDF4LLM| API Reads the pages of the file and outputs the text of its pages in |TXT| format. - .. important:: This method is only available in "layout mode", i.e. if the import of pymupdf4llm has happened **after** the statement ``import pymupdf.layout`` + .. important:: |PyMuPDFLayoutMode_Valid|. This method is only available with PyMuPDF Layout. :arg Document,str doc: the file, to be specified either as a file path string, or as a |PyMuPDF| :class:`Document` (created via `pymupdf.open`). In order to use `pathlib.Path` specifications, Python file-like objects, documents in memory etc. you **must** use a |PyMuPDF| :class:`Document`. @@ -158,7 +179,7 @@ The |PyMuPDF4LLM| API Parses the document and the specified pages and converts the result into a |JSON|-formatted string. - .. important:: This method is only available in "layout mode", i.e. if the import of pymupdf4llm has happened **after** the statement ``import pymupdf.layout`` + .. important:: |PyMuPDFLayoutMode_Valid|. This method is only available with PyMuPDF Layout. :arg Document,str doc: the file, to be specified either as a file path string, or as a |PyMuPDF| :class:`Document` (created via `pymupdf.open`). In order to use `pathlib.Path` specifications, Python file-like objects, documents in memory etc. you **must** use a |PyMuPDF| :class:`Document`. @@ -181,7 +202,7 @@ The |PyMuPDF4LLM| API .. note:: - Please see `this site `_ for more background and the current status of further improvements regarding layout mode. + Please see `this site `_ for more background and the current status of further improvements regarding usage with :ref:`PyMuPDF Layout `. .. method:: LlamaMarkdownReader(*args, **kwargs) @@ -198,7 +219,8 @@ The |PyMuPDF4LLM| API .. class:: IdentifyHeaders - .. note:: This class is not available in "layout mode", i.e. if the import of pymupdf4llm has happened **after** the statement ``import pymupdf.layout``. + .. note:: |PyMuPDFLayoutMode_Unavailable| + .. method:: __init__(self, doc: pymupdf.Document | str, *, pages: list | range | None = None, body_limit: float = 11, max_levels: int = 6) @@ -325,7 +347,7 @@ This user function uses the document's Table of Contents -- under the assumption .. class:: TocHeaders - .. note:: This class is not available in "layout mode", i.e. if the import of pymupdf4llm has happened **after** the statement ``import pymupdf.layout``. + .. note:: |PyMuPDFLayoutMode_Unavailable| .. method:: __init__(self, doc: pymupdf.Document | str) diff --git a/docs/pymupdf4llm/index.rst b/docs/pymupdf4llm/index.rst index a22a9f868..2c69a55d2 100644 --- a/docs/pymupdf4llm/index.rst +++ b/docs/pymupdf4llm/index.rst @@ -1,7 +1,7 @@ .. include:: ../header.rst -.. _pymupdf4llm +.. _pymupdf4llm: PyMuPDF4LLM @@ -9,7 +9,7 @@ PyMuPDF4LLM |PyMuPDF4LLM| is aimed to make it easier to extract |PDF| content in the format you need for **LLM** & **RAG** environments. It supports :ref:`Markdown extraction ` as well as :ref:`LlamaIndex document output `. -When using |PyMuPDF4LLM| with PyMuPDF-Layout, page layout detection will be greatly improved. This is true for table detection, but also for the detection of page headers and footers, footnotes, list items and text paragraphs. In addition two new methods become available, `to_json()` and `to_text()`. +When using |PyMuPDF4LLM| with PyMuPDF Layout, page layout detection will be greatly improved. This is true for table detection, but also for the detection of page headers and footers, footnotes, list items and text paragraphs. In addition two new methods become available, `to_json()` and `to_text()`. .. important:: @@ -22,8 +22,8 @@ Features - Support for image and vector graphics extraction (and inclusion of references in the MD text) - Support for page chunking output. - Direct support for output as :ref:`LlamaIndex Documents `. - - In "layout mode": Support for plain text output similar to Markdown - - In "layout mode": Support for JSON output + - When used with :ref:`PyMuPDF Layout ` : Support for plain text output similar to Markdown + - When used with :ref:`PyMuPDF Layout ` : Support for JSON output Functionality diff --git a/docs/recipes.rst b/docs/recipes.rst index c0125d50b..1ac6d9656 100644 --- a/docs/recipes.rst +++ b/docs/recipes.rst @@ -18,6 +18,11 @@ ---- +.. toctree:: + + recipes-ocr.rst + +---- .. toctree:: @@ -61,11 +66,6 @@ ---- -.. toctree:: - - recipes-ocr.rst - ----- .. toctree::