Installation

Whether on Windows or Linux simply run the supplied installer for your chosen OS (mores notes below).
Papillon requires that a PAPILLON_INSTALL_DIR environment variable be set to the root installation directory (for example C:\Users\JohnDoe\Papillon-X.Y.Z on Windows or /opt/Papillon on Linux).
- On Windows this is done by the installer.
- On Linux, you need to add the appropriate command to one of your startup files
Documentation (HTML) can be found in /doc from your installation directory (usually C:\Users\JohnDoe\Papillon-X.Y.Z\doc on Windows or /opt/Papillon/doc on Linux).

Linux

Installers for several different versions of Linux are available. The installer relies upon some 3rd party libraries (mainly for the video stream plugins) and the package managers will try and install these as well, if they are not already on the system.

Ubuntu 16.04 / Debian 8 and 9

To use Papillon you will need a build environment on your machine.

apt-get -y install build-essential doxygen cmake

The Papillon video plugins rely upon open source video codecs which need to be on your machine. These include gstreamer, ffmpeg and vlc. These can be installed with the following commands.

apt-get -y install gstreamer1.0-plugins-base \
                   gstreamer1.0-plugins-good \
                   libgstreamer1.0-dev \
                   libgstreamer-plugins-base1.0-dev \
                   vlc \
                   libvlc-dev \
                   libavcodec-dev \
                   libavdevice-dev \
                   libavfilter-dev \
                   libavformat-dev \
                   libavutil-dev \
                   ffmpeg

You will also have to install the following modules (if you do not already have them)

sudo apt-get -y install python-dev \
                        python-numpy \
                        python3-dev \
                        python3-numpy \
                        libjpeg-dev \
                        libpng-dev \
                        libtiff-dev \
                        libjasper-dev \
                        libatlas-base-dev \
                        libatlas-dev \
                        libpq-dev \
                        swig \
                        postgresql

Finally to install Papillon

sudo dpkg -i Papillon-X.Y.Z-Linux.deb

Ubuntu 14.04

To use Papillon you will need a build environment on your machine.

apt-get -y install build-essential doxygen cmake

The Papillon video plugins rely upon open source video codecs which need to be on your machine. These include gstreamer and ffmpeg. These can be installed with the following commands.

sudo apt-add-repository ppa:mc3man/trusty-media
sudo apt-get update
sudo apt-get install ffmpeg gstreamer0.10-ffmpeg

You will also have to install the following modules (if you do not already have them)

sudo apt-get install libtbb-dev libatlas3-base postgresql

Post Installation

Papillon will be installed in /opt/Papillon. You will need to set the following environment variables (example for bash shown).

export PAPILLON_INSTALL_DIR=/opt/Papillon

export LD_LIBRARY_PATH=/opt/Papillon/lib

Windows

Before you begin installation of Papillon you may need to set up a C++ compiler. There are several ways to do this, one option is to:

Install Visual Studio
- The Community Edition is sufficient and can be found at https://www.visualstudio.com/en-us/products/visual-studio-community-vs.aspx
- You may need to install IE10 before Visual Studio installation can complete
- The default Visual Studio installation does not include a C++ compiler. Make sure you select a custom installation and the tick the box marked Programming Languages/Visual C++
Install the latest version of CMake from http://cmake.org
- Make sure the CMake /bin directory is in your PATH environment variable

Compiling the Examples

The easiest way to compile the examples is to use CMake. If you do not have it already installed on your system you can get it from http://www.cmake.org/download. Platform specific instructions are below.

Windows

WARNING about CMake installation: if CMake gives you an error saying it cannot set the path (e.g. when the path is too long), you need to manually add the cmake path to the environment variable.

Then open a command-line prompt and type the following commands

mkdir %PAPILLON_INSTALL_DIR%\build
cd %PAPILLON_INSTALL_DIR%\build
cmake ..\examples

This will create a PAPILLON_INSTALL_DIR%\build\PapillonExamples.sln solution file which you can open in your MS Visual Studio.

Notes: You may need to specify your compiler. For this you can use -G option:

Visual Studio Version	Command Line to generate Visual Studio solution (from \build folder)
Visual Studio 2010, 64-bit compilation	`cmake -G "Visual Studio 10 Win64"..\examples`
Visual Studio 2012, 64-bit compilation	`cmake -G "Visual Studio 11 Win64"..\examples`
Visual Studio 2013, 64-bit compilation	`cmake -G "Visual Studio 12 Win64"..\examples`
Visual Studio 2015, 64-bit compilation	`cmake -G "Visual Studio 14 Win64"..\examples`
Visual Studio 2017, 64-bit compilation	`cmake -G "Visual Studio 15 Win64"..\examples`

Although cmake will look for your system compiler and use a sensible default. Alternatively, you can use cmake –build . on the console.

Linux

By default Papillon is installed as root user in /opt/Papillon.

You should have PAPILLON_INSTALL_DIR and LD_LIBRARY_PATH set in your environment:

export PAPILLON_INSTALL_DIR=/opt/Papillon

export LD_LIBRARY_PATH=/opt/Papillon/lib

To compile the examples run the following commands as the user:

cd ~ && mkdir Papillon && cd Papillon
cmake /opt/Papillon/examples
make

This will generate a set of binaries in ~/Papillon/bin.

Command Line Tools

In the examples folder there are also three command-line tools for performing common detector and face-recognition tasks, PapillonEnrollment, PapillonIdentification and PapillonVerification. These will get built along with the examples. Pre-compiled versions of these tools are also supplied in the $PAPILLON_INSTALL_DIR/bin directory. Extensive information on using these tools can be found in the main documentation.

Writing your own Programs

If you want to write your own programs using Papillon you can use CMake and use our examples as a guideline. Alternatively, you can just follow the basic steps outlined below.

Add include <PapillonCore.h> to your C++ code
On Windows 64 bit:
- Add PAPILLON_INSTALL_DIR\%\include\PapillonCore to your include path
- Add PAPILLON_INSTALL_DIR\%\lib to the library path in your linker settings
- Add the library PapillonCore to your linker
On Linux 64 bit:
- Add -I$PAPILLON_INSTALL_DIR/include/PapillonCore to your include path
- Add -L$PAPILLON_INSTALL_DIR/lib -lPapillonCore -Wl,-rpath,$PAPILLON_INSTALL_DIR/lib to your linker settings

Below is the traditional 'Hello World' example.

#include<PapillonCore.h>
int main()
{
    using namespace papillon;
    PapillonSDK::Initialise().OrDie();
    PImage image;
    image.Load("hello.jpg").OrDie();
    image.Display("Papillon SDK - Hello world...", papillon::WAIT_FOR_RETURN);
    PapillonSDK::Finalise();
    return 0;
}

Note for Windows users: the SDK is compatible with VS2010, VS2012, VS2013, VS2015 and VS2017 using the same binaries (lib and dll).

Example for Linux users: to compile an executable from a single source file (e.g. Basic image processing (load, save, convert and resize images)), you would use the following command line:

g++ -I$PAPILLON_INSTALL_DIR/include/PapillonCore -o ExampleCoreImage $PAPILLON_INSTALL_DIR/examples/ExampleCoreImage.cpp\

-L$PAPILLON_INSTALL_DIR/lib -lPapillonCore -Wl,-rpath,$PAPILLON_INSTALL_DIR/lib