Struct FaceEnrollmentAutomatic 

pub struct FaceEnrollmentAutomatic(/* private fields */);

Automatic face enrollment functionality.

Implementations

impl FaceEnrollmentAutomatic

pub fn get_face_ids(&self) -> Vec<FaceID>

Return the face IDs of all automatically enrolled faces.

This list of face IDs is not related to the faces currently in view. The face IDs returned by this function are all faces that have ever been enrolled into the face library. To retrieve information about the faces currently in view, use FaceIdentification::get_face_id.

pub fn max_face_library_size(&self) -> usize

Returns the maximum size of the face library.

When the library is full and new faces are detected, they will overwrite older faces, except for faces that are tagged as important using tag_face_id. When all faces are tagged as important, new faces will not be added to the library beyond this maximum size.

pub fn tag_face_id( &mut self, face_id: &FaceID, tag: FaceIDTag, ) -> Result<(), Error>

Tag a face ID as ‘important’ to prevent it from being overwritten.

When the face library is full and a new face is encountered, the algorithm will overwrite the oldest face in the library that is not tagged as important. A typical use-case of this is to tag a face as important when the user has named them in a front-end application.

When all entries in the face library are tagged as important and a new face is encountered, then no new faces will be enrolled.

By default, an automatically enrolled face is not tagged as important. However, library entries created by restore_enrollment_data are automatically tagged as important.

Errors

• Error::InvalidFaceID

pub fn remove_face_id(&mut self, face_id: FaceID) -> Result<(), Error>

Remove a face ID from the face library for any VideoIntelligence::process_frame calls that follow.

Errors

• Error::InvalidFaceID

pub fn remove_all_face_ids(&mut self)

Remove all face IDs from the face library.

pub fn get_enrollment_data( &self, face_id: &FaceID, snapshot_options: SnapshotOptions, ) -> Result<EnrollmentData, Error>

Get the face enrollment data for a face ID, for persistent storage.

This can for example be used to store the face library when a device shuts down and restore it later when it reboots.

This enrollment data can change during any VideoIntelligence::process_frame call.

Errors

• Error::InvalidFaceID

pub fn restore_enrollment_data( &mut self, face_id: &FaceID, enrollment_data: EnrollmentData, ) -> Result<(), Error>

Restore the face enrollment data for a face ID, from persistent storage.

When the specified face_id does not yet exist then it will be created. When the specified face_id already exists, the internal enrollment data will be overwritten with new enrollment data. If the new enrollment data is corrupt, this will result in removal of the existing face enrollment data.

If a new face_id was created, this function will automatically tag it as ‘important’, see also tag_face_id.

If the enrollment data does not include a face snapshot, then a face snapshot for this face ID will not be available. If the enrollment data includes a face snapshot, then configure_face_snapshots must have been called first, with enabled set to true and the same height and width as the stored data.

Errors

• Error::InvalidFaceID
• Error::FaceLibraryFull
• Error::StateCorrupt

pub fn merge_face_ids( &mut self, face_id_dst: &FaceID, face_id_src: FaceID, ) -> Result<(), Error>

Merge two entries of the face library.

If a single person is enrolled twice in the face library, this function can be used to merge their enrollments back to a single one. After calling this function face_id_src is no longer valid and face_id_dst will be updated with the additional information from face_id_src.

Errors

• Error::InvalidFaceID

pub fn get_merge_suggestion( &self, face_id: &FaceID, ) -> Result<Option<FaceID>, Error>

Suggest another entry of the face library to merge with.

If a single person is enrolled twice in the face library, this function can be used to find the other enrollment. The enrollments can then be merged with merge_face_ids. The suggestion is the entry that is most similar to face_id, but only if the algorithm is very confident that the entry is the same person.

Returns None when there is no suggestion.

Errors

• Error::InvalidFaceID

pub fn get_face_enrollment_track_ids( &self, face_id: &FaceID, ) -> Result<Vec<TrackID>, Error>

Return the track IDs for an automatically enrolled face.

The caller must provide a buffer of size at least max_tracks_per_face_id integers.

A face enrollment (face ID) can be made up of multiple person tracks, each of which is identified with a track ID. When a person is re-identified and their new face information is considered relevant for the algorithm, the new person track will be added to the existing face enrollment, or replace a previous one.

This list of track IDs can therefore change after processing any video frame.

Errors

• Error::InvalidFaceID

pub fn max_tracks_per_face_id(&self) -> usize

Returns the maximum number of tracks that a single face ID in the library consists of.

See get_face_enrollment_track_ids for more information.

When a face ID already has the maximum number of tracks stored, then a new person track will only update this face ID if it is of better quality than the existing tracks.

pub fn remove_face_enrollment_track( &mut self, face_id: &FaceID, track_id: TrackID, ) -> Result<(), Error>

Remove a track that is part of a face enrollment.

This can be used if the Plumerai library made a mistake with automatic enrollment, and a user wants to manually correct the face library. By inspecting the face snapshots of each track ID, the user can decide to remove a wrong track.

If this was the only track of face_id then this face ID is removed entirely.

Errors

• Error::InvalidFaceID
• Error::InvalidTrackID

pub fn reassign_face_enrollment_track( &mut self, face_id_src: FaceID, track_id_src: TrackID, face_id_dst: &FaceID, ) -> Result<(), Error>

Reassign a face track from face ID face_id_src to a new or existing face id face_id_dst.

This can be used if the Plumerai library made a mistake with automatic enrollment, and a user wants to manually correct the face library. By inspecting the face snapshots of each track ID, the user can decide to reassign a track to the correct face ID.

If face_id_dst does not exist, it will be created. If the face library is full, this will overwrite the oldest library entry, unless all of them are tagged as important in which case this function returns Error::FaceLibraryFull.

Note the following special behavior:

If face_id_src has only one track and it is reassigned, then face_id_src is automatically removed entirely.

It is possible that one or more existing tracks of face_id_dst are overwritten depending on whether the algorithm think it will improve the overall quality of the face enrollment.

The algorithm may determine that the original tracks of face_id_dst provide a better enrollment without the newly reassigned track. In such cases, face_id_dst remains unchanged, but the track is still removed from face_id_src.

Errors

• Error::InvalidFaceID
• Error::InvalidTrackID
• Error::FaceLibraryFull

pub fn configure_face_snapshots( &mut self, settings: FaceSnapshotSettings, ) -> Result<(), Error>

Configure the face snapshots for automatic enrollment.

By default, face snapshots are disabled.

Errors

• Error::InvalidSnapshotResolution

pub fn get_face_snapshot( &self, face_id: &FaceID, track_id: &TrackID, ) -> Result<FaceSnapshot, Error>

Return a snapshot of an automatically enrolled face.

A face enrollment can be made up of multiple person tracks. Every snapshot originates from a single person track. Use get_face_enrollment_track_ids to get a list of track IDs to use in this function.

After every processed frame the list of snapshots can change. New images might be used by the algorithm if they are of higher quality.

Errors

• Error::InvalidFaceID
• Error::InvalidTrackID
• Error::FaceSnapshotsDisabled

pub fn enroll_from_jpeg_images<T: AsRef<[u8]>>( &mut self, face_id: &FaceID, jpeg_images: &[T], decode_buffer: &mut [u8], ) -> Result<(), Error>

Explicitly enroll someone from a set of JPEG images.

This is meant as an optional addition to the regular automatic enrollment procedure, for example if a set of good enrollment images is available, or to enroll a face again from the images of get_enrollment_images. Each image should contain a single well visible face, other images are skipped. The images can be at most 1280 pixels in either dimension.

When save_enrollment_images is enabled, the JPEG images that are used for the enrollment are saved as they are passed to this function. To get the enrollment images of this face later on with get_enrollment_images, for example after the enrollment was updated while processing a video, enable save_enrollment_images before calling this function.

The JPEG images are decoded in decode_buffer, which is only used during this call. A buffer of 15MB is enough for an image of 1280x720 pixels, and 2.1MB for an image of 336x336 pixels.

The resulting library entry is treated internally similar to an automatically enrolled one and can be updated when the person is seen again. A face snapshot won’t be available until that time.

When the specified face_id does not yet exist then it will be created and tagged as ‘important’, see also tag_face_id. When the specified face_id already exists, it will be overwritten.

Errors

• Error::InvalidArgument when an image is not a valid JPEG or too large
• Error::NotEnoughMemory when the decode buffer is too small
• Error::EnrollmentFailed
• Error::LowQualityEnrollment, in which case the face is added
• Error::InvalidFaceID
• Error::FaceLibraryFull

pub fn save_enrollment_images( &mut self, buffer: Option<&'static mut [u8]>, ) -> Result<(), Error>

Save the images that are used for automatic enrollment.

By default, this is disabled. When enabled, the face images that are used for enrollment are saved as JPEG images in the given buffer, including those used by enroll_from_jpeg_images. The saved images can be retrieved with get_enrollment_images at the end, and can be used in a different VideoIntelligence instance to enroll the faces again through enroll_from_jpeg_images. The images are JPEG crops around the face with enough margin, except those of enroll_from_jpeg_images, which are saved as they are.

For face thumbnails or snapshots, use the configure_face_snapshots API instead.

When the buffer is full, new images are not saved. We recommend a buffer size of at least 8MB, but ideally 16MB. The exact requirement depends on JPEG compression and the number of people in the library and in view.

The buffer is used for the lifetime of the VideoIntelligence object or until the next call to this function, so it has to be 'static, for example Box::leak(vec![0; 16 * 1024 * 1024].into_boxed_slice()). Use None to disable this functionality.

Panics

When the buffer is too small to do any useful processing.

pub fn get_enrollment_images( &self, face_id: &FaceID, ) -> Result<Vec<Vec<u8>>, Error>

Get the JPEG images of an enrolled face, see save_enrollment_images.

For face thumbnails or snapshots, use the configure_face_snapshots API instead.

Errors

• Error::InvalidFaceID
• Error::NotAvailable when save_enrollment_images is not enabled

Trait Implementations

impl Debug for FaceEnrollmentAutomatic

fn fmt(&self, f: &mut Formatter<'_>) -> Result

Formats the value using the given formatter.