ars-lib 0.0.2
Attribute recognition system
Requires Python: >=3.6

<p align="center">
	<img src="https://user-images.githubusercontent.com/30909274/111303777-f8dd3e80-8665-11eb-9042-ca8ecba9d717.png">
</p>

# Распознавание полей документа с использованием Tesseract-OCR
______
## Содержание репозитория
* Модули
	* Создание и обучение свёрточной нейронной сети для распознавания формата листа документа
	* Создание датасета документов в виде файла с расширением `.csv`
	* Графический интерфейс приложения для распознавания определенных полей документа
	* Расчёт метрик, оценивающих качество выделения определенных полей документа
* Тесты
	* Pytest-тест качества распознавания формата листа документа
	* Pytest-тест качества выделения определенных полей документа
	* Pytest-тест функции вовзврата картинок областей из исходного документа

## Пояснения к содержимому репозитория
:bookmark: **Файл**
:bookmark: *Директория*
* *modules* - содержит модули.
	
	* **cnn_format.py** - содержит реализацию сверточной нейронной сети.
	* **create_dataset.py** - создает `.csv` файл, в который вручную заносится информацию о документе.
	* **function.py** - содержит все необходимые функции и зависимости для работы модулей.
	* **gui.py** - автоматически создавается при реализации GUI через QtDesigner.
	* **interface.py** - описание обработчиков событий кнопок из GUI.
	* **metrics_fields.py** - содержит метод, реализующий расчет основных метрик для оценки качества выделения полей.
	* **radon_transform.py** - демонстрирует работу пребразования Радона.
	* **relative_markup.py** - демонстрирует работу относительной разметки документа.
	* **cropping_image.py** - демонстрирует работу функции, возвращающий отдельные картинки областей.

* *tests* - содержит тесты.
	
	* **test_crop.py** - тест функции, возвращающей отдельные картинки областей.
	* **test_format.py** - тест реализации нейронной сети.
	* **test_markup.py** - тест относительной разметки документа.

* *sources* - содержит ресурсы проекта.
* *instruction* - содержит картинки с инструкцией по настройке pytest в PyCharm.
* **README.md** - краткое описание проекта.

## Запуск тестов
Для выполнения тестирования необходимо установить библиотеку [pytest](https://docs.pytest.org/en/stable/getting-started.html). Для работы
с pytest в среде разработки PyCharm необходимо указать каталог с тестами и корневой каталог проекта. 
Инструкцию по настройке pytest в PyCharm можно найти в *instruction*.
Запуск тестирования осуществляется нажатием кнопки `Run 'pytest in tests'`.

## Запуск модулей
Для корректной работы всех исходных модулей необходимо извлечь архив с дополнительными материалами в корневой каталог проекта.
Дополнительные материалы можно скачать по ссылке, указанной ниже. После этого можно воспользоваться имеющимся функционалом.

#### :white_circle: Скрипт, реализующий свёрточную нейронную сеть для распознавания формата листа документа
Данный скрипт написан для создания и обучения модели, осуществляющей автоматическое распознавание формата листа документа. Для работы необходимо запустить
на исполнение файл `cnn_format.py`. Скрипт содержит набор входных параметров:
* **num_epoch** - число эпох (*значение по умолчанию `10`*).
* **batch_size** - размер "батча" (*значение по умолчанию `16`*).
* **learning_rate** - скорость обучения (*значение по умолчанию `0.001`*).
* **action_mode** - режим работы (`"1"` - создание + обучение; `"0"` - тестирование существующей модели).
* **img_folder_path** - путь до каталога с датасетом изображений. Датасет изображений можно найти в дополнительных материалах, прикрепленных ниже.
(*./data/dataset_img/full_dataset_img_oversampling*).
* **split_test_size** - процент тестовых данных из датасета (*значение по умолчанию `0.4`*).
* **model_path** - конечный путь создаваемой/существующей нейронной сети (*значение по умолчанию `format.pth`*).

В режиме создания/обучения модели выполнение скрипта будет сопровождаться периодической индикацией текущего прогресса в консольном окне.
После завершения обучения модели в консольное окно выведется таблица с основными метриками, оценивающими качество распознавания формата
листа текущей моделью.

В режиме тестирования существующей модели происходит прогон этой модели по тестовым данным с выводом в консольное окно таблицы с основными метриками.

#### :white_circle: Скрипт, реализующий возможность создания рабочего датасета
Данный скрипт написан для создания `.csv-файла`, являющегося датасетом для текущего проекта. Для работы необходимо запустить на исполнение файл
`create_dataset.py`. Скрипт содержит набор входных параметров:
* **img_folder_path** - путь до каталога с датасетом изображений (*./data/dataset_img/full_dataset_img_without_classess*).
* **csv_file_path** - конечный путь создаваемого csv-файла.

После запуска скрипта происходит загрузка всех изображений из указанного каталога. Для каждого изображения четыре раза вызывается `cv2.selectROI`
с целью выделения необходимых полей документа. После выделения каждой области потребуется ввести данные из этой области в консольном окне.

#### :white_circle: Скрипт, реализующий графический интерфейс для приложения по распознаванию полей документа
Данный скрипт содержит логику работы графического интерфейса, созданного при помощи [QtDesigner](https://doc.qt.io/qt-5/qtdesigner-manual.html).
Здесь описаны обработчики нажатия на кнопки. Для работы необходимо запустить на исполнение файл `interface.py`.
На текущий момент исправно обрабатываются нажатия на кнопки:
* `Выбрать файл (.pdf)`.
* `Распознать`.

С помощью `Выбрать файл (.pdf)` загружается выбранный пользователем документ в формате *.pdf*. Эскиз документа выводится в соответствующем окне
графического интерфейса. Нажатие на кнопку `Распознать` демонстрирует работу обученной нейронной сети по определению формата листа документа.
Формат, предсказанный моделью, выводится в соответствующее поле в окне приложения.

Стоит отметить, что данный GUI **не является** финальной версией приложения и требует многочисленных доработок.

#### :white_circle: Скрипт, реализующий расчет основных метрик для оценки качества детектирования полей документа
Данный скрипт написан для оценки качества выделения полей из документа. Для работы необходимо запустить на исполнение файл `metrics_fields.py`.
Скрипт содержит набор входных параметров:
* **csv_path** - путь до *.csv-файла* с датасетом (*./data/dataset_csv/dataset_csv_new/fulldataset.csv*).
* **img_folder_path** - путь до каталога с документами в формате *.jpg*.
* **disp_mode** - режим работы скрипта (`"1"` - с отображением пересечения прямоугольников, соответствущих истинным областям из датасета и предсказанных
с использованием относительной разметки документа; `"0"` - без отображения пересечений прямоугольников).
* **with_jaccard** - флаг, определяющий необходимость расчета меры Жаккара (*значение по умолчанию `1`*).

Скрипт возвращает *4 списка* метрик (для каждого формата документа). Каждый список содержит *2 вложенных списка*:
* поле для распознавание.
* метрика (*при `with_jaccard = 1` - кортеж (jaccard, precision, recall, f1-score);*
*при `with_jaccard = 0` - кортеж (precision, recall, f1-score)*).

Результат работы скрипта также отображается в консольном окне в виде таблицы данных.

#### :white_circle: Скрипт, демонстрирующий работу преобразования Радона
Данный скрипт написан для демонстрации работы преобразования Радона. Для работы необходимо запустить на исполнение файл `radon_transform.py`.
Скрипт содержит 2 входных параметра:
* **img_path** - конечный путь до изображения.
* **disp_mode** - режим работы скрипта (`"1"` - с отображением графиков; `"0"` - без отображения графиков).

Скрипт возвращает довернутое изображение. В консольное окно выводится угол доворота.

#### :white_circle: Скрипт, демонстрирующий работу функции, возвращающей картинки задетектированных полей документа
Данный скрипт написан для демонстрации работы функции, возвращающей картинки полей документа. Для работы необходимо запустить на исполнение
файл `cropping_image.py`. Скрипт содержит 2 входных параметра:
* **img_path** - конечный путь до изображения. 
* **cnn_path** - конечный путь до обученной нейронной сети.

Результатом работы скрипта является вывод 4-х изображений - задетектированных полей из документа.

#### :white_circle: Скрипт, демонстрирующий работу относительной разметки документа
Данный скрипт написан для демонстрации детектирования полей с помощью относительной разметки документа. Для работы необходимо запустить на
исполнение файл `relative_markup.py`. Скрипт содержит 2 входных параметра:
* **img_folder_path** - путь до каталога с документами в формате *.jpg*.
* **cnn_path** - конечный путь до обученной нейронной сети.

Результатом является исходный документ с выделенными на нем полями.

#### :white_circle: Скрипт, выполняющий распознавание текста из задетектированных полей документа
Данный скрипт написан для распознавания текста из выделенных полей. Для работы необходимо запустить на исполнение файл `recognize_crop.py`.
Входных параметров у скрипта нет, но для корректной работы неоходимо задать несколько переменных окружения:
* **tess_cmd** - путь до tesseract.exe.
* **cust_conf** - конфигурационная строка, определяющая режим работы tesseract.

Результат работы скрипта - распознанный текст, который выводится в консольное окно.

## Установка Tesseract-OCR
Подробную инструкцию по установке можно найти в [официальной документации](https://tesseract-ocr.github.io/tessdoc/Installation.html).
_____