Skip to main content
Version: 10.3

OCR REST API

Authentication​

Like some other components of Work.AI, Optical Character Recognition (OCR) uses a JSON Web Token (JWT) for authentication. To access most OCR resources, you need to log into a Workfusion instance and retrieve a short-living JWT token.

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

You can use that token in the HTTP Authorization header:

Authorization:Bearer

Using command line​

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

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

    Output: copy the task ID to execute the next command.

    <?xml version="2.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/v2/cloud/download?taskId=5693d8f77b78005fcbbfbe84&amp;result=1" resultUrl2="http://ocr.hostname:8080/api/v2/cloud/download?taskId=5693d8f77b78005fcbbfbe84&amp;result=2" resultUrl3="http://ocr.hostname:8080/api/v2/cloud/download?taskId=5693d8f77b78005fcbbfbe84&amp;result=3" statusChangeTime="2016-01-11T16:32:28" status="Completed"/></response>

  • Get a status by the task ID:

    curl -s "http://ocr.hostname:8080/api/v2/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="2.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/v2/cloud/download?taskId=5693d8f77b78005fcbbfbe84&amp;result=1" resultUrl2="http://ocr.hostname:8080/api/v2/cloud/download?taskId=5693d8f77b78005fcbbfbe84&amp;result=2" resultUrl3="http://ocr.hostname:8080/api/v2/cloud/download?taskId=5693d8f77b78005fcbbfbe84&amp;result=3" statusChangeTime="2016-01-11T16:32:28" status="Completed"/></response>

API usage​

API sequence call​

  1. Upload the file with submitImage.

  2. Copy 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/v2/cloud/download?taskId=5b06b1b295ac0b000144fb7e&amp;
      result=1" resultUrl2="http://ocr2-dev2.crowdcomputingsystems.com:8080/api/v2/cloud/download?taskId=5b06b1b295ac0b000144fb7e&amp;
      result=2" resultUrl3="http://ocr2-dev2.crowdcomputingsystems.com:8080/api/v2/cloud/download?taskId=5b06b1b295ac0b000144fb7e&amp;
      result=3" statusChangeTime="2018-05-24T12:36:02" 
      status="Submitted"/>
      </response>

  3. Start image processing with processDocument.

  4. Check the task status with getTaskStatus. Make sure to specify correct taskId.

    If the task is complete (status="Completed"), open the 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.

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

  • skipPreprocessing (false by default) disables all preprocessing steps for a document. Parameters that are disabled if skipPreprocessing=true:

    • convertTo
    • changeDPI
    • useAutoDetectedDPIFromRange
    • removeNoiseModels
    • removeGarbageSize
    • removeColorObjectsType
    • removeColorObjects
    • discardColorImage
    • enhanceLocalContrast
    • correctOrientation
    • lowResolutionMode
    • useWordsFromDictionaryOnly

  • useWordsFromDictionaryOnly specifies if dictionary words are allowed during recognition in the 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. The parameter is optional, valid value > 0 and -1 for automatic garbage size detection.

  • skipTextLayerExtraction: a text layer of the source PDF file is not used, whereas 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 might increase the recognition quality. It is efficient in the following use cases:

    • Photos or scans of documents with textures 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
    • handwritten
    • 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.

Preprocessing parameters:

  • discardColorImage (false by default) leaves only a black-and-white plane in the prepared image. The parameter discards the color plane of a document, so it is incompatible with the removeColorObjects parameter.

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

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

  • removeColorObjectsType specifies the type of the objects to be removed. Supported types:

    • 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. Only one type per request is admissible.

  • 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 DPI value. 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 a 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.

  • 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
    • dataExtraction for extracting all possible data from a document and storing it in a structured way, including objects, such as printed and handwritten text, tables, barcodes, checkmarks, and images with their location and attributes.

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

  • 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 preprocessing steps for a document. The following parameters are disabled if skipPreprocessing=true:

    • convertTo
    • changeDPI
    • useAutoDetectedDPIFromRange
    • removeNoiseModels
    • removeGarbageSize
    • removeColorObjectsType
    • removeColorObjects
    • 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 the 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.

  • 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. The parameter is optional, and valid values are > 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 a low-resolution image.

  • skipTextLayerExtraction: text layer of the source PDF file is not used, whereas 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 can also contain several text types separated with commas, for example, normal,matrix. The following values can be used:

    • normal
    • handwritten
    • 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:

  • discardColorImage(false by default) leaves only the black-and-white plane in a prepared image. The parameter discards the color plane of a document, so 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: 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. The admissible range is 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 exceeds the given timeout, the task is forcibly killed.

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

Custom APIs​

GET /cloud/summary​

Returns the total number of tasks with statuses.

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="2.0" encoding="UTF-8"?>
<MultipleTaskInfo>
  <taskInfoList>
    <message>string</message>
    <tasksCount>0</tasksCount>
  </taskInfoList>
</MultipleTaskInfo>

GET /cloud/cancelTasks​

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

Example value:

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

Add a 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="2.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 is terminated during the task processing, 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. The 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/v2/cloud/processImage​

Starts image processing:

  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: recognition result is available by this link after completion of recognition.

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

Checks the task status. Set the taskId parameter (determined in the previous step) 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/v2/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/v2/cloud/submitImage​

Use the API call to upload a file and copy taskId from the 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/v2/cloud/processDocument​

Starts image processing.

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

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

Checks a task status. Make sure to 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/v2/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.

Larger 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/v2/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/v2/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 the trained one 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/v2/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/v2/cloud/submitImage​

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

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

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

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

Starts image processing. 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 improvement​

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.