Linux Development with the Carrida SDK

Guidelines for the Carrida 4 ANPR Engine

Revision: 1.3
Date: 2018-03-02
Contact: support@carrida-technologies.com
Copyright: 1996-2018 Carrida Technologies GmbH, Ettlingen, Germany
Author: CT Support

Home page

Table of Contents

A list of abbreviations used throughout this document:

ARM64
Stands for processors with the v8 AARCH 64-bit instruction set.
ARM
Stands for processors with the v7 ARM 32-bit instruction set.
ALPR
Automatic License Plate Reader.
dB
Decibel, in the Carrida documents used to describe a relative sensitivity (gain) value in cameras.
fps
Frames per second.
FOV
Field of view.
HW
Hardware.
LP
License Plate.
mA
Milli-Ampere, one 1/1000 th of an ampere.
ms
Millisecond, one 1/1000 th of a second.
PC
Personal Computer.
PK
Product Key (for software licensing).
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. 32-bit hardware.
x86_64
Stands for Processor Architectures with the Intel instruction set. 64-bit hardware.
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 lightbulb highlights the hints and the 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 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 included files which are necessary to build an application that 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, optimized for the 32-bit ARMv7 architecture (from Cortex A8 CPUs upwards), and for the 64-bit ARM64 architecture.

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 platform - 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 a 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 ARM hardware platform. For volume licensing please contact Carrida 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 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. 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. 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 ... do NOT install external 3rd party libs (default: yes)
 -a ... install Carrida ANPR Server (default: no)
 -w ... install Carrida ANPR service for this user - default: 'who am i'
 -o ... perform online installation (default: no)

On Intel Linux systems we recommend to use options -g, -d, -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.

On ARM Linux systems we recommend to use options -d, -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.

Note

Note Sign For Intel systems only:

As a 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 installed by the Sentinel installation script. After successful installation, the Sentinel license server daemon will be launched automatically.

After installing the Sentinel runtime system, the Carrida dynamic library haspvlib_109654.so is copied to the /var/hasplm folder. In case of licensing errors, check if this library has been copied correctly.

4.1   The Carrida x86_64 and ARM Linux Distribution

The Carrida 4 engine for x86-32 and x86-64 is distributed as Debian package. 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 packages, 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 Carrida 4 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

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 functions, 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 included files are located in the svcapture library and header files, which are a 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 an 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.