Metadata-Version: 2.4
Name: bretina
Version: 1.0.0
Summary: Bender Robotics Visual Test Support
Author-email: Bender Robotics <kumpan@benderrobotics.com>
License: MIT
Project-URL: Homepage, https://www.benderrobotics.com
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3.10
Classifier: Programming Language :: Python :: 3.11
Classifier: Programming Language :: Python :: 3.12
Classifier: Programming Language :: Python :: 3.13
Classifier: License :: OSI Approved :: MIT License
Classifier: Operating System :: OS Independent
Requires-Python: >=3.10
Description-Content-Type: text/markdown
License-File: LICENSE
Requires-Dist: opencv-contrib-python>=4.10.0.84
Requires-Dist: numpy>=1.24
Requires-Dist: pytesseract<=0.3.10,>=0.3.9
Requires-Dist: Pillow>=8.3.2
Requires-Dist: htmllogging>=0.0.1
Requires-Dist: paddlepaddle<4.0,>=3.3.1
Requires-Dist: paddleocr<4.0,>=3.7.0
Provides-Extra: models
Requires-Dist: bretina-models<2.0,>=1.0; extra == "models"
Provides-Extra: dev
Requires-Dist: ruff>=0.16; extra == "dev"
Requires-Dist: yapf>=0.43; extra == "dev"
Requires-Dist: mypy>=2.3; extra == "dev"
Requires-Dist: pytest; extra == "dev"
Requires-Dist: pytest-cov; extra == "dev"
Requires-Dist: pre-commit; extra == "dev"
Requires-Dist: build; extra == "dev"
Requires-Dist: types-Pillow; extra == "dev"
Provides-Extra: docs
Requires-Dist: Sphinx; extra == "docs"
Requires-Dist: sphinx-rtd-theme; extra == "docs"
Dynamic: license-file

[![pipeline status](https://gitlab.benderrobotics.com/br/tools/bretina/badges/devel/pipeline.svg)](https://gitlab.benderrobotics.com/br/tools/bretina/-/pipelines)&thinsp;[![coverage report](https://gitlab.benderrobotics.com/br/tools/bretina/badges/devel/coverage.svg)](https://gitlab.benderrobotics.com/br/tools/bretina/-/commits/devel)&thinsp;[![pre-commit](https://img.shields.io/badge/pre--commit-enabled-brightgreen?logo=pre-commit&logoColor=white)](https://github.com/pre-commit/pre-commit)&thinsp;[![Latest Release](https://gitlab.benderrobotics.com/br/tools/bretina/-/badges/release.svg)](https://gitlab.benderrobotics.com/br/tools/bretina/-/releases)


# Bretina - Python Image Testing Framework

Bretina is a python package designed to support testing of the images.

![Intro](docs/_static/fig_intro.png)

Bretina is designed as an extension of the python
[unit test](https://docs.python.org/3/library/unittest.html) module. Provides
set of assertions which can be used to verify correctness of the image.

In typical application, content of the device LCD display is captured with a
camera and Bretina is used to verify correctness of the defined regions in the
image - such as region color, presence of an icon, correctness of the text
representation and other aspects.

## Documentation

can be found on https://docs.benderrobotics.com/bretina (Not publicly available ATM).

## Download and install latest release

Bretina can be downloaded from within the internal BR network by calling:

```console
    $ pip install bretina
```

For optical character recognition Bretina offers two engines:
- [Tesseract](https://github.com/tesseract-ocr/tesseract)
- [PaddleOCR](https://github.com/PADDLEPADDLE/PADDLEOCR)

To change the OCR engine set the `bretina.OCR_ENGINE` to either OcrEngine.TESSERACT
or OcrEngine.PADDLE. By default OcrEngine.TESSERACT is set.

### PaddleOCR local models

By default PaddleOCR downloads its models from the internet on first use. To use
models bundled locally instead, install the `models` extra. The `bretina-models`
package is hosted on the Bender Robotics private PyPI, so it has to be passed as
the extra index:

```console
    $ pip install bretina[models] --extra-index-url https://pypi.benderrobotics.com
```

When the `bretina-models` package is available, PaddleOCR automatically uses the
local models instead of downloading them.

### PaddleOCR on Windows

PaddleOCR's native library (`paddlepaddle`) requires the Microsoft Visual C++
Redistributable (x64). Without it, the first Paddle OCR call fails with
`ImportError: DLL load failed while importing libpaddle: The specified module
could not be found.`. Install the latest redistributable from
https://learn.microsoft.com/en-us/cpp/windows/latest-supported-vc-redist?view=msvc-170#latest-supported-redistributable-version
and reboot.

### Tesseract usage

To utilize Tesseract, it has to be installed as a standalone application
and registered into system `PATH`. Installation files can be downloaded from
https://github.com/tesseract-ocr/tesseract (tested with Tesseract version 5).
Windows installer is provided by **Mannheim University Library** at
https://github.com/UB-Mannheim/tesseract/wiki.

After the installation, add path to the `tesseract.exe` to your system `PATH`.

For the best OCR performance install the slower, but more accurate datasets
`tessdata_best` (https://github.com/tesseract-ocr/tessdata_best). Extract the
downloaded archive into the installation directory of the tesseract OCR.

This is an expected structure of the tesseract installation directory:

- `C:\Program Files\Tesseract-OCR`- tesseract installation
  - `\tessdata` - original tessdata dataset
    - `afr.traineddata`
    - ...
  - `\tessdata_best` - extracted best dataset
    - `afr.traineddata`
    - ...

## Working with the source

Clone the repository first, then check out `devel` for the latest version, or a
`feature/*` branch for the cutting edge one.

```console
    $ git checkout devel
```

### Development setup

Install the package in editable mode with the development dependencies:

```console
    $ pip install -e .[dev]
```

Do this before anything else. The version is derived from the git tags by
setuptools-scm, which writes the generated `src/bretina/__version__.py` at
install and build time. A freshly cloned, never installed checkout has no such
file, so `import bretina` fails until you install or build once.

Install the git hooks as well, so the formatting and lint gate runs before every
commit instead of failing in CI:

```console
    $ pre-commit install
```

### Building the wheel

```console
    $ python -m build
```

The wheel and the source distribution are written to `dist/`.

### VS Code tasks

The recommended entry point for everyday work are the tasks in
`.vscode/tasks.json`, run through *Terminal* > *Run Task...*. They are the same
commands CI runs, so a green task means a green pipeline (usually):

| Task            | Command                                   | Purpose                                    |
| --------------- | ----------------------------------------- | ------------------------------------------ |
| `install (dev)` | `pip install -e .[dev]`                   | editable install with the dev dependencies |
| `build`         | `python -m build`                         | build the wheel and the sdist              |
| `lint`          | `ruff check`                              | lint the package and the tests             |
| `format`        | `yapf -i -r src tests tools docs/conf.py` | reformat in place                          |
| `typing`        | `mypy`                                    | type check                                 |
| `test`          | `pytest`                                  | run the whole test suite                   |

Neither `ruff` nor `mypy` takes a path argument, both are configured in `pyproject.toml`.
