Linux Development with the Carrida SDK

Guidelines for the Carrida 4 ANPR Engine

Revision: 1.2
Date: 2018-02-05
Contact: alpr.support@vision-components.com
Copyright: 1996-2018 Carrida Technologies GmbH, Ettlingen, Germany
Author: VC Support

Home page

Table of Contents

A list of abbreviations used throughout this document:

ARM
Stands for processors with the ARM instruction set.
ALPR
Automatic License Plate Reader.
dB
Decibel, in the Carrida documents used to describe a relative sensitivity (gain) value in cameras.
FOV
Field of view.
HW
Hardware.
LP
License Plate.
ms
Millisecond, one 1/1000 th of a second.
PC
Personal Computer.
px
Pixel. The smallest unit of resolution in an image. For example, VGA images are made up of 640x480 pixels.
ROI
Region of Interest, typically a marked area in an image.
SDK
Software Development Kit.
SW
Software.
x86
Stands for Processor Architectures with the Intel instruction set.
VC
Vision Components GmbH.
OSD
On-screen display
Image symbols used in this document
Symbol Meaning
Note Sign Points to especially important aspects of the manual or the software.
Hint Sign The Light bulb highlights hints and ideas that may be helpful.
Warning Sign This warning sign alerts of possible pitfalls to avoid. Please pay careful attention to sections marked with this sign.

1   Intended Audience

This technical note is aimed at Linux software developers who want to develop their own applications with the Carrida SDK on x86, X64, or ARM Linux systems, including SW development on the VC Carrida cam.

2   Introduction

The Carrida SDK is a collection of libraries and tools which are used for Automated Number Plate Recognition (ALPR). The software is designed to run under the Linux and Windows operating systems. Carrida is designed to be as hardware independent as possible.

Definition of some terms used throughout this document:

Carrida
The set of tools and libraries for number plate reading.
Carrida SDK
The shared libraries and include files which are necessary to build an application which uses Carrida.
Carrida engine
The set of functions and algorithms for reading the license plate information. The core functionality of Carrida.
classifier
The font and license plate information for a specific country/state. A classifier needs to be trained using image samples.

The following documents are directly related to Carrida 4 software development:

Carrida SDK
Description of the Carrida 4 API which is valid for Windows and Linux.
Carrida Parameters
Description of the Carrida initialisation parameters as stored in the Carrida .ini files (e.g. the lpr.ini file)

Carrida 4 is available for x86-32 (Windows only), x86-64 (Windows and Linux), and for ARM processor architectures as 32-bit version optimized for the ARMv7 architecture (from Cortex A8 CPUs upwards).

Note

Note Sign The ABI convention used on all ARM platforms is hardfloat.

The programming interface on all supported operating systems is identical, so that it is easy to port your application from Windows to Linux, or between different Linux systems.

The VC Nano Z camera, as well as the VC Pro Z camera are essentially complete Linux embedded computers. Software development on these cameras is practically identical to the Intel Linux systems on your PC. This document therefore makes no differentiation between VC Cameras, Intel Linux systems, or any other ARM board - only where necessary, the differences will be highlighted.

3   What you need for software development with Carrida

Starting development for a Carrida application is no different to SW development for other Linux applications. You need to have a standard Linux build system (GNU compilers and make) and several 3 rd party libraries installed. Most importantly Carrida 4 relies on

Note

Note Sign We recommend gstreamer 1.0 to read and save videos, and to process streaming video data from network cameras. As a somewhat less complex alternative, OpenCV also offers integrated functionality for video and network IO. Both frameworks can be built and installed on Windows, Linux, and many ARM based systems.

We recommend to use OpenCV 3.4 with the Carrida SDK.

3.1   The fplc tool

Carrida on Linux requires a software license activation. Licensing is done using the fplc tool, which is provided as part of this distribution. Details of the SW licensing procedure can be found in the Carrida Licensing user manual.

Note

Note Sign Carrida licenses are bound to a specific HW platform or board. For volume licensing please contact Vision Components GmbH.

4   Installation of the Carrida SDK

The following sections describe the installation procedure for the Carrida 4 SDK and the required 3 rd party support libraries:

For the installation of the Carrida 4 SDK first copy all files of the package to a temporary location, preferably /tmp.

If you do not yet have installed a Linux build system, you can install the basic GNU compiler suite and toolset with

sudo apt-get -y install build-essential cmake

Hint

Hint Sign If your Linux distribution uses RPM packages, you can use one of many the existing tools to convert the Debian dpkg files to rpm file format.

Then, with root privileges, run the Carrida setup script to install the Carrida 4 SDK, to see all available options use:

sudo ./install-carrida.sh  -h

The install script provides the following options:

install-carrida [-h -s sample_dir -u -v -d -f -g]
  -h ... print this help message
  -v ... be more verbose
  -u ... update the system before software installation
  -s ... set a new destination folder for samples
           (/usr/local/share/carrida/samples)
  -g ... install Gemalto Sentinel RT (default: no)
  -d ... install the documentation files (default: no)
  -f ... install external 3rd party libs (default: no)

We recommend to use -g, -d, -f, -v on the first invocation in order to install the required 3rd party libraries and also to install the Sentinel Software protection libraries and daemon.

The script tries to install the necessary support libraries and eventually installs the Carrida 4 library and include files. It can be used on x86, ARM, as well as on the VC Nano camera.

Note

Note Sign For Intel systems only:

As part of the Carrida installation process, the Sentinel software protection runtime environment will be installed on your system if the -g option is set. This is necessary in order to use Carrida in your application. If your system does not yet have the ia32 compatibility SW layer installed, it will be downloaded by the Sentinel installation script. After successful installation, the Sentinel license server daemon will be launched automatically.

On the VC Carrida cameras the external ffmpeg and OpenCV libraries will be installed from pre-compiled packages which come with the Carrida 4 distribution.

Hint

Hint Sign If you want to install or update only specific libraries, you can do this by running the dpkg command.

E.g.

sudo dpkg –i  liblprcarrdida-4.1.8-1_amd64.deb

4.1   The Carrida x86 and ARM Linux Distribution

The Carrida 4 engine for x86-32 and x86-64 is distributed as Debian package, e.g. the

liblprcarrdida-4.1.8-1_amd64.deb

file. This package contains the Carrida 4 shared object, the necessary Carrida 4 include files, HTML documentation, and sample source code files and Makefiles.

The country specific classifier files are distributed in their own package, e.g.:

carrida—nz_1.0_all.deb

The Carrida 4 package is installed at the following locations:

/usr/local/lib
liblprcarrida.so ... The Carrida 4 shared library
/usr/local/include/carrida

The Carrida 4 include files. You need to add this path to your compiler include path, e.g. for the GNU compiler:

-I /usr/local/include/carrida
/usr/local/share/carrida

This Carrida 4 installation package contains a classifier file world.dat and a default configuration file lpr.ini. Both files are copied to /usr/local/share/carrida.

Your application can read the files from this location, but you can also copy the files to a location of your choice. Make sure that your application loads the lpr.ini file from the correct path as specified in lpr.ini.

/usr/local/share/doc/carrida
Carrida 4 documentation in HTML format.
/usr/local/share/carrida/samples
Carrida 4 sample programs for C, C++, including Makefiles.

4.2   Carrida on the VC Nano Z/VC Pro Z camera

Typically the Carrida engine and a classifier for a country is pre-installed on the Carrida camera. You can find the Carrida classifier files and support libraries in the locations described in the previous sections. The only difference on the Carrida camera is that the classifier files have only one fixed name, regardless of the country or state which they represent.

The following classifier name is used:

/usr/local/share/classifier.dat

5   Developing applications with the Carrida SDK

The Linux API of the Carrida 4 engine is source code compatible with the Windows version. The sample programs are installed in

/usr/local/share/carrida/samples

This section details only the Linux specific build process, for a description of the full|car4| API, consult the Carrida programming manual.

The Carrida 4 Linux SDK comes with several sample programs and accompanying Makefiles, which can be used as starting points for C and C++ projects.

carrida_image.cpp
Demonstrates the basic use of the Carrida 4 SDK. It is best to start with this program.
carrida_overview.cpp
Demonstrates the basic use of the Carrida 4 SDK and functions. The code demonstrates how to read and modify parameters of Carrida operation during within an application.
lprcli.cpp
A more complete application, which can read images, or a folder of images.

In order to build an application with the Carrida SDK, you need to set the correct include path, and link your application module with the Carrida 4 shared library and the required support libraries:

Required system libraries :

  • boost_program_options (for the lprcli tool)
  • gomp, the OpenMP library
  • lprcarrida

Required include paths:

/usr/local/include/carrida

Required library paths:

/usr/local/lib

6   Using images within Carrida

The Carrida 4 SDK can read and write a few standard image formats, or it can accept raw image data (pure pixel data in memory).

The suported standard image formats for Carrida on Linux are
  • JPEG
  • PNG
  • BMP
  • TIFF

These image formats can be directly used with Carrida 4 function calls (see carrida_image.cpp example).

Note

Note Sign In order to use the Carrida image IO functins, the svcapture library must be installed. It is part of standard Carrida 4 installation package.

If you plan to use external standard video sources, we recommend to build and use OpenCV 3, gstreamer, or ffmpeg for this purpose. gstreamer for example allows you to read RTSP video network streams directly.

If you are fetching images from another source, e.g. a custom frame grabber, it is possible to use those images directly as raw data. Carrida 4 offers an interface function to import your pixel data. This interface looks as follows:

int image_width        = my_raw_image_width;
int image_height       = my_raw_image_height;
int image_step         = total_number_of_bytes_per_image_line;
char* image_data       = ptr_to_image_raw_data;
int num_channels       = 1;      // 3 for RGB  raw data
svPixelFormat pix_type = GRAY8;  // RGB24  for rgb raw data
image = svcapture::Image( image_width, image_height, image_step,
                          num_channels, image_data, pix_type );

The necessary functions and include files are located in the svcapture library and header files, which are part of the Carrida 4 installation. The documentation for svcapture can be found in the Carrida 4 SDK documentation.

7   Additional SW components and support files on the VC cameras

The installation on the Carrida camera always installs and activates the anprServer software. This server is responsible for the communication from the PC side with the Carrida camera. If the server is not needed, it can be disabled using the Linux systemctl mechanism. An example for this is given below.

7.1   Maintaining the anprServer on the VC Nano/VC Pro Z Cameras

The Carrida VC Nano and VC Pro Z cameras are pre-installed with a country classifier and also the ANPR server software. The ANPR server software component is responsible for communication over the network, it also acts as the default application on the camera when the camera is used as ANPR sensor for access control applications.

The ANPR server is installed in the folder

/root/anprServer

The sub-folder

/root/anprServer/data

contains a soft link to the actual classifier files which are located in

/usr/local/share/carrida

The ANPR Server is installed as standard Linux service, which can be started, and stopped using the systemctl command. The systemctl command is also used to permanently disable the server in case it is not needed.

Starting and stopping the ANPR Server as service on the camera is achieved using the commands:

systemctl start anprServer

and:

systemctl stop anprServer

To disable the Carrida ANPR Server permanently, use:

systemctl disable anprServer

To obtain information about the current status of the ANPR Server status, use:

systemctl status anprServer

In order to disable the ANPR Server service permanently on the camera use:

systemctl disable anprServer

Use:

systemctl enable anprServer

to permanently enable the ANPR Server again.

8   Default lpr.ini Configuration File

The following listing shows the default lpr.ini, which is installed in /usr/local/share/carrida. You can use this file as a starting point for your configuration.

[ANPR_ENGINE]

Mode = best
NumberCores = 2
Classifier =       /usr/share/carrida/world.dat
MinLetterHeight = 10
MaxLetterheight = 40
MaxPlateAngle = 20
MinCharactersToAccept = 4
MaxCharactersToAccept = 9
MinCharConfidence = 13
MinPlateConfidence = 50