README.md

# DAN: a Segmentation-free Document Attention Network for Handwritten Document Recognition

[![Python >= 3.10](https://img.shields.io/badge/Python-%3E%3D3.10-blue.svg)](https://www.python.org/downloads/release/python-3100/)

## Documentation

To use DAN in your own scripts, install it using pip:

```console
pip install -e .
```

For more details about this package, make sure to see the documentation available at https://teklia.gitlab.io/atr/dan/.

## Development

For development and tests purpose it may be useful to install the project as a editable package with pip.

* Use a virtualenv (e.g. with virtualenvwrapper `mkvirtualenv -a . dan`)
* Install `dan` as a package (e.g. `pip install -e .`)

### Linter

Code syntax is analyzed before submitting the code.\
To run the linter tools suite you may use pre-commit.
```shell
pip install pre-commit
pre-commit run -a
```

### Run tests

Tests are executed with `tox` using [pytest](https://pytest.org).
To install `tox`,
```shell
pip install tox
tox
```

To reload the test virtual environment you can use `tox -r`

Run a single test module: `tox -- <test_path>`
Run a single test: `tox -- <test_path>::<test_function>`

The tests use a large file stored via [Git-LFS](https://docs.gitlab.com/ee/topics/git/lfs/). Make sure to run `git-lfs pull` before running them.

### Update documentation

Please keep the documentation updated when modifying or adding features.
It's pretty easy to do:
```shell
pip install -r doc-requirements.txt
mkdocs serve
```

You can then write in Markdown in the relevant `docs/*.md` files, and see live output on http://localhost:8000.

## Inference

To apply DAN to an image, one needs to first add a few imports and to load an image. Note that the image should be in RGB.
```python
import cv2
from dan.predict import DAN

image = cv2.cvtColor(cv2.imread(IMAGE_PATH), cv2.COLOR_BGR2RGB)
```

Then one can initialize and load the trained model with the parameters used during training.
```python
model_path = 'model.pt'
params_path = 'parameters.yml'
charset_path = 'charset.pkl'

model = DAN('cpu')
model.load(model_path, params_path, charset_path, mode="eval")
```

To run the inference on a GPU, one can replace `cpu` by the name of the GPU. In the end, one can run the prediction:
```python
text, confidence_scores = model.predict(image, confidences=True)
```

## Training

This package provides three subcommands. To get more information about any subcommand, use the `--help` option.

### Get started

See the [dedicated section](https://teklia.gitlab.io/atr/dan/get_started/training/) on the official DAN documentation.

### Data extraction from Arkindex

See the [dedicated section](https://teklia.gitlab.io/atr/dan/usage/datasets/extract/) on the official DAN documentation.

### Dataset formatting

See the [dedicated section](https://teklia.gitlab.io/atr/dan/usage/datasets/format/) on the official DAN documentation.

### Model training

See the [dedicated section](https://teklia.gitlab.io/atr/dan/usage/train/) on the official DAN documentation.

### Model prediction

See the [dedicated section](https://teklia.gitlab.io/atr/dan/usage/predict/) on the official DAN documentation.