Interface object that stores a captured face sample. More...

#include <RawSample.h>

Classes
struct	Angles
	Face orientation angles. More...

Public Types
enum	SampleType { SAMPLE_TYPE_FRONTAL = 0, SAMPLE_TYPE_LEFT_PROFILE = 1, SAMPLE_TYPE_RIGHT_PROFILE = 2 }
	Sample types (see also Capturer::CapturerType). More...

enum	ImageFormat { IMAGE_FORMAT_JPG = 0, IMAGE_FORMAT_PNG = 1, IMAGE_FORMAT_TIF = 2, IMAGE_FORMAT_BMP = 3 }
	Image formats for saving. More...

enum	FaceCutType { FACE_CUT_BASE = 0, FACE_CUT_FULL_FRONTAL = 1, FACE_CUT_TOKEN_FRONTAL = 2 }
	Face cropping types. More...

typedef LightSmartPtr < RawSample >::tPtr	Ptr
	Alias for the type of a smart pointer to RawSample.

typedef pbio::Rectangle	Rectangle
	Rectangle in an image.

typedef pbio::Point	Point
	2D point.

Public Member Functions
Rectangle	getRectangle () const
	Get a face bounding rectangle. Thread-safe. More...

std::vector< Point >	getLandmarks () const
	Get anthropometric landmarks. Only frontal samples. Thread-safe. More...

std::vector< Point >	getIrisLandmarks () const
	Get the characteristic points of the eyes. Only frontal samples. Thread-safe. More...

Point	getLeftEye () const
	Get a point of the left eye. Only frontal samples. Thread-safe. More...

Point	getRightEye () const
	Get a point of the right eye. Only frontal samples. Thread-safe. More...

Angles	getAngles () const
	Get a face orientation. Only frontal samples. Thread-safe. More...

int	getID () const
	Get a face ID. Thread-safe. More...

int	getFrameID () const
	Get an ID of the frame, in which this RawSample is detected (for samples made with VideoWorker). Thread-safe. More...

bool	hasOriginalImage () const
	Does the sample store the original image (true for samples made with VideoWorker with enabled store_original_frame_in_raw_sample). Thread-safe. More...

float	getScore () const
	Get the score of the detected face (for samples made with supported single-shot Capturers). Thread-safe. More...

float	getFaceVisibilityScore () const
	Get the score of face visibility. Thread-safe. More...

void	getOriginalImage (int &rows, int &cols, IRawImage::Format &format, void const *&data) const
	Get an original image. Throws an exception if a sample doesn’t contain an original image (check with RawSample::hasOriginalImage first). Thread-safe. More...

SampleType	getType () const
	Get a sample type. Thread-safe. More...

std::vector< Point >	getFaceCutRectangle (FaceCutType cut_type) const
	Get a cropping rectangle (for preview) that will be used in cutFaceImage. Thread-safe. More...

void	cutFaceImage (std::ostream &binary_stream, ImageFormat format, FaceCutType cut_type) const
	Crop the face and save in the specified format. Thread-safe. More...

RawImage	cutFaceRawImage (RawImage::Format color_model, FaceCutType cut_type) const
	Crop face in RawImage format (with raw pixels). Thread-safe. More...

void	cutFaceImage (pbio::stl_wraps::WrapOStream &binary_stream, ImageFormat format, FaceCutType cut_type) const
	Crop the face and save in the specified format. Thread-safe. More...

void	cutFaceImage (const RawImage original_image, std::ostream &binary_stream, ImageFormat format, FaceCutType cut_type) const
	Crop the face and save it in original size in the specified format. Thread-safe. More...

void	cutFaceImage (const RawImage original_image, pbio::stl_wraps::WrapOStream &binary_stream, ImageFormat format, FaceCutType cut_type) const
	Crop the face and save it in original size in the specified format. Thread-safe. More...

void	save (std::ostream &binary_stream, ImageFormat format) const
	Save (serialize) the sample. Original image will not be saved (i.e. only the part of an image containing the face is saved). The format is platform-independent. Thread-safe. After saving, you can load it with FacerecService::loadRawSample. More...

void	save (pbio::stl_wraps::WrapOStream &binary_stream, ImageFormat format) const
	Save (serialize) the sample. Original image will not be saved (i.e. only the part of an image containing the face is saved). The format is platform-independent. Thread-safe. After saving, you can load it with FacerecService::loadRawSample. More...

void	saveWithoutImage (pbio::stl_wraps::WrapOStream &binary_stream, const double space_translation_x=0, const double space_translation_y=0, const double space_scale=1) const
	Save (serialize) all sample information except the image. You have to store the image on your own in order to pass it to the FacerecService::loadRawSampleWithoutImage for deserialization. If you transformed the image in soma way, you can set the parameters of coordinate space transformation: (x, y) -> ( (x + space_translation_x) * space_scale, (y + space_translation_y) * space_scale ) that will be applied to the information about face position. Note that you must set the same transformation only once - either during serialization or during deserialization, otherwise transformation will be applied twice, which is wrong. The format is platform-independent. Thread-safe. After saving, you can load it with FacerecService::loadRawSampleWithoutImage. More...

void	saveWithoutImage (std::ostream &binary_stream, const double space_translation_x=0, const double space_translation_y=0, const double space_scale=1) const
	Save (serialize) all sample information except the image. You have to store the image on your own in order to pass it to the FacerecService::loadRawSampleWithoutImage for deserialization. If you transformed the image in soma way, you can set the parameters of coordinate space transformation: (x, y) -> ( (x + space_translation_x) * space_scale, (y + space_translation_y) * space_scale ) that will be applied to the information about face position. Note that you must set the same transformation only once - either during serialization or during deserialization, otherwise transformation will be applied twice, which is wrong. The format is platform-independent. Thread-safe. After saving, you can load it with FacerecService::loadRawSampleWithoutImage. More...

RawSample::Ptr	downscaleToPreferredSize () const
	Clone this RawSample with an internal face image downscaled to suitable size and without an original image. In order to reduce memory consumption (both in RAM and after serialization). At work Capturer and VideoWorker automatically downscale all RawSamples if the downscale_rawsamples_to_preferred_size parameter is enabled (enabled by default), but it decreases the performance. It's recommended to disable downscale_rawsamples_to_preferred_size and use RawSample::downscaleToPreferredSize manually for RawSamples that you need to save or keep in RAM for a long time. More...

pbio::Context	toContext () const
	will transform RawSample into a container-Context More...

Detailed Description

Interface object that stores a captured face sample.

Member Enumeration Documentation

enum pbio::RawSample::FaceCutType

Face cropping types.

Enumerator
FACE_CUT_BASE	Unspecified cropping (any sample type).
FACE_CUT_FULL_FRONTAL	ISO/IEC 19794-5 Full Frontal (for ID, travel documents) (only frontal sample type).
FACE_CUT_TOKEN_FRONTAL	ISO/IEC 19794-5 Token Frontal (fixed eye positions) (only frontal sample type).

enum pbio::RawSample::ImageFormat

Image formats for saving.

Enumerator
IMAGE_FORMAT_JPG	JPEG (lossy compression).
IMAGE_FORMAT_PNG	PNG (lossless compression).
IMAGE_FORMAT_TIF	TIFF (lossless compression).
IMAGE_FORMAT_BMP	BMP (no compression).

enum pbio::RawSample::SampleType

Sample types (see also Capturer::CapturerType).

Enumerator
SAMPLE_TYPE_FRONTAL	The face is frontal-oriented.
SAMPLE_TYPE_LEFT_PROFILE	The face is left-profile-oriented.
SAMPLE_TYPE_RIGHT_PROFILE	The face is right-profile-oriented.

Member Function Documentation

void RawSample::cutFaceImage	(	std::ostream &	binary_stream,
		RawSample::ImageFormat	format,
		RawSample::FaceCutType	cut_type
	)		const

inline

Crop the face and save in the specified format. Thread-safe.

Parameters

[out]	binary_stream	Output stream object for image saving. The file stream (std::ofstream) (if any) must be opened with the set std::ios_base::binary flag.
[in]	format	Image encoding format.
[in]	cut_type	Face cropping types.

void RawSample::cutFaceImage	(	pbio::stl_wraps::WrapOStream &	binary_stream,
		ImageFormat	format,
		FaceCutType	cut_type
	)		const

inline

Crop the face and save in the specified format. Thread-safe.

Parameters

[out]	binary_stream	Output stream object for image saving. The file stream (std::ofstream) (if any) must be opened with the set std::ios_base::binary flag.
[in]	format	Image encoding format.
[in]	cut_type	Face cropping types.

void RawSample::cutFaceImage	(	const RawImage	original_image,
		std::ostream &	binary_stream,
		ImageFormat	format,
		FaceCutType	cut_type
	)		const

inline

Crop the face and save it in original size in the specified format. Thread-safe.

Parameters

[in]	original_image	Image that was used to create this sample.
[out]	binary_stream	Output stream object for image saving. The file stream (std::ofstream) (if any) must be opened with the set std::ios_base::binary flag.
[in]	format	Image encoding format.
[in]	cut_type	Face cropping type.

void RawSample::cutFaceImage	(	const RawImage	original_image,
		pbio::stl_wraps::WrapOStream &	binary_stream,
		ImageFormat	format,
		FaceCutType	cut_type
	)		const

inline

Crop the face and save it in original size in the specified format. Thread-safe.

Parameters

[in]	original_image	Image that was used to create this sample.
[out]	binary_stream	Output stream object for image saving. The file stream (std::ofstream) (if any) must be opened with the set std::ios_base::binary flag.
[in]	format	Image encoding format.
[in]	cut_type	Face cropping type.

RawImage RawSample::cutFaceRawImage	(	RawImage::Format	color_model,
		FaceCutType	cut_type
	)		const

inline

Crop face in RawImage format (with raw pixels). Thread-safe.

Parameters

[in]	color_model	Image color model.
[in]	cut_type	Face cropping types.

Returns: RawImage with cropped face

RawSample::Ptr RawSample::downscaleToPreferredSize ( ) const

inline

Clone this RawSample with an internal face image downscaled to suitable size and without an original image. In order to reduce memory consumption (both in RAM and after serialization).
At work Capturer and VideoWorker automatically downscale all RawSamples if the downscale_rawsamples_to_preferred_size parameter is enabled (enabled by default), but it decreases the performance.
It's recommended to disable downscale_rawsamples_to_preferred_size and use RawSample::downscaleToPreferredSize manually for RawSamples that you need to save or keep in RAM for a long time.

Returns: Created RawSample.

RawSample::Angles RawSample::getAngles ( ) const

inline

Get a face orientation. Only frontal samples. Thread-safe.

Returns: Face orientation angles in degrees.

std::vector< RawSample::Point > RawSample::getFaceCutRectangle ( FaceCutType cut_type ) const

inline

Get a cropping rectangle (for preview) that will be used in cutFaceImage. Thread-safe.

Returns: 4 points that are corners of a rectangle in the counterclockwise order starting from the upper left corner.

Parameters

[in] cut_type Face cropping types.

float RawSample::getFaceVisibilityScore ( ) const

inline

Get the score of face visibility. Thread-safe.

Returns: One if face is fully visible,
zero if face is invisible,
otherwise - a number in the range [0 ... 1].

int RawSample::getFrameID ( ) const

inline

Get an ID of the frame, in which this RawSample is detected (for samples made with VideoWorker). Thread-safe.

Returns: Zero if this RawSample was made not with VideoWorker,
otherwise it's a nonnegative integer - id (that was returned by the VideoWorker::addVideoFrame) of the frame, in which this RawSample is detected.

int RawSample::getID ( ) const

inline

Get a face ID. Thread-safe.

Returns

A non-negative track id, if this sample was captured by a tracker, or
Any meaningless negative value, otherwise.

std::vector< RawSample::Point > RawSample::getIrisLandmarks ( ) const

inline

Get the characteristic points of the eyes. Only frontal samples. Thread-safe.

Returns: The vector of the positions of the points of the pupils and the boundaries of the eyelids in the original image.

std::vector< RawSample::Point > RawSample::getLandmarks ( ) const

inline

Get anthropometric landmarks. Only frontal samples. Thread-safe.

Returns: The vector of anthropometric points in the original image.

RawSample::Point RawSample::getLeftEye ( ) const

inline

Get a point of the left eye. Only frontal samples. Thread-safe.

Returns: Point of the left eye.

void RawSample::getOriginalImage	(	int &	rows,
		int &	cols,
		IRawImage::Format &	format,
		void const *&	data
	)		const

inline

Get an original image. Throws an exception if a sample doesn’t contain an original image (check with RawSample::hasOriginalImage first). Thread-safe.

Parameters

[out]	rows	Height of the original image.
[out]	cols	Width of the original image.
[out]	format	Format of the original image.
[out]	data	Pointer to the image data buffer.

RawSample::Rectangle RawSample::getRectangle ( ) const

inline

Get a face bounding rectangle. Thread-safe.

Returns: Rectangle bounding face on the original image.

RawSample::Point RawSample::getRightEye ( ) const

inline

Get a point of the right eye. Only frontal samples. Thread-safe.

Returns: Point of the right eye.

float RawSample::getScore ( ) const

inline

Get the score of the detected face (for samples made with supported single-shot Capturers). Thread-safe.

Returns: One if this RawSample was made with an unsupported detector,
otherwise - a number in the range [0 ... 1].

RawSample::SampleType RawSample::getType ( ) const

inline

Get a sample type. Thread-safe.

Returns: Type of the sample.

bool RawSample::hasOriginalImage ( ) const

inline

Does the sample store the original image (true for samples made with VideoWorker with enabled store_original_frame_in_raw_sample). Thread-safe.

Returns: true, if it has original image, otherwise false.

void RawSample::save	(	std::ostream &	binary_stream,
		ImageFormat	format
	)		const

inline

Save (serialize) the sample. Original image will not be saved (i.e. only the part of an image containing the face is saved). The format is platform-independent. Thread-safe. After saving, you can load it with FacerecService::loadRawSample.

Parameters

[out]	binary_stream	Output stream object for saving the raw sample. The file stream (std::ofstream) (if any) must be opened with the set std::ios_base::binary flag.
[in]	format	Image encoding format.

void RawSample::save	(	pbio::stl_wraps::WrapOStream &	binary_stream,
		ImageFormat	format
	)		const

inline

Save (serialize) the sample. Original image will not be saved (i.e. only the part of an image containing the face is saved). The format is platform-independent. Thread-safe. After saving, you can load it with FacerecService::loadRawSample.

Parameters

[out]	binary_stream	Output stream object for saving the raw sample. The file stream (std::ofstream) (if any) must be opened with the set std::ios_base::binary flag.
[in]	format	Image encoding format.

void RawSample::saveWithoutImage	(	pbio::stl_wraps::WrapOStream &	binary_stream,
		const double	space_translation_x = `0`,
		const double	space_translation_y = `0`,
		const double	space_scale = `1`
	)		const

inline

Save (serialize) all sample information except the image. You have to store the image on your own in order to pass it to the FacerecService::loadRawSampleWithoutImage for deserialization. If you transformed the image in soma way, you can set the parameters of coordinate space transformation: (x, y) -> ( (x + space_translation_x) * space_scale, (y + space_translation_y) * space_scale ) that will be applied to the information about face position. Note that you must set the same transformation only once - either during serialization or during deserialization, otherwise transformation will be applied twice, which is wrong. The format is platform-independent. Thread-safe. After saving, you can load it with FacerecService::loadRawSampleWithoutImage.

Parameters

[out]	binary_stream	Output stream object for saving the raw sample. The file stream (std::ofstream) (if any) must be opened with the set std::ios_base::binary flag.
[in]	space_translation_x	Coordinate space transform parameter.
[in]	space_translation_y	Coordinate space transform parameter.
[in]	space_scale	Coordinate space transform parameter.

void RawSample::saveWithoutImage	(	std::ostream &	binary_stream,
		const double	space_translation_x = `0`,
		const double	space_translation_y = `0`,
		const double	space_scale = `1`
	)		const

inline

Save (serialize) all sample information except the image. You have to store the image on your own in order to pass it to the FacerecService::loadRawSampleWithoutImage for deserialization. If you transformed the image in soma way, you can set the parameters of coordinate space transformation: (x, y) -> ( (x + space_translation_x) * space_scale, (y + space_translation_y) * space_scale ) that will be applied to the information about face position. Note that you must set the same transformation only once - either during serialization or during deserialization, otherwise transformation will be applied twice, which is wrong. The format is platform-independent. Thread-safe. After saving, you can load it with FacerecService::loadRawSampleWithoutImage.

Parameters

[out]	binary_stream	Output stream object for saving the raw sample. The file stream (std::ofstream) (if any) must be opened with the set std::ios_base::binary flag.
[in]	space_translation_x	Coordinate space transform parameter.
[in]	space_translation_y	Coordinate space transform parameter.
[in]	space_scale	Coordinate space transform parameter.

pbio::Context RawSample::toContext ( ) const

inline

will transform RawSample into a container-Context

Returns: container-Context

Classes

Public Types

Public Member Functions

Detailed Description

Member Enumeration Documentation

Member Function Documentation