pdf417 pro user guide rev.05.12

PDF417 Decoding SDK (Professional Edition)

2D Technology Group, Inc. Rev. 05/12 1

User’s Guide

Table of Contents 1. Introduction. ......................................................................................................................................... 2

1.1 Scope ............................................................................................................................................. 2

1.2 Normative references ................................................................................................................... 2

1.3 SDK composition ........................................................................................................................... 2

1.4 Features Description ..................................................................................................................... 2

1.5 Program session ............................................................................................................................ 3

2. The Basic Interface Structures .............................................................................................................. 4

2.1 Decoder options. ........................................................................................................................... 4

2.2 Image info. .................................................................................................................................... 4

2.3 Symbol info. .................................................................................................................................. 4

2.4 Symbol Quality .............................................................................................................................. 5

2.5 The Constants. .............................................................................................................................. 5

3. The Interface Procedures and Functions .............................................................................................. 6

3.1 C++(Windows DLL) ........................................................................................................................ 6

3.1.1 Connect_PDF417_Decoder ................................................................................................... 6

3.1.2 Disconnect_PDF417_Decoder............................................................................................... 7

3.1.3 PDF417_Options_Create. ...................................................................................................... 7

3.1.4 PDF417_Options_Delete. ...................................................................................................... 7

3.1.5 DecodeBitsF .......................................................................................................................... 7

3.1.6 Get_PDF417_ImageInfo ........................................................................................................ 8

3.1.7 Get_PDF417_Info .................................................................................................................. 8

3.2 Windows DLL. ................................................................................................................................ 9

4. Demo application - GUI ....................................................................................................................... 12

5. Deployment......................................................................................................................................... 14

5.1 Single workstation ....................................................................................................................... 14

5.2 Network ...................................................................................................................................... 14



1. Introduction.

1.1 Scope

This document is applicable to the Professional Edition of the PDF417 Decoding SDK.

SDK is notated as PDF_PRO_YY, where YY=32|64, and notation “32|64” means 32 bit or

64 bit version.

Library interface is uniform for Windows, Linux, and certain embedded platforms. Both

static and dynamic libraries are available.

The library is designed to decode PDF417 Codes in accordance with ISO/IEC 16022

Symbology specification. Symbol quality assessment is provided in accordance with ISO/IEC

15415 standard.

The Quality Parameters option is user-selectable.

Library processes 8-bit images only.

1.2 Normative references

ISO/IEC 15438:2006 - Symbology specification – PDF417

ISO/IEC 15415 - Symbol quality - Two-dimensional symbols

1.3 SDK composition

Decoding SDK contains:

Windows DLL (PDF_PRO.DLL) designed to perform PDF417 Code search, recognition

and decoding.

C++ source code of the Demo programs in Borland CBuilder v 3.0 and/or MSVC 2008

that illustrate the DLL usage.

Current User’s Guide.

1.4 Features Description

Edition specific features of the Library are described in the Table below:



PDF417 SDK (PDF SDK)

Features EDITION

Standard Professional

DR (PDF Direct) √

SP (PDF Speed) √

QP (PDF QP) √

MM (Multi Mode) √

Features Description

DR (PDF Direct)

allows to decrease image capture time, if barcode orientation is

known, by providing for three optional settings – “Horizontal”,

“Vertical”, “All”

SD (PDF Speed)

speed control setting with two optional modes:

Robust Mode - Standard speed; highest accuracy level – for

poor quality images

Turbo Mode - High speed decoding (2-3x faster than robust

mode) for applications where decoding time is critical and image

quality is relatively good

QP (PDF QP) Quality Parameters evaluation in accordance with ISO 15415, 15416

MM (Multi Mode) decodes up to 100 barcodes in one image via variable setting

1.5 Program session

Typical program session looks as follows:

Step 1. Connect decoder

Step 2. Create and set decoder options

Loop

Step 3. Capture/read bitmap image

Step 4. Process image

Step 5. Request image and symbols info

… // further application-specific data processing and interaction with user

End Loop

Step 6. Delete decoder options

Step 7. Disconnect decoder.



2. The Basic Interface Structures

The library includes the following structures:

struct TPDF417_OptMode The set of decoder options

struct TPDF417_ImageInfo Features of decoded image

struct TPDF417_Info Features of decoded symbols

struct TPDF417_Quality Quality Parameters of decoded symbols

2.1 Decoder options. struct TPDF417_OptMode

{

int MaxSymbolCount; //

int SpeedMode; // SP_Robust, SP_Fast

int CalcGrade; //

int DirectMode; // DM_LeftRight, DM_Horizontal, DM_All

int TimeOut; // milliseconds, zero - not applied

int ScanStep; // step of scan lines

};

2.2 Image info. struct TPDF417_ImageInfo

{ // averall image properties

int SymbolCount; // number of well decoded PDF417 symbols within image

int ErrorCode; // nonzero, if no one symbols had been decoded

char* ErrorString; // pointer to error string

};

2.3 Symbol info.

Each decoded symbol is described by the following structures: struct TPDF417_Info

{ //result of decoding per each PDF417 symbol

int ErrorCode; // Result

int rowcols[8]; // symbol corners

bool rcFlag; // true if a corners of symbol was found

int RSErrorCount; // number of Reed Solomon errors

int ColCount; // horizontal dimension (from 1 to 30)

int RowCount; // vertical dimension (from 4 to 90)

char* ErrorString; // pointer to error string

int ECLevel; // Error Correction Level (from 0 to 8)

int pchlen; // length of decoded byte array

unsigned char* pch;// decoded byte array



char* c_str; // decoded char array (points to the same allocation in

memory)

TPDF417_Quality Quality; // parameters of symbol quality (if possible)

};

2.4 Symbol Quality

struct TDM_Quality

{

// 0..100 , -1 = have not been calculated

float symbol_contrast; // symbol contrast(SC) = Rmax-Rmin

float min_reflectance; // Rmin

float max_reflectance; // Rmax

float global_threshold; // global_threshold(GT) = (Rmax+Rmin)/2

float min_edge_contrast; // ECmin

float modulation; // modulation (MOD) = ECmin/SC

float defects; //

float decodability; // V

float width_height_proportion;

float unused_error_correction; // UEC

// grades

// 0..4, 0 = Worst , 4 = Best, -1 = have not been calculated

float decode_grade;

float symbol_contrast_grade;

float min_reflectance_grade;

float min_edge_contrast_grade;

float modulation_grade;

float defects_grade;

float decodability_grade;

float unused_error_correction_grade;

float overall_grade;

};

2.5 The Constants.

// TPDF417_SpeedMode

const int

SP_Fast = 1,

SP_Robust = 0;

// TPDF417_DirectMode

const int

DM_LeftRight = 0, // Scan only horizontal barcodes with Start Pattern

// on left side of image

DM_Horizontal = 1, // Scan only horizontal barcodes with Start Pattern

// on left or right side of image

DM_All = 2; // Scan barcode with any orientation



// TPDF417_CalcGradeMode

const int

CG_No = 0, //

CG_Yes = 1; // Calculate Bar code print quality

// See ISO/IEC 15415, ISO/IEC 15416

const int// error codes

//

############################################################################

PDF417_OK = 0,

PDF417_Rectangle_Error = -1, // no Start and Stop Patterns were found

PDF417_ColCount_Error = -4,

PDF417_RowCount_Error = -5,

PDF417_ECCodeword_Error = -6,

PDF417_ErasuresLimit_Error = -7, // too many codewords with improper

clasters

PDF417_RS_Error = -8, // too many errors in Reed Solomon code

PDF417_CharEncodation_Error = -9, // unexpected encodation scheme

PDF417_StartPattern_Error = -10, // Start pattern is not found

PDF417_StopPattern_Error = -11, // Stop pattern is not found

PDF417_Indikators_Error = -12, // incorrect data in row indicators

PDF417_Geometry_Error = -13; // unallowed module size

const int// error codes

PDF417_NOMEMORY = -99,

PDF417_UNKNOWN = -100,

PDF417_DISCONNECTED = -200;

//=========================================

3. The Interface Procedures and Functions

3.1 C++(Windows DLL)

3.1.1 Connect_PDF417_Decoder

PPDF417_Decoder Connect_PDF417_Decoder(int maxcolcount, int maxrowcount)

Description.

Function generates new instance of class encapsulating the decoder functionality.

Parameters.

Maximum values of vertical and horizontal image sizes.

Return value.



Pointer to structure TPDF417_Decoder if decoder is created, null otherwise

3.1.2 Disconnect_PDF417_Decoder

void Disconnect_PDF417_Decoder(PPDF417_Decoder& pdecoder)

Description.

Procedure destroys decoder class and frees memory.

Parameters.

pdecoder - the variable containing the pointer on structure TPDF417_Decoder.

3.1.3 PDF417_Options_Create.

PPDF417_Options PDF417_Options_Create(PPDF417_Decoder pdecoder, TPDF417_OptMode

optmode)

Description.

Function generates new instance of class encapsulating the decoder with desirable options.

Parameters.

The pointer on structure TPDF417_Decoder.

3.1.4 PDF417_Options_Delete.

void PDF417_Options_Delete(PPDF417_Options& poptions)

Description.

Procedure destroys instance of the decoder with options.

Parameters.

The variable containing the pointer on structure TPDF417_Options.

3.1.5 DecodeBitsF int DecodeBitsF // base decoding function

(PPDF417_Options poptions

,int rowcount // The number of rows in the image

,int colcount // The number of columns

,TRow* ppbits // Points to array of pointers:

//{pbits[0],...,pbits[rowcount-1]} to bitmap

lines

);

Description.



The function processes an image and fills ImageInfo and array of SymbolInfo’s.

Parameters.

poptions – pointer on structure TPDF417_Options

rowcount – number of image rows,

colcount – number of image columns,

ppbits – array of pointers to image rows. Every row is a byte array with pixels brightness.

(We have typedef unsigned char* TRow; )

Return value.

<0, if no one symbol was decoded, >=0 otherwise.

3.1.6 Get_PDF417_ImageInfo

TPDF417_ImageInfo* Get_PDF417_ImageInfo(PPDF417_Options poptions); // inspects

image info after decoding

Parameters.

poptions – pointer on structure TPDF417_Options

Return value.

Pointer to Image Info.

3.1.7 Get_PDF417_Info

TPDF417_Info* Get_PDF417_Info(PPDF417_Options poptions, int dmNum); // inspects

symbol info after decoding

Parameter.

poptions – pointer on structure TPDF417_Options.

dmNum - number of decoded symbol in image.

If no symbols were decoded then dmNum = 0 extracts Info for most possible symbol

location.

Return value.

Pointer to Symbol Info.



3.2 Windows DLL.

Windows DLL has the same functions. The only difference is in parameters and return

values.

Here we use technique like opening the file represented by file handler.

// file PDF417Pro_Types.h

//=========================================

// constants – see 2.5

//=========================================

struct TPDF417_OptMode; // see Error! Reference source not found.

Struct TPDF417_ImageInfo; // see Error! Reference source not found.

Struct TPDF417_Info; // see Error! Reference source not found.

Struct TPDF417_Quality; // see 2.4

//=========================================

typedef void* PPDF417_Decoder;

typedef void* PPDF417_Options;

typedef TDM_ImageInfo* pDM_ImageInfo;

typedef TDM_Info* pDM_Info;

typedef unsigned char* TRow; // pointer to bitmap line

typedef PPDF417_Decoder ( __stdcall *TConnect_PDF_Decoder

)(int,int);

typedef void ( __stdcall *TDisconnect_PDF_Decoder

)(PPDF417_Decoder&);

typedef PPDF417_Options ( __stdcall *TCreate_PDF_Options

)(PPDF417_Decoder,TPDF417_OptMode);

typedef void ( __stdcall *TDelete_PDF_Options

)(PPDF417_Options&);

typedef int ( __stdcall *TDecodeBitsF

)(PPDF417_Options,int,int,unsigned char ** );

typedef bool ( __stdcall *TCleanupPDF

)(PPDF417_Options);

typedef pPDF417_ImageInfo( __stdcall *TGetPDF_ImageInfo

)(PPDF417_Options);

typedef pPDF417_Info ( __stdcall *TGetPDF_Info

)(PPDF417_Options,int);

// end of file PDF417Pro_Types.h



// example of Windows application // ========================= variables ==============================

#include "PDF417Pro_Types.h"

int rowcount, colcount; // The Img dimentions

TRow pbits[4000]; // array of pointers to bitmap lines

// (input parameter for decoding)

PPDF417_Decoder pdecoder;

PPDF417_Options poptions1, poptions2;

TPDF417_OptMode optmode;

TPDF417_ImageInfo* pimageinfo;

TPDF417_Info* pdminfo;

HINSTANCE DLLInstance;

TConnect_PDF_Decoder Connect_PDF_Decoder ;

TDisconnect_PDF_Decoder Disconnect_PDF_Decoder ;

TCreate_PDF_Options Create_PDF_Options ;

TDelete_PDF_Options Delete_PDF_Options ;

TDecodeBitsF Decode_PDF_BitsF ;

TGetPDF_ImageInfo Get_PDF_ImageInfo ;

TGetPDF_Info Get_PDF_Info ;

TCleanupPDF Cleanup_PDF ;

...

// ============================ program =================================

DLLInstance = ::LoadLibrary("icPDF417_DecWinPro.dll");

if (DLLInstance!=0) {

Connect_PDF_Decoder = (TConnect_PDF_Decoder

)::GetProcAddress(DLLInstance,"Connect_PDF417_Decoder");

Disconnect_PDF_Decoder = (TDisconnect_PDF_Decoder

)::GetProcAddress(DLLInstance,"Disconnect_PDF417_Decoder");

Create_PDF_Options = (TCreate_PDF_Options

)::GetProcAddress(DLLInstance,"PDF417_Options_Create");

Delete_PDF_Options = (TDelete_PDF_Options

)::GetProcAddress(DLLInstance,"PDF417_Options_Delete");

Decode_PDF_BitsF = (TDecodeBitsF

)::GetProcAddress(DLLInstance,"PDF417_Options_DecodeBitsF");

Get_PDF_ImageInfo = (TGetPDF_ImageInfo

)::GetProcAddress(DLLInstance,"PDF417_Options_ImageInfo");

Get_PDF_Info = (TGetPDF_Info

)::GetProcAddress(DLLInstance,"PDF417_Options_Info");

Cleanup_PDF = (TCleanupPDF

)::GetProcAddress(DLLInstance,"PDF417_Options_Cleanup");

}



if (Connect_PDF_Decoder != NULL) {

// ==== construct decoder:

pdecoder = Connect_PDF_Decoder(4000,4000);

// ==== assign option modes:

optmode.MaxSymbolCount = 1;

optmode.SpeedMode = SP_Fast;

optmode.CalcGrade = true;

optmode.DirectMode = DM_All;

// ==== construct the options:

poptions1 = Create_PDF_Options(pdecoder, optmode);

optmode.MaxSymbolCount = 1;

optmode.SpeedMode = SP_Robust;

optmode.CalcGrade = false;

optmode.DirectMode = DM_All;

// ==== construct the options:

poptions2 = Create_PDF_Options(pdecoder, optmode);

while(...) { // =========== begin decode loop:

// ... Load new image into pbits

Decode_PDF_BitsF(poptions1, rowcount, colcount, pbits); // decode the

array

Decode_PDF_BitsF(poptions2, rowcount, colcount, pbits); // decode the

array

// show first result

pimageinfo = Get_PDF_ImageInfo(poptions1);

// display pimageInfo

pdminfo = GetDM_Info(poptions1,0);

// display pdmInfo [0]

DecodedSymbolNo = pimageinfo-> SymbolCount;

for (i=1; i<DecodedMatrixNo; i++){

pdminfo = GetDM_Info(poptions1,i);

// display pdmInfo [i]

}

// show second result

pimageinfo = Get_PDF_ImageInfo(poptions2);

// display pimageInfo

pdminfo = GetDM_Info(poptions2,0);

// display pdmInfo [0]

DecodedSymbolNo = pimageinfo-> SymbolCount;



for (i=1; i<DecodedMatrixNo; i++){

pdminfo = GetDM_Info(poptions2,i);

// display pdmInfo [i]

}

} // ============ end decode loop

Delete_PDF_Options(poptions1);

Delete_PDF_Options(poptions2);

Disconnect_PDF_Decoder (pdecoder);

::FreeLibrary(DLLInstance);

4. Demo application - GUI

Decoding Library comes with the Demo application build in Borland CBuilder v 3.0.

GUI illustrates all major features of the Library:



Options:

Max. Symbol Count – setting the maximum number of symbols in the image to be

decoded (program will stop when it reaches this number even if there are more symbols

in the image)

Speed - speed control setting with two optional modes:

o Robust Mode - Standard speed; highest accuracy level – for poor quality images

o Turbo Mode - High speed decoding (2-3x faster than robust mode) for

applications where decoding time is critical and image quality is relatively good

Symbol Quality – turns Quality Assessment option “ON/OFF”

Direct – setting scan direction (if barcode orientation is known) to minimize symbol

search time within the image; default value – “All”

Step (range: 1-32) – distance between the scan-lines (in pixels); default value - 4 pixels

Timeout - allows to set timeout value (in ms); “0” means – no timeout is set (default).

Image Info:

Time (ms) – total decode time (all PDF417 symbols within the image

Decoded – number of PDF417 symbols decoded within the image

Rejection - in some cases decoding library can return certain error codes and textual

information, associated with the decoding process (this parameter characterizes the whole

image if it contains more than 1 symbol). They are as follows:

o Rectangle_Error = -1 - no Start and Stop Patterns were found

o ColCount_Error = -4 -

o RowCount_Error = -5 -

o ECCodeword_Error = -6 -

o ErasuresLimit_Error = -7 - too many codewords with improper clasters

o RS_Error = -8 - too many errors in Reed Solomon code

o CharEncodation_Error = -9 - unexpected encodation scheme

o StartPattern_Error = -10 - Start pattern is not found

o StopPattern_Error = -11 - Stop pattern is not found

o Indikators_Error = -12 - incorrect data in row indicators

o Geometry_Error = -13 - unallowed module size

Note: successful decoding always returns “OK” and “0” in these fields

Break – reason for stopping decode process:

o “0” – all symbols within the image are inspected

o “1” - timeout



Decode Window – displays all PDF417 Codes found (per Image Info/ Decoded field). Decode

data on each code (window below) are available by “clicking” “arrow” on the

top-right corner of the screen.

Symbol Data – code page

Symbol Info:

Rejection – the same as in Image Info, but for the considered symbol only.

Row, col – number of Rows and Columns in the symbol

ECLevel – Error Correction Level

Reed Solomon errors – number of errors in Reed Solomon code

Corners: coordinates of the symbol corners (in pixels)

Symbol Quality – results of the symbol quality assessment in accordance with ISO/IEC 15415

5. Deployment

5.1 Single workstation

We recommend that license for the library would be activated when running Demo application

(APP) supplied with the library. By default Library is located in the application folder.

The structure of the Demo application provides for the pass to the library as follows:

dllinstance = LoadLibrary("PDF_PRO.dll");

If the library is moved to the different folder (ABC) the pass will be different too:

dllinstance = LoadLibrary("..\\ABC\\ PDF_PRO.dll").

When integrating library with your APP, we would recommend keeping it in the APP folder as

well.

5.2 Network

Network deployment would require network license for the library. Network licensing is only

supported when running the wrapped library over the network; this will not work with the library

running locally.

It’s not sold in our store because it needs to be implemented on an individual basis - our Network

Floating model for controlling access to your application over a network requires knowing a



number of concurrent uses in the system. Contact Customer Service if you need Network

License.

Typical deployment scenario for network licensing looks as follows:

APP would need to be installed to a network share and all workstations will need to have

read/write/execute permissions.

Our DLL-library shall be placed into the same folder as APP.

Run the application over the network and activate using the steps described in the

Installation Instructions.

Activating the application from one workstation will enable all workstations to have

access.

If the application will need to be ran locally on the server, you will have to activate the

application a second time from the server.

Note: Setting up a file server, network share, and the necessary permissions is beyond the scope

of this manual.

pdf417 pro user guide rev.05.12

Documents

2d technology

pdf417 decoding

construct

structure

start pattern

pdf speed

decoded symbol

symbol quality