Простой шаблонизатор DOCX-документов с помощью Smart Document Engine

Мы в Smart Engines занимаемся системами распознавания документов, и мы решили проверить, сколько нужно времени, чтобы создать MVP инструмента, позволяющего предзаполнять типовые шаблоны в формате DOCX данными, извлекаемые из сканов и фотографий документов. В этой статье мы вам покажем как на базе нашей системы распознавания Smart Document Engine быстро сделать простой шаблонизатор, готовый к использованию и не требующий никакой предварительной подготовки пользователя. Кому интересно - добро пожаловать под кат!

Как же часто такое банальное действие, как заполнение какого-то договора, акта, или другого бизнес-документа, может доставлять море проблем и неудобств. Еще куда ни шло, если нужно заполнить ФИО из только что отсканированного паспорта в какой-нибудь банковский договор, и другое дело, если вам нужно заполнить несколько десятков однотипных документов, с источниками информации в других документах, и все это нужно сделать быстро, без ошибок, и в присутствии нетерпеливого клиента. 

Конечно, все эти операции можно и нужно автоматизировать. На помощь могут прийти, например, RPA-системы, с помощью которых пользователь должен лишь выполнить правильную последовательность действий по загрузке-выгрузке данных. Но для того, чтобы в компании RPA была внедрена, как правило, нужно выполнить целый большой проект, собрать нужное количество компонент, настроить их, научить пользователей пользоваться, и так далее и тому подобное. Что если пользователю нужно всего лишь сканировать набор типовых документов и заполнять банальные Word-овые документы с правильными реквизитами?

Мы покажем, как просто собрать минимальный, но функциональный шаблонизатор, используя Smart Document Engine и python с несколькими общедоступными пакетами. Манипуляции все будут демонстрироваться на примере SDK для MacOS, однако все то же самое заработает также и для Windows и для систем на базе Linux.

Распознавание документов с помощью Smart Document Engine

В основе шаблонизатора лежит, само собой, распознавание документов с помощью Smart Document Engine. Библиотека обладает рядом интерфейсов интеграции (основной интерфейс C++ и набор оберток), но, для максимальной простоты, функцию распознавания мы реализуем в виде CLI-приложения, используя в качестве основы С++-пример, который находится прямо в SDK-пакете.

Чтобы скомпилировать поставляемый консольный пример docengine_sample, нужно вставить в код подпись клиента, которая берется из документации SDK-пакета:

// Creating a session object - a main handle for performing recognition.
std::unique_ptr<se::doc::DocSession> session(
    engine->SpawnSession(*session_settings, “ABCDEFG….”));

После этого его можно собирать (например, лежащим рядом скриптом build_cpp.sh).

Консольный пример docengine_sample принимает три параметра: путь к изображению документа, путь к конфигурационному архиву и маску типов документа. Проверяем распознавание в стандартном режиме, к примеру, платежного поручения:

$ DYLD_LIBRARY_PATH=../../bin ./docengine_sample ../../testdata/rus.payment_order_sample.png ../../data-zip/bundle_docengine_photo.se "rus.payment_order*"
Smart Document Engine version 1.11.0
image_path = ../../testdata/rus.payment_order_sample.png
config_path = ../../data-zip/bundle_docengine_photo.se
document_types = rus.payment_order*

(... Скрыто много дополнительной информации …)

    Text fields (35 in total):
        amount                    : 20 003 000-00
        amount_words              : ДВАДЦАТЬ МИЛЛИОНОВ ТРИ ТЫСЯЧИ РУБЛЕЙ 00 КОПЕЕК
        beneficiary               : ООО "МЕЧТА"
        beneficiary_account       : 11223344556677889900
        beneficiary_bank          : МЕЖДУНАРОДНЫЙ ЗАПАДНЫЙ БАНК
        beneficiary_bank_invoice  : 33344455566677788899
        bik_beneficiary           : 987654321
        bik_payer                 : 012345678

(... и так далее …)

Для целей создания шаблонизатора слегка модифицируем код приложения:

1. В конфигурационном бандле bundle_docengine_photo.se по умолчанию используется режим, оптимизированный для распознавания фотографий (в нашем демо-приложении этот режим используется при распознавания документов с фотографий, полученных непосредственно на устройстве). Выставим сессиям распознавания режим “universal”, который более подходит в случае, когда заранее неизвестно, скан будет распознаваться или фотография (в демо-приложении этот режим используется при распознавании из галереи):

session_settings->SetCurrentMode("universal"); // переходим в режим universal
// For starting the session we need to set up the mask of document types
//     which will be recognized.
session_settings->AddEnabledDocumentTypes(document_types.c_str());

2. Уберем весь отладочный/информационный вывод и упростим функцию OutputRecognitionResult так, чтобы она выписывала тип и текстовые поля распознаванного документа в JSON-формате:

void OutputRecognitionResult(
    const se::doc::DocResult& recog_result) {
  if (recog_result.GetDocumentsCount() == 0) {
    printf("{}\n");
  } else {
    const se::doc::Document& doc = recog_result.DocumentsBegin().GetDocument();
    printf("{\"DOCTYPE\": \"%s\"", doc.GetAttribute("type"));
    for (auto f_it = doc.TextFieldsBegin();
         f_it != doc.TextFieldsEnd();
         ++f_it) {
      std::string escaped_value = std::regex_replace(
          f_it.GetField().GetOcrString().GetFirstString().GetCStr(), 
          std::regex("\""), "\\\"");
      printf(",\"%s\": \"%s\"", 
          f_it.GetKey(),
          escaped_value.c_str());
    }
    printf("}\n");
  }
}

3. Переименуем получившийся исходник в docengine_cli.cpp и перенесем его в директорию рядом с динамической библиотекой libdocengine.dylib (в моем случае - в директорию /bin SDK-пакета), после чего скомпилируем с rpath-привязкой так, чтобы он искал библиотеку рядом в исполняемым файлом:

$ clang++ docengine_cli.cpp -O2 -I ../include -L. -l docengine -o docengine_cli -Wl,-rpath,"@executable_path"

Проверяем (в вывод программы добавлены переводы строк для читабельности):

$ ./docengine_cli ../testdata/rus.payment_order_sample.png ../data-zip/bundle_docengine_photo.se "rus.payment_order*"
{"DOCTYPE": "rus.payment_order.type1","amount": "20 003 000-00",
 "amount_words": "ДВАДЦАТЬ МИЛЛИОНОВ ТРИ ТЫСЯЧИ РУБЛЕЙ 00 КОПЕЕК",
 "beneficiary": "ООО \"МЕЧТА\"","beneficiary_account": "11223344556677889900",
 "beneficiary_bank": "МЕЖДУНАРОДНЫЙ ЗАПАДНЫЙ БАНК",
 "beneficiary_bank_invoice": "33344455566677788899",
 "bik_beneficiary": "987654321","bik_payer": "012345678",
 "budget_classification_code": "","code1": "0401060","code_payment": "",
 "date": "05.11.2020","date_document_payment_basis": "",
 "debiting_date": "05.11.2020","inn_beneficiary": "1111111111",
 "inn_payer": "1234567890","invoice_number": "98765432109876543210",
 "kpp_beneficiary": "222222222","kpp_payer": "125125125",
 "number_document_basis_payment": "","number_payment_order": "345",
 "oktmo_code": "","payer": "ИП \"ДОБРОЕ УТРО\"",
 "payer_bank": "ПУШКИНСКОЕ ОТДЕЛЕНИЕ БАНК \"ЗДОРОВЬЕ\"",
 "payer_bank_invoice": "12345678901234567890","payment_code": "0",
 "payment_reason_code": "","payment_type": "","place_payment": "8",
 "purpose_payment": "ОПЛАТА ПО ДОГОВОРУ №23456 ЗА ВЫПОЛНЕНИЕ СТРОИТЕЛЬНЫХ И ФУНКЦИОНАЛЬНЫХ РАБОТ ПО ИССЛЕДОВАНИЮ ОРГАНИЗМА. НДС НЕ ОБЛАГАЕТСЯ",
 "purpose_payment_1": "","receipt_date": "05.11.2020","tax_period": "",
 "type_payment": "","wage_type": "01"}

То, что надо! Теперь переходим к шаблонизатору.

Шаблонизатор

Что хотим? Хотим простое GUI-приложение, которое бы умело загружать шаблонные документы в формате DOCX, в стратегических местах которых проставлены теги вида ${very_important_info}, загружать изображения нужных документов, и сохранять документ с заполненными данными.

В первую очередь заведем конфигурационный файл, в котором будет указано, какое CLI-приложение нужно запускать, с каким конфигурационным бандлом, с какими масками типов документов для интересующих нас типов (пусть нас интересует Российские платежное поручение и справка о доходах физлица, и, скажем, социальная карта Армении), и как поля с разных документов должны транслироваться в теги шаблона.

Пусть из платежного поручения мы хотим извлекать название плательщика и его банка, реквизиты получателя, сумму прописью и назначение платежа. Из 2-НДФЛ извлекаем ФИО, дату рождения (справка о доходах физического лица, формально говоря, уже не называется 2-НДФЛ, но изжить такой прижившийся термин, думаю, будет непросто), и, наконец, из справки о социальном номере Армении извлекаем ФИО на армянском и, собственно, номер. Для целей демонстрации возможностей шаблонизатора вполне хватит. Конфигурационный файл (config.json) получился такой:

{
  "executable": "docengine_cli",
  "bundle": "bundle_docengine_photo.se",
  "sessions": {
    "rus_payment_order": {
      "documents_mask": "rus.payment_order*",
      "text": "payment order"
    },
    "arm_social_card": {
      "documents_mask": "arm.ref_public*",
      "text": "social card"
    },
    "rus_2ndfl": {
      "documents_mask": "rus.2ndfl*",
      "text": "income form"
    }
  },
  "tags": {
    "rus_payment_order:payer": "payer_name",
    "rus_payment_order:payer_bank": "payer_bank_name",
    "rus_payment_order:beneficiary": "beneficiary_name",
    "rus_payment_order:beneficiary_account": "beneficiary_account",
    "rus_payment_order:beneficiary_bank": "beneficiary_bank_name",
    "rus_payment_order:bik_beneficiary": "beneficiary_bik",
    "rus_payment_order:kpp_beneficiary": "beneficiary_kpp",
    "rus_payment_order:amount_words": "payment_amount",
    "rus_payment_order:purpose_payment": "payment_purpose",
    "rus_2ndfl:surname": "surname",
    "rus_2ndfl:name": "name",
    "rus_2ndfl:patronymic": "patronymic",
    "rus_2ndfl:birth_date": "birth_date",
    "arm_social_card:name_patronymic_surname": "arm_fio",
    "arm_social_card:public_service_number": "arm_number"
  }
}

Конфигурационный файл поместим в директорию resources, вместе со всем необходимым для запуска распознавания: конфигурационным бандлом bundle_docengine_photo.se, исполняемым файлом docengine_cli и библиотекой libdocengine.dylib.

В качестве самого шаблонизатора напишем простенькое GUI-приложение на wxPython. Не имеет смысла углубляться в детали, ограничусь лишь тем, что у меня ушло на все про все около двух часов (без опыта работы с wx) и 292 строчки кода. Разберем лишь процедуры распознавания изображения и заполнения шаблона.

В GUI-приложении распознавание изображения инициируется нажатием на кнопку, которая соответствует той или иной сессии распознавания, прописанной в config.json. Предлагаем пользователю выбрать файл с изображением документа, после чего запускаем docengine_cli при помощи модуля subprocess и парсим JSON, который получаем на выходе. После этого, согласно прописанным тегам в config.json обновляем словарь со значениями тегов:

def loadImage(self, event):
  '''
    Загружает изображение, распознает документ, обновляет словарь тегов
  '''
  button_name = event.GetEventObject().GetName() # соответствует ключу в словаре “sessions” конфигурационного файла config.json
  self.tlog.AppendText('Loading image of %s...\n' % self.config['sessions'][button_name]['text'])

  with wx.FileDialog(self, 'Open %s image file' % self.config['sessions'][button_name]['text'], \
                     wildcard="PNG, JPG or TIF image (*.png;*.jpg;*.jpeg;*.tif;*.tiff)|*.png;*.jpg;*.jpeg;*.tif;*.tiff", \
                     style=wx.FD_OPEN | wx.FD_FILE_MUST_EXIST) as fileDialog:
    if fileDialog.ShowModal() == wx.ID_CANCEL:
      return

    pathname = fileDialog.GetPath()
    try:
      self.tlog.AppendText('Recognizing %s...\n' % pathname)
      # запускаем docengine_cli
      output = subprocess.run([
        os.path.join(self.resources_path, self.config['executable']), # путь к исполняемому файлу docengine_cli
        pathname, # путь к изображению
        os.path.join(self.resources_path, self.config['bundle']), # путь к конфигурационному бандлу Smart Document Engine
        Self.config['sessions'][button_name]['documents_mask'] # маска типа документа
      ], capture_output = True)

      # парсим вывод docengine_cli
      output_json = None
      try:
        output_json = json.loads(output.stdout)
      except Exception:
        pass

      if output_json is None:
        self.tlog.AppendText('Failed to retrieve any data.\n')
      else:
        # обновляем словарь тегов
        any_fields_extracted = False
        for tag in self.config['tags'].keys():
          if tag.split(':')[0] != button_name:
            continue
          prop_name = tag.split(':')[-1]
          if prop_name not in output_json.keys():
            continue
          prop_value = output_json[prop_name]
          self.keyval[self.config['tags'][tag]] = prop_value
          self.tlog.AppendText('Extracted %s: %s\n' % (self.config['tags'][tag], prop_value))
          any_fields_extracted = True

        if not any_fields_extracted:
          self.tlog.AppendText('No fields extracted.\n')

    except Exception as e:
      self.tlog.AppendText('Cannot process file %s: %s\n' % (pathname, str(e)))

Заполнение шаблона инициируется нажатием на другую кнопку, при котором подгруженный заранее DOCX-шаблон загружается при помощи пакета python-docx, после чего просматриваются все параграфы документа и все параграфы каждой ячейки каждой таблицы, с заменой найденных тегов на значения, извлеченные из распознанных документов. Скорее всего заполнение шаблона можно было сделать проще, но я уже в пижаме:

def applyTagsToParagraph(self, paragraph):
  '''
    Применяет словарь тегов self.keyval к одному параграфу DOCX-документа, сохраняя формат куска, содержащего символ “$”.
  '''
  for i in range(len(paragraph.runs)):
    while '$' in paragraph.runs[i].text:
      end_index = -1
      found_key = None
      composite_text = ''
      for j in range(i, len(paragraph.runs)):
        composite_text += paragraph.runs[j].text
        for key in self.keyval.keys():
          if '${%s}' % key in composite_text:
            found_key = key
            end_index = j
            break
        if found_key is not None:
          break
      if found_key is not None:
        paragraph.runs[i].text = composite_text.replace('${%s}' % found_key, self.keyval[found_key])
        for k in range(i + 1, end_index + 1):
          paragraph.runs[k].clear()
      else:
        break

def saveDocument(self, event):
  '''
    Загружает шаблон документа из self.template_path, применяет словарь тегов self.keyval к документу и предлагает пользователю сохранить получившийся документ.
  '''
  if len(self.keyval) == 0:
    self.tlog.AppendText('Nothing to apply.\n')
    return

  self.tlog.AppendText('Applying values to template file %s:\n' % self.template_path)
  for k, v in self.keyval.items():
    self.tlog.AppendText('  %s: %s\n' % (k, v))

  document = docx.Document(self.template_path)

  # применяем к параграфам документа
  for paragraph in document.paragraphs:
    self.applyTagsToParagraph(paragraph)
  # применяем к таблицам документа
  for table in document.tables:
    for row in table.rows:
      for cell in row.cells:
        for paragraph in cell.paragraphs:
          self.applyTagsToParagraph(paragraph)

  with wx.FileDialog(self, "Save DOCX file", wildcard="DOCX files (*.docx)|*.docx", \
                     style=wx.FD_SAVE | wx.FD_OVERWRITE_PROMPT) as fileDialog:

    if fileDialog.ShowModal() == wx.ID_CANCEL:
      return

    pathname = fileDialog.GetPath()
    # на всякий случай добавляем расширение docx и безопасно сохраняем файл
    if not pathname.lower().endswith('.docx'):
      new_pathname = pathname + '.docx'
      while os.path.exists(new_pathname):
        new_pathname = new_pathname[:-5] + '-copy.docx'
      pathname = new_pathname
    try:
      document.save(pathname)
      self.tlog.AppendText('Saved to %s\n' % pathname)
    except IOError:
      self.tlog.AppendText('Cannot save to file %s\n' % pathname)

Шаблонизатор готов! Для того, чтобы запускать его как любое другое приложение, можно применить удобный инструмент pyinstaller, он позволяет создавать готовое приложение для целевой операционки, упаковать внутрь директорию resources и подложить иконку:

$ pyinstaller -w docengine_templater.py --name="Docengine Templater" --add-data resources:resources -i docengine.icns

Тестим!

Для теста шаблонизатора создадим простой DOCX-файл, использующий все теги, которые мы ранее добавляли в config.json:

Окно шаблонизатора после загрузки шаблона и распознавания трех изображений:

Сохраненный документ:

На этом, пожалуй все! Код шаблонизатора (и модифицированного семпл-приложения docengine_cli.cpp) вы можете посмотреть здесь.

Если вам интересен продукт Smart Document Engine, вы можете узнать про него больше на сайте нашей компании, или обратиться там же к нашим специалистам за подробностями.

Спасибо за внимание!