PWatchlist Class Reference

Detailed Description

The PWatchlist class represents a collection of PDescription typically used to detect a face from a list ok known people in Face Recognition; thread-safe.

Using its Search function, given a probe PDescription you can return a ranked list of known IDs (PIdentifyResults) along with a confidence score of them being the same identity as the probe PDescription. You need to supply a PCompare function which is used to match the descriptions during the search.

Multiple analytics modules (e.g. FaceLog) can use the same watchlist at the same time.

dot_inline_dotgraph_15.png

Definition at line 114 of file PWatchlist.h.

#include <PWatchlist.h>

Constructor & Destructor Documentation

◆ PWatchlist() [1/2]

PWatchlist::PWatchlist ( )

Constructs an empty collection of descriptions.

◆ PWatchlist() [2/2]

PWatchlist::PWatchlist ( const PWatchlist other)

Constructs a shared copy of other.

◆ ~PWatchlist()

virtual PWatchlist::~PWatchlist ( )
virtual

Destroys this object.

Member Function Documentation

◆ Add()

PResult PWatchlist::Add ( const PDescription d)

Adds the specified description to this collection.

Returns an error if there is already a description with the same id. Returns PResult::C_OK if success, another result otherwise.

See also
Update()
Remove()

◆ BatchSearch()

PResult PWatchlist::BatchSearch ( const PList unknowns,
const PComparer comparer,
papillon::int32  topN,
float  threshold,
PList results 
) const

Searches for the specified unknown descriptions in this watchlist and attempts to make them known.

The unknown descriptions are compared with each subject present in this watchlist; the N best results (topN) with a match score greater or equal to the specified threshold are returned in the specified PIdentifyResults object.

  • 'unknowns' is a list of PDescription objects, each one representing a subject to identify
  • 'topN' parameter should typically be in the range: 1 .. NUMBER_OF_SUBJECTS_IN_THE_WATCHLIST
  • 'threshold' parameter should typically be in the range: 0 .. 1
  • 'results' (output) is a list of PIdentifyResults objects representing the results of identification. There is 1 PIdentifyResults for each input PDescription; results are stored in the same order than input data. The 'results' list is first cleared.

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

◆ Clear()

void PWatchlist::Clear ( )

Removes all the descriptions stored in this collection.

◆ FindIdentityIdsByName()

PList PWatchlist::FindIdentityIdsByName ( const PString name,
PString::ECaseSensitivity  caseSensitivity = PString::E_CASE_SENSITIVE 
) const

Gets all the objects id held in the watchlist with the specified name (see PDescription::GetName()) A same name can be used for several descriptions.

◆ GetAllDescribeId()

PResult PWatchlist::GetAllDescribeId ( PList  ids)

Returns the list of all describe-ids used in this watchlist.

See also
PDescriber::GetDescribeId()

◆ GetAllDescriptions()

PList PWatchlist::GetAllDescriptions ( ) const

Returns all descriptions contained in this watchlist.

◆ GetDescription()

PResult PWatchlist::GetDescription ( const PGuid objectId,
PDescription description 
) const

Gets a description from the watchlist from its id.

◆ GetId()

PGuid PWatchlist::GetId ( ) const

Returns the global identifier associated with this collection.

◆ GetIdentityIds()

PList PWatchlist::GetIdentityIds ( ) const

Gets all the objects id held in the watchlist.

◆ GetNumberOfDescriptors() [1/2]

papillon::int32 PWatchlist::GetNumberOfDescriptors ( ) const

Returns the number of descriptors contained in this watchlist (each description contained in a watchlist can have several PDescriptor objects).

◆ GetNumberOfDescriptors() [2/2]

papillon::int32 PWatchlist::GetNumberOfDescriptors ( const PGuid describerId) const

Returns the number of descriptors computed by the specified describer engine (describerId), contained in this watchlist.

◆ GetSearchStats()

void PWatchlist::GetSearchStats ( papillon::int32 &  count,
papillon::int64 &  sumTopN,
double &  totalTimeMs 
)

Gets some statistics about Search().

◆ Has()

bool PWatchlist::Has ( const PGuid objectId) const

Returns true if this watchlist has a description with the specified id, false otherwise.

◆ InvalidateSearchCache()

void PWatchlist::InvalidateSearchCache ( )

Invalidate the cache used by Search() for fast searching; the cache will be automatically rebuilt on next call to Search().

◆ IsCompatibleWith()

bool PWatchlist::IsCompatibleWith ( const PGuid describeId) const

Returns true if this watchlist is compatible with the specified engine (describeId, see PDescriber), false otherwise.

A watchlist is compatible if at least 1 description can be compared with another description coming from the specified engine, i.e. there is at least one descriptor with describe-id (see PDescriptor::GetDescribeId()) equal to the specified describeId input parameter.

◆ IsEmpty()

bool PWatchlist::IsEmpty ( ) const

Returns true if this watchlist is empty, false otherwise.

◆ operator=()

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

Performs a shared copy of other to this object.

◆ ReadDescriptionFromFileIncrementaly()

static PResult PWatchlist::ReadDescriptionFromFileIncrementaly ( const PString filename,
PFileStream file,
int &  numberOfSubjects 
)
static

Opens a watchlist file for incremental reading.

This method will return the number of subjects in the watchlist and the file object to be used to read descriptions. Returns PResult::C_OK if success, another result otherwise.

See also
ReadNextDescriptionFromFile()

◆ ReadFromFile()

static PResult PWatchlist::ReadFromFile ( const PString filename,
PWatchlist watchlist 
)
static

Reads a PWatchlist from a binary file on disk.

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

See also
ReadFromStore()
PFileIO::ReadFromFile()

◆ ReadFromStore()

static PResult PWatchlist::ReadFromStore ( const PStore store,
PWatchlist watchlist 
)
static

DEPRECATED, should not be used.

Reads a PWatchlist from a PStore object. Returns PResult::C_OK if success, another result otherwise.

See also
ReadFromFile()

◆ ReadNextDescriptionFromFile()

static PResult PWatchlist::ReadNextDescriptionFromFile ( PFileStream file,
PDescription description 
)
static

Reads the next description from the specified watchlist file (assumes ReadDescriptionFromFileIncrementaly() has been called before).

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

See also
ReadDescriptionFromFileIncrementaly()

◆ RecomputeDescriptors()

papillon::int32 PWatchlist::RecomputeDescriptors ( const PGuid describeId,
const PDetector detector,
const PDescriber describer 
)

Recomputes the descriptors (PDescriptor) computed with the specified describeId (PDescriber) using the specified PDetector and PDescriber.

Descriptors must contain images (stored under the name "Thumbnail" in the PProperties container attached with each descriptor). Returns the number of upgraded descriptors.

◆ Remove()

PResult PWatchlist::Remove ( const PGuid objectId)

Removes a specific description from the watchlist from its id.

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

See also
Add()
Update()

◆ Search() [1/2]

PResult PWatchlist::Search ( const PDescription unknown,
const PComparer compare,
PIdentifyResults results,
papillon::int32  topN,
float  threshold,
bool  scoreNormalisation = false 
) const

DEPRECARED.

Searches for the specified unknown description in the watchlist and attempts to make it known. Returns PResult::C_OK if success, another result otherwise.

See also
Search() with PWatchlistOptions

◆ Search() [2/2]

PResult PWatchlist::Search ( const PDescription unknown,
const PComparer comparer,
const PWatchlistOptions options,
PIdentifyResults results 
) const

Searches for the specified unknown description in the watchlist and attempts to make it known.

Last argument 'results' which is the list of results, will be first cleared.

Warning: when using PWatchlistOptions to configure this Search algorithm, 'threshold' parameter has higher priority than 'topN' parameter, so the algorithm will first filter by threshold and then return the topN of what is left.

WARNING: from Papillon 4.5.0 and higher, PResult::C_OK is returned even is there is no match (this is to be consistent with other methods in the SDK). The PResult object returned by this method is just an indicator of a major failure in the algorithm. Previously, the algorithm was returning PResult::C_FALSE if no match (which is wrong because there was no associated error message).

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

◆ SetAynchronousUpdater()

void PWatchlist::SetAynchronousUpdater ( PIAsynchronousWatchlistUpdater updater,
papillon::int32  maxChangesPerSecond = 10000 
)

Sets asynchronous updater.

You have to write a class implementing PIAsynchronousWatchlistUpdater (must be thread-safe). To remove 'updater', call this method with updater argument set to NULL.

◆ SetNormalisationDistributions()

PResult PWatchlist::SetNormalisationDistributions ( double  meanScorePositive,
double  meanScoreNegative,
double  sigmaScorePositive,
double  sigmaScoreNegative 
)

Sets the distributions used for score normalisation when doing watchlist searches (when normalisation is activated).

◆ Size()

papillon::int32 PWatchlist::Size ( ) const

Returns the number of descriptions contained in this watchlist.

When used for FaceRecognition, Size() returns the number of subjects held in the watchlist.

◆ Update()

PResult PWatchlist::Update ( const PDescription d)

Adds the specified description to this collection.

If a description with the same id already exists, then merges the two descriptions (see details below).

When two descriptions A (description already in the watchlist) and B (input parameter of this method) are merged:

  1. The new description will have the name of A
  2. Object types must be the same, otherwise an error is returned
  3. Identity ids are the same
  4. List of descriptors are merged: new list of A = list of A concat with list of B
  5. The new description will have the additional properties of A (properties of B are ignored)

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

See also
Add()
Remove()

◆ WriteToFile()

PResult PWatchlist::WriteToFile ( const PString filename)

Writes this watchlist to file as binary data.

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

See also
WriteToStore()
PFileIO::WriteToFile()

◆ WriteToStore()

PResult PWatchlist::WriteToStore ( PStore  store)

DEPRECATED, should not be used.

Writes this watchlist to the specified PStore object. Returns PResult::C_OK if success, another result otherwise.

See also
WriteToFile()

Friends And Related Function Documentation

◆ PWatchlistImpl

friend class PWatchlistImpl
friend

Definition at line 370 of file PWatchlist.h.