Gap : NLP/CV Data Engineering Framework

Natural Language Processing for PDF, TIFF, and Camera Captured Documents, and

Computer Vision Processing for Images


The Gap NLP/CV data engineering framework provides an easy to get started into the world of machine learning for your unstructured data in PDF documents, scanned documents, TIFF facsimiles and camera captured documents, and your image data in image files and image repositories.

NLP , v0.9.3 (Pre-launch: alpha)

CV , v0.9.4 (Pre-launch: beta)

The framework consists of a sequence of Python modules which can be retrofitted into a variety of configurations. The framework is designed to fit seamlessly and scale with an accompanying infrastructure. To achieve this, the design incorporates:


This framework is ideal for any organization planning to do:


The source code is made available under the Apache 2.0 license: Apache 2.0


The Gap framework extensively uses a number of open source applications/modules. The following applications and modules will be downloaded onto your computer/laptop when the package OR setup file is installed.

  1. Artifex's Ghostscript - extracting text from text PDF
  2. ImageMagic's Magick - extracting image from scanned PDF
  3. Google's Tesseract - OCR of scanned/image captured text
  4. NLTK (Natural Language Toolkit) - stemming/lemmatizer/parts of speech annotation
  5. unidecode - romanization of latin character codes
  6. numpy - high performance in-memory arrays (tensors)
  7. HDF5 - high performance of on-disk data (tensors) access
  8. openCV - image manipulation and processing for computer vision
  9. imutils - image manipulation for computer vision

Pip Installation:

The Gap framework is supported on Windows, MacOS, and Linux. It has been packaged for distribution via PyPi on launch.

  1. install miniconda

  2. install conda virtual environment and required packages

  3. exiting conda virtual environment:

    • Windows: deactivate
    • Linux/macOS: source deactivate Installation:

To install GapML via

  1. clone from the Github repo.

    • git clone
  2. install the GapML setup file.

    • python install


The framework provides the following pipeline of modules to support your data and knowledge extraction from both digital and scanned PDF documents, TIFF facsimiles and image captured documents.


The splitter module is the NLP entry point into the pipeline. It consists of a Document and Page class. The Document class handles the splitting of PDF documents into PDF pages, TIFF facsimiles into TIFF pages, OCR and raw text extraction. PDF splitting and image extraction is handled by the open source Artifex’s Ghostscript ©, and TIFF splitting by open source Image Magic’s Magick ©. OCR is handled by the open source Google’s Tesseract ©. The Document object stores the individual PDF/TIFF/image pages and corresponding raw text and optionally page images (when scanned PDF, TIFF or images) in the specified storage path. The splitting process can be done synchronously or asynchronously, where in the latter case an event handler signals when the splitting/OCR has been completed and the page table is accessible.

For OCR, the resolution of the image extraction is settable, which will affect the quality of the OCR, and corresponding processing time. If the resolution of the original scanned page is lower than the setting, it will be up-sampled, and conversely if it is higher it will be down-sampled.

The Page class handles access to the individual pages, via the page table of the document class. Access is provided to the individual PDF, TIFF or image page, the scanned image (when scanned PDF, TIFF or images), raw text and the Natural Language Processing (NLP) processed tokens (when SYNTAX module is installed).

NLP processing of the raw text is deferred until first access (JIT), and then preserved in memory as long as the corresponding page object is referenced. The NLP processed tokens may be further segmented into regions, consisting of tables, paragraphs, columns, etc. when the SEGMENTATION module is installed.

The document and corresponding pages may be classified (i.e., category of the content) when the CLASSIFICATION module is installed.



The syntax module follows the splitter module in the pipeline. It consists of the Words and Vocabulary classes. The Words class handles natural language processing (NLP) of the extracted text. The NLP processing can be configured for tokenization, stemming, lemmatizing, stop word removal, syntax analysis and word classification, with Unicode support.

The word classifier recognizes:

Dates, numbers and units of measure can be converted to either USA Standard or ISO Standard. USA and Canadian postal addresses are converted to the USPO standard for address matching.

Along with the builtin stemmer and lemmatizer, the module can optionally be configured to use the NLTK (open source) stemmers, lemmatizer and parts of speech annotations.



The segmentation module was introduced as part of the pre-launch of Gap v0.9. It currently is in the demonstration stage, and not ready for commericial-product code ready. The segmentation module examines the whitespace layout of the text to identify 'human' layout of text and corresponding context, such as paragraphs, headings, columns, page numbering, letterhead, etc. The text is then separated into segments based on recognized layout and within the segments the text is NLP preprocessed. In this mode, the NLP preprocessed text is hierarchical. At the top level are the segments, with corresponding segment tag, and the child is the NLP preprocessed text within the segment.



The splitter module is the CV entry point into the pipeline. It consists of a Images and Image class. The Images class handles the storage and (random access) batch retrieval of CV machine learning ready data, using open source openCV image processing, numpy high performance arrays (tensors) and HDF5 high performance disk (tensor) access. The Image class handles preprocessing of individual images into CV machine learning ready data. The batch and image preprocessing can be done synchronously or asynchronously, where in the latter case an event handler signals when the preprocessing of an image or batch has been completed and the machine learning ready data is accessible.

The vision module handles:


User's Guide

The User's (Programming) Quick Start Guide can be found here



The GAP framework is developed using Test Driven Development methodology. The automated unit tests for the framework use pytest, which is a xUnit style form of testing (e.g., jUnit, nUnit, jsUnit, etc).

Installation and Documentation

The pytest application can be installed using pip:

pip install pytest

Online documentation for pytest


The following are the pre-built automated unit tests, which are located under the subdirectory tests:    # Tests the Document Class in the Splitter Module        # Tests the Page Class in the Splitter Module       # Tests the Words and Addresses Class in the Syntax Module     # Tests the Segment Class in the Segment Module       # Tests the Image and Images Class in the Vision Module

The automated tests are executed as follows:

  1. From directory root enter cd tests

  2. Tests can be run by:

    pytest -v pytest -v pytest -v pytest -v pytest -v

Code Coverage

Information on the percent of code that is covered (and what source lines not covered) by the automated tests is obtained using pytest-cov. This version of pytest is installed using pip:

pip install pytest-cov
  1. From directory root enter cd tests

  2. To run tests with coverage:

    pytest --cov=gapml.splitter

    Statements=456, Missed=60, Percent Covered: 87%

    pytest --cov=gampml.syntax

    Statements=456, Missed=60, Percent Covered: 93%

    pytest --cov=gampml.address

    Statements=456, Missed=60, Percent Covered: 90%


    Statements=652, Missed=56, Percent Covered: 91%