PDescriber Class Reference

Detailed Description

The PDescriber class is the parent class for all describer algorithms which turns an object detected in an image coming from a detector (PDetector) into a description (PDescription);.

It can be used to generate a biometric template (a binary model) from a face used to perform Face Recognition. Another example: it can also be used to identify gender from a face, see example below.

Example: the following example create a "Face Metadata Describer" to extract gender information (male or female) on faces detected in video streams:

/*
* Copyright (C) 2015-2018 Digital Barriers plc. All rights reserved.
* Contact: http://www.digitalbarriers.com/
*
* This file is part of the Papillon SDK.
*
* You can't use, modify or distribute any part of this file without
* the explicit written agreements of Digital Barriers.
*/
#include <PapillonCore.h>
USING_NAMESPACE_PAPILLON
const PString SAMPLE_DIR = PPath::Join(PUtils::GetEnv("PAPILLON_INSTALL_DIR"), "Data", "Samples"); // path to find sample data: $PAPILLON_INSTALL_DIR/Data/Samples
static void RunDemo()
{
// ************************************************************************
// 1. Open Video Stream
// ************************************************************************
if (PInputVideoStream::Open("device:0", ivs).Failed()) // failed to use webcam, try to use a sample video instead...
PInputVideoStream::Open(PPath::Join(SAMPLE_DIR, "face_log.avi"), ivs).OrDie();
// ************************************************************************
// 2. Create and configure Face Detector
// ************************************************************************
PDetector faceDetector;
PDetector::Create("FaceDetector2", PProperties(), faceDetector).OrDie();
faceDetector.EnableLocaliser(true); // enable localiser (detect feature points on faces); required to use "DesciberDnn" in section 3.
// ************************************************************************
// 3. Create Face Metadata Describer to get gender classification
// ************************************************************************
PDescriber faceMetaDataDescriber;
PProperties genderDnnParameters = PProperties::CreateFromKeyValueString("type=Gender;gpuId=-1"); // use gpuId=-1 to disable GPU (use CPU only)
// gpuId=0 to use 1st GPU if available
// gpuId=1 to use 2nd GPU if available ...
PDescriber::Create("DescriberDnn", genderDnnParameters, faceMetaDataDescriber).OrDie();
// ************************************************************************
// 4. Display "Male" or "Female" for each detected face in the video stream
// ************************************************************************
PDetectionList listFaces;
PFrame frame;
while (ivs.GetFrame(frame).Ok() && !PUtils::IsEscPressed())
{
if (faceDetector.Detect(frame, listFaces).Failed())
continue;
// for each detected face, compute a description and extract metadata (e.g. "Male" or "Female")
for (int32 i=0, ni=listFaces.Size(); i<ni; ++i)
{
const PDetection& face = listFaces.Get(i);
PDescription description;
if (faceMetaDataDescriber.Describe(face, description).Failed())
continue;
PFaceMetaData faceMetaData = PFaceMetaData::FromDescription(description);
}
frame.Display("Papillon SDK - Face MetaData Classifier");
}
}
int main()
{
RunDemo();
return 0;
}

Definition at line 62 of file PDescriber.h.

#include <PDescriber.h>

Constructor & Destructor Documentation

◆ PDescriber() [1/3]

PDescriber::PDescriber ( )

Constructs a null describer (do nothing); use PDescriber::Create() factory to instantiate a detector.

◆ PDescriber() [2/3]

PDescriber::PDescriber ( PDescriberInterface describerInterface)

Constructs a PDescriber by wrapping a describer specified from a PDescriberInterface.

The memory management is delegated to the wrapper, i.e. the PDescriberInterface will be deleted when the PDescriber object will be deleted.

◆ PDescriber() [3/3]

PDescriber::PDescriber ( const PDescriber other)

Constructs a shared copy of other.

◆ ~PDescriber()

virtual PDescriber::~PDescriber ( )
virtual

Destroys this object.

Member Function Documentation

◆ Create() [1/2]

static PResult PDescriber::Create ( const PString productName,
const PProperties parameters,
PDescriber describer 
)
static

Factory: creates a PDescriber from the specified plugin and parameters (factory).

Returns PResult::C_OK if success, another result otherwise.

◆ Create() [2/2]

static PResult PDescriber::Create ( const PPlugin plugin,
const PProperties parameters,
PDescriber describer 
)
static

Factory: creates a PDescriber from the specified plugin and parameters (factory).

Returns PResult::C_OK if success, another result otherwise.

◆ Describe() [1/3]

PResult PDescriber::Describe ( const PExampleSet exampleSet,
PDescription outputDescription 
) const

Applies this describer on the specified set of examples and retrieve a description if the quality of the input data is high enough.

Note: outputDescription name and id are copied from exampleSet.

If any error occurs, then outputDescription is reset (see PDescription::Reset()).

Returns PResult::C_OK if success, another result otherwise (e.g. bad quality of data, no detection, etc.).

◆ Describe() [2/3]

PResult PDescriber::Describe ( const PDetection example,
const PString name,
const PGuid identityId,
PDescription description 
) const

Applies this describer on a single detection and retrieve a description if the quality of the input data is high enough.

Note: outputDescription name and id are specified by "name" and "identityId".

If any error occurs, then outputDescription is reset (see PDescription::Reset()). Returns PResult::C_OK if success, another result otherwise (e.g. bad quality of data, no detection, etc.).

◆ Describe() [3/3]

PResult PDescriber::Describe ( const PDetection detection,
PDescription description 
) const

Applies this describer on a single detection and retrieve a description if the quality of the input data is high enough.

Note: As a name or identity are not given a unknown id and name will be assigned.

If any error occurs, then outputDescription is reset (see PDescription::Reset()). Returns PResult::C_OK if success, another result otherwise (e.g. bad quality of data, no detection, etc.).

◆ DescribeBatch()

PResult PDescriber::DescribeBatch ( const PDetectionList batchDetections,
PDescriptionList batchDescription 
) const

Applies this describer on the specified set of PDetection's and retrieve a description if the quality of the input data is high enough.

If any error occurs, then outputDescription is reset (see PDescription::Reset()).

Returns PResult::C_OK if success, another result otherwise (e.g. bad quality of data, no detection, etc.).

◆ GetDescribeId()

PGuid PDescriber::GetDescribeId ( ) const

Returns the describe id, i.e.

the id of the algorithm and/or model, of this describer.

◆ GetModelName()

PString PDescriber::GetModelName ( ) const

Returns the name of the underlying model if it exists or an empty string otherwise.

◆ GetObjectType()

PObjectType PDescriber::GetObjectType ( ) const

Returns the object type that this describer describes, e.g.

PObjectType::E_FACE.

◆ operator=()

PDescriber& PDescriber::operator= ( const PDescriber other)

Performs a shared copy of other to this object.

Member Data Documentation

◆ C_PARAM_BOOL_DESCRIPTOR_THUMBNAIL

const PString PDescriber::C_PARAM_BOOL_DESCRIPTOR_THUMBNAIL
static

Definition at line 69 of file PDescriber.h.

◆ C_PARAM_FLOAT_FACE_THRESHOLD

const PString PDescriber::C_PARAM_FLOAT_FACE_THRESHOLD
static

Definition at line 67 of file PDescriber.h.

◆ C_PARAM_FLOAT_POINT_THRESHOLD

const PString PDescriber::C_PARAM_FLOAT_POINT_THRESHOLD
static

Definition at line 66 of file PDescriber.h.

◆ C_PARAM_INT_MEAN_FACE

const PString PDescriber::C_PARAM_INT_MEAN_FACE
static

Definition at line 68 of file PDescriber.h.

◆ C_PARAM_INT_VALID_POINTS

const PString PDescriber::C_PARAM_INT_VALID_POINTS
static

Definition at line 65 of file PDescriber.h.