OCR troubleshooting · WorkFusion Documentation

OCR license

License usage countdown

Expand to learn more

Question

How does the license page counter depend on the recognized page size?

Answer

The so-called soft counter is used for Intelligent Automation Cloud Enterprise. It means that page count within a document is considered only (1 page = 1 license). The counter doesn't depend on the page size.

Maximum available units in license

Expand to learn more

Question

What is the meaning of the "The maximum number of units available in the license has been reached" error? What to do in such a case?

Answer

It means that you have recognized the maximum number of pages that the license allows. So the license does not allow you to recognize more pages. First of all, use the activeLicense API and check in the volumeRemaining and volumeRefreshingPeriod response attributes (refer to OCR API). The volumeRemaining attribute is most likely to be equal to 0. If the volumeRefreshingPeriod attribute is not infinite, then upon finishing the refresh period, more pages will be automatically included into the license. The volumeRemaining attribute will be equal to volume. Otherwise, you need a new license. Contact our support to get a new license. To activate it, see here.

Maximum number of concurrent recognition processes executed in parallel

Expand to learn more

Question

How many recognition processes can be executed in parallel?

Answer

According the license limitations, it equals to the number of cores allowed by OCR license. This is defined by the allowedCoresCount attribute of the license. You can use the activeLicense API to get the information about the license and check the allowedCoresCount attribute in the response. If the value of this attribute is 0, the number of CPU cores is unlimited. See the OCR API page.

License consumption history

Expand to learn more

Question

For planning the OCR license need, it is necessary to see the previous OCR consumption history. Is there a way to know how many pages were consumed in the past weeks or months on a given period of time?

Answer

In this case, it is possible to try the following approach.

Run the GET /api/v1/cloud/activeLicense request and check the volumeRemaining attribute. Mind that to run the command, you need to SSH into the OCR server firstly. For more details, refer to Activate OCR license | Verify license.
After some time, for example, one week, run the request again and subtract the volumeRemaining attribute from the previous result.

You can also automate these actions using a scheduled business process or in some other way.

New licence_request.txt generation

Expand to learn more

Symptoms

I deleted (lost) the correct license_request.txt file and get the following error on the OCR server when trying to activate the OCR license: "Cannot activate the license. Seems that prepareLicense action was called not on this server."

Resolution

Get the license_request information from the OCR server and save it using the curl command below.

curl -X POST http://localhost:9002/api/v1/cloud/prepareLicense > INSTALL_DIR/ABBYY_FRE11/license_request.txt

OCR recognition quality

Character appended to policy number incorrectly

Expand to learn more

Symptoms

OCR incorrectly appends a character to a policy number: PLC-4567 on the original image, PLC-4567S in the OCR output. A number is incorrectly recognized by OCR: 2258.40 on the original image, 2254.40 in the OCR output.

Resolution

There is no universal approach to guarantee 100% recognition quality. Below there are some hints for quality improvement.

A reason for poor quality must be evaluated. Are there some background noise on the image, or some geometric distortions, skew, etc.?
There are some available measures to fix some problems. Experiment with using removeNoiseModels and removeGarbageSize parameters of processImage request. See the OCR API reference. You can also try using the discardColorImage=true or enhanceLocalContrast=true parameters.
Try to use a combination of pattern and alphabetExtension to allow OCR processing of unusual symbols. See the OCR API reference and Recognition quality for more details.

Handwriiten parts removed by OCR engine

Expand to learn more

Symptoms

The OCR engine completely removes handwritten parts it cannot map to any text from the document. Is it possible to render these parts (at least with some "fancy" characters) instead of being cut off?

Resolution

The allowedRegionTypes parameter specifies the allowed region types for classification of identified blocks. If allowedRegionTypes = empty, all types will be processed.

To keep information from handwritten parts, it is necessary to suppress the classification of the region as a picture of any type by specifying the parameter value as follows:

BT_Table,BT_Text,BT_Barcode,BT_Separator,BT_SeparatorGroup,BT_Checkmark,BT_CheckmarkGroup

note

No automatic handwriting recognition will be applied. Information will be rendered as an unreadable set of characters.

Example:

<http-param name="allowedRegionTypes">
        BT_Table,BT_Text,BT_Barcode,BT_Separator,BT_SeparatorGroup,BT_Checkmark,BT_CheckmarkGroup
</http-param>

Extra spaces added in words when processing a searchable PDF

Expand to learn more

Symptoms

Extra spaces are added in words when processing a searchable PDF.

Resolution

Convert a searchable PDF into an image-based PDF using the following transformation:

invoke(new ProcessBuilder(new String[] {
                        "convert",
            "-density","300",
                        inputFile.getAbsolutePath(),
                        result.getAbsolutePath()}
                    ));

The full bot step downloads the original file to the file system, converts it to an image-based PDF using ImageMagick, uploads the new PDF file to S3, removes temporary files, and exports a link to the new PDF to the next step:

<?xml version="1.0" encoding="UTF-8"?>
<config charset="UTF-8">

    <required name="original_document_url"/>

    <var-def name="file_path">
        <script return="convert(original_document_url.toString())"><![CDATA[
            import java.io.BufferedReader;
            import java.io.File;
            import java.io.IOException;
            import java.io.InputStreamReader;
            import java.net.URL;
            import com.google.common.io.Files;
            import org.apache.commons.io.FileUtils;
            import org.apache.commons.io.FilenameUtils;

            static File outputFolder;

            static boolean getOS(){
                return ((String)System.getProperties().get("os.name")).contains("Windows");
            }

            boolean isWindows=getOS();

            static File convert(String documentLink) throws IOException, InterruptedException {
                File baseDir = Files.createTempDir();
                sys.defineVariable("tmpDirPath", baseDir.getPath());
                File inputFolder = new File(baseDir, "input");

                URL documentUrl = new URL(documentLink);
                String inputFileName = FilenameUtils.getName(documentUrl.getPath());

                if (inputFileName == null || inputFileName.isEmpty()) {
                    inputFileName = "input.pdf";
                }
                sys.defineVariable("inputFileName", inputFileName.substring(0,inputFileName.lastIndexOf(".")));

                File inputFile = new File(inputFolder, inputFileName);
                FileUtils.copyURLToFile(documentUrl, inputFile);

                outputFolder = new File(baseDir, "output");
                FileUtils.forceMkdir(outputFolder);

                File result = new File(outputFolder, "output.pdf");

                if (isWindows){
                    invoke(new ProcessBuilder(new String[] {
                        "magick",
                        "convert",
                        "-density","300",
                        inputFile.getAbsolutePath(),
                        result.getAbsolutePath()}
                    ));
                } else {
                    invoke(new ProcessBuilder(new String[] {
                        "convert",
                        "-density","300",
                        inputFile.getAbsolutePath(),
                        result.getAbsolutePath()}
                    ));
                }

                return result;
            }

            static void invoke(ProcessBuilder builder) throws IOException, InterruptedException {
                builder.redirectErrorStream(true);
                Process process = builder.start();

                BufferedReader in = new BufferedReader(new InputStreamReader(process.getInputStream()));
                String line;
                while ((line = in.readLine()) != null) {
                    log.info(line);
                }
                in.close();

                int code = process.waitFor();
                if (code != 0) {
                    log.error("Failed to invoke process: " + builder.command() + ". Return code: " + code);
                    throw new RuntimeException("Failed to invoke process: " + builder.command() + ". Return code: " + code);
                }
            }
        ]]></script>
    </var-def>

    <var-def name="content">
        <file path="${file_path}" type="binary"/>
    </var-def>

    <var-def name="converted_link">
        <s3  bucket="str">
            <s3-put-public path="converted/converted-${inputFileName}.pdf" content="${content}" content-type="application/pdf" content-disposition="inline"/>
        </s3>
    </var-def>

    <script><![CDATA[
        FileUtils.deleteDirectory(new File(tmpDirPath.toString()));
    ]]></script>

    <export include-original-data="true">
        <single-column name="converted_document_link" value="${converted_link}" />
    </export>
</config>

OCR formats

OCR-supported input formats

Expand to learn more

Question

What are OCR-supported input formats?

Answer

For OCR-supported input formats, see the table below.

Input data format	Documentation
PDF	Standard OCR process
Excel	Excel to HTML converter
Word	Formats of input documents: Word
Image: TIFF, JPEG, PNG	Input image quality requirements
Email	Formats of input documents: Email
Digital formats to text	to-text plugin

For export formats, refer to OCR REST API.

Input image quality requirements

Expand to learn more

Question

Are there any defined input image quality requirements for the OCR output generation?

Answer

For scanned images:

For text printed in fonts of size 10 pt or larger, the recommended resolution is 300 dpi.
For text printed in fonts of 9 pt or smaller, the recommended resolution is 400-600 dpi.
Brightness must be tuned appropriately. A medium value of around 50% must be appropriate in most cases. If characters are "torn" or very light, lower the brightness to make the image darker. If characters are distorted, stuck together, or filled out, increase the brightness to make the image brighter.
Poor-quality documents with "noise" (i.e., random black dots or speckles), blurred and uneven letters, or skewed lines and shifted table borders, are best scanned in grayscale.

For photoed images:

Lighting must be evenly distributed across the page and in such a way that there are no dark areas or shadows.
The paper must be straightened out.
A camera must be positioned parallel to the plane of the document, so that the lens looks to the center of the text being photographed, usually at a distance of 50-60 cm.
A camera must be used with a tripod, or an anti-shake system must be used.
A camera must have at least a 5-megapixel sensor.
Flash must be disabled.
Manual aperture control or aperture priority mode, manual focus are recommended.
There must be enough light, preferably daylight or two light sources positioned so as to avoid shadows.
Use a white sheet of paper to set the white balance in the camera.

Some input formats cannot be processed

Expand to learn more

Question

Multiple input formats (PDF, Excel, Word, Emails, Screenshots) cannot be processed by OCR. Is there a workaround to automate such a process without the required OCR capability?

Resolution

Mind that OCR is not processing password-protected PDF documents according to the license agreement between ABBYY and Adobe.

The OCR Service is intended for text recognition, not for conversion an arbitrary format to another.

OCR within Intelligent Automation Cloud Enterprise can process PDF documents and several of image formats. See the full list of supported formats on the the format list page.
OCR within Intelligent Automation Cloud Business supports the same image formats, but not PDF. However, it's possible to use the PDFBox library to automate the conversion of PDF documents inputs to images.

TIFF format conversion failed

Expand to learn more

Symptoms

The following error is observed: "no decode delegate for this image format 'TIFF' @ error/constitute.c/ReadImage/501. – no TIFF delegate installed".

Resolution

To fix the issue, do as follows.

Download ImageMagick-7.0.7-7-RHEL7.x.tar.gz to the Application server.

Unpack it.

- tar -xvf ImageMagick-7.0.7-7-RHEL7.x.tar.gz

Open install_im_7.0.7-7_rhel7.x.sh and check that all paths are correct.
Run the script.

Check.

>convert -version
Version: ImageMagick 7.0.7-7 Q16 x86_64 2017-10-07

Alternative to ImageMagick - convert PDF to TIFF

Expand to learn more

Question

Are there any alternatives to ImageMagick?

Answer

Use the converTo(value=tiff) parameter that performs auto-detection of the file type and its conversion to TIFF (convert before processing). Accepted formats are PDF, PNG, JPG, JPEG. For more details, refer to the OCR API reference.

OCR performance

Maximum number of concurrent recognition processes started

Expand to learn more

Question

How many recognition processes does OCR Service actually start?

Answer

There is the worker.executor.abbyy.pool.size configuration property in the ocr-worker.yml configuration file (Zookeeper path: /config/ocr-worker) for the OCR Worker component. It specifies the maximum number of concurrent recognition processes performed per OCR Worker instance. If it is not specified, the default value of 2 is applied. If you have a single OCR Worker instance, worker.executor.abbyy.pool.size must be equal to allowedCoresCount-1 so that one core remains free for license monitoring and health check. If you have more OCR Worker servers, the sum of worker.executor.abbyy.pool.size of each OCR Worker must be equal to allowedCoresCount-1.

Increasing throughput per single OCR server

Expand to learn more

Question

How to increase throughput per single OCR server?

Answer

Consider increasing the number of available CPUs in your hardware.

Once upgraded, adjust the following property in the application configuration.

worker.executor.abbyy.pool.size=15 
# Where 15 is number of OCR license cores minus 1. Maximum is 32

API cannot be accessed on OCR server

Expand to learn more

Symptoms

There is no way to access any API available on the OCR server. The error "404 Not Found" is in response.

Resolution

Possible root causes: OCR services are not running, or a wrong port is used.

Go to the OCR server and do as follows.

$ ps -C java -opid,cmd | grep -c "ocr-rest"
$ ps -C java -opid,cmd | grep -c "ocr-worker"

Each of them must not be less than 1.

To find the port, perform the following command.
```
$ grep "PORT_OCR2=" system.conf
```
Use this port in the URL of the request: http://ocr_server:[PORT]/api/v1/cloud.

Orientation correction

Expand to learn more

Question

For pages with incorrect orientation (rotated by 90/270 degrees), correctOrientation=true sometimes does not help.

Answer

Try using exportFormat=xmlForCorrectedImage. For more details, refer to the OCR API reference.

OCR result link expired

Expand to learn more

Symptoms

The OCR result link becomes invalid after a while and is unavailable for further review and analysis.

Resolution for Intelligent Automation Cloud Enterprise

There are three properties in the ocr-rest.yml OCR REST component configuration file.

# how long input documents or patterns are stored in S3;
# default value – 2000 minutes
db.cleanup.abbyy.input=2000
# how long output result is stored in S3, though metadata and inputs are not affected;
# default value – 2000 minutes
db.cleanup.abbyy.output=2000
# how long records are stored in db (after that full cleanup in db and S3;
# default value – 600 minutes
db.cleanup.abbyy.record=600

Once the smaller of these two has elapsed (1440 minutes = 1 day in this case), the recognition result is deleted. To keep the OCR result for a longer period, it is necessary to set an appropriate number. It means the OCR Service is not intended for storing large volumes of OCR inputs and outputs for a long time. If you need to increase the retention period to prevent from the negative impact on the OCR Service performance, you must configure the service to use an S3-storage profile instead of the default gridfs-storage profile.

Resolution for Intelligent Automation Cloud Business

OCR results are deleted not by time, but according to the number of stored OCR "tasks".

ocr.tasks.abbyy.storage.capacity=50

This is configured in application.properties of OCR Service for Intelligent Automation Cloud Express/Business. OCR inputs and outputs are stored in memory, so it's not recommended to set the value too high. For example, if your average input image size + exported document size are equal to 1 MB and you set the capacity to 1,000, then it will consume approximately 1 GB of your RAM.

It is necessary to emphasize, that as the data is kept in memory, it will be lost as soon as you shutdown or restart the OCR Service.

Bot config for OCR

Expand to learn more

Question

Is it difficult to create and modify a bot config using the OCR Service?

Answer

We do not recommend OCR Plugin, use a direct link instead. If you need to use the http-extended plugin, be careful not to use variables and input CSV columns with the names mentioned on the Apply Web-Harvest and WorkFusion context variables page.