VPAR v - Neural Labs · Nuera NeuD VPAR v.7 DLL Reference Manual May 16 NEURAL LABS S.L. Carrer...

VPAR v.7

DLL Reference Manual

May 16

Nuera

NeuD VPAR v.7 DLL Reference Manual

May 16

NEURAL LABS S.L. Carrer Sant Eduard 31. 08290 Cerdanyola del Valles. Barcelona - Spain. http://www.neurallabs.net

2 de 46

Table of Contents

Initialization / Finalization 4

vparInit 4

vparEnd 6

vpmrAddCountry 7

Reading Plates 8

vparRead 8

vparReadRGB24 9

vparReadRGB32 10

vparReadBMP 11

vparReadJPG 12

Reading candidate zones 13

Structure 13

vpmrFindCandidateRegionsFromGreyscale 14

vpmrFindCandidateRegionsFromRGB24 15

vpmrFindCandidateRegionsFromRGB32 16

vpmrFindCandidateRegionsFromBMP 17

vpmrFindCandidateRegionsFromJPG 18

Retrieving Results 19

vparGetNumberOfPlates 19

vparGetText 20

vparGetNumberOfCharacters 21

vparGetPolarity 22

vparGetGlobalConfidence 23

vparGetAverageCharacterHeight 24

vparGetCharacterConfidence 25

vparGetRectangle 26

vparGetFormat 27

vpmrSavePlateImage 28

vpmrGetCharRectangle 29

Time Management 30

vparGetProcessingTime 30

vparSetTimeOut 31

Optional Configuration 32

vparSetCorrectionCoefficients 32

vparSetCorrectionCoefficientsEx 33

Nuera


May 16


3 de 46

vparSetDistortionCorrectionOff 34

vparConfigureAutomaticCharacterHeight 35

vparSetRectangle 36

vpmrShadowKillerOn 37

vpmrShadowKillerOff 38

vpmrStrictSyntaxOn 39

vpmrStrictSyntaxOff 40

vpmrSetScaleFactor 41

vpmrReturnSpaces 42

Storing Data into the HASP Dongle 43

vparWriteHASP 43

vparReadHASP 44

Miscellaneous 45

vparComparePlates 45

Example of Use 46

Nuera


May 16


4 de 46

Initialization / Finalization

vparInit Initializes the Vehicle Plates Automatic Reader (VPAR). It loads the Artificial

Neural Networks used by the OCR and initializes parameters. This function must be called before calling any other function in this library.

long vparInit (long lCountryCode, long lAverageCharacterHeight,

bool bDuplicateLines = false, long lreserved1, long lreserver2,

bool bTrace = false );

Arguments

lCountryCode County code used for selecting the target country for license

plate recognition. See declaration file for a list of supported

countries.

lAvCharacterHeight Approximate average height of the characters in the plates to read. If this argument is -1, the library uses automatic height mode and tries to read characters of any height.

If -1 is passed, the processing time will be increased.

bDuplicateLines In order to properly recognize images acquired with only half of the scan lines, this argument must be true. For images

acquired with all the lines, this parameter must be false. lreserved1 Sort characters in squared plates (plates with two rows of

characters). If this argument is false, the characters in the top row are returned first, followed by the characters in the

bottom row. If it is true, the characters are re-arranged to match the Spanish format. (For example, if this parameter is true, a plate with the top line “BU AX” and bottom line

“5278” would be re-arranged to generate the result “BU5278AX”. In the other hand, if this argument is false,

the result would be “BUAX5278”).

Nuera


May 16


5 de 46

lreserved2 Activate special filter for colour treatment. Possible values

are:

0 Average value of the three channels (Recommended, default value) 1 Use first colour channel (red for RGB image or blue in case of BGR) 2 Use second colour channel (green always)

3 Use the third colour channel (blue for RGB image, red for BGR image) < 0 Error

> 3 Error bTrace This parameter must be set to false.

Return Value

0 Error.

1 Ok.

Nuera


May 16


6 de 46

vparEnd

Frees the memory allocated by the Vehicle Plates Automatic Reader (VPAR). Only call this function at the end of the program.

void vparEnd ( void );

Nuera


May 16


7 de 46

vpmrAddCountry This function only is used when the library has been initialized with the country code

LOC_CODE_EU (for Europe). In this case, AddCountry is used to add European countries to take into account for reading.

Initially (after Init), no countries are included and AddCountry must be called at least once.

The countries supported by this function are: Spain

France Italy Germany

UK Portugal

Netherlands Greece Poland

long vpmrAddCountry ( long lCountryCode);

Parameters

lCountryCode Country code

Return value

0 Error. 1 Ok.

Remark: We recommend using the multicountry code in vpmrinit function. To generate this code will use the code generation tools included in the CD.

Nuera


May 16


8 de 46

Reading Plates

vparRead

This function reads the license plate present within an image. The input to this function is an image. It analyzes the image looking for a vehicle plate and if it finds it,

it reads the plate. A set of functions is supplied to retrieve the result of the recognition (see Retrieving Results chapter bellow).

The input supplied to this function is the image buffer in 256 grayscale levels (1 byte per pixel). The width and height of the image must be supplied as well.

long vparRead ( long lWidth, long lHeight, unsigned char * pbImageData );

Arguments

lWidth Width (in pixels) of the image that will be analyzed.

lHeight Height (in pixels) of the image that will be analyzed.

pbImageData Buffer with the image data (pixels), in 256 grey levels (1 byte per pixel).

Return Value

0 Error.

1 Ok.

Nuera


May 16


9 de 46

vparReadRGB24

This function reads the vehicle plate present within an image. The input to this function is an image. It analyzes the image looking for a vehicle plate and if it finds it,


The input supplied to this function is the image buffer in RGB-24 bits (3 bytes per pixel) format. The width and height of the image must be supplied as well.

long vparReadRGB24 ( long lWidth, long lHeight,

unsigned char * pbImageData,

bool bFlip = false );

Arguments



pbImageData Buffer with the image data (pixels) using 3 bytes per pixel (RED, GREEN, BLUE).

bFlip This value must be true only if the RGB buffer contains first the bottom row of the image, then the next one upwards,

and so on. The last line of values in the buffer contains the top row of pixels in the image. Some devices acquire the RGB buffer in this way (bottom-up).

Return Value

0 Error.

1 Ok.

Nuera


May 16


10 de 46

vparReadRGB32



The input supplied to this function is the image buffer in RGB-32 bits (4 bytes per pixel) format. The width and height of the image must be supplied as well.

long vparReadRGB32 ( long lWidth, long lHeight,

unsigned char * pbImageData,

bool bFlip = false );

Arguments



pbImageData Buffer with the image data (pixels) using 4 bytes per pixel

(RED, GREEN, BLUE, ALPHA).

bFlip This value must be true only if the RGB buffer contains first

the bottom row of the image, then the next one upwards, and so on. The last line of values in the buffer contains the top row of pixels in the image. Some devices acquire the

RGB buffer in this way (bottom-up).

Return Value

0 Error.

1 Ok.

Nuera


May 16


11 de 46

vparReadBMP This function reads the vehicle plate present within an image. The input to this

function is an image. It analyzes the image looking for a vehicle plate and if it finds it, it reads the plate. A set of functions is supplied to retrieve the result of the recognition

(see Retrieving Results chapter bellow). The input supplied to this function is an image file in standard Bitmap (BMP) format.

long vparReadBMP ( char * strFilename );

Arguments

strFilename Filename of BMP image to process.

Return Value

0 Error. 1 Ok.

Nuera


May 16


12 de 46

vparReadJPG



The input supplied to this function is an image file in standard Jpeg (JPG) format.

long vparReadJPG ( char * strFilename );

Arguments

strFilename Filename of JPG image to process.

Return Value

0 Error.

1 Ok.

Nuera


May 16


13 de 46

Reading candidate zones

Structure

The following structure is used to define the candidate regions to obtain a plate.

struct CandidateRegion {

long left; long top;

long right; long bottom;

long ach;

};

Parameters

left Left coordinate of region within image (in pixels)

top Top coordinate of region within image (in pixels) right Right coordinate of region within image (in pixels)

bottom Bottom coordinate of region within image (in pixels) ach Approximate Average Character Height of region (in pixels)

Nuera


May 16


14 de 46

vpmrFindCandidateRegionsFromGreyscale

Finds one or more regions that might contain a vehicle number plate. Returns the number of regions and their coordinates.

long vpmrFindCandidateRegionsFromGreyscale( long lWidth,

long lHeight, unsigned char* pbImageData, long* plNumRegions,

CandidateRegion* pRegions, long lMaxRegions,

bool zPreciseCoordinates = false); Parameters

lWidth Image Width (in pixels).

lHeight Image Height (in pixels)

pbImageData Buffer with the image pixels (greylevel, 8 bits/pixel).

plNumRegions Pointer to receive the returned number of regions found. pRegions Array of CandidateRegion elements where the coordinates of

the found regions will be copied.

lMaxRegions Number of elements in the pRegions array. zPreciseCoordinates Return de coordinates without security margin.

Return value

0 Error. 1 Ok.

Nuera


May 16


15 de 46

vpmrFindCandidateRegionsFromRGB24


long vpmrFindCandidateRegionsFromRGB24( long lWidth,

long lHeight, unsigned char* pbImageDataRGB,

bool bFlip,

long* plNumRegions, CandidateRegion* pRegions,

long lMaxRegions, bool zPreciseCoordinates = false);

Parameters

lWidth Image Width (in pixels). lHeight Image Height (in pixels)

pbImageData Buffer with the image pixels (RGB, 24 bits / pixel)

bFlip True to perform a Vertical Flip of the image buffer.

plNumRegions Pointer to receive the returned number of regions found.

pRegions Array of CandidateRegion elements where the coordinates of the found regions will be copied.

lMaxRegions Number of elements in the pRegions array.

zPreciseCoordinates Return de coordinates without security margin.

Return value

0 Error.

1 Ok.

Nuera


May 16


16 de 46

vpmrFindCandidateRegionsFromRGB32


long vpmrFindCandidateRegionsFromRGB32(

long lWidth,

long lHeight, unsigned char* pbImageDataRGB,

bool bFlip, long* plNumRegions, CandidateRegion* pRegions,


Parameters

lWidth Image Width (in pixels).

lHeight Image Height (in pixels) pbImageData Buffer with the image pixels (RGB, 32 bits / pixel)

bFlip True to perform a Vertical Flip of the image buffer.





Return value

0 Error.

1 Ok.

Nuera


May 16


17 de 46

vpmrFindCandidateRegionsFromBMP


long vpmrFindCandidateRegionsFromBMP (

char* strFileName,

long* plNumRegions, CandidateRegion* pRegions,


Parameters

strFilename BMP file





Return value

0 Error. 1 Ok.

Nuera


May 16


18 de 46

vpmrFindCandidateRegionsFromJPG

Finds one or more regions that might contain a vehicle number plate. Returns the

number of regions and their coordinates.

long vpmrFindCandidateRegionsFromJPG ( char* strFileName,

long* plNumRegions,

CandidateRegion* pRegions, long lMaxRegions,

bool zPreciseCoordinates = false); Parameters

strFilename JPG file plNumRegions Pointer to receive the returned number of regions found.

pRegions Array of CandidateRegion elements where the coordinates of

the found regions will be copied. lMaxRegions Number of elements in the pRegions array.


Return value

0 Error.

1 Ok.

Nuera


May 16


19 de 46

Retrieving Results

vparGetNumberOfPlates

Returns the number of plates found and recognized in the last analyzed image.

long vparGetNumberOfPlates ( void );

Return Value

Returns the number of vehicle plates read.

Remarks

This value will be 0 if no vehicle plate is found or if it cannot be read. It will be 1 if one vehicle plate was found and recognized and 2 only if vparInit was called with the argument bTrailersOn set to true and the processed image contains the two plates at

the back of a truck carrying a trailer.

Nuera


May 16


20 de 46

vparGetText

Returns the text (in ASCII format) of the vehicle plate read in the last processed image.

long vparGetText ( char * strResult,

long lPlate = 0 );

Arguments

strResult String where the ASCII text is returned.

lPlate Index of the plate we want to retrieve.

If only one plate was read, number 0 must be specified.

If two plates where read (a truck with two plates at the back), the result for plate number 0 or number 1 can be requested.

Return Value

0 Error.

1 Ok.

Nuera


May 16


21 de 46

vparGetNumberOfCharacters

Returns the number of characters present in the last plate processed by VPAR.

long vparGetNumberOfCharacters ( long lPlate = 0 );

Arguments

lPlate Index of the plate we want to retrieve. If only one plate was read, number 0 must be specified.


Return Value

Number of recognized characters.

Nuera


May 16


22 de 46

vparGetPolarity

Returns the polarity of the plate.

long vparGetPolarity ( long lPlate = 0 );

Arguments



Return Value

Polarity of the plate: 1 for dark chars on bright backgorund, 2 otherwise.

Nuera


May 16


23 de 46

vparGetGlobalConfidence

Returns a confidence factor for the result of the last plate recognized by the Vehicle Plates Automatic Reader.

This value is expressed as a percentage (0% – 100%).

float vparGetGlobalConfidence ( long lPlate = 0 );

Arguments



Return Value

The Confidence Factor for the last recognition.

Nuera


May 16


24 de 46

vparGetAverageCharacterHeight

Returns the average height (in pixels) of the characters present in the last plate recognized by the Vehicle Plates Automatic Reader.

float vparGetAverageCharacterHeight ( long lPlate = 0 );

Arguments


If only one plate was read, number 0 must be specified. If two plates where read (a truck with two plates at the back), the result for plate number 0 or number 1 can be requested.

Return Value

The average height (in pixels) of the characters in the last plate analyzed.

Nuera


May 16


25 de 46

vparGetCharacterConfidence

Returns a confidence factor for a given character within the last plate analyzed.

This value is expressed as a percentage (0% – 100%).

float vparGetCharacterConfidence ( long lIndex ,

long lPlate = 0 );

Arguments

lIndex (0..n) Index of the character we want to retrieve the confidence

factor for.


If only one plate was read, number 0 must be specified. If two plates where read (a truck with two plates at the back), the result for plate number 0 or number 1 can be requested.

Return Value

Character Confidence Factor.

Nuera


May 16


26 de 46

vparGetRectangle

Returns the coordinates of the rectangle containing the vehicle license plate in the last image processed.

void vparGetRectangle ( long * plLeft, long * plTop, long * plRight,

long * plBottom, long lPlate = 0 );

Arguments

plLeft X-Coordinate of the Upper-Left corner of the rectangle.

plTop Y-Coordinate of the Upper-Left corner of the rectangle. plRight X-Coordinate of the Lower-Right corner of the rectangle.

plBottom Y-Coordinate of the Lower-Right corner of the rectangle.


If only one plate was read, number 0 must be specified.


Nuera


May 16


27 de 46

vparGetFormat

This property returns the country code that matches license plate result. Example: If the software detects reading of a Spanish license plate, code returned is 101. If no

country is detected it returns 0. For European license plates (no country detected) it returns 100.

long vparGetFormat ( long lPlate);

Parameters

lPlate Number of license plate read result to query about (0 to 7).

Return value

0 No license plate format detected.

N Country code or continent of detected format.

Nuera


May 16


28 de 46

vpmrSavePlateImage

Saves a BMP image containing the specified plate.

long vpmrSavePlateImage ( char* strBMPFilename, long lPlate);

Parameters

strBMPFilename File name to save.

lPlate If there is more than one plate found, this is the plate index

(0 for the first one). Return value

true OK.

false Error.

Nuera


May 16


29 de 46

vpmrGetCharRectangle

Returns the coordinates of the rectangle containing a given character in the last plate analyzed. The coordinates are relatives to saved image by

vpmrSavePlateImage function.

void vpmrGetRectangle (long lIndex, long * plLeft,

long * plTop, long * plRight,

long * plBottom, long lPlate = 0 );

Parameters

lIndex Index of the character (first character has index = 0).

plLeft X-Coordinate of the Upper-Left corner of the rectangle.

plTop Y-Coordinate of the Upper-Left corner of the rectangle.

plRight X-Coordinate of the Lower-Right corner of the rectangle. plBottom Y-Coordinate of the Lower-Right corner of the rectangle.

lPlate If there is more than one plate found, this is the plate index (0 for

the first one)

Nuera


May 16


30 de 46

Time Management

vparGetProcessingTime

Returns the processing time for the last reading operation.

This value is expressed in milliseconds.

long vparGetProcessingTime ( );

Return Value

Processing time (in milliseconds) for the last reading.

Nuera


May 16


31 de 46

vparSetTimeOut

This function specifies the maximum processing time for reading operations.

This value is expressed in milliseconds.

void vparSetTimeOut ( long lMilliseconds );

Arguments

lMilliseconds Maximum processing time (in milliseconds).

Remarks

This maximum time is approximate. This means that the actual processing time can be (in some cases) slightly longer that the time-out specified.

Nuera


May 16


32 de 46

Optional Configuration

vparSetCorrectionCoefficients

This function sets the distortion correction coefficients that will be applied to all the images before being analyzed.

The types of distortions that can be corrected are: tangential distortion (horizontal

and/or vertical perspective) and rotation. The specified coefficients will be applied to all the images until this function is called

again with different arguments of vparSetDistortionCorrectionOff is called.

void vparSetCorrectionCoefficients ( float fDistance,

float fVerticalCoeff,

float fHorizontalCoeff, float fAngle);

Arguments

fDistance Approximate distance between camera and object (in meters).

fVerticalCoeff Coefficient for correcting Vertical Perspective.

fHorizontalCoeff Coefficient for correcting Horizontal Perspective.

fAngle Angle for correcting Rotation.

Nuera


May 16


33 de 46

vparSetCorrectionCoefficientsEx

This function sets the distortion correction coefficients that will be applied to all the images before being analyzed.

The types of distortions that can be corrected are: tangential distortion (horizontal

and/or vertical perspective) and rotation. The specified coefficients will be applied to all the images until this function is called

again with different arguments of vparSetDistortionCorrectionOff is called.

void vparSetCorrectionCoefficients ( float fDistance,

float fVerticalCoeff,

float fHorizontalCoeff, float fAngle,

float fVerticalSkew, float fHorizontalSkew );

Arguments

fDistance Approximate distance between camera and object (in

meters).

fVerticalCoeff Coefficient for correcting Vertical Perspective.

fHorizontalCoeff Coefficient for correcting Horizontal Perspective.

fAngle Angle for correcting Rotation.

fVerticalCoeff Coefficient for correcting Vertical Skew.

fHorizontalCoeff Coefficient for correcting Horizontal Skew.

Nuera


May 16


34 de 46

vparSetDistortionCorrectionOff

This function deactivates the distortion correction pre-process.

Use vparSetCorrectionCoefficients to activate it again.

void vparSetDistortionCorrectionOff ();

Nuera


May 16


35 de 46

vparConfigureAutomaticCharacterHeight

This function configures the Automatic Character Height steps.

When vparInit is called with the argument lAvCharacterHeight set to -1, the automatic character height mode is selected. By default, the range of character

heights scanned in this mode is from 25 pixels to 60 pixels. By using this function, the user can select the heights that VPAR will scan.

long vparConfigureAutomaticCharacterHeight ( long lNumSteps, long * plSteps );

Arguments

lNumSteps Always 2. plSteps Array with the start of the interval in the first position and

the end of the interval in second position, e.g. 25, 45

Return Value

0 Error. 1 Ok.

Remarks

To recover the default configuration, the following code must be executed: long lSteps[2] = { 25, 60 };

vparConfigureAutomaticCharacterHeight (2, lSteps );

Nuera


May 16


36 de 46

vparSetRectangle

Sets the rectangle within the image where the inspection process will take place. Only the provided region will be inspected to look for a license plate.

This function can be used to speed up the process when the approximate position of

the license plate within the image is known.

long vparSetRectangle ( long lLeft, long lTop,

long lWidth, long lHeight );

Arguments

lLeft, lTop Left-top corner coordinates of the rectangle (in píxels). lWidth, lHeight Rectangle dimensions (in píxels).

Return Value

0 Error.

1 Ok.

Remarks

The inspection rectangle specified will be applied to all the further inspections until

vparSetRectangle is called again with different parameters. In order to inspect the whole image, vparSetRectangle must be called with all its parameters set to 0:

vparSetRectangle (0, 0, 0, 0);

By default, after library initialization with vparInit, the inspection rectangle is set to inspect the whole image.

Nuera


May 16


37 de 46

vpmrShadowKillerOn

Activates the pre-processing for dealing with shadows cast on the upper side of the

plates.

void vpmrShadowKillerOn ();

Nuera


May 16


38 de 46

vpmrShadowKillerOff

Deactivates the pre-processing for dealing with shadows cast on the upper side of the

plates. void vpmrShadowKillerOff ();

Nuera


May 16


39 de 46

vpmrStrictSyntaxOn

By calling this function, the format returned for custom plates (plates not following the

standard country's syntax) is 0. void vpmrStrictSyntaxOn ();

Nuera


May 16


40 de 46

vpmrStrictSyntaxOff

By calling this function, the format returned for custom plates (plates not following the

standard country's syntax) is the country's format (this is the default mode). void vpmrStrictSyntaxOff ();

Nuera


May 16


41 de 46

vpmrSetScaleFactor

Scales the image internally before processing it.

void vparSetScaleFactor ( float fScale );

Parámetros

fScale Scale factor. Width and height dimensions of the input image are multiplied by this factor.

Remark: The scaling takes place internally and therefore the configuration

parameters (character height, rectangle of interest, etc...) must relate to the original image. The results (average character height, rectangle, etc...) also relate to the

original dimensions of the image.

Nuera


May 16


42 de 46

vpmrReturnSpaces

By calling this function after vpmrInit the number plates recognized will be returned

including the spaces between characters. void vpmrReturnSpaces ();

Nuera


May 16


43 de 46

Storing Data into the HASP Dongle

vparWriteHASP Writes data into the internal memory of the HASP dongle. This capability for storing

data into the HASP can be used for any purpose. Data is encrypted automatically before being written into the HASP memory.

A maximum of 24 bytes can be written.

long vparWriteHASP ( unsigned char * pData,

long lSize );

Arguments

pData Buffer containing the data to be written in to the HASP

internal memory. lSize Size (in bytes) of the data to write (maximum 24 bytes).

Return Value

0 Error. 1 Ok.

Nuera


May 16


44 de 46

vparReadHASP

Reads the data stored in the internal memory of the HASP dongle. Data is automatically decrypted after being read from the HASP memory.

long vparReadHASP ( unsigned char * pData,

long lSize );

Arguments

pData Buffer where the retrieved data will be stored.

lSize Size (in bytes) of the data to read.

Return Value

0 Error.

1 Ok.

Nuera


May 16


45 de 46

Miscellaneous

vparComparePlates

Compares two number plates and produces a similarity measure.

The maximum length of the compared plates is 15 characters. Comparison is not case sensitive. Spaces are internally removed prior to comparison and not taken into

account. long vparComparePlates (char * pPlate1,char * pPlate2 );

Arguments

pPlate1 Buffer containing the first license plate string to be

compared

pPlate2 Buffer containing the second license plate string to be

compared

Return Value

Similarity score between 0 and 1000 (1000 meaning that both plates are identical). A negative value is returned if an error occurs.

Nuera


May 16


46 de 46

Example of Use

void func () {

bool ok;

// The characters in the images to process have about 30 pixels in height,

// there is no need to duplicate horizontal lines (all the scan lines are acquired) // and we want two-lines plates to be re-arranged to fit the spanish format.

ok = (bool) vparInit (LOC_CODE_ITA,30, false, true, false, false);

if (ok) {

unsigned char * buffer; // Image buffer. long numchars; // Number of characters read. char text[32]; // String where the result will be stored.

float Cf; // Confidence Factor of the reading result. float characterCf[32]; // Array to store the characters confidence factor.

// Buffer memory allocation. . . . // Acquire the image buffer in 256 grayscale levels (1 byte per pixel) and store it

// into buffer. . . .

// Image dimensions are 384x288 pixels. ok = (bool) vparRead (384, 288, buffer); if (ok)

{ vparGetText (text, 0);

Cf = vparGetGlobalConfidence (0); numchars = vparGetNumberOfCharacters (0);

for (long i = 0; i < numchars; i++) {

characterCf[i] = vparGetCharacterConfidence (i, 0);

} }

else { // Error reading license plate.

}

// Read more images. . . . // Finalize the software

vparEnd ();

} else

{

// Error initializing the VPAR. }

}

VPAR v - Neural Labs · Nuera NeuD VPAR v.7 DLL Reference Manual May 16 NEURAL LABS S.L. Carrer...

Documents

Transcript of VPAR v - Neural Labs · Nuera NeuD VPAR v.7 DLL Reference Manual May 16 NEURAL LABS S.L. Carrer...