Plumerai People Detection library
for Arm Cortex-A and x86¶

This document describes how to use the C and C++ library for the Plumerai People Detection software for videos on Arm Cortex-A and x86. For documentation about the API and a basic example, please see here for C++, here for C, here for Python, and here for Java (using JNI). For more examples, see the examples page that illustrates how easy it is to use the API to build applications. Go here for more information about the Plumerai People Detection solution and to try it out yourself.

Overview¶

The Plumerai People Detection software expects a video feed and computes bounding boxes with a confidence value, for each person that is detected. The software assumes that the camera does not move. For the best results we recommend mounting the camera to a fixed position. The software works for any input resolution, but a higher resolution is always preferred and leads to higher accuracy. Although there is a small latency overhead the extra accuracy is usually worth it. The software works for any aspect ratio, but for best accuracy we recommend an aspect ratio between 16:9 and 9:16.

Contents of the package¶

The library package consists of the following files inside a plumeraipeopledetection.zip archive:

plumeraipeopledetection/include/plumerai/box_prediction.h
plumeraipeopledetection/include/plumerai/people_detection.h
plumeraipeopledetection/include/plumerai/people_detection_c.h
plumeraipeopledetection/lib/{target}/libplumeraipeopledetection.{a,so,dylib}
plumeraipeopledetection/python/plumerai_people_detection-{target}.whl
plumeraipeopledetection/README.md
plumeraipeopledetection/VERSION

Multiple {target} options are available for x86 and Arm. For the Arm targets we also include files libgcc.a, libstdc++.a and libstdc++.so.6.0.24, which could be needed on older systems, see below.

They can be unzipped to a folder of your choice, which is referred to as $PLUMERAI_DIR below. For example:

unzip plumeraipeopledetection.zip -d /opt/
export PLUMERAI_DIR=/opt/plumeraipeopledetection/

To install the Python API, see below.

Building and linking¶

Follow these steps to build and link your application with the Plumerai library (example applications can be found here for C++ and here for C):

• Link to the Plumerai library, e.g. $PLUMERAI_DIR/lib/{target}/libplumeraipeopledetection.a.
• Add $PLUMERAI_DIR/include to the include path, e.g. -I$PLUMERAI_DIR/include.

Here's how an example C++ application can be built and linked:

g++ -std=c++11 example.cc $PLUMERAI_DIR/lib/arm-linux-gnueabihf/libplumeraipeopledetection.a -I$PLUMERAI_DIR/include -lpthread -ldl -o example

And similarly for C:

gcc -std=c99 example.c $PLUMERAI_DIR/lib/arm-linux-gnueabihf/libplumeraipeopledetection.a -I$PLUMERAI_DIR/include -lstdc++ -lm -lpthread -ldl -o example

There are different versions of the library for different targets:

1. There are x86_64-linux-gnu and x86_64-macos versions which can be used with a normal 64-bit Intel or AMD CPU on Linux or x86-64 macOS respectively (see below for arm64 macOS).

2. There is a arm64-macos version for more recent Apple computers with macOS and Arm CPUs, such as the M1 or M2.

3. There is a aarch64-linux-gnu version for use on Cortex-A (or similar) Arm devices with a 64-bit CPU and OS. See below for instructions for systems with old versions of the C++ standard library.

4. There are arm-linux-gnueabi (compiled with -mfloat-abi=softfp) and arm-linux-gnueabihf (compiled with -mfloat-abi=hard) versions for the AArch32 target, for use on Arm devices with a 32-bit CPU and OS. See below for instructions for systems with old versions of the C++ standard library.

Dependency: glibc¶

The library has been linked with GLIBC 2.19 which is the minimum required version to run our software. This is the version of C library that comes with GCC 4.9.4 by default.

Dependency: libstdc++ and libgcc¶

The library requires libstdc++.so.6.0.24 (or newer) and libgcc which come with GCC 7.2 (or newer). For systems with an older version of libstdc++ or libgcc, we provided copies of libstdc++ and libgcc in our release. We recommend linking to them statically, by adding their path to the linking command, for example:

LIB_DIR=$PLUMERAI_DIR/lib/arm-linux-gnueabihf
gcc -std=c99 example.c $LIB_DIR/libplumeraipeopledetection.a $LIB_DIR/libstdc++.a $LIB_DIR/libgcc.a -I$PLUMERAI_DIR/include -lm -lpthread -ldl -o example

It is possible to link with the libstdc++ library dynamically instead of statically, although this increases the total binary size. In this case, make sure the rpath property of the final executable or the LD_LIBRARY_PATH environment variable is set correctly so that the loader finds the newer libstdc++.so before the default system library. Note that libgcc does not allow for dynamic linking.

In case dynamic linking with libplumeraipeopledetection.so is preferred, then libstdc++.so must also be linked dynamically.

Installing Python wrapper¶

The Python wrapper for Linux and macOS can be installed for Python 3.8 or newer using:

pip install --no-index --find-links $PLUMERAI_DIR/python/ plumerai_people_detection

We provide pre-built wheels for Arm and x86 for Python 3.8, 3.9, 3.10, and 3.11. If you have different requirements, please contact Plumerai.

An API description along with a Python example can be found here.

Expected latency¶

Below is a table with expected latency numbers for some example Arm CPUs and input resolutions¹: