[reading order] Improve reading order and add exporters

docs/source/modules/io.rst

@@ -60,6 +60,14 @@ A Page is a collection of Blocks that were on the same physical page.
 .. autoclass:: Page
 
    .. automethod:: show
+   .. automethod:: items_in_reading_order
+   .. automethod:: export_as_markdown
+   .. automethod:: export_as_asciidoc
+   .. automethod:: export_as_html
+   .. automethod:: export_as_xml
+   .. automethod:: export
+   .. automethod:: render
+   .. automethod:: export_as
 
 
 KIEPage
@@ -71,6 +79,13 @@ semantic class rather than by spatial layout.
 .. autoclass:: KIEPage
 
    .. automethod:: show
+   .. automethod:: export_as_markdown
+   .. automethod:: export_as_asciidoc
+   .. automethod:: export_as_html
+   .. automethod:: export_as_xml
+   .. automethod:: export
+   .. automethod:: render
+   .. automethod:: export_as
 
 
 Document
@@ -81,6 +96,13 @@ A Document is a collection of Pages.
 .. autoclass:: Document
 
    .. automethod:: show
+   .. automethod:: export_as_markdown
+   .. automethod:: export_as_asciidoc
+   .. automethod:: export_as_xml
+   .. automethod:: export_as_html
+   .. automethod:: export
+   .. automethod:: render
+   .. automethod:: export_as
 
 
 KIEDocument
@@ -117,3 +139,41 @@ High-performance file reading and conversion to processable structured data.
    .. automethod:: from_url
 
    .. automethod:: from_images
+
+
+.. _reading_order:
+
+Reading order
+-------------
+
+The reading-order-aware export of a :class:`Document` / :class:`Page` to Markdown, AsciiDoc, HTML, or XML is available
+through the ``export_as_markdown`` / ``export_as_asciidoc`` / ``export_as_html`` / ``export_as_xml`` / ``export_as`` / ``export`` / ``render`` methods documented above, which
+delegate to the exporters of :mod:`doctr.io.exporters`.
+The underlying ordering primitives live in :mod:`doctr.models.reading_order`.
+
+Every export path shares the same linearization, so ``render()``, ``export()``, ``export_as_xml()`` and the
+Markdown / AsciiDoc / HTML exports all present the content in the same order. The result is memoized on the
+page, so exporting one page to several formats orders it only once.
+
+.. currentmodule:: doctr.io
+
+.. autoclass:: TextExporter
+    :members: export_page, export_kie_page, export_document
+
+.. autoclass:: MarkdownExporter
+    :members: export_page, export_kie_page, export_document
+
+.. autoclass:: AsciiDocExporter
+    :members: export_page, export_kie_page, export_document
+
+.. autoclass:: HTMLExporter
+    :members: export_page, export_kie_page, export_document
+
+.. autoclass:: XMLExporter
+    :members: export_page, export_kie_page, export_document
+
+.. autofunction:: doctr.io.exporters.page_reading_order
+
+.. autofunction:: doctr.io.exporters.predictions_in_reading_order
+
+.. autofunction:: doctr.io.exporters.to_json_safe

docs/source/using_doctr/using_models.rst

@@ -221,7 +221,7 @@ For a comprehensive comparison, we have compiled a detailed benchmark:
 +--------------------------------------------------+-----------------+---------------+------------------+-------------+--------------+--------------------+
 | lw_detr_s                                        | (1024, 1024, 3) | 15.1 M        |                  |             |              | 0.5                |
 +--------------------------------------------------+-----------------+---------------+------------------+-------------+--------------+--------------------+
-| lw_detr_m                                        | (1024, 1024, 3) | 29.5 M        |                  |             |              | 0.7                |
+| lw_detr_m                                        | (1024, 1024, 3) | 29.5 M        | soon             | soon        | soon         | 0.7                |
 +--------------------------------------------------+-----------------+---------------+------------------+-------------+--------------+--------------------+
 
 
@@ -628,6 +628,35 @@ For reference, here is a sample XML byte string output:
     </body>
   </html>
 
+To export the output in reading order as Markdown, AsciiDoc, HTML or XML, you can use the `export_as_markdown`,
+`export_as_asciidoc`, `export_as_html` and `export_as_xml` methods (also available on a single :class:`Page`).
+Reading order is always applied by these exporters: the content is linearized column by column, the reading direction is inferred from the
+recognized text (e.g. right-to-left for Arabic or Hebrew documents), and - when the predictor is run with
+layout detection (``detect_layout=True``) - the layout regions are used to render headings, list items and
+recognized tables, and to place the page furniture (headers, footers, footnotes):
+
+.. code-block:: python
+
+  markdown_output = result.export_as_markdown()
+  asciidoc_output = result.export_as_asciidoc()
+  html_output = result.export_as_html()
+  xml_output = result.export_as_xml()
+  raw_text_output = result.render()  # same as result.export_as("text")
+  dict_output = result.export()      # same as result.export_as("json")
+
+The `export_as` method is a convenience dispatcher over all the formats above::
+
+  result.export_as("markdown")  # or "md"
+  result.export_as("asciidoc")  # or "adoc"
+  result.export_as("html")
+  result.export_as("text")      # same as render()
+  result.export_as("json")      # same as export()
+  result.export_as("xml")       # same as export_as_xml()
+
+The document structure itself can also be produced in reading order by building the predictor with
+``keep_reading_order=True``, which sorts the blocks of every page in reading order::
+
+  predictor = ocr_predictor(pretrained=True, keep_reading_order=True)
 
 Advanced options
 ^^^^^^^^^^^^^^^^

doctr/io/__init__.py

@@ -1,4 +1,5 @@
 from .elements import *
+from .exporters import *
 from .html import *
 from .image import *
 from .pdf import *