parisaocr 0.2.0__tar.gz

parisaocr-0.2.0/LICENSE

@@ -0,0 +1,73 @@
+Apache License
+Version 2.0, January 2004
+http://www.apache.org/licenses/
+
+TERMS AND CONDITIONS FOR USE, REPRODUCTION, AND DISTRIBUTION
+
+1. Definitions.
+
+"License" shall mean the terms and conditions for use, reproduction, and distribution as defined by Sections 1 through 9 of this document.
+
+"Licensor" shall mean the copyright owner or entity authorized by the copyright owner that is granting the License.
+
+"Legal Entity" shall mean the union of the acting entity and all other entities that control, are controlled by, or are under common control with that entity. For the purposes of this definition, "control" means (i) the power, direct or indirect, to cause the direction or management of such entity, whether by contract or otherwise, or (ii) ownership of fifty percent (50%) or more of the outstanding shares, or (iii) beneficial ownership of such entity.
+
+"You" (or "Your") shall mean an individual or Legal Entity exercising permissions granted by this License.
+
+"Source" form shall mean the preferred form for making modifications, including but not limited to software source code, documentation source, and configuration files.
+
+"Object" form shall mean any form resulting from mechanical transformation or translation of a Source form, including but not limited to compiled object code, generated documentation, and conversions to other media types.
+
+"Work" shall mean the work of authorship, whether in Source or Object form, made available under the License, as indicated by a copyright notice that is included in or attached to the work (an example is provided in the Appendix below).
+
+"Derivative Works" shall mean any work, whether in Source or Object form, that is based on (or derived from) the Work and for which the editorial revisions, annotations, elaborations, or other modifications represent, as a whole, an original work of authorship. For the purposes of this License, Derivative Works shall not include works that remain separable from, or merely link (or bind by name) to the interfaces of, the Work and Derivative Works thereof.
+
+"Contribution" shall mean any work of authorship, including the original version of the Work and any modifications or additions to that Work or Derivative Works thereof, that is intentionally submitted to Licensor for inclusion in the Work by the copyright owner or by an individual or Legal Entity authorized to submit on behalf of the copyright owner. For the purposes of this definition, "submitted" means any form of electronic, verbal, or written communication sent to the Licensor or its representatives, including but not limited to communication on electronic mailing lists, source code control systems, and issue tracking systems that are managed by, or on behalf of, the Licensor for the purpose of discussing and improving the Work, but excluding communication that is conspicuously marked or otherwise designated in writing by the copyright owner as "Not a Contribution."
+
+"Contributor" shall mean Licensor and any individual or Legal Entity on behalf of whom a Contribution has been received by Licensor and subsequently incorporated within the Work.
+
+2. Grant of Copyright License. Subject to the terms and conditions of this License, each Contributor hereby grants to You a perpetual, worldwide, non-exclusive, no-charge, royalty-free, irrevocable copyright license to reproduce, prepare Derivative Works of, publicly display, publicly perform, sublicense, and distribute the Work and such Derivative Works in Source or Object form.
+
+3. Grant of Patent License. Subject to the terms and conditions of this License, each Contributor hereby grants to You a perpetual, worldwide, non-exclusive, no-charge, royalty-free, irrevocable (except as stated in this section) patent license to make, have made, use, offer to sell, sell, import, and otherwise transfer the Work, where such license applies only to those patent claims licensable by such Contributor that are necessarily infringed by their Contribution(s) alone or by combination of their Contribution(s) with the Work to which such Contribution(s) was submitted. If You institute patent litigation against any entity (including a cross-claim or counterclaim in a lawsuit) alleging that the Work or a Contribution incorporated within the Work constitutes direct or contributory patent infringement, then any patent licenses granted to You under this License for that Work shall terminate as of the date such litigation is filed.
+
+4. Redistribution. You may reproduce and distribute copies of the Work or Derivative Works thereof in any medium, with or without modifications, and in Source or Object form, provided that You meet the following conditions:
+
+     (a) You must give any other recipients of the Work or Derivative Works a copy of this License; and
+
+     (b) You must cause any modified files to carry prominent notices stating that You changed the files; and
+
+     (c) You must retain, in the Source form of any Derivative Works that You distribute, all copyright, patent, trademark, and attribution notices from the Source form of the Work, excluding those notices that do not pertain to any part of the Derivative Works; and
+
+     (d) If the Work includes a "NOTICE" text file as part of its distribution, then any Derivative Works that You distribute must include a readable copy of the attribution notices contained within such NOTICE file, excluding those notices that do not pertain to any part of the Derivative Works, in at least one of the following places: within a NOTICE text file distributed as part of the Derivative Works; within the Source form or documentation, if provided along with the Derivative Works; or, within a display generated by the Derivative Works, if and wherever such third-party notices normally appear. The contents of the NOTICE file are for informational purposes only and do not modify the License. You may add Your own attribution notices within Derivative Works that You distribute, alongside or as an addendum to the NOTICE text from the Work, provided that such additional attribution notices cannot be construed as modifying the License.
+
+     You may add Your own copyright statement to Your modifications and may provide additional or different license terms and conditions for use, reproduction, or distribution of Your modifications, or for any such Derivative Works as a whole, provided Your use, reproduction, and distribution of the Work otherwise complies with the conditions stated in this License.
+
+5. Submission of Contributions. Unless You explicitly state otherwise, any Contribution intentionally submitted for inclusion in the Work by You to the Licensor shall be under the terms and conditions of this License, without any additional terms or conditions. Notwithstanding the above, nothing herein shall supersede or modify the terms of any separate license agreement you may have executed with Licensor regarding such Contributions.
+
+6. Trademarks. This License does not grant permission to use the trade names, trademarks, service marks, or product names of the Licensor, except as required for reasonable and customary use in describing the origin of the Work and reproducing the content of the NOTICE file.
+
+7. Disclaimer of Warranty. Unless required by applicable law or agreed to in writing, Licensor provides the Work (and each Contributor provides its Contributions) on an "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied, including, without limitation, any warranties or conditions of TITLE, NON-INFRINGEMENT, MERCHANTABILITY, or FITNESS FOR A PARTICULAR PURPOSE. You are solely responsible for determining the appropriateness of using or redistributing the Work and assume any risks associated with Your exercise of permissions under this License.
+
+8. Limitation of Liability. In no event and under no legal theory, whether in tort (including negligence), contract, or otherwise, unless required by applicable law (such as deliberate and grossly negligent acts) or agreed to in writing, shall any Contributor be liable to You for damages, including any direct, indirect, special, incidental, or consequential damages of any character arising as a result of this License or out of the use or inability to use the Work (including but not limited to damages for loss of goodwill, work stoppage, computer failure or malfunction, or any and all other commercial damages or losses), even if such Contributor has been advised of the possibility of such damages.
+
+9. Accepting Warranty or Additional Liability. While redistributing the Work or Derivative Works thereof, You may choose to offer, and charge a fee for, acceptance of support, warranty, indemnity, or other liability obligations and/or rights consistent with this License. However, in accepting such obligations, You may act only on Your own behalf and on Your sole responsibility, not on behalf of any other Contributor, and only if You agree to indemnify, defend, and hold each Contributor harmless for any liability incurred by, or claims asserted against, such Contributor by reason of your accepting any such warranty or additional liability.
+
+END OF TERMS AND CONDITIONS
+
+APPENDIX: How to apply the Apache License to your work.
+
+To apply the Apache License to your work, attach the following boilerplate notice, with the fields enclosed by brackets "[]" replaced with your own identifying information. (Don't include the brackets!)  The text should be enclosed in the appropriate comment syntax for the file format. We also recommend that a file or class name and description of purpose be included on the same "printed page" as the copyright notice for easier identification within third-party archives.
+
+Copyright [yyyy] [name of copyright owner]
+
+Licensed under the Apache License, Version 2.0 (the "License");
+you may not use this file except in compliance with the License.
+You may obtain a copy of the License at
+
+http://www.apache.org/licenses/LICENSE-2.0
+
+Unless required by applicable law or agreed to in writing, software
+distributed under the License is distributed on an "AS IS" BASIS,
+WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+See the License for the specific language governing permissions and
+limitations under the License.

parisaocr-0.2.0/NOTICE

@@ -0,0 +1,23 @@
+ParisaOCR
+Copyright 2026 Ali Javadi
+
+This product is licensed under the Apache License, Version 2.0 (see LICENSE).
+
+It includes:
+
+- parisaocr/models/ppocrv6-det-small.onnx: the PP-OCRv6 small text detection
+  model of PaddleOCR (https://github.com/PaddlePaddle/PaddleOCR), Copyright
+  PaddlePaddle Authors, licensed under the Apache License, Version 2.0, in the
+  ONNX conversion distributed by RapidOCR (https://github.com/RapidAI/RapidOCR),
+  also under the Apache License, Version 2.0.
+
+- parisaocr/models/parisaocr-fa-0.1.safetensors: a text recognition model
+  trained with Kraken (https://github.com/mittagessen/kraken, Apache License,
+  Version 2.0). See MODEL_CARD.md for its training data, including synthetic
+  lines rendered from Persian and English Wikipedia text (CC BY-SA 4.0).
+
+- parisaocr/fonts/Vazirmatn-Regular.ttf: the Vazirmatn font
+  (https://github.com/rastikerdar/vazirmatn), Copyright 2015 The Vazirmatn
+  Project Authors, licensed under the SIL Open Font License 1.1
+  (parisaocr/fonts/OFL-Vazirmatn.txt). It is embedded, subset, in the
+  invisible text layer of the searchable PDFs ParisaOCR writes.

parisaocr-0.2.0/PKG-INFO

@@ -0,0 +1,223 @@
+Metadata-Version: 2.4
+Name: parisaocr
+Version: 0.2.0
+Summary: Open-source OCR for printed Persian: PP-OCR line detection and a Kraken recognizer trained on Persian books
+Author: Ali Javadi
+License-Expression: Apache-2.0
+Project-URL: Homepage, https://github.com/givia/ParisaOCR
+Project-URL: Issues, https://github.com/givia/ParisaOCR/issues
+Project-URL: Model, https://huggingface.co/givia/ParisaOCR
+Keywords: ocr,persian,farsi,text recognition,kraken,rtl
+Classifier: Development Status :: 4 - Beta
+Classifier: Intended Audience :: Developers
+Classifier: Intended Audience :: Science/Research
+Classifier: Natural Language :: Persian
+Classifier: Operating System :: OS Independent
+Classifier: Programming Language :: Python :: 3
+Classifier: Topic :: Scientific/Engineering :: Image Recognition
+Classifier: Topic :: Text Processing :: Linguistic
+Requires-Python: <3.14,>=3.10
+Description-Content-Type: text/markdown
+License-File: LICENSE
+License-File: NOTICE
+Requires-Dist: pillow
+Requires-Dist: numpy
+Requires-Dist: rapidocr>=3.9
+Requires-Dist: onnxruntime
+Requires-Dist: kraken==7.1.1
+Requires-Dist: reportlab
+Requires-Dist: pikepdf
+Provides-Extra: surya
+Requires-Dist: surya-ocr; extra == "surya"
+Dynamic: license-file
+
+# ParisaOCR (پریسا اوسی‌آر)
+
+Open-source OCR for printed Persian. It reads scanned book pages about as well
+as Google's Gemini Flash models, runs on your own machine (CPU or GPU, no
+internet needed), and costs a few cents per thousand pages to run.
+
+**Status: preview.** It works well on printed Persian books and
+documents; see [Known limitations](#known-limitations). Feedback with example
+pages is very welcome.
+
+[فارسی](#فارسی) · [Model on Hugging Face](https://huggingface.co/givia/ParisaOCR) · [PyPI](https://pypi.org/project/parisaocr/)
+
+## Install
+
+```
+pip install parisaocr
+```
+
+Python 3.10 to 3.13. The two models (text-line detector and recognizer, 22 MB)
+are included. PyTorch is installed as a dependency of Kraken; a GPU is used
+when one is available, otherwise the CPU (about 5 to 10 seconds per page).
+For PDF input, Poppler's command-line tools must be installed
+(`poppler-utils` on Debian and Ubuntu, `poppler` on Arch, Homebrew and conda-forge).
+
+## Use
+
+```
+parisaocr ocr page.png                        # print the text
+parisaocr ocr scans/ --out out                # out/txt/*.txt and out/hocr/*.hocr
+parisaocr ocr book.pdf --out out --format txt,hocr,jsonl
+parisaocr ocr book.pdf --out out --first 10 --last 20
+parisaocr ocr book.pdf --out out --format pdf     # out/pdf/book.pdf: searchable
+```
+
+Inputs are images, directories of images, or a PDF (scanned pages are
+extracted losslessly, born-digital pages rendered). Outputs: plain text (one
+line per printed line, columns right to left), hOCR with line and word boxes on
+the original page, and JSONL with text, boxes and confidences.
+
+### Searchable PDFs
+
+`--format pdf` writes PDFs you can search, select and copy text in, with the
+page images exactly as they were:
+
+- **PDF input:** `out/pdf/NAME.pdf` is the original file with an invisible text
+  layer over each page that was read. The scans are not re-encoded; page
+  rotation is respected. Pages that already have a text layer (born-digital
+  pages, or scans someone OCRed before) are left as they are; `--pdf-text add`
+  adds ours to them too, e.g. over a poor earlier OCR layer.
+- **Image input:** one PDF per image in `out/pdf/`, or all of them in one file
+  with `--merge-pdf NAME`. The page size follows the image's dpi.
+
+The text layer is stored the way word processors store Persian text (one run
+per line in visual order), so PDF viewers find and copy it in reading order.
+Tested with Poppler (`pdftotext`, used by Okular and Evince) and pdf.js
+(Firefox): words and their order come out right; pdftotext sometimes moves
+punctuation at the edge of a word, and pdf.js drops half-spaces when copying.
+Tools that do not reorder right-to-left text (such as pdfminer) return each
+line reversed, as they do for any Persian PDF.
+
+From Python:
+
+```python
+from parisaocr import OCR
+
+ocr = OCR()                         # loads the models once
+print(ocr.text("page.png"))
+for line in ocr.lines("page.png"):  # reading order
+    print(line.bbox, line.conf, line.text)
+```
+
+## Accuracy
+
+Measured on material the model never saw in training.
+
+| Test set | ParisaOCR 0.1 | Gemini 3.8 Flash | Tesseract fas_print¹ |
+|---|---|---|---|
+| 32 book pages from 11 books, verified text: words found | **96.7%** | 94.7% | 94.7% |
+| 750 lines from the same books: character error, ignoring spaces | 0.39% | 0.36% | 1.19% |
+| same lines: word error | **6.1%** | 7.9% | 7.3% |
+| 74 printed pages of [PersianML/persian-ocr-benchmark](https://huggingface.co/datasets/PersianML/persian-ocr-benchmark): words found | 77.9% | 81.7% | 71.1% |
+| cost per 1,000 pages | about $0.14 (consumer GPU at $0.60/h) | $2.86 (list price) | about $0.10 |
+
+¹ Our earlier Persian Tesseract model ([tessdata_contrib](https://github.com/tesseract-ocr/tessdata_contrib/pull/19)),
+reading the lines found by the Surya detector.
+
+On the benchmark the gap to Gemini comes mostly from very small,
+low-resolution scans (lines under about 16 pixels high), where Gemini reads
+about 78% of the words and ParisaOCR 74%. Many benchmark pages are hard even
+for a human reader, and its page-level character error (about 40% for every
+reader) mostly measures reading order on multi-column pages.
+
+The verified test set is small (750 lines from 11 books), so treat the numbers
+as a guide rather than a precise ranking. Details in [MODEL_CARD.md](MODEL_CARD.md).
+
+## Known limitations
+
+- **Printed Persian only.** Handwriting, Nastaliq calligraphy, manuscripts and
+  Urdu are not supported.
+- **Very small text** (lines under about 14 pixels high, i.e. low-resolution
+  scans) loses accuracy; ParisaOCR prints a warning for such pages. Scan at
+  300 dpi when you can.
+- **Layout is simple.** Columns are read right to left and top to bottom;
+  tables, captions and complex magazine layouts may come out in the wrong
+  order. Text rotated sideways is not read.
+- **Small ornaments** (a box, a dingbat) are sometimes read as a letter.
+- **Spacing conventions.** The model follows standard Persian spelling for
+  half-spaces (ZWNJ) and sometimes differs from the printed spacing.
+- **Diacritics** (vowel marks) are read less reliably than letters.
+
+## How it works
+
+1. **Lines.** The PP-OCRv6 text detector (PaddleOCR, Apache-2.0) finds the
+   text lines, run with ONNX Runtime.
+2. **Crops.** Each line is cut out with a margin that keeps the dots above and
+   below the letters; neighbouring lines inside the margin are painted over.
+3. **Reading.** A Kraken recognition model (PP-OCR-style architecture, CTC)
+   trained for Persian print reads each line. ParisaOCR turns the model's
+   visual-order output into reading order itself, keeping the half-space
+   (ZWNJ), and with each line's own direction, so English lines and footnotes
+   come out right.
+4. **Order.** Lines are grouped into columns, read right to left.
+
+The model was trained on about 83,000 lines from about 200 scanned Persian
+books, labelled automatically with Gemini, plus about 90,000 synthetic lines
+(Persian and English text, special characters, low-resolution copies). See
+[MODEL_CARD.md](MODEL_CARD.md), and the modules in [docs/architecture.md](docs/architecture.md).
+
+## Other models and detectors
+
+`--model` accepts another Kraken model (`kraken:model.safetensors`) or a
+Tesseract model (`TESSDATA_DIR:LANG`); `--detector` accepts other PP-OCR sizes
+(`ppocr:v6-medium`), Kraken's segmenter (`kraken`), or Surya (`surya`, after
+`pip install parisaocr[surya]`; note that Surya's weights are free only for
+research, personal use and small companies). `parisaocr cut` cuts the lines of
+scanned books for building training data.
+
+## Feedback
+
+Please [open an issue](https://github.com/givia/ParisaOCR/issues/new/choose)
+with the page (only if you are allowed to share it), the command you ran, and
+what came out wrong.
+
+## License
+
+Apache License 2.0, for the code and the models. The bundled PP-OCRv6 detector
+is PaddleOCR's (Apache-2.0); see [NOTICE](NOTICE).
+
+---
+
+## فارسی
+
+پریسا اوسی‌آر یک اوسی‌آر متن‌باز برای متن چاپی فارسی است. صفحه‌های اسکن‌شدهٔ کتاب را
+تقریباً هم‌اندازهٔ مدل‌های Gemini Flash گوگل می‌خواند، روی رایانهٔ خودتان اجرا می‌شود
+(بدون نیاز به اینترنت، با CPU یا GPU) و هزینهٔ اجرایش برای هر هزار صفحه چند سنت است.
+
+**وضعیت: پیش‌نمایش.** روی کتاب‌ها و اسناد چاپی فارسی خوب کار می‌کند. محدودیت‌ها
+را پایین‌تر ببینید. بازخورد همراه با صفحهٔ نمونه بسیار ارزشمند است.
+
+نصب:
+
+```
+pip install parisaocr
+```
+
+استفاده:
+
+```
+parisaocr ocr page.png                      # چاپ متن
+parisaocr ocr book.pdf --out out            # out/txt و out/hocr
+parisaocr ocr book.pdf --out out --format pdf   # out/pdf/book.pdf: پی‌دی‌اف جست‌وجوپذیر
+```
+
+با `--format pdf` خروجی یک پی‌دی‌اف جست‌وجوپذیر است: تصویر صفحه‌ها همان است که بود و
+یک لایهٔ متن نامرئی روی آن قرار می‌گیرد، تا بتوانید در آن جست‌وجو کنید و متن را انتخاب
+و کپی کنید.
+
+محدودیت‌ها:
+
+- فقط متن چاپی فارسی. دست‌نوشته، خط نستعلیق، نسخهٔ خطی و اردو پشتیبانی نمی‌شوند.
+- متن خیلی ریز (اسکن با وضوح پایین) دقت کمتری دارد. در صورت امکان با ۳۰۰ dpi اسکن کنید.
+- چیدمان صفحه ساده خوانده می‌شود. جدول‌ها و صفحه‌های مجله‌ای پیچیده ممکن است ترتیب
+  درستی نداشته باشند.
+- نیم‌فاصله‌ها طبق املای استاندارد نوشته می‌شوند و گاهی با چاپ کتاب فرق دارند.
+- اِعراب‌ها کمتر از حروف دقیق خوانده می‌شوند.
+
+بازخورد: لطفاً در [بخش Issues](https://github.com/givia/ParisaOCR/issues/new/choose) صفحه
+(فقط اگر اجازهٔ انتشارش را دارید)، فرمانی که اجرا کردید و خطای خروجی را بفرستید.
+
+مجوز: Apache 2.0، برای کد و مدل‌ها.

parisaocr-0.2.0/README.md

@@ -0,0 +1,190 @@
+# ParisaOCR (پریسا اوسی‌آر)
+
+Open-source OCR for printed Persian. It reads scanned book pages about as well
+as Google's Gemini Flash models, runs on your own machine (CPU or GPU, no
+internet needed), and costs a few cents per thousand pages to run.
+
+**Status: preview.** It works well on printed Persian books and
+documents; see [Known limitations](#known-limitations). Feedback with example
+pages is very welcome.
+
+[فارسی](#فارسی) · [Model on Hugging Face](https://huggingface.co/givia/ParisaOCR) · [PyPI](https://pypi.org/project/parisaocr/)
+
+## Install
+
+```
+pip install parisaocr
+```
+
+Python 3.10 to 3.13. The two models (text-line detector and recognizer, 22 MB)
+are included. PyTorch is installed as a dependency of Kraken; a GPU is used
+when one is available, otherwise the CPU (about 5 to 10 seconds per page).
+For PDF input, Poppler's command-line tools must be installed
+(`poppler-utils` on Debian and Ubuntu, `poppler` on Arch, Homebrew and conda-forge).
+
+## Use
+
+```
+parisaocr ocr page.png                        # print the text
+parisaocr ocr scans/ --out out                # out/txt/*.txt and out/hocr/*.hocr
+parisaocr ocr book.pdf --out out --format txt,hocr,jsonl
+parisaocr ocr book.pdf --out out --first 10 --last 20
+parisaocr ocr book.pdf --out out --format pdf     # out/pdf/book.pdf: searchable
+```
+
+Inputs are images, directories of images, or a PDF (scanned pages are
+extracted losslessly, born-digital pages rendered). Outputs: plain text (one
+line per printed line, columns right to left), hOCR with line and word boxes on
+the original page, and JSONL with text, boxes and confidences.
+
+### Searchable PDFs
+
+`--format pdf` writes PDFs you can search, select and copy text in, with the
+page images exactly as they were:
+
+- **PDF input:** `out/pdf/NAME.pdf` is the original file with an invisible text
+  layer over each page that was read. The scans are not re-encoded; page
+  rotation is respected. Pages that already have a text layer (born-digital
+  pages, or scans someone OCRed before) are left as they are; `--pdf-text add`
+  adds ours to them too, e.g. over a poor earlier OCR layer.
+- **Image input:** one PDF per image in `out/pdf/`, or all of them in one file
+  with `--merge-pdf NAME`. The page size follows the image's dpi.
+
+The text layer is stored the way word processors store Persian text (one run
+per line in visual order), so PDF viewers find and copy it in reading order.
+Tested with Poppler (`pdftotext`, used by Okular and Evince) and pdf.js
+(Firefox): words and their order come out right; pdftotext sometimes moves
+punctuation at the edge of a word, and pdf.js drops half-spaces when copying.
+Tools that do not reorder right-to-left text (such as pdfminer) return each
+line reversed, as they do for any Persian PDF.
+
+From Python:
+
+```python
+from parisaocr import OCR
+
+ocr = OCR()                         # loads the models once
+print(ocr.text("page.png"))
+for line in ocr.lines("page.png"):  # reading order
+    print(line.bbox, line.conf, line.text)
+```
+
+## Accuracy
+
+Measured on material the model never saw in training.
+
+| Test set | ParisaOCR 0.1 | Gemini 3.8 Flash | Tesseract fas_print¹ |
+|---|---|---|---|
+| 32 book pages from 11 books, verified text: words found | **96.7%** | 94.7% | 94.7% |
+| 750 lines from the same books: character error, ignoring spaces | 0.39% | 0.36% | 1.19% |
+| same lines: word error | **6.1%** | 7.9% | 7.3% |
+| 74 printed pages of [PersianML/persian-ocr-benchmark](https://huggingface.co/datasets/PersianML/persian-ocr-benchmark): words found | 77.9% | 81.7% | 71.1% |
+| cost per 1,000 pages | about $0.14 (consumer GPU at $0.60/h) | $2.86 (list price) | about $0.10 |
+
+¹ Our earlier Persian Tesseract model ([tessdata_contrib](https://github.com/tesseract-ocr/tessdata_contrib/pull/19)),
+reading the lines found by the Surya detector.
+
+On the benchmark the gap to Gemini comes mostly from very small,
+low-resolution scans (lines under about 16 pixels high), where Gemini reads
+about 78% of the words and ParisaOCR 74%. Many benchmark pages are hard even
+for a human reader, and its page-level character error (about 40% for every
+reader) mostly measures reading order on multi-column pages.
+
+The verified test set is small (750 lines from 11 books), so treat the numbers
+as a guide rather than a precise ranking. Details in [MODEL_CARD.md](MODEL_CARD.md).
+
+## Known limitations
+
+- **Printed Persian only.** Handwriting, Nastaliq calligraphy, manuscripts and
+  Urdu are not supported.
+- **Very small text** (lines under about 14 pixels high, i.e. low-resolution
+  scans) loses accuracy; ParisaOCR prints a warning for such pages. Scan at
+  300 dpi when you can.
+- **Layout is simple.** Columns are read right to left and top to bottom;
+  tables, captions and complex magazine layouts may come out in the wrong
+  order. Text rotated sideways is not read.
+- **Small ornaments** (a box, a dingbat) are sometimes read as a letter.
+- **Spacing conventions.** The model follows standard Persian spelling for
+  half-spaces (ZWNJ) and sometimes differs from the printed spacing.
+- **Diacritics** (vowel marks) are read less reliably than letters.
+
+## How it works
+
+1. **Lines.** The PP-OCRv6 text detector (PaddleOCR, Apache-2.0) finds the
+   text lines, run with ONNX Runtime.
+2. **Crops.** Each line is cut out with a margin that keeps the dots above and
+   below the letters; neighbouring lines inside the margin are painted over.
+3. **Reading.** A Kraken recognition model (PP-OCR-style architecture, CTC)
+   trained for Persian print reads each line. ParisaOCR turns the model's
+   visual-order output into reading order itself, keeping the half-space
+   (ZWNJ), and with each line's own direction, so English lines and footnotes
+   come out right.
+4. **Order.** Lines are grouped into columns, read right to left.
+
+The model was trained on about 83,000 lines from about 200 scanned Persian
+books, labelled automatically with Gemini, plus about 90,000 synthetic lines
+(Persian and English text, special characters, low-resolution copies). See
+[MODEL_CARD.md](MODEL_CARD.md), and the modules in [docs/architecture.md](docs/architecture.md).
+
+## Other models and detectors
+
+`--model` accepts another Kraken model (`kraken:model.safetensors`) or a
+Tesseract model (`TESSDATA_DIR:LANG`); `--detector` accepts other PP-OCR sizes
+(`ppocr:v6-medium`), Kraken's segmenter (`kraken`), or Surya (`surya`, after
+`pip install parisaocr[surya]`; note that Surya's weights are free only for
+research, personal use and small companies). `parisaocr cut` cuts the lines of
+scanned books for building training data.
+
+## Feedback
+
+Please [open an issue](https://github.com/givia/ParisaOCR/issues/new/choose)
+with the page (only if you are allowed to share it), the command you ran, and
+what came out wrong.
+
+## License
+
+Apache License 2.0, for the code and the models. The bundled PP-OCRv6 detector
+is PaddleOCR's (Apache-2.0); see [NOTICE](NOTICE).
+
+---
+
+## فارسی
+
+پریسا اوسی‌آر یک اوسی‌آر متن‌باز برای متن چاپی فارسی است. صفحه‌های اسکن‌شدهٔ کتاب را
+تقریباً هم‌اندازهٔ مدل‌های Gemini Flash گوگل می‌خواند، روی رایانهٔ خودتان اجرا می‌شود
+(بدون نیاز به اینترنت، با CPU یا GPU) و هزینهٔ اجرایش برای هر هزار صفحه چند سنت است.
+
+**وضعیت: پیش‌نمایش.** روی کتاب‌ها و اسناد چاپی فارسی خوب کار می‌کند. محدودیت‌ها
+را پایین‌تر ببینید. بازخورد همراه با صفحهٔ نمونه بسیار ارزشمند است.
+
+نصب:
+
+```
+pip install parisaocr
+```
+
+استفاده:
+
+```
+parisaocr ocr page.png                      # چاپ متن
+parisaocr ocr book.pdf --out out            # out/txt و out/hocr
+parisaocr ocr book.pdf --out out --format pdf   # out/pdf/book.pdf: پی‌دی‌اف جست‌وجوپذیر
+```
+
+با `--format pdf` خروجی یک پی‌دی‌اف جست‌وجوپذیر است: تصویر صفحه‌ها همان است که بود و
+یک لایهٔ متن نامرئی روی آن قرار می‌گیرد، تا بتوانید در آن جست‌وجو کنید و متن را انتخاب
+و کپی کنید.
+
+محدودیت‌ها:
+
+- فقط متن چاپی فارسی. دست‌نوشته، خط نستعلیق، نسخهٔ خطی و اردو پشتیبانی نمی‌شوند.
+- متن خیلی ریز (اسکن با وضوح پایین) دقت کمتری دارد. در صورت امکان با ۳۰۰ dpi اسکن کنید.
+- چیدمان صفحه ساده خوانده می‌شود. جدول‌ها و صفحه‌های مجله‌ای پیچیده ممکن است ترتیب
+  درستی نداشته باشند.
+- نیم‌فاصله‌ها طبق املای استاندارد نوشته می‌شوند و گاهی با چاپ کتاب فرق دارند.
+- اِعراب‌ها کمتر از حروف دقیق خوانده می‌شوند.
+
+بازخورد: لطفاً در [بخش Issues](https://github.com/givia/ParisaOCR/issues/new/choose) صفحه
+(فقط اگر اجازهٔ انتشارش را دارید)، فرمانی که اجرا کردید و خطای خروجی را بفرستید.
+
+مجوز: Apache 2.0، برای کد و مدل‌ها.

parisaocr-0.2.0/parisaocr/__init__.py

@@ -0,0 +1,27 @@
+"""ParisaOCR: open-source OCR for printed Persian.
+
+A text-line detector (PP-OCRv6, run with ONNX Runtime) finds the lines of a
+page; a Kraken recognition model trained for Persian print reads each line; the
+lines are ordered into right-to-left columns and written as text, hOCR (with
+line and word boxes on the original page) or JSONL. Both models ship with the
+package, so it runs offline, on a CPU or a GPU.
+
+    parisaocr ocr page.png                      # print the text
+    parisaocr ocr book.pdf --out out            # out/txt, out/hocr
+    parisaocr ocr book.pdf --out out --format pdf   # out/pdf/book.pdf, searchable
+
+    from parisaocr import OCR
+    print(OCR().text("page.png"))
+
+The recognition model and the detector are replaceable (`--model`, `--detector`):
+Tesseract models and the Surya detector are supported for comparison, and
+`parisaocr cut` cuts the lines of scanned books for building training data.
+"""
+__version__ = "0.2.0"
+
+
+def __getattr__(name):  # the interface imports torch and Kraken; only load them when asked for
+    if name == "OCR":
+        from .api import OCR
+        return OCR
+    raise AttributeError(name)

parisaocr-0.2.0/parisaocr/__main__.py

@@ -0,0 +1,3 @@
+from .cli import main
+
+main()

parisaocr-0.2.0/parisaocr/api.py

@@ -0,0 +1,54 @@
+"""Python interface: read a page image and get its text or its lines.
+
+    from parisaocr import OCR
+    ocr = OCR()                       # loads the detector and the recognition model once
+    print(ocr.text("page.png"))       # the page's text, lines in reading order
+    for line in ocr.lines("page.png"):
+        print(line.bbox, line.conf, line.text)
+
+`OCR(model=..., detector=..., device=...)` takes the same model and detector
+specifications as the command line (`parisaocr ocr --help`).
+"""
+import pathlib
+import tempfile
+from types import SimpleNamespace
+
+from PIL import Image
+
+from . import output
+from .cli import build_engine
+from .order import order
+from .pipeline import recognize_batch
+
+
+class OCR:
+    def __init__(self, model="default", detector="ppocr:v6-small:1.3", cpu=False, line_order="rtl"):
+        opts = SimpleNamespace(model=model, detector=detector, cpu=cpu, min_width=1600, max_width=2000, batch=1,
+                               pad=6, pad_frac=0.4, min_height=40, block_tall=True, fallback=True, jobs=8)
+        self.detector, self.reader, self.options = build_engine(opts)
+        self.line_order = line_order
+
+    def columns(self, image):
+        """Lines of one page (a path or a PIL image) as reading-order columns of `pipeline.Line`."""
+        with tempfile.TemporaryDirectory(prefix="parisaocr-") as tmp:
+            tmp = pathlib.Path(tmp)
+            if not isinstance(image, (str, pathlib.Path)):
+                path = tmp / "page.png"
+                image.save(path)
+            else:
+                path = pathlib.Path(image)
+            with Image.open(path) as page:
+                im, f = self.detector.prepare(page)
+                rec = {"page": "page", "image": str(path), "width": im.width, "height": im.height, "scale": f,
+                       "orig_width": page.width, "orig_height": page.height}
+            rec["lines"] = self.detector.detect([im])[0]
+            lines = recognize_batch([rec], self.reader, self.options, tmp)["page"]
+        return order(lines, self.line_order)
+
+    def lines(self, image):
+        """The lines of one page in reading order (text, bbox on the page, mean confidence, words)."""
+        return [line for col in self.columns(image) for line in col]
+
+    def text(self, image):
+        """The text of one page: one line per printed line, columns right to left."""
+        return output.text(self.columns(image))

parisaocr-0.2.0/parisaocr/bidi.py

@@ -0,0 +1,37 @@
+"""Reading order <-> display order for one text line, with each line's own base direction.
+
+Recognition models see a line image from left to right, so they are trained on
+the display order of the text and their output is turned back into reading
+order. Kraken can do both itself, but (mittagessen/kraken#809) its bidi code
+deletes ZWNJ, the Persian half-space, and it gives every line the same base
+direction, so a Latin-only line such as "1. Vercingétorix" is trained as
+"Vercingétorix .1". Here the Unicode bidi algorithm of kraken.lib.bidi runs
+with ZWNJ protected (swapped for U+00A6, a neutral that stays in place between
+two letters) and with the base direction taken from the line itself.
+"""
+import unicodedata
+
+ZWNJ, PLACEHOLDER = "‌", "¦"
+
+
+def base_direction(text):
+    """"L" for a line with more Latin than Arabic-script letters, else "R"."""
+    latin = sum(1 for c in text if c.isalpha() and unicodedata.bidirectional(c) == "L")
+    arabic = sum(1 for c in text if unicodedata.bidirectional(c) in ("R", "AL"))
+    return "L" if latin > arabic else "R"
+
+
+def to_display(text, base=None):
+    """Display (left-to-right visual) order of a line in reading order; ZWNJ kept."""
+    from kraken.lib.bidi import get_display
+    base = base or base_direction(text)
+    return get_display(text.replace(ZWNJ, PLACEHOLDER), base_dir=base).replace(PLACEHOLDER, ZWNJ)
+
+
+def to_logical(display, base=None):
+    """Reading order of a line in display order, and for each character of the result the index
+    of the display character it came from (to carry character positions along)."""
+    from kraken.lib.bidi import get_display_map
+    base = base or base_direction(display)
+    text, order = get_display_map(display.replace(ZWNJ, PLACEHOLDER), base_dir=base)
+    return text.replace(PLACEHOLDER, ZWNJ), order