PWatchlist2 Class Reference

Detailed Description

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

The PWatchlist2 class has been designed to handle huge watchlist, up to several millions of subjects. PWatchlist2 is a persistent object; it relies on a database backend and has an automatic audit trail.

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.

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

IMPORTANT: if you are using old PWatchlist class, you should switch to PWatchlist2 which is faster and has more features.

Definition at line 54 of file PWatchlist2.h.

#include <PWatchlist2.h>

Constructor & Destructor Documentation

◆ PWatchlist2() [1/2]

PWatchlist2::PWatchlist2 ( )

Constructs an empty watchlist (then, you have to use OpenXXX() to link the watchlist to a specified backend).

◆ PWatchlist2() [2/2]

PWatchlist2::PWatchlist2 ( const PWatchlist2 other)

Constructs a shared copy of other.

◆ ~PWatchlist2()

virtual PWatchlist2::~PWatchlist2 ( )
virtual

Destroys this object.

Member Function Documentation

◆ AddDescriptor()

PResult PWatchlist2::AddDescriptor ( const PGuid subjectId,
const PDescriptor descriptor 
)

Attaches a descriptor to the specified subject.

This method will returns an error if a descriptor with the same id already exists. Returns PResult::C_OK if success, another result otherwise.

◆ AddSubjectFromDescription()

PResult PWatchlist2::AddSubjectFromDescription ( const PDescription d)

Adds (or updates) the specified subject to this watchlist from a PDescription object.

If a subject with the same id already exists, information will be merged. Assumes, we have two descriptions A (description already in the watchlist) and B (the specified description). Then, the merge is done as follows:

  • The new description will have the name of B.
  • Quality remains unchanged.
  • The new description will have the thumbnail of B, if any (default quality is used JPG(85)).
  • List of descriptors are merged: new list of descriptors = (list of A) union (list of B)
  • Metadata are merged and updated from B to A.

WARNING: you cannot use this method to remove descriptors and/or metadata to a subject; use RemoveDescriptor() and RemoveSubjectMetadata() for this purpose.

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

◆ AddSubjectsToCollection()

PResult PWatchlist2::AddSubjectsToCollection ( const PGuid collectionId,
const PList listSubjectId 
)

Add a list of subjects to the specified collection.

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

◆ AddSubjectToCollection()

PResult PWatchlist2::AddSubjectToCollection ( const PGuid collectionId,
const PGuid subjectId 
)

Adds the specified subject to a given collection.

Both subject and collection must exists. Returns PResult::C_OK if success, another result otherwise.

◆ BatchSearch()

PResult PWatchlist2::BatchSearch ( const PGuid searchListId,
const PList unknowns,
const PWatchlistOptions options,
PList 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.

◆ ComputeDescriptorsForANewEngine()

PResult PWatchlist2::ComputeDescriptorsForANewEngine ( const PGuid sourceDescribeEngineId,
const PDetector detector,
const PDescriber describer 
)

Computes a new set of descriptors from the descriptors of a specific engine (sourceDescribeEngineId).

Input descriptors must contain source images to be able to compute new descriptors. Returns PResult::C_OK if success, another result otherwise.

◆ CreateCollection()

PResult PWatchlist2::CreateCollection ( const PGuid collectionId,
const PString collectionName 
)

Creates a new (empty) collection (a subset of this watchlist) from a name and an id (name and id must be unique; you cannot have 2 collections with the same name and/or id).

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

◆ CreateSubject()

PResult PWatchlist2::CreateSubject ( const PString name,
const PObjectType type,
const PGuid id 
)

Creates a new subject from its name, its type and its unique id (e.g.

"John Doe", type PObjectType::C_FACE). You can use PGuid::CreateUniqueId() to create a new id.

With this method, you can create a new subject and attach some descriptors, metadata, etc. in a second time using the subject id. An alternative is to use the method AddSubjectFromDescription(). Returns PResult::C_OK if success, another result otherwise.

See also
AddSubjectFromDescription()

◆ FilterSubjectsByMetadata()

PResult PWatchlist2::FilterSubjectsByMetadata ( const PStringList listSqlConditionOnMetadata,
const PGuid collectionId,
PList listIds 
) const

Returns a list of subjects (ids) using the specified filter applied on subject metadata.

The filter must use SQL format and the two fields named 'key' and 'value' (both of type string).

If you want to filter the full watchlist, use collectionId set to PGuid::Null(), otherwise provide a valid collectionId.

Example 1: get the list of subjects where metadata 'age' is > 18: listSqlConditionOnMetadata = ["key='age' and CAST(value as int) > 18"].

Example 2: get the list of subjects where metadata 'age' is > 18 AND 'gender'='male': listSqlConditionOnMetadata = ["key='age' and CAST(value as int) > 18", "key='gender' and value='male'"].

WARNING: conditions must not contain ';' (to avoid SQL injection issue).

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

◆ FindSubject()

PResult PWatchlist2::FindSubject ( const PString name,
PString::ECaseSensitivity  caseSensitivity,
PList listIds 
) const

Gets all the subject ids (PGuid) held in the watchlist with the specified name.

A same name can be used for several descriptions. Returns PResult::C_OK if success, another result otherwise.

◆ GetCollectionByName()

PResult PWatchlist2::GetCollectionByName ( const PString collectionName,
PGuid collectionId 
) const

Gets a collection id from its name.

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

◆ GetCollectionName()

PResult PWatchlist2::GetCollectionName ( const PGuid collectionId,
PString collectionName 
) const

Gets the name of the specified collection.

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

◆ GetDescribeEngineFormat()

PResult PWatchlist2::GetDescribeEngineFormat ( const PGuid describeEngineId,
PString format 
) const

Gets the format of descriptors generated by the specified describe engine.

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

◆ GetDescriptor()

PResult PWatchlist2::GetDescriptor ( const PGuid descriptorId,
PDescriptor descriptor 
) const

Gets all information related to the specified descriptor (including biometric data, source image, metadata).

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

◆ GetDescriptorAllMetadata()

PResult PWatchlist2::GetDescriptorAllMetadata ( const PGuid descriptorId,
PProperties metadata 
) const

Gets all metadata attached to a descriptor.

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

◆ GetDescriptorData()

PResult PWatchlist2::GetDescriptorData ( const PGuid descriptorId,
PByteArray data 
) const

Gets the binary data (biometric data) attached to the specified descriptor, if any.

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

◆ GetDescriptorMetadata()

PResult PWatchlist2::GetDescriptorMetadata ( const PGuid descriptorId,
const PString metadataName,
PObject metadataValue 
) const

Gets a metadata attached to a descriptor.

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

◆ GetDescriptorQuality()

double PWatchlist2::GetDescriptorQuality ( const PGuid descriptorId) const

Gets the quality score associated with a descriptor.

Returns the quality score if any, -1 if not set and PMath::NaN if failure.

◆ GetDescriptorSourceImage()

PResult PWatchlist2::GetDescriptorSourceImage ( const PGuid descriptorId,
PImage image 
) const

Gets the source image attached to the specified descriptor if any.

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

◆ GetNumberOfDescriptors()

papillon::int32 PWatchlist2::GetNumberOfDescriptors ( const PGuid describeEngineId) const

Returns the number of descriptors for the specified describe-engine.

◆ GetSearchList()

PResult PWatchlist2::GetSearchList ( const PGuid describeEngineId,
const PGuid collectionId,
PGuid searchListId 
)

Gets the specified search list (load data if the specified search list has not been used before); set collectionId to PGuid::Null() to search through the full watchlist).

Using this function, you will get a search-id to be used in SearchXXX() functions.

According to the size of the watchlist, this function can take a long time because it has to load descriptor data from the underlying database. Returns PResult::C_OK if success, another result otherwise.

◆ GetSubjectAllMetadata()

PResult PWatchlist2::GetSubjectAllMetadata ( const PGuid subjectId,
PProperties metadata 
) const

Gets all the metadata attached to a subject.

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

◆ GetSubjectCreationTime()

PResult PWatchlist2::GetSubjectCreationTime ( const PGuid subjectId,
PDateTime creationTimeUTC 
) const

Gets the creation time (UTC) of the specified subject.

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

◆ GetSubjectDescription()

PResult PWatchlist2::GetSubjectDescription ( const PGuid subjectId,
PDescription description 
) const

Gets the full description (name, thumbnail, metadata, descriptors, etc.) of a subject from its id.

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

◆ GetSubjectMetadata()

PResult PWatchlist2::GetSubjectMetadata ( const PGuid subjectId,
const PString metadataName,
PObject metadataValue 
) const

Gets a metadata attached to a subject.

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

◆ GetSubjectModificationTime()

PResult PWatchlist2::GetSubjectModificationTime ( const PGuid subjectId,
PDateTime modificationTimeUTC 
) const

Gets the modification time (UTC) of the specified subject.

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

◆ GetSubjectName()

PResult PWatchlist2::GetSubjectName ( const PGuid subjectId,
PString name 
) const

Gets the name of the specified subject.

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

◆ GetSubjectQuality()

double PWatchlist2::GetSubjectQuality ( const PGuid subjectId) const

Gets the quality score associated with the specified subject.

Returns the quality score if any, -1 if not set or PMath::NaN if failure.

◆ GetSubjectThumbnail()

PResult PWatchlist2::GetSubjectThumbnail ( const PGuid subjectId,
PImage thumbnail 
) const

Gets the thumbnail attached to a subject, if any.

Returns an error if no thumbnail attached to the specified subject. Returns PResult::C_OK if success, another result otherwise.

◆ GetSubjectType()

PResult PWatchlist2::GetSubjectType ( const PGuid subjectId,
PObjectType type 
) const

Gets the type of the specified subject.

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

◆ GetWatchlistCreationTimeUTC()

PDateTime PWatchlist2::GetWatchlistCreationTimeUTC ( ) const

Returns the creation time of this watchlist.

◆ GetWatchlistId()

PGuid PWatchlist2::GetWatchlistId ( ) const

Returns the global identifier of this watchlist.

◆ GetWatchlistName()

PString PWatchlist2::GetWatchlistName ( ) const

Returns the name of this watchlist.

◆ GetWatchlistVersion()

PVersion PWatchlist2::GetWatchlistVersion ( ) const

Returns the database version number of this watchlist.

◆ HasCollection()

bool PWatchlist2::HasCollection ( const PGuid collectionId) const

Returns true if there is a collection with the specified id, false otherwise.

◆ HasDescriptor()

bool PWatchlist2::HasDescriptor ( const PGuid descriptorId) const

Returns true if the watchlist contained the specified descriptor, false otherwise.

◆ HasSubject()

bool PWatchlist2::HasSubject ( const PGuid subjectId) const

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

◆ IsCompatibleWith()

bool PWatchlist2::IsCompatibleWith ( const PGuid describeEngineId) const

Returns true if this watchlist is compatible with the specified describe-engine (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 PWatchlist2::IsEmpty ( ) const

Returns true if this watchlist is empty (no subjects/objects), false otherwise.

◆ IsSubjectDeleted()

PResult PWatchlist2::IsSubjectDeleted ( const PGuid subjectId,
bool &  isDeleted 
) const

Gets the deleted status of the specified subject.

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

◆ ListCollections()

PResult PWatchlist2::ListCollections ( PList listIds) const

Lists all the available collections (each collection is identified by a collectionId (PGuid)).

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

◆ ListCollectionSubjects()

PResult PWatchlist2::ListCollectionSubjects ( const PGuid collectionId,
PList listIds 
) const

Returns the list of subject ids (PGuid) contained in the specified collection.

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

◆ ListDescribeEngineDescriptors()

PResult PWatchlist2::ListDescribeEngineDescriptors ( const PGuid describeEngineId,
PList listIds 
) const

Gets all descriptor ids (PGuid) for the specified describe-engine-id.

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

◆ ListDescribeEngines()

PResult PWatchlist2::ListDescribeEngines ( PList listIds)

Gets the list of all describe-engine-ids (PGuid) used in this watchlist.

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

See also
PDescriber::GetDescribeId()

◆ ListSubjectDescriptors()

PResult PWatchlist2::ListSubjectDescriptors ( const PGuid subjectId,
PList listIds 
) const

Gets the list of ids (PGuid) of the descriptors attached to the specified subject.

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

◆ ListSubjects()

PResult PWatchlist2::ListSubjects ( PList listIds) const

Gets all subject ids (PGuid) held in this watchlist (each subject has a unique id).

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

◆ OpenPostgreSQL()

static PResult PWatchlist2::OpenPostgreSQL ( const PString dbHost,
papillon::int32  dbPort,
const PString watchlistName,
const PString dbUsername,
const PString dbPassword,
PWatchlist2 watchlist 
)
static

Opens the specified watchlist using PostgreSQL backend; WARNING: (1) the provided user must have rights to CREATE database and CREATE/DROP tables and (2) 'watchlistName' must in lowercase.

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

◆ OpenSQLite()

static PResult PWatchlist2::OpenSQLite ( const PString watchlistName,
PWatchlist2 watchlist 
)
static

Opens the specified watchlist using SQLite backend.

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

◆ operator=()

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

Performs a shared copy of other to this object.

◆ RemoveAllSubjects()

PResult PWatchlist2::RemoveAllSubjects ( )

Removes all subjects and all related data (clear the watchlist).

WARNING: use it carefully; this method will clear the underlying database. There is no way to recover deleted data using this class. Returns PResult::C_OK if success, another result otherwise.

◆ RemoveCollection()

PResult PWatchlist2::RemoveCollection ( PGuid collectionId)

Removes the specified collection.

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

◆ RemoveDescribeEngine()

PResult PWatchlist2::RemoveDescribeEngine ( const PGuid describeEngineId)

Removes all the descriptors for the specified describe-engine.

◆ RemoveDescriptor()

PResult PWatchlist2::RemoveDescriptor ( const PGuid descriptorId)

Removes a descriptor from the specified subject.

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

◆ RemoveDescriptorMetadata()

PResult PWatchlist2::RemoveDescriptorMetadata ( const PGuid descriptorId,
const PString metadataName 
)

Removes a metadata attached to a descriptor.

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

◆ RemoveSubject()

PResult PWatchlist2::RemoveSubject ( const PGuid subjectId)

Removes a subject and all related data from the watchlist.

WARNING: once a subject has been removed, there is no way to recover it. Returns PResult::C_OK if success, another result otherwise.

◆ RemoveSubjectFromCollection()

PResult PWatchlist2::RemoveSubjectFromCollection ( const PGuid collectionId,
const PGuid subjectId 
)

Removes the specified subject from a given collection.

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

◆ RemoveSubjectMetadata()

PResult PWatchlist2::RemoveSubjectMetadata ( const PGuid subjectId,
const PString metadataName 
)

Removes a metadata attached to a subject.

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

◆ RemoveSubjectsMarkedAsDeleted()

PResult PWatchlist2::RemoveSubjectsMarkedAsDeleted ( )

Removes all subjects marked as deleted.

WARNING: use it carefully; this method will clear the underlying database. There is no way to recover deleted data using this class. Returns PResult::C_OK if success, another result otherwise.

◆ RemoveSubjectThumbnail()

PResult PWatchlist2::RemoveSubjectThumbnail ( const PGuid subjectId)

Removes the thumbnail attached to a subject.

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

◆ RenameCollection()

PResult PWatchlist2::RenameCollection ( const PGuid collectionId,
const PString newName 
)

Renames the specified collection.

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

◆ Search()

PResult PWatchlist2::Search ( const PGuid searchListId,
const PDescription unknown,
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.

You can use PrepareSearch() function to preload all data required for a specific search.

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

◆ SetDescriptorMetadata()

PResult PWatchlist2::SetDescriptorMetadata ( const PGuid descriptorId,
const PString metadataName,
const PObject metadataValue 
)

Sets a metadata attached to a descriptor.

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

◆ SetDescriptorQuality()

PResult PWatchlist2::SetDescriptorQuality ( const PGuid descriptorId,
double  quality 
)

Sets the quality score associated with a descriptor.

This field is typically used to store ISO face quality when PWatchlist2 is used for Face Recognition. Returns PResult::C_OK if success, another result otherwise.

◆ SetDescriptorSourceImage()

PResult PWatchlist2::SetDescriptorSourceImage ( const PGuid descriptorId,
const PImage image 
)

Sets the source image attached to the specified descriptor.

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

◆ SetSubjectDeleted()

PResult PWatchlist2::SetSubjectDeleted ( const PGuid subjectId,
bool  isDeleted 
)

Sets the deleted status of the specified subject.

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

◆ SetSubjectMetadata()

PResult PWatchlist2::SetSubjectMetadata ( const PGuid subjectId,
const PString metadataName,
const PObject metadataValue 
)

Sets a metadata attached to a subject.

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

◆ SetSubjectName()

PResult PWatchlist2::SetSubjectName ( const PGuid subjectId,
const PString name 
)

Sets the name of the specified subject.

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

◆ SetSubjectQuality()

PResult PWatchlist2::SetSubjectQuality ( const PGuid subjectId,
double  quality 
)

Sets the quality score of the specified subject.

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

◆ SetSubjectThumbnail()

PResult PWatchlist2::SetSubjectThumbnail ( const PGuid subjectId,
const PImage thumbnail,
PImage::EFileFormat  format = PImage::E_JPG,
papillon::int32  quality = 85 
)

Sets the thumbnail attached to a subject.

By default JPG format is used to store the image but you can use all image format supported by this SDK, see PImage. Returns PResult::C_OK if success, another result otherwise.

◆ SetSubjectType()

PResult PWatchlist2::SetSubjectType ( const PGuid subjectId,
const PObjectType type 
)

Sets the type of the specified subject.

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

◆ SetThumbnailFormatAndQuality()

void PWatchlist2::SetThumbnailFormatAndQuality ( PImage::EFileFormat  imageFormat,
papillon::int32  quality 
)

Sets thumbnail image format and quality.

If this method is not called, the default parameters that will be used are: JPG / quality=85

◆ SetUsername()

void PWatchlist2::SetUsername ( const PString username)

Sets the user name that will be used for logging.

◆ Size()

papillon::int32 PWatchlist2::Size ( ) const

Returns the number of subjects/objects contained in this watchlist.

◆ SizeCollection()

papillon::int32 PWatchlist2::SizeCollection ( const PGuid collectionId) const

Returns the size of the specified collection, or -1 if failure.

◆ UnloadSearchList()

PResult PWatchlist2::UnloadSearchList ( const PGuid searchListId)

Unloads the specified search list from memory.

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

Friends And Related Function Documentation

◆ PWatchlist2Impl

friend class PWatchlist2Impl
friend

Definition at line 616 of file PWatchlist2.h.