formhtr 0.1.0__tar.gz

formhtr-0.1.0/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2023 Matej Troják
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

formhtr-0.1.0/MANIFEST.in

@@ -0,0 +1,2 @@
+recursive-include src/formhtr/data *
+

formhtr-0.1.0/PKG-INFO

@@ -0,0 +1,183 @@
+Metadata-Version: 2.4
+Name: formhtr
+Version: 0.1.0
+Summary: Handprint text recognition in form documents.
+Author-email: Matej Trojak <matej.trojak@embl.de>
+License-Expression: MIT
+Project-URL: Repository, https://github.com/grp-bork/formHTR
+Keywords: ocr,forms,computer-vision
+Classifier: Programming Language :: Python :: 3
+Classifier: Operating System :: OS Independent
+Requires-Python: >=3.10
+Description-Content-Type: text/markdown
+License-File: LICENSE
+Requires-Dist: numpy
+Requires-Dist: opencv-python
+Requires-Dist: pillow==9.5.0
+Requires-Dist: pdf2image
+Requires-Dist: pandas
+Requires-Dist: xlsxwriter
+Requires-Dist: imutils
+Requires-Dist: zxing-cpp
+Requires-Dist: google-cloud-vision
+Requires-Dist: rtree
+Requires-Dist: boto3
+Requires-Dist: azure-cognitiveservices-vision-computervision
+Requires-Dist: pyzbar
+Requires-Dist: biopython
+Requires-Dist: scikit-image
+Requires-Dist: img2pdf
+Requires-Dist: PyPDF2
+Dynamic: license-file
+
+# formHTR
+Handprint text recognition in form documents.
+
+[![PyPI version](https://img.shields.io/pypi/v/formhtr.svg)](https://pypi.org/project/formhtr/)
+
+![Trec](https://github.com/grp-bork/formHTR/assets/15349569/c0789616-80d0-43c8-8693-d3d9f070511c)
+
+## Installation
+
+### pip
+
+```bash
+pip install formhtr
+```
+
+The tool also requires the `zbar` shared library installed (used by `pyzbar`).
+For PDF-related tooling, `qpdf` is also required.
+
+System dependencies:
+
+- macOS (Homebrew): `brew install zbar qpdf`
+- Debian/Ubuntu: `sudo apt-get install libzbar0 qpdf`
+- Fedora: `sudo dnf install zbar qpdf`
+
+You can verify runtime requirements with:
+
+```bash
+formhtr doctor
+```
+
+### conda (dev)
+
+```
+conda env create -f conda_env.yaml
+```
+
+## Usage
+
+Run `formhtr --help` for full CLI help.
+
+### Quickstart
+
+```bash
+# 1) Verify system dependencies
+formhtr doctor
+
+# 2) Create ROI config for a template
+formhtr select-rois --pdf-file template.pdf --output-file config.json
+
+# 3) Optionally annotate ROI types and variable names
+formhtr annotate-rois --pdf-file template.pdf --config-file config.json --output-file config_annotated.json
+
+# 4) Process a scanned logsheet into XLSX
+formhtr process-logsheet \
+  --pdf-logsheet scan.pdf \
+  --pdf-template template.pdf \
+  --config-file config_annotated.json \
+  --output-file output.xlsx \
+  --google google_credentials.json \
+  --amazon amazon_credentials.json \
+  --azure azure_credentials.json
+```
+
+### Create ROIs
+
+This functionality is split (for now) into two separate scripts.
+
+#### select ROIs
+
+Find and define locations of regions of interest (ROIs) in the given PDF.
+
+Generally, it is possible to draw ROIs (rectangles) manually but also to detect them automatically.
+The coordinates of ROIs are stored in a JSON file.
+
+The tool is supposed to be run from the command line, as the control commands are entered there.
+
+*Control commands*
+
+* Press `q` or `Esc` to exit editing and save the config file.
+* Press `r` to remove the last rectangle.
+
+Run `formhtr select-rois -h` for details.
+
+#### annotate ROIs
+
+Specify the type of content for each rectangle.
+
+The workflow is designed in a way that you can navigate over specified ROIs and assign them the expected type of their content.
+This is done by pressing appropriate control commands.
+
+*Control commands*
+
+* Press `q` or `Esc` to exit editing and save the config file.
+* Press `h` to add "Handwritten" type to the current ROI.
+* Press `c` to add "Checkbox" type to the current ROI.
+* Press `b` to add "Barcode" type to the current ROI.
+* Press `r` or `d` to delete the type from the current ROI.
+* Press `v` to enter the variable name.
+* Press an arrow to navigate through ROIs (only left and right for now).
+
+Run `formhtr annotate-rois -h` for details.
+
+### process logsheet
+
+Extract values from specified ROIs.
+
+This is the crucial step that applies various techniques to extract the information as precisely as possible.
+It can process one logsheet at a time, given the template and config files.
+
+Run `formhtr process-logsheet -h` for details.
+
+#### Credentials
+
+The processing of logsheets is using external services requiring credentials to use them. Here we specify structure that is expected for credentials, always in JSON format.
+
+__Google__
+
+```
+{
+  "type": "service_account",
+  "project_id": "theid",,
+  "private_key_id": "thekey",
+  "private_key": "-----BEGIN PRIVATE KEY-----anotherkey-----END PRIVATE KEY-----\n"
+  "client_email": "emailaddress",
+  "client_id": "id",
+  "auth_uri": "https://accounts.google.com/o/oauth2/auth",
+  "token_uri": "https://oauth2.googleapis.com/token",
+  "auth_provider_x509_cert_url": "https://www.googleapis.com/oauth2/v1/certs",
+  "client_x509_cert_url": "someurl",
+  "universe_domain": "googleapis.com"
+}
+```
+
+__Amazon__
+
+```
+{
+    "ACCESS_KEY": "YOUR_KEY_ID_HERE",
+    "SECRET_KEY": "YOUR_ACCESS_KEY_HERE",
+    "REGION": "YOUR_REGION_NAME_HERE"
+}
+```
+
+__Microsoft__
+
+```
+{
+    "SUBSCRIPTION_KEY": "YOURKEYHERE",
+    "ENDPOINT": "https://ENDPOINT"
+}
+```

formhtr-0.1.0/README.md

@@ -0,0 +1,151 @@
+# formHTR
+Handprint text recognition in form documents.
+
+[![PyPI version](https://img.shields.io/pypi/v/formhtr.svg)](https://pypi.org/project/formhtr/)
+
+![Trec](https://github.com/grp-bork/formHTR/assets/15349569/c0789616-80d0-43c8-8693-d3d9f070511c)
+
+## Installation
+
+### pip
+
+```bash
+pip install formhtr
+```
+
+The tool also requires the `zbar` shared library installed (used by `pyzbar`).
+For PDF-related tooling, `qpdf` is also required.
+
+System dependencies:
+
+- macOS (Homebrew): `brew install zbar qpdf`
+- Debian/Ubuntu: `sudo apt-get install libzbar0 qpdf`
+- Fedora: `sudo dnf install zbar qpdf`
+
+You can verify runtime requirements with:
+
+```bash
+formhtr doctor
+```
+
+### conda (dev)
+
+```
+conda env create -f conda_env.yaml
+```
+
+## Usage
+
+Run `formhtr --help` for full CLI help.
+
+### Quickstart
+
+```bash
+# 1) Verify system dependencies
+formhtr doctor
+
+# 2) Create ROI config for a template
+formhtr select-rois --pdf-file template.pdf --output-file config.json
+
+# 3) Optionally annotate ROI types and variable names
+formhtr annotate-rois --pdf-file template.pdf --config-file config.json --output-file config_annotated.json
+
+# 4) Process a scanned logsheet into XLSX
+formhtr process-logsheet \
+  --pdf-logsheet scan.pdf \
+  --pdf-template template.pdf \
+  --config-file config_annotated.json \
+  --output-file output.xlsx \
+  --google google_credentials.json \
+  --amazon amazon_credentials.json \
+  --azure azure_credentials.json
+```
+
+### Create ROIs
+
+This functionality is split (for now) into two separate scripts.
+
+#### select ROIs
+
+Find and define locations of regions of interest (ROIs) in the given PDF.
+
+Generally, it is possible to draw ROIs (rectangles) manually but also to detect them automatically.
+The coordinates of ROIs are stored in a JSON file.
+
+The tool is supposed to be run from the command line, as the control commands are entered there.
+
+*Control commands*
+
+* Press `q` or `Esc` to exit editing and save the config file.
+* Press `r` to remove the last rectangle.
+
+Run `formhtr select-rois -h` for details.
+
+#### annotate ROIs
+
+Specify the type of content for each rectangle.
+
+The workflow is designed in a way that you can navigate over specified ROIs and assign them the expected type of their content.
+This is done by pressing appropriate control commands.
+
+*Control commands*
+
+* Press `q` or `Esc` to exit editing and save the config file.
+* Press `h` to add "Handwritten" type to the current ROI.
+* Press `c` to add "Checkbox" type to the current ROI.
+* Press `b` to add "Barcode" type to the current ROI.
+* Press `r` or `d` to delete the type from the current ROI.
+* Press `v` to enter the variable name.
+* Press an arrow to navigate through ROIs (only left and right for now).
+
+Run `formhtr annotate-rois -h` for details.
+
+### process logsheet
+
+Extract values from specified ROIs.
+
+This is the crucial step that applies various techniques to extract the information as precisely as possible.
+It can process one logsheet at a time, given the template and config files.
+
+Run `formhtr process-logsheet -h` for details.
+
+#### Credentials
+
+The processing of logsheets is using external services requiring credentials to use them. Here we specify structure that is expected for credentials, always in JSON format.
+
+__Google__
+
+```
+{
+  "type": "service_account",
+  "project_id": "theid",,
+  "private_key_id": "thekey",
+  "private_key": "-----BEGIN PRIVATE KEY-----anotherkey-----END PRIVATE KEY-----\n"
+  "client_email": "emailaddress",
+  "client_id": "id",
+  "auth_uri": "https://accounts.google.com/o/oauth2/auth",
+  "token_uri": "https://oauth2.googleapis.com/token",
+  "auth_provider_x509_cert_url": "https://www.googleapis.com/oauth2/v1/certs",
+  "client_x509_cert_url": "someurl",
+  "universe_domain": "googleapis.com"
+}
+```
+
+__Amazon__
+
+```
+{
+    "ACCESS_KEY": "YOUR_KEY_ID_HERE",
+    "SECRET_KEY": "YOUR_ACCESS_KEY_HERE",
+    "REGION": "YOUR_REGION_NAME_HERE"
+}
+```
+
+__Microsoft__
+
+```
+{
+    "SUBSCRIPTION_KEY": "YOURKEYHERE",
+    "ENDPOINT": "https://ENDPOINT"
+}
+```

formhtr-0.1.0/pyproject.toml

@@ -0,0 +1,52 @@
+[build-system]
+requires = ["setuptools>=68", "wheel"]
+build-backend = "setuptools.build_meta"
+
+[project]
+name = "formhtr"
+version = "0.1.0"
+description = "Handprint text recognition in form documents."
+readme = "README.md"
+requires-python = ">=3.10"
+license = "MIT"
+authors = [
+  { name = "Matej Trojak", email = "matej.trojak@embl.de" }
+]
+keywords = ["ocr", "forms", "computer-vision"]
+classifiers = [
+  "Programming Language :: Python :: 3",
+  "Operating System :: OS Independent",
+]
+dependencies = [
+  "numpy",
+  "opencv-python",
+  "pillow==9.5.0",
+  "pdf2image",
+  "pandas",
+  "xlsxwriter",
+  "imutils",
+  "zxing-cpp",
+  "google-cloud-vision",
+  "rtree",
+  "boto3",
+  "azure-cognitiveservices-vision-computervision",
+  "pyzbar",
+  "biopython",
+  "scikit-image",
+  "img2pdf",
+  "PyPDF2",
+]
+
+[project.urls]
+Repository = "https://github.com/grp-bork/formHTR"
+
+[project.scripts]
+formhtr = "formhtr.cli:main"
+
+[tool.setuptools]
+package-dir = {"" = "src"}
+include-package-data = true
+
+[tool.setuptools.packages.find]
+where = ["src"]
+

formhtr-0.1.0/setup.cfg

@@ -0,0 +1,4 @@
+[egg_info]
+tag_build = 
+tag_date = 0
+

formhtr-0.1.0/src/formhtr/__init__.py

@@ -0,0 +1,8 @@
+"""formHTR: handprint text recognition in form documents."""
+
+from __future__ import annotations
+
+__all__ = ["__version__"]
+
+__version__ = "0.1.0"
+

formhtr-0.1.0/src/formhtr/cli.py

@@ -0,0 +1,163 @@
+from __future__ import annotations
+
+import argparse
+import sys
+
+from . import __version__
+from .deps import check_system_dependencies, ensure_system_dependencies
+from .logsheet import load_credentials, process_logsheet_to_xlsx
+from .manual_align import manual_align_pdf
+from .roi_tools import annotate_rois, select_rois
+
+
+def _build_parser() -> argparse.ArgumentParser:
+    parser = argparse.ArgumentParser(prog="formhtr", description="formHTR CLI")
+    parser.add_argument("--version", action="version", version=f"%(prog)s {__version__}")
+
+    sub = parser.add_subparsers(dest="command", required=True)
+
+    p_process = sub.add_parser("process-logsheet", help="Extract values from a scanned logsheet to XLSX")
+    p_process.add_argument("--pdf-logsheet", required=True, help="Scanned logsheet PDF")
+    p_process.add_argument("--pdf-template", required=True, help="Template PDF")
+    p_process.add_argument("--config-file", required=True, help="Config JSON")
+    p_process.add_argument("--output-file", required=True, help="Output XLSX file")
+    p_process.add_argument("--google", required=True, help="Path to Google Vision credentials JSON")
+    p_process.add_argument("--amazon", required=True, help="Path to Amazon credentials JSON")
+    p_process.add_argument("--azure", required=True, help="Path to Azure credentials JSON")
+    p_process.add_argument("--debug", action=argparse.BooleanOptionalAction, default=False, help="Output annotated PDFs")
+    p_process.add_argument("--backside", action=argparse.BooleanOptionalAction, default=False, help="Backside page present")
+    p_process.add_argument("--backside-template", help="Backside template PDF")
+    p_process.add_argument("--backside-config", help="Backside config JSON")
+    p_process.add_argument(
+        "--ugly-checkboxes",
+        action=argparse.BooleanOptionalAction,
+        default=False,
+        help="Checkboxes have irregular shape / thick edges",
+    )
+    p_process.add_argument(
+        "--aligned",
+        action=argparse.BooleanOptionalAction,
+        default=False,
+        help="Scanned image already aligned with template (skip alignment)",
+    )
+    p_process.add_argument(
+        "--filter-grayscale",
+        action=argparse.BooleanOptionalAction,
+        default=False,
+        help="During alignment keep only darkest grayscale pixels",
+    )
+
+    p_align = sub.add_parser("manual-align", help="Interactively align a scanned PDF to a template")
+    p_align.add_argument("--pdf-template", required=True, help="Template PDF")
+    p_align.add_argument("--pdf-logsheet", required=True, help="Scanned logsheet PDF")
+    p_align.add_argument("--output", required=True, help="Output aligned PDF")
+    p_align.add_argument("--backside-template", help="Backside template PDF")
+
+    p_select = sub.add_parser("select-rois", help="Interactively define ROIs in a template PDF")
+    p_select.add_argument("--pdf-file", required=True, help="Template PDF")
+    p_select.add_argument("--output-file", required=True, help="Output config JSON")
+    p_select.add_argument("--autodetect", action=argparse.BooleanOptionalAction, default=False)
+    p_select.add_argument("--autodetect-filter", type=float, default=3)
+    p_select.add_argument("--config-file", default=None, help="Existing config JSON to continue editing")
+    p_select.add_argument("--detect-residuals", action=argparse.BooleanOptionalAction, default=False)
+    p_select.add_argument("--credentials", default=None, help="Google credentials JSON (for residual detection)")
+    p_select.add_argument("--display-residuals", action=argparse.BooleanOptionalAction, default=False)
+
+    p_annot = sub.add_parser("annotate-rois", help="Interactively label ROI types/variables")
+    p_annot.add_argument("--pdf-file", required=True, help="Template PDF")
+    p_annot.add_argument("--config-file", required=True, help="Input config JSON")
+    p_annot.add_argument("--output-file", required=True, help="Output config JSON")
+    p_annot.add_argument("--remove-unannotated", action=argparse.BooleanOptionalAction, default=False)
+    p_annot.add_argument("--display-residuals", action=argparse.BooleanOptionalAction, default=False)
+
+    sub.add_parser("doctor", help="Check required system dependencies")
+
+    return parser
+
+
+def main(argv: list[str] | None = None) -> int:
+    parser = _build_parser()
+    args = parser.parse_args(argv)
+
+    if args.command == "process-logsheet":
+        ensure_system_dependencies({"zbar"})
+        if args.backside and (not args.backside_template or not args.backside_config):
+            parser.error("--backside requires --backside-template and --backside-config.")
+
+        credentials = load_credentials(
+            google_credentials_path=args.google,
+            amazon_credentials_path=args.amazon,
+            azure_credentials_path=args.azure,
+        )
+
+        ratio = process_logsheet_to_xlsx(
+            scanned_logsheet_pdf=args.pdf_logsheet,
+            template_pdf=args.pdf_template,
+            config_json=args.config_file,
+            output_xlsx=args.output_file,
+            credentials=credentials,
+            debug=args.debug,
+            backside=args.backside,
+            backside_template_pdf=args.backside_template,
+            backside_config_json=args.backside_config,
+            ugly_checkboxes=args.ugly_checkboxes,
+            already_aligned=args.aligned,
+            filter_grayscale=args.filter_grayscale,
+        )
+        if ratio is not None:
+            print(f"Success ratio: {ratio['ratio']:.3f}")
+        return 0
+
+    if args.command == "manual-align":
+        ensure_system_dependencies({"qpdf"})
+        manual_align_pdf(
+            template_pdf=args.pdf_template,
+            scanned_logsheet_pdf=args.pdf_logsheet,
+            output_pdf=args.output,
+            backside_template_pdf=args.backside_template,
+        )
+        return 0
+
+    if args.command == "select-rois":
+        if args.detect_residuals and not args.credentials:
+            parser.error("--detect-residuals requires --credentials.")
+        select_rois(
+            template_pdf=args.pdf_file,
+            output_config_json=args.output_file,
+            autodetect=args.autodetect,
+            autodetect_filter=args.autodetect_filter,
+            existing_config_json=args.config_file,
+            detect_residuals=args.detect_residuals,
+            google_credentials_path=args.credentials,
+            display_residuals=args.display_residuals,
+        )
+        return 0
+
+    if args.command == "annotate-rois":
+        annotate_rois(
+            template_pdf=args.pdf_file,
+            config_json=args.config_file,
+            output_config_json=args.output_file,
+            remove_unannotated=args.remove_unannotated,
+            display_residuals=args.display_residuals,
+        )
+        return 0
+
+    if args.command == "doctor":
+        missing = check_system_dependencies()
+        if not missing:
+            print("All required system dependencies are available: qpdf, zbar.")
+            return 0
+
+        print("Missing system dependencies:")
+        for name, hint in missing:
+            print(f"- {name}: {hint}")
+        return 1
+
+    parser.error(f"Unknown command: {args.command}")
+    return 2
+
+
+if __name__ == "__main__":
+    raise SystemExit(main(sys.argv[1:]))
+

formhtr-0.1.0/src/formhtr/deps.py

@@ -0,0 +1,42 @@
+from __future__ import annotations
+
+import ctypes.util
+import platform
+import shutil
+
+
+def _install_hint(dep_name: str) -> str:
+    system = platform.system().lower()
+    if system == "darwin":
+        return f"brew install {dep_name}"
+    if system == "linux":
+        if dep_name == "zbar":
+            return "apt: sudo apt-get install libzbar0  |  dnf: sudo dnf install zbar"
+        return f"apt: sudo apt-get install {dep_name}  |  dnf: sudo dnf install {dep_name}"
+    return f"Install {dep_name} using your system package manager."
+
+
+def check_system_dependencies() -> list[tuple[str, str]]:
+    missing: list[tuple[str, str]] = []
+
+    if shutil.which("qpdf") is None:
+        missing.append(("qpdf", _install_hint("qpdf")))
+
+    if ctypes.util.find_library("zbar") is None:
+        missing.append(("zbar", _install_hint("zbar")))
+
+    return missing
+
+
+def ensure_system_dependencies(required: set[str]) -> None:
+    missing = check_system_dependencies()
+    missing_required = [(name, hint) for name, hint in missing if name in required]
+    if not missing_required:
+        return
+
+    lines = ["Missing required system dependencies:"]
+    for name, hint in missing_required:
+        lines.append(f"- {name}: {hint}")
+    lines.append("Run `formhtr doctor` for a full dependency report.")
+    raise RuntimeError("\n".join(lines))
+

formhtr-0.1.0/src/formhtr/libs/__init__.py

@@ -0,0 +1,2 @@
+from __future__ import annotations
+