TLDR-422 readme extending and PyPI publication (#2)

.github/check_version.py

@@ -0,0 +1,33 @@
+import argparse
+import re
+from typing import Pattern
+
+
+def is_correct_version(version: str, tag: str, old_version: str, regexp: Pattern) -> bool:
+    match = regexp.match(version)
+
+    if match is None:
+        print("New version doesn't match the pattern")  # noqa
+        return False
+
+    if not (tag.startswith("v") and tag[1:] == version):
+        print("Tag value should be equal to version with `v` in the beginning")  # noqa
+        return False
+
+    return old_version < version
+
+
+if __name__ == "__main__":
+    parser = argparse.ArgumentParser()
+    parser.add_argument("--tag", help="Tag of the release", type=str)
+    parser.add_argument("--new_version", help="New release version", type=str)
+    parser.add_argument("--old_version", help="Previous release version", type=str)
+    args = parser.parse_args()
+
+    print(f"Old version: {args.old_version}, new version: {args.new_version}, tag: {args.tag}")  # noqa
+
+    version_pattern = re.compile(r"^\d+\.\d+(\.\d+)?$")
+    correct = is_correct_version(args.new_version, args.tag, args.old_version, version_pattern)
+
+    assert correct
+    print("Version is correct")  # noqa

.github/workflows/release.yaml

@@ -0,0 +1,37 @@
+name: Publish to PyPI
+
+on:
+  release:
+    types: [published]
+
+jobs:
+  # Publish the package to PyPI https://pypi.org
+  pypi-publish:
+    runs-on: ubuntu-latest
+    steps:
+      - name: Checkout repo
+        uses: actions/checkout@v1
+
+      - name: Set up Python ${{ matrix.python-version }}
+        uses: actions/setup-python@v2
+        with:
+          python-version: '3.9'
+
+      - name: Check version correctness
+        run: |
+          python3 .github/check_version.py --tag $GITHUB_REF_NAME --new_version $(< VERSION) --old_version $(git cat-file -p $(git rev-parse "$GITHUB_SHA"^1):VERSION)
+
+      - name: Install dependencies
+        run: |
+          python3 -m pip install --upgrade pip
+          pip3 install .[dev]
+
+      - name: Build and publish to PyPI
+        if: ${{ success() }}  # publish only when version passed the checks
+        env:
+          TWINE_USERNAME: ${{ secrets.PYPI_USERNAME }}
+          TWINE_PASSWORD: ${{ secrets.PYPI_PASSWORD }}
+        run: |
+          python3 -m build -w
+          twine check dist/*
+          twine upload --repository pypi dist/*

CHANGELOG.md

@@ -1,6 +1,6 @@
 Changelog
 =========
 
-v0.1 (2023-07-**)
+v0.1 (2023-07-26)
 -------------------
 * First version of the library

README.md

@@ -1,9 +1,17 @@
 # dedoc-utils
 
-This library contains useful utilities for automatic document images processing.
+This library contains useful utilities for automatic document images processing:
+
+1. Preprocessing
+    * binarization
+    * skew correction
+2. Text detection
+3. Line segmentation
+4. Text recognition
 
 ## Installation
 
+The library requires Tesseract OCR to be installed.
 To install the library use the following command:
 
 ```bash
@@ -30,4 +38,103 @@ pip install ."[torch]"
 
 ## Basic usage
 
-TODO
+### Using preprocessors
+
+```python
+from dedocutils.preprocessing import AdaptiveBinarizer, SkewCorrector
+import cv2
+import matplotlib.pyplot as plt
+
+binarizer = AdaptiveBinarizer()
+skew_corrector = SkewCorrector()
+
+image = cv2.imread("examples/before_preprocessing.jpg")
+binarized_image = binarizer.preprocess(image)
+preprocessed_image = skew_corrector.preprocess(binarized_image)
+
+fig = plt.figure(figsize=(10, 7))
+rows, columns = 1, 3
+
+fig.add_subplot(rows, columns, 1)
+plt.imshow(image)
+plt.axis('off')
+plt.title("Before preprocessing")
+
+fig.add_subplot(rows, columns, 2)
+plt.imshow(binarized_image)
+plt.axis('off')
+plt.title("After binarization")
+
+fig.add_subplot(rows, columns, 3)
+plt.imshow(preprocessed_image)
+plt.axis('off')
+plt.title("After preprocessing")
+```
+
+![](examples/after_preprocessing.png)
+
+### Using text detectors
+
+```python
+from dedocutils.text_detection import DoctrTextDetector
+
+text_detector = DoctrTextDetector()
+bboxes = text_detector.detect(preprocessed_image)
+
+for bbox in bboxes[:5]:
+    print(bbox)
+```
+
+> BBox(x_top_left=2415, y_top_left=3730, width=202, height=97)  
+BBox(x_top_left=790, y_top_left=3613, width=383, height=105)  
+BBox(x_top_left=1690, y_top_left=3488, width=407, height=104)  
+BBox(x_top_left=2171, y_top_left=3488, width=377, height=92)  
+BBox(x_top_left=885, y_top_left=3505, width=27, height=50)  
+
+### Using text recognizers
+
+```python
+from dedocutils.text_recognition import TesseractTextRecognizer
+
+text_recognizer = TesseractTextRecognizer()
+
+for bbox in bboxes[:10]:
+    word_image = preprocessed_image[bbox.y_top_left:bbox.y_bottom_right, bbox.x_top_left:bbox.x_bottom_right]
+    text = text_recognizer.recognize(word_image, parameters=dict(language="eng"))
+    print(text)
+```
+
+> Fie-  
+afjefjores.  
+coluntur,  
+dicuntur  
+delubro  
+eodem  
+dii
+in  
+plures
+
+### Using line segmenters
+
+In the previous example, the order of the recognized words isn't the same 
+as the order of the words in the document.
+It happens because of undetermined work of the text detector.
+In this case, one may use line segmenter to sort bboxes from the text detector.
+
+```python
+from dedocutils.line_segmentation import ClusteringLineSegmenter
+
+line_segmenter = ClusteringLineSegmenter()
+sorted_bboxes = line_segmenter.segment(bboxes)
+for bbox in sorted_bboxes[1]:
+    word_image = preprocessed_image[bbox.y_top_left:bbox.y_bottom_right, bbox.x_top_left:bbox.x_bottom_right]
+    text = text_recognizer.recognize(word_image, parameters=dict(language="eng"))
+    print(text)
+```
+
+> gentes,  
+fimul.  
+obibant  
+munera  
+fumma  
+facra,  

pyproject.toml

@@ -23,14 +23,14 @@ classifiers=[
 description = "Utils for automatic document images processing"
 keywords = ["text detection", "text recognition", "OCR", "deep learning", "computer vision"]
 readme="README.md"
-license = {file = "LICENSE.txt"}
+license = {file = "LICENSE"}
 dynamic = ["version"]
 requires-python = ">=3.6"
 dependencies = [
     "numpy==1.23.3",
     "opencv-python==4.6.0.66",
     "pyclipper==1.3.0.post4",  # for doctr
-    "pytesseract==0.3.0",
+    "pytesseract==0.3.10",
     "scikit_learn==1.0.2",
     "shapely==2.0.1",  # for doctr
     "tqdm==4.65.0",  # for doctr
@@ -42,6 +42,8 @@ torch = [
     "torchvision~=0.12.0"
 ]
 dev = [
+    "build==0.10.0",
+    "twine==4.0.2",
     "pycodestyle==2.7.0",
     "flake8==3.9.2",
     "flake8-annotations==2.6.2",