Developer Docs

Welcome to the ConPDS OCR Engine documentation! The documentation is laid out so that it is easy to navigate.

1. Introduction

1.1 The OCR Engine

The ConPDS OCR engine is not an OCR SDK but a pre-compiled, plug-and-play library, ready-to-use in your software projects. It supports the detection of BIC container codes (ISO 6346) including ISO Size and Type and ILU container codes (EN 13044-1 standard).

As we have taken care of all the factors that result in excellent and accurate recognition, you will save many, many development hours compared to using other OCR SDK’s where you need to tweak and tune many parameters to get the desired result.

1.2 Current releases

The current release for all versions is 2019.2 (version 2.2.0)

Next release will be 2019.3 (version 2.3.x) (scheduled to be released mid Q4 2019)

2. How it works

2.1 Capture

Capture the image with container code and load it into OCR engine.

2.2 Preprocessing

Preprocessing is making image noise reduction, binarization, image emphasis, skew correction, and document orientation detection.

2.3 Detection

Detection phase is our optimized set of algorithms that analyze the image and detects areas with letters in patterns specified in BIC and ILU standards. Additionally, detected area is cleaned and noise removed.

2.4 Recognition

Detected areas on the image are recognized and assigned a confidence factor. In case multiple recognitions each candidate is assigned a confidence factor. The confidence factor indicates how confident OCR engine was in the final choice of container code.

2.5 Result processing

Recognition results are returned as JSON response and can be used in further processing or exported. The developer has full control over the OCR results.

3. Prerequisites

3.1 Supported Operating Systems

  • Microsoft Windows 7, 8, 10, 2008R2, 2012R2, 2016 – 64bit, 2019 – 64bit
  • Linux Ubuntu version 16.04 or newer and Debian version 8 or newer – 64bit
  • Android version 4.0 (API version 14) or newer
  • Apple iOS version 9.x or newer

3.2 License activation

For activation of a license, there should be access to the ConPDS licensing server via Internet (TCP port 443). Once activated, there is no longer such requirement unless new license key has to be applied and activated.

3.3 Supported image format

Images should be in JPEG format (https://en.wikipedia.org/wiki/JPEG).

3.3 Image resolutions

For optimal recognition speed we recommend bellow resolutions.

 

Aspect ratio Resolutions (HxW or WxH) *
4:3 1024×768, 1280×960, 1400×1050, 1440×1080
16:10 1280×800, 1440×900, 1680×1050

*) Lower resolutions are supported but results might not be as accurate as possible. Higher resolutions are also supported, but it will result in larger files which results in slower recognition.

4. OCR engine output

4.1 JSON response

Below is a description of JSON response from OCR engine

Field
Type and description
license
String. Missing
result
String. Missing
 
 
processing_time_ms
integer. Total time in milliseconds OCR engine used on recognition.
recognition_type
String. BIC of ILU. Detected container code standard. BIC (ISO 6346) or ILU (EN 13044-1)
result
String. Container code (11 alphanumerics) with the highest confidence factor.
checksum
Boolean. Indicates if recognized container code check digit matches the calculated check digit.
iso_size_type
String. If recognition_type is BIC, then the value will be the recognized ISO Size Type (4 alphanumerics) https://en.wikipedia.org/wiki/ISO_6346#Size_and_Type_Codes
confidence
Integer. Indicates recognitions calculated confidence fator.
 
 
recognition_area
This section gives information about the area of detection. Can be useful if you
ul_x
Integer. Upper left X coordinate
ul_y
Integer. Upper left Y coordinate
lr_x
Integer. Lower right X coordinate
lr_y
Integer. Lower right Y coordinate
 
 
candidates
OCR engine can return results of additional candidates. For each candidate, there will be a section with below fields. The calculated confidence factor orders sections.
recognition_type
String. BIC of ILU.
Result
String.
checksum
Boolean
iso_size_type
String.
confidence
Integer. Calculated confidence factor. As this is a candidate, this will always be lower than the main result.
 
 
image_metadata
This section will output some image metadata.
image_resolution
Contains information about the resolution of the processed image.
width
Integer. The width of the image
height
Integer. The height of the image.

5. Android

5.1 Prerequisites

The minimum version of Android 4.0 (API version 14)

Permissions
• Read/write from/to external storage
• Internet

5.2 Preparation for usage

Import library

  • Copy aar file to the folder ‘libs’ of your project
  • Add dependency on file to build.gradle file of your project
    • compile (name:‘licensed-ocr-engine-release’, ext:’aar’)

Extend or specify App class

  • Please specify the App class in the tag name in the Manifest of your project:
    <application
    android:name=".App"
    ...
  • If you already have the custom class that extends Application class and is specified in android:name tag then please extend your custom application class from App:
    public class CustomApp extends App {
    ...
    <application
    android:name=".CustomApp"
    ...

Recognize

  • Create an instance of the class MainInteractorImpl
  • Call the method doRecognize of the created instance and pass the next arguments to the method
    • API Key
    • Licensed API Key
    • Array of paths to the photos to be recognized
    • Implementation of interface MainInteractor.Callback, that has the methods, described in Process results of recognizing.

Process results of recognizing

There are two methods, that may be called during recognize process.

  • recogOk(Map<String, String> recognizedData)
    • recognizedData map has results. Each entry of the map consist of {key} – {path-to-file} and {value} – {resultof-recognizing}
  • recogError(String msg)
    • This method is called when an error has been occurred in license checking process.
    • Possible values of parameter ‘msg’
    • “Invalid API key”
    • “License request requires approval”
    • “The license is blocked”
    • “The license is not valid”

5.3 Sample code

Download sample project here (coming soon)

6. IOS

6.1 Prerequisites

Apple iOS version 9.x or newer

6.2 Preparation for usage

Import library

  • Add .framework file to project
  • Add .framework file to “Linked frameworks and libraries” to project target

Licensing

  • Use static instance of class License
  • Use method ‘getPublicKeyFromServer:completion’ to get server public key. Completion contains public key (optional) and error (optional)
  • Use method ‘sendLicenseRequest:serverPublicKey:apiKey:licenseApiKey:completion’ to get information about license. Completion contains instance of class LicenseInfo(optional) and error (optional)

Recognize

  • Create instance of class RecognitionWrapper
  • Call method ‘recognizeCodes’
  • The method returns pointer to instance of NSArray. It is ‘nil’ if recognizing failed. If recognition is successful, it contains two strings: container number and ISO size and type code.

6.3 Sample code

Download sample project here (coming soon)

7. Microsoft Windows (library)

Free for paying customers via the Software Solution Assurance program.

7.1 Prerequisites

Microsoft .NET 4.6.1 Framework or later.

7.2 Preparation for usage

From the download link, you received, download and extract archive.

Put library “ConPDS_OCR.dll” and the license file “keys” into the folder with your executable file (*.exe).
Modify the license file “keys” and insert the api_key and license_key provided to you via email.

Example keys file: 
{
api_key=b8726d5-1114-4d7b-b6a7-5ab2ef92ed7f
license_key=bcece19-fb59-4c8e-8221-41948f42cb0a
}

Finally add reference to wrapper “ConPDS.Net.dll” inside your .NET project.

7.3 Using the library

Library offers following methods

  • string ConPDS.Net.Proxy.RecogFromBMPToJSON(System.Drawing.Image image)
    • Input parameter – picture for recognition
    • Function returns a string in json format (JSON structure. Click here for description)
  • ContainerCodeData ConPDS.Net.Proxy.RecogFromBMP(System.Drawing.Image image)
    • Input parameter image – picture for recognition
    • Function returns a Container Code/ISO Size & Type (structure. Should be managed by developer)

Example of usage

private void btnLoad_Click(object sender, RoutedEventArgs e)
{
   OpenFileDialog op = new OpenFileDialog();
   op.Title = "Select a picture";
   op.Filter = "All supported graphics|*.jpg;*.jpeg;*.png|" +
   "JPEG (*.jpg;*.jpeg)|*.jpg;*.jpeg|" +
   "Portable Network Graphic (*.png)|*.png";
   if (op.ShowDialog() == true)
   {
      imgPhoto.Source = new BitmapImage(new Uri(op.FileName));

      System.Drawing.Image img = System.Drawing.Image.FromFile(op.FileName);
      ContainerCodeData recogStructure = ConPDS.Net.Proxy.RecogFromBMPToJSON(img);
      if (recogStructure.Result == null)
      {
      textValue.Text = "<text not Recognized>";
      }
      else
      {
      textValue.Text = recogStructure.Result;
      }
   }
}

8. Microsoft Windows (console app)

8.1 Prerequisites

Java version 1.8 or newer

8.2 Preparation for usage

From the download link, you received, download and save the conPDS.jar file in any folder or your choice. Create new or modify config.properties file in same folder as the conPDS.jar file and insert the api_key and license_key provided to you via email.

Example config.properties file:
api_key=cc62f4b0-ccf1-44ac-b965-24b9cfcf7bfb
license_key=240bac2-58fb-4178-b21d-a4df3edab338

8.3 Running the application

The conPDS.jar is a java console application and accessed from the command line. On the first launch, application checks if the API and license keys are valid and activated. If not it contacts the ConPDS Licensing Server to get an activation key. Activation keys are then stored locally in a subfolder called \conpds. On the first launch, the application creates two subfolders: \incoming and \completed You have four options to process photos:

  1. Store photos inside the folder \incoming and call command line: java –jar conPDS.jar
  2. Call command line: java –jar conPDS.jar {path_to_photo}\{file_name}
  3. Call command line: java –jar conPDS.jar -listen 9999
  4. Call command line: java –jar conPDS.jar -monitor

Option 1 …
processes all photos in \incoming and moves them to \completed folder.

Option 2 …
processes a single specified photo only.

Option 3 …
launches app in listen mode ready for socket connection. This mode is used if you don’t want to save images onto disk and then process but instead just load the binary stream of the image directly into OCR engine and it will be processed just like it was a file. Port number (9999) can be any port of your choice. Please download code snippet for how to use socket connection.

Option 4 …
launches app in monitoring mode. This mode will automatically process all image saved inside \incoming folder and move them to \completed folder.

NOTE: Option 3 and 4 can be combined. In all situations, a new folder called \logs is created and will contain a log file with processing results. Log files are named with the current date. You need to write your code and logic to read output whether it is to log file or console. In both situations, a new folder called \logs is created and contains a log file with processing results. Log files are named with the current date. You need to write your code and logic to read output whether it is to log file or console. Results are returned as JSON response and will be saved into logfile or printed in the console.

8.4 Help

Calling java –jar ConPDS.jar –help prints below output:

Usage: java -jar conPDS.jar [-options] [path_to_image]
-version    prints application compatible OS and version and exit
-id          prints application ID and exit
-listen      launch app in listen mode on specified port number
-monitor     launch app in monitor mode
-nomove      leaves photo/-s in original place instead of moving into /completed folder
-nolog       don’tgenerate logfile

8.5 Sample code

Download sample code for using socket connection (download here)

9. Linux

9.1 Prerequisites

Java version 1.8 or newer Minimum one (1) CPU (can be virtual), minimum 10MB free disk space and minimum 50MB of RAM.

9.2 Preparation for usage

From the download link, you received, download and save the conPDS.jar file in any folder or your choice. Create new or modify config.properties file in same folder as the conPDS.jar file and insert the api_key and license_key provided to you via email.

Example config.properties file:
api_key=cc62f4b0-ccf1-44ac-b965-24b9cfcf7bfb
license_key=240bac2-58fb-4178-b21d-a4df3edab338

9.3 Running the application

The conPDS.jar is a java console application and accessed from the command line. On the first launch, application checks if the API and license keys are valid and activated. If not it contacts the ConPDS Licensing Server to get an activation key. Activation keys are then stored locally in a subfolder called /conpds. On the first launch, the application creates two subfolders: /incoming and /completed You have four options to process photos:

  1. Store photos inside the folder /incomingand call command line: java –jar conPDS.jar
  2. Call command line: java –jar conPDS.jar {path_to_photo}/{file_name}
  3. Call command line: java –jar conPDS.jar -listen 9999
  4. Call command line: java –jar conPDS.jar -monitor

Option 1 …
processes all photos in /incoming and moves them to /completed folder.

Option 2 …
processes a single specified photo only.

Option 3 …
launches app in listen mode ready for socket connection. This mode is used if you don’t want to save images onto disk and then process but instead just load the binary stream of the image directly into OCR engine and it will be processed just like it was a file. Port number (9999) can be any port of your choice. Please download code snippet for how to use socket connection.

Option 4 …
launches app in monitoring mode. This mode will automatically process all image saved inside /incoming folder and move them to /completed folder.

NOTE: Option 3 and 4 can be combined. In all situations, a new folder called /logs is created and will contain a log file with processing results. Log files are named with the current date. You need to write your code and logic to read output whether it is to log file or console. In both situations, a new folder called /logs is created and contains a log file with processing results. Log files are named with the current date. You need to write your code and logic to read output whether it is to log file or console. Results are returned as JSON response and will be saved into logfile or printed in the console.

9.4 Help

Calling java –jar ConPDS.jar –help prints below output:

Usage: java -jar conPDS.jar [-options] [path_to_image]
-version     prints application compatible OS and version and exit
-id              prints application ID and exit
-listen        launch app in listen mode on specified port
-monitor     launch app in monitor mode
-nomove    leavesphoto/-sin original place instead of moving into /completed folder
-nolog        don’tgenerate logfile

9.5 Sample code

Download sample code for using socket connection (download here)

10. REST API

10.1 Prerequisites

Access to internet HTTPS (port 443)

10.2 Sample code

Download swagger definition here (download here)

11. Support services

11.1 Support

If you are experiencing difficulties with any of our products, you can contact ConPDS Support directly via support@conpds.com.

11.2 Software solution assurance

To protect your investment, it is mandatory that you purchase one initial year of Solution Assurance with each license purchase. Solution Assurance unlocks access to Technical Support, Product Updates, and Upgrades. The Solution Assurance is extended automatically at the end of each 12 month period, and this is done automatically unless, you as a customer, specify otherwise.

11.3 Product upgrades and service releases

Product Upgrades and Service Releases – To upgrade your version of ConPDS OCR engine to the latest available version, you can download from the download link provided when purchasing the product. If you no longer have the link, please contact ConPDS Support by sending email to support@conpds.com.

Container Photo Documentation System

ConPDS eliminates the need for digital cameras, memory cards and transportation from container yard to administration. With the ConPDS mobile app, container photo documentation simply becomes click-and-go.

Ready To Get Started?