Skip to main content
Version: 10.2.9

OCR REST API

tip

Authentication​

Like some other components of Work.AI, Optical Character Recognition (OCR) uses JWT for authentication. To access most OCR resources, retrieve the JWT token. For that, you can access any Workfusion instance, provide a user login and password and retrieve a short-living JWT token:

curl -X POST -H Content-Type:application/json -d '{"username":"'","password":""}' http:///workfusion/api/v1/jwt/login

You can use that token in the HTTP Authorization header:

Authorization:Bearer

Using command line​

  • Process image: specifies an appropriate location of a file (FILENAME) and OCR parameters to the processImage API call.

    curl -s --form "file=@FILENAME" "http://ocr.hostname:8080/api/v1/cloud/processImage?correctSkew=true&xml:writeRecognitionVariants=false&profile=documentConversion&exportFormat=txt&language=English&correctOrientation=true"

    Output: copies a task ID for the next command.

    <?xml version="1.0" encoding="UTF-8" standalone="yes"?><response><task id="5693d8f77b78005fcbbfbe84" message="OK" processEndTime="2016-01-11T16:32:00" processStartTime="2016-01-11T16:31:56" registrationTime="2016-01-11T16:32:28" resultUrl="http://ocr.hostname:8080/api/v1/cloud/download?taskId=5693d8f77b78005fcbbfbe84&amp;result=1" resultUrl2="http://ocr.hostname:8080/api/v1/cloud/download?taskId=5693d8f77b78005fcbbfbe84&amp;result=2" resultUrl3="http://ocr.hostname:8080/api/v1/cloud/download?taskId=5693d8f77b78005fcbbfbe84&amp;result=3" statusChangeTime="2016-01-11T16:32:28" status="Completed"/></response>

  • Gets status by the task ID:

    curl -s "http://ocr.hostname:8080/api/v1/cloud/getTaskStatus?taskId=5693d8f77b78005fcbbfbe84"

    Output: If message="OK", you can download results from links in resultUrl,resultUrl2,resultUrl3 (depends on the export format).

    <?xml version="1.0" encoding="UTF-8" standalone="yes"?><response><task id="5693d8f77b78005fcbbfbe84" message="OK" processEndTime="2016-01-11T16:32:00" processStartTime="2016-01-11T16:31:56" registrationTime="2016-01-11T16:32:28" resultUrl="http://ocr.hostname:8080/api/v1/cloud/download?taskId=5693d8f77b78005fcbbfbe84&amp;result=1" resultUrl2="http://ocr.hostname:8080/api/v1/cloud/download?taskId=5693d8f77b78005fcbbfbe84&amp;result=2" resultUrl3="http://ocr.hostname:8080/api/v1/cloud/download?taskId=5693d8f77b78005fcbbfbe84&amp;result=3" statusChangeTime="2016-01-11T16:32:28" status="Completed"/></response>

API usage​

API sequence call​

  • Uploads the file with submitImage.

    Copies taskId from the response:

    <?xml version="1.0" encoding="UTF-8" standalone="yes"?>
      <response>
          <task id="5b06b1b295ac0b000144fb7e" processEndTime="" processStartTime="" registrationTime="2018-05-24T12:36:02" 
      resultUrl="http://ocr2-dev2.crowdcomputingsystems.com:8080/api/v1/cloud/download?taskId=5b06b1b295ac0b000144fb7e&amp;
      result=1" resultUrl2="http://ocr2-dev2.crowdcomputingsystems.com:8080/api/v1/cloud/download?taskId=5b06b1b295ac0b000144fb7e&amp;
      result=2" resultUrl3="http://ocr2-dev2.crowdcomputingsystems.com:8080/api/v1/cloud/download?taskId=5b06b1b295ac0b000144fb7e&amp;
      result=3" statusChangeTime="2018-05-24T12:36:02" 
      status="Submitted"/>
      </response>

  • Starts image processing with processDocument.

  • Checks task status with getTaskStatus (specify correct taskId).

    If the task is complete (status="Completed"), open results from the resultUrl, resultUrl2 or resultUrl3 fields (replace &amp; with &).

Custom request parameters​

To implement custom or additional request parameters, see the sections below.

GET /cloud/processDocument​

  • exportFormat stands for the OCR API export format. Available options are as follows:

    • html: HTML page.
    • pdfSearchable: the PDF type allows searching for text.
    • xml: file contains characters or words along with their location in the original document (coordinates or frames).
    • xmlForCorrectedImage: the same as xml, except the location is taken from a processed or adjusted document.
    • xmlWithoutRecognitionVariants: the same as xml, but does not contains character-related data.
    • txt: plain text (default).

    For multiple export formats, you can use combinations delimited by a comma: pdfSearchable,xmlForCorrectedImage,html. You can add maximum three types at a time.

  • customRegions is a JSON variable that defines an area of a special type. The following supported types perform actions within a specified region:

    • BT_Table: table recognition.
    • BT_Barcode: barcode recognition.
    • BT_Checkmark: single checkmark recognition; supports the checkmarkConfiguration field with checkmark settings.
    • BT_CheckmarkGroup: group of checkmark recognition; supports the checkmarkConfiguration field with checkmark settings; expects the innerRegions field.
    • One of BT_RasterPicture,BT_VectorPicture,BT_Separator,BT_SeparatorGroup enables analysis within the specified region only without including the information from the surrounding context.
    [
        {
            "type": "BT_Table",
            "page": 1,
            "left": 0,
            "top": 0,
            "right": 2000,
            "bottom": 2000
        },
        {
            "type": "BT_Table",
            "page": 1,
            "left": 0,
            "top": 2000, 
            "right": 4000,
            "bottom": 4000,
        },
        {
            "type": "BT_Table",
            "page": 2,
            "left": 0,
            "top": 0,
            "right": 4000,
            "bottom": 4000
        }
    ]

    The example to select one table region for all pages:

    [
        {
            "type": "BT_Table",
            "left": 0,
            "top": 0,
            "right": 2000,
            "bottom": 2000
        }
    ]

  • correctSkew (default true): if true, the page skew is detected and automatically corrected.

  • correctOrientation (default true) specifies whether the orientation of the image should be automatically detected and corrected. If true, the page orientation is detected. If it differs from normal, it is automatically rotated.

  • skipPreprocessing (default false) disables all pre-processing steps for a document. Parameters that are disabled if skipPreprocessing=true: convertTo, changeDPI, useAutoDetectedDPIFromRange, removeNoiseModels, removeGarbageSize, removeColorObjectsType, removeColorObjects, correctSkew, invertImage, discardColorImage, enhanceLocalContrast, correctOrientation, lowResolutionMode, useWordsFromDictionaryOnly.

  • useOnlyCustomRegions (default false) skips the original analyzing stage to process custom regions only and extracts information from custom regions only.

  • useWordsFromDictionaryOnly specifies if dictionary words are allowed during recognition in this base language only. If true, a word that is not found in the dictionary of the base language can appear in the recognized text only if the OCR engine found no dictionary variants.

  • dictionary is a word or a combination of characters that can be used to improve OCR recognition. The set of words extends, not limits, the default dictionary.

  • alphabetExtension is a string with special symbols to extend the already defined alphabet, for example, abc123.

  • customAlphabet is a string with special symbols to extend the already defined alphabet, for example, abc123.

  • useDefaultPattern (false by default): if true, it requires applying the default pattern from the OCR application bundle.

  • removeNoiseModels removes noise on the image (optional, comma-separated values are valid: CorrelatedNoise, WhiteNoise). The method can be used for color and 8-bit gray images only.

  • removeGarbageSize removes garbage (excess dots that are smaller than a certain size) from the image (optional, valid value > 0 and -1 for automatic detecting garbage size).

  • skipTextLayerExtraction: a text layer of the source PDF file is not used; the image layer is recognized by the OCR engine.

  • debug turns off cleanup of temporary files once the recognition is finished. Also, turns on the OCR engine logging.

  • discardColorImage: if you work with black-and-white images or the color of images is not important, set discardColorImage to true.

  • enhanceLocalContrast specifies whether the local contrast of an image should be increased. Such preprocessing may increase the recognition quality. It is efficient in the following use cases:

    • Photos or scans of documents with texture or pictures in the background
    • Photos or scans of documents with a highly colorful background or text highlighting

  • language specifies a predefined language, for example, English. You can also define multiple languages and use a comma as a separator: English,German,Polish.

  • lowResolutionMode: true, by default. When set to false, it improves the recognition of images with low resolution, for example, faxes.

  • textType specifies the text type in the document. The parameter can also contain several text types separated with commas, for example normal,matrix. The following values can be used:

    • normal
    • typewriter
    • matrix
    • ocrA
    • ocrB
    • e13b
    info

    The text type recognition works on the block level by default. It means one paragraph cannot contain a mix of types. To enable recognition per word, use the textExtraction profile.

Pre-processing parameters:

  • invertImage (default false) inverts image colors.

  • discardColorImage (default false) leaves only a black-and-white plane in the prepared image.

    info

    The parameter discards the color plane of a document. Therefore, it is incompatible with the removeColorObjects parameter.

  • removeColorObjects removes color objects from an image, color values: Blue, Green, Red, Yellow.

    info

    The parameter applies color filtering to the color image plane of a document. Therefore, it is incompatible with the discardColorImage parameter.

  • removeColorObjectsType specifies the type of the objects to be removed. Supported types: Full, Background, Stamp.

    • Full: all color objects on the image
    • Background (default): color objects on the background
    • Stamp: only color stamps and signatures
    info

    The method can be used for color images only. You can also use only one type per request.

  • convertTo (value=TIFF): automatic detection of the file type and conversion to TIFF (convert before processing). Accepts images of the following formats: PDF, PNG, JPG, JPEG.

  • pages: selection of pages from PDF files for recognition, for example, pages=1,2,3,10-15.

  • changeDPI contains the new value of DPI. Available values: from 50 to 3,200, for example, changeDPI=300.

  • useAutoDetectedDPIFromRange selects the best resolution from the specified range and changes the resolution of the image. The range should be in the JSON format, for example, {"min": 50,"max": 3200}. ChangeDPI is not applicable when useAutoDetectedDPIFromRange is defined. When the engine cannot define the best DPI, the original DPI is used.

  • timeout sets up timeout in seconds between task execution.

  • storePreprocessedDoc specifies whether preprocessed documents should be saved into data storage.

POST /cloud/processImage​

  • file stands for the file in one of the following formats: PDF, PNG, JPG, JPEG.

  • exportFormat defines the OCR API export format:

    • html: HTML page.
    • pdfSearchable: the PDF type allows searching for text.
    • xml: the file contains characters or words along with their location in the original document (coordinates and frames).
    • xmlForCorrectedImage: the same as XML, except location is taken from a processed or adjusted document.
    • txt: plain text (default).

    For multiple export formats, you can use combinations delimited by the comma: pdfSearchable,xmlForCorrectedImage,html. You can use maximum three types at a time.

  • xml:writeRecognitionVariants sets the XML and xmlForCorrectedImage formats to contain all variants of a character or word, in which case OCR considers them as a possible recognition.

  • customRegions (JSON variable) defines the area of a special type. The following supported types perform actions within a specified region:

    • BT_Table: table recognition.
    • BT_Barcode: barcode recognition.
    • BT_Checkmark: single checkmark recognition. Supports the checkmarkConfiguration field with checkmark settings.
    • BT_CheckmarkGroup: group of checkmark recognition. Supports the checkmarkConfiguration field with checkmark settings. Expects the innerRegions field.

  • detectLanguage specifies whether FineReader Engine should automatically detect the recognition language of a text. Auto detection is intended to be used during the recognition of documents the language of which is not known to you.

  • profile allows fine-tuning the FineReader Engine. Supported profiles:

    • documentConversion for converting documents into editable formats, optimized for accuracy
    • textExtraction for extracting text from documents, optimized for accuracy
    • barcodeRecognition for extracting barcodes, optimized for accuracy

    The settings in these profiles are most suitable in the corresponding situations.

  • correctSkew (true by default): if true, the page skew is detected and automatically corrected.

  • correctOrientation (true by default): if true, the page orientation is detected. If it differs from normal, the page is automatically rotated.

  • skipPreprocessing (false by default) disables all pre-processing steps for a document. The following parameters are disabled if skipPreprocessing=true: convertTo, changeDPI, useAutoDetectedDPIFromRange, removeNoiseModels, removeGarbageSize, removeColorObjectsType, removeColorObjects, correctSkew, invertImage, discardColorImage, enhanceLocalContrast, correctOrientation, lowResolutionMode, useWordsFromDictionaryOnly.

  • customAlphabet: a string with special symbols to extend the already defined alphabet, for example, abc123.

  • useWordsFromDictionaryOnly: specifies if only the dictionary words are allowed during recognition in this base language. If true, a word that is not found in the dictionary of the base language can appear in the recognized text only if the OCR engine found no dictionary variants.

  • useOnlyCustomRegions (false by default): skips the original analyzing stage and extracts information from custom regions only.

  • alphabetExtension: a string with special symbols to extend an already defined alphabet.

  • useDefaultPattern (false by default): if true, it requires applying the default pattern from the OCR application bundle.

  • dictionary: a file where each line contains a word or combination of characters that can be used to improve OCR recognition. The set of words extends, not limits, the default dictionary.

  • removeNoiseModels removes noise in an image (optional, comma-separated values are also valid: CorrelatedNoise, WhiteNoise). This method can be used for color and 8-bit gray images only.

  • removeGarbageSize removes garbage (excess dots that are smaller than a certain size) from an image (optional, valid value > 0).

  • enhanceLocalContrast specifies whether the local contrast of an image should be increased. Such preprocessing can increase the recognition quality. It is efficient in the following cases:

    • Photos or scans of documents with a texture or pictures in the background
    • Photos or scans of documents with a highly colorful background or text highlighting

  • language specifies a predefined language, for example, English.

  • lowResolutionMode improves recognition of images with low resolution, for example, faxes. If true, it adapts to low resolution image.

  • skipTextLayerExtraction: text layer of the source PDF file is not used; the image layer is recognized by the OCR engine.

  • debug turns off cleanup of temporary files once the recognition is finished. Also, turns on the OCR engine logging.

  • textType specifies the text type in the document. This parameter may also contain several text types separated with commas, for example normal,matrix. The following values can be used:

    • normal
    • typewriter
    • matrix
    • ocrA
    • ocrB
    • e13b
    info

    Text type recognition works on the block level by default. It means one paragraph cannot contain a mix of types. To enable recognition per word, use the textExtraction profile.

Preprocessing parameters:

  • invertImage (false by default) inverts image colors.

  • discardColorImage(false by default) leaves only the black-and-white plane in a prepared image.

    info

    The parameter discards the color plane of a document. Therefore, it is incompatible with the removeColorObjects parameter.

  • removeColorObjects removes color objects from an image. Available colors values: Blue, Green, Red, Yellow.

  • removeColorObjectsType specifies the type of the objects to be removed. Supported types: Full, Background, Stamp.

    • Full: all color objects on the image
    • Background: color objects in the background
    • Stamp: only color stamps and signatures.
    info

    The method can be used for color images only. Also, you can use only one type per request.

  • convertTo (value=TIFF): autodetection of the file type and conversion to TIFF (convert before processing). Accepts images of the following formats: PDF, PNG, JPG, JPEG.

  • pages: selection of pages from PDF files for recognition, for example, pages=1,2,3,10-15.

  • changeDPI contains the new value of DPI. Available values are from 50 to 3200, for example, changeDPI=300.

  • useAutoDetectedDPIFromRange selects the best resolution from the specified range and changes the image resolution. The range should be in the JSON format, for example, {"min": 50,"max": 3200}. ChangeDPI is not applicable when useAutoDetectedDPIFromRange is defined. When the engine cannot define the best DPI, the original DPI is used.

  • timeout: the maximum allowed timeout (in seconds) for a single task execution by an OCR Worker. The timeout countdown starts when the OCR Worker starts task execution. If the task execution time exceeded the given timeout, the task is forcibly killed.

  • storePreprocessedDoc specifies whether preprocessed documents should be saved into data storage.

Custom APIs​

GET /cloud/summary​

Returns the total number of tasks with status.

Sample response:

        Total tasks SUBMITTED
        0
    
    
        Total tasks QUEUED
        0
    
    
        Total tasks SCHEDULED
        0
    
    
        Total tasks INPROGRESS
        0
    
    
        Total tasks COMPLETED
        1124
    
    
        Total tasks PROCESSINGFAILED
        283
    
    
        Total tasks DELETED
        0
    
    
        Total tasks CANCELLED
        28

Example value:

<?xml version="1.0" encoding="UTF-8"?>
<MultipleTaskInfo>
  <taskInfoList>
    <message>string</message>
    <tasksCount>0</tasksCount>
  </taskInfoList>
</MultipleTaskInfo>

GET /cloud/cancelTasks​

Cancels all tasks with the status SUBMITTED, QUEUED, and INPROGRESS. Returns the number of cancelled tasks for each status group.

Example value:

<?xml version="1.0" encoding="UTF-8"?>
<MultipleTaskInfo>
  <taskInfoList>
    <message>string</message>
    <tasksCount>0</tasksCount>
  </taskInfoList>
</MultipleTaskInfo>
tip

Add the new parameter that defines which tasks to cancel. For example, the upload date or task ID.

POST /cloud/trainPattern​

Trains a user pattern for the symbol.

  • file: image file with a symbol.
  • baseLine contains the distance from the base line to the top edge of the cropped image of the character. The base line is the line on which the characters are located.
  • The top edge of the image is determined by the character orientation (H1 in the figure below).
  • smallSymbolHeight specifies the height of small characters in pixels in the source image (H2 in the figure below).
  • symbol: symbol associated with pictures.
  • mergePattern: pattern uploaded as a file. If provided, the training output pattern is combined with the uploaded.

Request example:

The response is a downloadable pattern file in a proprietary binary format.

Example value:

<?xml version="1.0" encoding="UTF-8"?>
<Error>
  <message>
    <content>string</content>
  </message>
</Error>
note

When using a custom pattern, you need to specify alphabetExtension with the trained symbol in processImage or processDocument.

POST /submitPattern​

The method attaches a pattern file for recognition of special symbols to an existing task created with submitImage. To be consequently processed with the processDocument action.

Parameters:

  • pattern: the pattern file to upload
  • taskId: mandatory

GET /project-info​

Returns information about the OCR version.

{
  "branch": "string",
  "buildDate": "string",
  "revision": "string",
  "tags": "string",
  "version": "string"
}

GET /health-check​

Returns information about the health of OCR components.

{
  "components": [
    null
  ],
  "errorCount": 0,
  "errors": [
    "string"
  ],
  "infos": [
    "string"
  ],
  "name": "string",
  "projectInfo": {
    "branch": "string",
    "buildDate": "string",
    "revision": "string",
    "tags": "string",
    "version": "string"
  },
  "status": "OK",
  "warningCount": 0,
  "warnings": [
    "string"
  ]
}

GET /cloud/activeLicense​

Returns the current active license and all available information about this license.

Result example
{
  "allowedCoresCount": 0,
  "availableBarcodeModules": [
    "string"
  ],
  "availableEngineModules": [
    "string"
  ],
  "availableExportFormats": [
    "string"
  ],
  "availableLanguageSets": [
    "string"
  ],
  "availableTextTypes": [
    "string"
  ],
  "availableVisualComponents": [
    "string"
  ],
  "category": "string",
  "expirationDate": "string",
  "limited": true,
  "minimumCoresCountPerInstance": 0,
  "serialNumber": "string",
  "volume": 0,
  "volumeRefreshingPeriod": "string",
  "volumeRemaining": 0,
  "warnings": [
    "string"
  ]
}

The meaning of the fields in the response:

AttributeExplanation
availableTextTypesSet of the text types available in the license.
availableBarcodeModulesSet of the OCR engine barcode modules available in the license.
availableEngineModulesSet of the OCR engine modules available in the license.
availableExportFormatsSet of the export formats available in the license.
availableVisualComponentsSet of visual components available in the license.
availableLanguageSetsSet of the language sets available in the license.
volumeRefreshingPeriodInformation about the limitation period if the license limits the number of processed pages or characters during this period.
volumeTotal number of pages or characters that can be processed during a period if the license has such a limitation.
volumeRemainingRemaining number of pages or characters that can be processed till the end of the current period if the license has such a limitation. When this property value reaches 0, the analysis, recognition, and export operations are no longer possible.
serialNumberSerial number of the license.
allowedCoresCountNumber of CPU cores that can be used simultaneously. If the value of this property is 0, the number of CPU cores is unlimited.
minimumCoresCountPerInstanceMinimum number of CPU cores allocated by the OCR engine at initialization.

GET /cloud/listLicenses​

Returns a list of all licenses connected to the current OCR engine.

List of licenses
[
  {
    "allowedCoresCount": 0,
    "availableBarcodeModules": [
      "string"
    ],
    "availableEngineModules": [
      "string"
    ],
    "availableExportFormats": [
      "string"
    ],
    "availableLanguageSets": [
      "string"
    ],
    "availableTextTypes": [
      "string"
    ],
    "availableVisualComponents": [
      "string"
    ],
    "category": "string",
    "expirationDate": "string",
    "limited": true,
    "minimumCoresCountPerInstance": 0,
    "serialNumber": "string",
    "volume": 0,
    "volumeRefreshingPeriod": "string",
    "volumeRemaining": 0,
    "warnings": [
      "string"
    ]
  }
]

POST /cloud/prepareLicense​

Generates an input for a license request.

Example value:

"string"

POST /cloud/activateLicense​

Activates a license. For activation, you need to have a file with the license.

Example value:

{
  "message": {
    "content": "string"
  }
}

GET /metrics/count​

Gets a task count with the status.

Request example:

The parameters are as follows:

  • status: either one of TaskStatus values or aggregates, such as DONE, PROCESSING, ALL.
  • period: number of minutes to subtract from the current time. By default, the range is NOW-MINUTES to NOW. When the period is negative, the range is BEGINNING to NOW-MINUTES. The default is 60 minutes.

GET /metrics/stats​

Request example:

The parameters are as follows:

  • period: number of minutes to subtract from the current time. By default, the range is NOW-MINUTES to NOW. The default is 60 minutes.
  • minProcessingTime: tasks with a processing time less than this value are discarded. The default is 1,000 (1 second).
  • stat: descriptive statistics. Possible values are min, max, n (number of values), std, percentileN (where N is any number 0-100), or all.

Multi-worker processing​

When a process starts to handle a specific task, it changes the task status so that other processes can't also start working with that task. Thus, one task can be processed only by one process-worker.

When a server during the task processing is terminated, there is no way of sending the task to the queue immediately, but there's a service that runs on a schedule and adds such tasks to the queue.

Server specification and usage guidance​

Currently, it's a low-parameter instance. Don't submit many documents. License allows only 10K pages to be recognized.

How to use OCR API​

OCR is a technology for converting document images into editable text.

You can recognize images using one of the API endpoints:

  • processImage
  • processDocument

The example below illustrates how the calls are applied for data recognition:

Recognition with processImage​

Use authentication if needed.

POST host:port/api/v1/cloud/processImage​

Start image processing with processImage.

  1. Upload a document or an image as a file.
  2. Add parameters for correct recognition.
  3. Send a request.

A response has a lot of useful information: taskId, processing time, result URLs, status of recognition.

  • taskId: used during the next requests in the following steps (copy taskId from a response).
  • ResultUrl: a recognition result is available by this link after completion of recognition.

GET host:port/api/v1/cloud/getTaskStatus?taskId=value​

Check task status with getTaskStatus (specify correct taskId).

The taskId value is determined in the previous step.

Set the taskId parameter and send a request.

As a result, the task status with resultUrls are provided in a response.

If the task is complete (status="Completed"), open results from the resultUrl, resultUrl2, or resultUrl3 fields (replace &amp; with &).

GET host:port/api/v1/cloud/download?taskId=value​

If a task is complete (status="Completed"), you can download results from links in resultUrl, resultUrl2, resultUrl3 (depends on the export format).

Recognition with processDocument​

POST host:port/api/v1/cloud/submitImage​

Upload a file with submitImage and copy taskId from a response.

If you need to upload several files for recognition, do as follows:

  1. Submit an image.
  2. Copy ID.
  3. Add the taskId parameter to the submitImage API call.
  4. Submit one more image.

POST host:port/api/v1/cloud/processDocument​

Start image processing with processDocument.

  1. The taskId value is determined in the previous step. Set the taskId parameter.
  2. Add parameters for correct recognition.
  3. Send a request.

GET host:port/api/v1/cloud/getTaskStatus?taskId=value​

Check a task status with getTaskStatus (specify correct taskId).

If a task is complete (status="Completed"), open results from the resultUrl, resultUrl2, or resultUrl3 fields (replace &amp; with &).

GET host:port/api/v1/cloud/download?taskId=value​

If a task is complete (status="Completed"), you can also download results from the links in resultUrl, resultUrl2, resultUrl3 (depends on the export format).

OCR pattern creation​

Extended recognition with a custom trained pattern can be used for:

  • Text set in decorative fonts
  • Texts containing unusual characters, for example, mathematical symbols
  • Long documents of low print quality (more than a hundred pages)

For example:

The OCR product provides a possibility to create and train a user pattern that will be used for the further recognition.

The pattern training works as follows: symbols are recognized in the training mode, and, subsequently, a pattern is created. The pattern is used as a source of additional information during recognition to aid the recognition of the remaining text.

At first, prepare images and data for training. Then, prepare several examples of symbols in different views and define symbol parameters: baseLine, smallSymbolHeight.

  • baseLine contains the distance from the base line to the top edge of the cropped image of the character. The base line is the line on which the characters are located.

    The top edge of the image is determined by the character orientation (H1 in the figure above).

  • smallSymbolHeight specifies the height of small characters in pixels in the source image (H2 in the figure above).

To optimize recognition, experiment with the baseLine and smallSymbolHeight parameters. See the examples below:

ImageValue
  • baseLine=22
  • smallSymbolHeight=14
  • baseLine=19
  • smallSymbolHeight=10
  • baseLine=27
  • smallSymbolHeight=18
  • baseLine=34
  • smallSymbolHeight=26
  • baseLine=18
  • smallSymbolHeight=12
  • baseLine=28
  • smallSymbolHeight=18
  • baseLine=21
  • smallSymbolHeight=14
  • baseLine=19
  • smallSymbolHeight=12
  • baseLine=23
  • smallSymbolHeight=15
  • baseLine=22
  • smallSymbolHeight=14

To determine the baseLine and smallSymbolHeight parameters, consider the symbol position in the text line within the actual document. For example, if you consider a checkbox in a tax form, it is much bigger than normal letters, and the base line is slightly higher (1 pixel for W-8BEN-E) than the bottom line of the checkbox. So don't guess the parameters looking at the symbol in isolation, consider the document layout.

Greater pictures of symbols are more efficient for training, preferably around 40-50 pixels.

Generally, you need multiple input images for training.

POST host:port/api/v1/cloud/trainPattern​

Set all available examples of a symbol with parameters and required parameters to an API request.

  • file: image file with the symbol.
  • baseLine: value from the previous step.
  • smallSymbolHeight: value from the previous step.
  • symbol: symbol associated with pictures.

(symbol=₡)

Send and download the trainPattern result as a PTN file.

mergePattern​

  • mergePattern: file upload for a pattern; if provided, the training output pattern is combined with the uploaded pattern.

Prepare images and data for training as was described in OCR pattern creation.

POST host:port/api/v1/cloud/trainPattern​

Set all available examples of symbol with parameters and required parameters to an API request.

  • file: image file with the symbol
  • baseLine: value from the previous step
  • smallSymbolHeight: value from the previous step
  • symbol: symbol that is associated with pictures

(symbol=₡)

Use the mergePattern parameter to combine the existing pattern with trained in advanced.

In the current case, ae.ptn is a trained pattern for recognition of the Æ symbol.

Send and download the trainPattern result as a PTN file.

As a result, the trained pattern is available for recognition of two symbols.

Apply the pattern for the first symbol as described below.

  • pattern: file upload for a pattern to be applied to recognize special symbols.
note
  • You need the symbol to be added to alphabetExtension (alphabetExtension = Æ).
  • You can use either an explicit pattern uploaded with the field or useDefaultPattern=true, not both.

processImage: apply OCR pattern​

POST host:port/api/v1/cloud/processImage​

Add the trainPattern file to the ProcessImage request.

  • pattern: a file parameter for better recognition.

Download the results where trainPattern is applied: the ₡ symbol is recognized as expected.

processDocument: apply OCR pattern​

First, submit an image for recognition.

POST host:port/api/v1/cloud/submitImage​

Copy the ID for the subsequent steps. After that, apply the trained and downloaded submitPattern.

POST host:port/api/v1/cloud/submitPattern​

The taskId value is determined in the previous step. Set the taskId parameter and a pattern file.

POST host:port/api/v1/cloud/processDocument​

Start image processing with processDocument. The trained pattern was uploaded in the previous step.

  1. Set the taskId parameter.

  2. Add parameters for correct recognition.

  3. Send a request.

  4. Download results where trainPattern is applied: the ₡ symbol is recognized as expected.

Practical usage tips​

Recognition quality​

The following recommendations can help you improve recognition quality:

  • Use custom dictionary.
  • Fetch plain text from PDF and set it to the originalText parameter.
  • Don't use the removeGarbageSize parameter for searchable PDFs and use it carefully for scanned PDF or image. Sometimes, it can degrade results.
  • Train and use patterns for repeatable unrecognized cases. By default, the costa_rica_currency pattern.
  • A searchable PDF is more preferable for recognition than a high-DPI image created from it.
  • The recommended resolution for a source image: 300 DPI for typical texts (10 pt or larger) and 400-600 DPI for texts in smaller fonts (9 pt or smaller).

Performance improvements​

The following recommendations can help you improve recognition quality:

  • Use skipPreprocessing=true at least for searchable PDF documents. It saves up to 30% processing time.
  • Use xml:writeRecognitionVariants=false if you don't need character or word variants in the output XML file. It saves up to 30% processing time, memory, and disk space.