Linux Development with the CARRIDA SDK

Home page

1   Guidelines for the CARRIDA ANPR Engine

Revision:4.9.1
Date:2022-09-22
Contact:support@carrida-technologies.com
Copyright:2018-2023 CARRIDA Technologies GmbH, Ettlingen, Germany
Author:CARRIDA Support

1.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.


1.2   Introduction

The CARRIDA SDK is a collection of libraries and tools used for Automated Number Plate Recognition (ANPR). 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 software development:

CARRIDA SDK
Description of the CARRIDA 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 is available for 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 32-bit 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.


1.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 relies on

  • GNU compiler suite (g++ >= 4.9)
  • make
  • boost
  • OpenCV >= 4.5 (optional, but recommended)

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 >=4.5 with the CARRIDA SDK.


1.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 |car| 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.


1.4   Installation of the CARRIDA SDK

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

For the installation of the CARRIDA 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 SDK. The script tries to install the necessary support libraries and eventually installs the CARRIDA library and include files. It can be used on x86 and ARM. To see all available options use:

sudo ./install-|car|.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/|car|/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 |car| ANPR Server (default: no)
 -w ... install |car| 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.


1.4.1   The CARRIDA x86_64 and ARM Linux Distribution

The CARRIDA engine for x86-64 is distributed as Debian package. This package contains the CARRIDA shared object, the necessary CARRIDA 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 package is installed at the following locations:

/usr/local/lib
liblprcarrida.so ... The CARRIDA shared library
/usr/local/include/CARRIDA

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

-I /usr/local/include/|car|
/usr/local/share/CARRIDA

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

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 documentation in HTML format.
/usr/local/share/CARRIDA/samples
CARRIDA sample programs for C, C++, including Makefiles.

1.5   Developing applications with the CARRIDA SDK

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

|
/usr/local/share/|car|/samples

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

The CARRIDA 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 SDK. It is best to start with this program.
carrida_overview.cpp
Demonstrates the basic use of the CARRIDA 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 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

1.6   Using images within CARRIDA

The CARRIDA 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
  • RAW pixels (images stored in memory as byte data)

These image formats can be directly used with CARRIDA 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 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 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 installation. The documentation for svcapture can be found in the CARRIDA SDK documentation.