Plumerai People Detection library for Arm Cortex-A¶

This document describes how to use the C and C++ library for the Plumerai People Detection software for videos on Arm Cortex-A. For documentation about the API and an example, please see here for C++, here for C and here for Python. 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

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/

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

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

The final binary size for a minimal example with the Plumerai People Detection library should be around 3MB for an ARMv7 device. By using strip example it can be further reduced to 2.4MB.

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 Intel or AMD CPU on Linux or macOS (x86) respectively. Note however that this is not optimized for speed and only made available to be able to try out the API or to do qualitative evaluation on a regular laptop or desktop computer.

2. There is a arm64-macos version for more recent Apple computers with macOS and Arm CPUs, such as the M1 or M2. Similar to the x86 versions above, this is only made available to be able to try out the API or to do qualitative evaluation on a regular laptop or desktop computer.

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

Expected latency¶

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