sfe_core.h File Reference

File containing API of sfe_core library as part of SFE Toolkit. More...

#include <stdbool.h>
#include <stddef.h>
#include <stdint.h>
#include "sfe_core_detection.h"

Go to the source code of this file.

Data Structures
struct	SFEImage
	Raw owned raster image representation, HWC|BGR order. More...
struct	SFEImageInfo
	Image information structure, for describing image format and size. More...
struct	SFESolverParameter
	Solver parameter used to configure solvers. More...
struct	SFEEntity
	Entity type, used to group templates for entity identification. This type is compatible with uuid_v4 that can be used to generate unique ids. More...
struct	SFETemplateIdentificationCandidate
	Candidate for identification by template. More...
struct	SFEEntityIdentificationCandidate
	Candidate for identification by entity. More...
struct	SFETracked
	Tracked entity struct. More...

Typedefs
typedef enum SFEHwidMethod	SFEHwidMethod
	Supported methods for Hardware ID (HWID) computation.
typedef enum SFELicenseType	SFELicenseType
	License types.
typedef enum SFEImageFormat	SFEImageFormat
	Supported image formats.
typedef struct SFEImage	SFEImage
	Raw owned raster image representation, HWC|BGR order.
typedef SFEImage	SFEImageView
	Raw raster image view, HWC|BGR order.
typedef struct SFEImageInfo	SFEImageInfo
	Image information structure, for describing image format and size.
typedef void *	SFEError
	Error type used to hold optional error message.
typedef void *	SFESolver
	Solver provides an abstract interface over inference models and engines.
typedef struct SFESolverParameter	SFESolverParameter
	Solver parameter used to configure solvers.
typedef struct SFEEntity	SFEEntity
	Entity type, used to group templates for entity identification. This type is compatible with uuid_v4 that can be used to generate unique ids.
typedef struct SFETemplateIdentificationCandidate	SFETemplateIdentificationCandidate
	Candidate for identification by template.
typedef struct SFEEntityIdentificationCandidate	SFEEntityIdentificationCandidate
	Candidate for identification by entity.
typedef void *	SFETracker
	Tracker is a ByteTrack implementation for multi-modal tracking across multiple frames.
typedef struct SFETracked	SFETracked
	Tracked entity struct.

Enumerations
enum	SFEHwidMethod {   SFE_HWID_METHOD_AUTO = 0 , SFE_HWID_METHOD_DISK_ID = 1 , SFE_HWID_METHOD_MAC = 2 , SFE_HWID_METHOD_SERIAL_NUMBER = 3 ,   SFE_HWID_METHOD_IMEI = 4 , SFE_HWID_METHOD_SM_BIOS = 5 , SFE_HWID_METHOD_AMAZON = 6 , SFE_HWID_METHOD_APP_ID = 7 ,   SFE_HWID_METHOD_PHY = 8 , SFE_HWID_METHOD_MAC_ADDRESS = 9 , SFE_HWID_METHOD_SYS = 10 , SFE_HWID_METHOD_ANDROID_ID = 11 }
	Supported methods for Hardware ID (HWID) computation. More...
enum	SFELicenseType {   SFE_LICENSE_TYPE_NONE = 0 , SFE_LICENSE_TYPE_FILE = 1 , SFE_LICENSE_TYPE_MEMORY = 2 , SFE_LICENSE_TYPE_TOKEN = 3 ,   SFE_LICENSE_TYPE_ENV = 4 }
	License types. More...
enum	SFEImageFormat {   SFE_IMAGE_FORMAT_PNG = 0 , SFE_IMAGE_FORMAT_JPEG = 1 , SFE_IMAGE_FORMAT_GIF = 2 , SFE_IMAGE_FORMAT_TGA = 3 ,   SFE_IMAGE_FORMAT_BMP = 4 , SFE_IMAGE_FORMAT_QOI = 5 }
	Supported image formats. More...
enum	SFETrackedState { SFE_TRACKED_STATE_NEW = 0 , SFE_TRACKED_STATE_TRACKED = 1 , SFE_TRACKED_STATE_LOST = 2 , SFE_TRACKED_STATE_REMOVED = 3 }
	Tracked state. More...

Functions
const char *const	sfeVersion ()
	Get version of the toolkit library.
void	sfeErrorFree (SFEError error)
	Free memory associated with SFEError.
const char *	sfeErrorMessage (SFEError error)
	Get error message.
SFEError	sfeHwidGet (char *out_hwid, size_t *in_out_hwid_len, SFEHwidMethod method)
	Get Hardware ID (HWID) of the current machine.
SFEError	sfeLicenseValidate (void)
	Validate a license for this product. This process conducts checks to confirm the license's validity for this product and the current machine. Upon successful validation, the product is ready for use.
SFEError	sfeLicenseType (SFELicenseType *out_license_type)
	Get license type. This function returns the type of license that is currently active without performing full license validation.
void	sfeLicenseSet (const unsigned char *data, const size_t data_len)
	Set the license data via environment variable. The environment variable that will be set: ILICENSE_DATA. The provided data will be converted into a base64 string internally since the ILICENSE_DATA environment variable expects data in this format.
SFEError	sfeSolverCreate (const char *solver_file, const SFESolverParameter *solver_parameters, size_t solver_parameters_count, SFESolver *out_solver)
	Create new solver from solver file.
void	sfeSolverFree (SFESolver solver)
	Free memory associated with SFESolver.
SFEError	sfeImageDecode (const unsigned char *data, size_t data_len, SFEImage *out_image)
	Decode SFEImage from raw image data of various formats. Eg. PNG, JPEG ..
SFEError	sfeImageEncode (SFEImageView image, SFEImageFormat image_format, unsigned char *out_data, size_t *in_out_data_len)
	Encode SFEImage into a buffer with specified image_format.
SFEError	sfeImageInfo (const unsigned char *data, size_t data_len, SFEImageInfo *out_image_info)
	Try to get information from image data without fully decoding it.
void	sfeImageFree (SFEImage image)
	Free memory associated with SFEImage.
SFEError	sfeImageColorTranspose (SFEImageView image, SFEImage *out_image)
	Transpose RGB<->BGR color channel order.
SFEError	sfeImageResize (SFEImageView image, size_t width, size_t height, SFEImage *out_image)
	Resize image.
SFEError	sfeImageResizeWithAspectRatio (SFEImageView image, size_t width, size_t height, SFEImage *out_image)
	Resize image with maintaining aspect ratio. Whole resized image will be fitted and centered inside output image with black edges.
SFEError	sfeDetect (SFESolver solver, SFEImageView image, float threshold, SFEDetection *out_detections, size_t *in_out_detection_count)
	Detect objects in the source image using unified detection API.
SFEError	sfeDetectionTrackerCreate (float new_track_threshold, float track_high_threshold, float track_low_threshold, float match_threshold, uint64_t max_time_lost, SFETracker *out_tracker)
	Create a new tracker.
void	sfeDetectionTrackerFree (SFETracker tracker)
	Free the tracker.
SFEError	sfeDetectionTrackerUpdate (SFETracker tracker, const SFEDetection *detections, size_t detections_count, SFETracked *out_tracked, size_t *in_out_tracked_count)
	Update the tracker.
SFEError	sfeDetectionTrackerLost (SFETracker tracker, SFEEntity *out_entities, size_t *in_out_entities_count)
	Get lost entities after update.
SFEError	sfeDetectionTrackerRemoved (SFETracker tracker, SFEEntity *out_entities, size_t *in_out_entities_count)
	Get removed entities after update.

Detailed Description

File containing API of sfe_core library as part of SFE Toolkit.

Author

Innovatrics - SmartFace Embedded

Date

16.5.2023

Definition in file sfe_core.h.

Typedef Documentation

SFEEntity

typedef struct SFEEntity SFEEntity

Entity type, used to group templates for entity identification. This type is compatible with uuid_v4 that can be used to generate unique ids.

SFEEntityIdentificationCandidate

typedef struct SFEEntityIdentificationCandidate SFEEntityIdentificationCandidate

Candidate for identification by entity.

SFEError

typedef void* SFEError

Error type used to hold optional error message.

Note

In case of no error NULL is returned.

Warning

Use sfeErrorFree to release memory associated with returned errors.

Definition at line 97 of file sfe_core.h.

SFEHwidMethod

typedef enum SFEHwidMethod SFEHwidMethod

Supported methods for Hardware ID (HWID) computation.

SFEImage

typedef struct SFEImage SFEImage

Raw owned raster image representation, HWC|BGR order.

Note

For non-owning variant use SFEImageView.

Warning

This type retains ownership of the data, call sfeImageFree to free the allocated image data.

SFEImageFormat

typedef enum SFEImageFormat SFEImageFormat

Supported image formats.

SFEImageInfo

typedef struct SFEImageInfo SFEImageInfo

Image information structure, for describing image format and size.

SFEImageView

typedef SFEImage SFEImageView

Raw raster image view, HWC|BGR order.

Note

For owning variant use SFEImage.

Definition at line 81 of file sfe_core.h.

SFELicenseType

typedef enum SFELicenseType SFELicenseType

License types.

SFESolver

typedef void* SFESolver

Solver provides an abstract interface over inference models and engines.

Warning

Use sfeSolverFree to release memory associated with the solver.

Definition at line 102 of file sfe_core.h.

SFESolverParameter

typedef struct SFESolverParameter SFESolverParameter

Solver parameter used to configure solvers.

SFETemplateIdentificationCandidate

typedef struct SFETemplateIdentificationCandidate SFETemplateIdentificationCandidate

Candidate for identification by template.

SFETracked

typedef struct SFETracked SFETracked

Tracked entity struct.

SFETracker

typedef void* SFETracker

Tracker is a ByteTrack implementation for multi-modal tracking across multiple frames.

Warning

Use sfeDetectionTrackerFree to release memory associated with the tracker.

Definition at line 286 of file sfe_core.h.

Enumeration Type Documentation

SFEHwidMethod

enum SFEHwidMethod

Supported methods for Hardware ID (HWID) computation.

Enumerator
SFE_HWID_METHOD_AUTO
SFE_HWID_METHOD_DISK_ID
SFE_HWID_METHOD_MAC
SFE_HWID_METHOD_SERIAL_NUMBER
SFE_HWID_METHOD_IMEI
SFE_HWID_METHOD_SM_BIOS
SFE_HWID_METHOD_AMAZON
SFE_HWID_METHOD_APP_ID
SFE_HWID_METHOD_PHY
SFE_HWID_METHOD_MAC_ADDRESS
SFE_HWID_METHOD_SYS
SFE_HWID_METHOD_ANDROID_ID

Definition at line 21 of file sfe_core.h.

                           {
  SFE_HWID_METHOD_AUTO = 0,
  SFE_HWID_METHOD_DISK_ID = 1,
  SFE_HWID_METHOD_MAC = 2,
  SFE_HWID_METHOD_SERIAL_NUMBER = 3,
  SFE_HWID_METHOD_IMEI = 4,
  SFE_HWID_METHOD_SM_BIOS = 5,
  SFE_HWID_METHOD_AMAZON = 6,
  SFE_HWID_METHOD_APP_ID = 7,
  SFE_HWID_METHOD_PHY = 8,
  SFE_HWID_METHOD_MAC_ADDRESS = 9,
  SFE_HWID_METHOD_SYS = 10,
  SFE_HWID_METHOD_ANDROID_ID = 11,
} SFEHwidMethod;

SFEImageFormat

enum SFEImageFormat

Supported image formats.

Enumerator
SFE_IMAGE_FORMAT_PNG	Portable Network Graphics format.
SFE_IMAGE_FORMAT_JPEG	Joint Photographic Experts Group format.
SFE_IMAGE_FORMAT_GIF	Graphics Interchange Format.
SFE_IMAGE_FORMAT_TGA	Truevision TGA format.
SFE_IMAGE_FORMAT_BMP	Windows Bitmap format.
SFE_IMAGE_FORMAT_QOI	Quite OK Image format.

Definition at line 51 of file sfe_core.h.

                            {
  SFE_IMAGE_FORMAT_PNG = 0,
  SFE_IMAGE_FORMAT_JPEG = 1,
  SFE_IMAGE_FORMAT_GIF = 2,
  SFE_IMAGE_FORMAT_TGA = 3,
  SFE_IMAGE_FORMAT_BMP = 4,
  SFE_IMAGE_FORMAT_QOI = 5,
} SFEImageFormat;

SFELicenseType

enum SFELicenseType

License types.

Enumerator
SFE_LICENSE_TYPE_NONE	License was not read.
SFE_LICENSE_TYPE_FILE	License was read from a file.
SFE_LICENSE_TYPE_MEMORY	License was read from memory.
SFE_LICENSE_TYPE_TOKEN	License was read from a USB token.
SFE_LICENSE_TYPE_ENV	License was read from an environment variable.

Definition at line 37 of file sfe_core.h.

                            {
  SFE_LICENSE_TYPE_NONE = 0,
  SFE_LICENSE_TYPE_FILE = 1,
  SFE_LICENSE_TYPE_MEMORY = 2,
  SFE_LICENSE_TYPE_TOKEN = 3,
  SFE_LICENSE_TYPE_ENV = 4,
} SFELicenseType;

SFETrackedState

enum SFETrackedState

Tracked state.

Enumerator
SFE_TRACKED_STATE_NEW
SFE_TRACKED_STATE_TRACKED
SFE_TRACKED_STATE_LOST
SFE_TRACKED_STATE_REMOVED

Definition at line 289 of file sfe_core.h.

                     {
  SFE_TRACKED_STATE_NEW = 0,
  SFE_TRACKED_STATE_TRACKED = 1,
  SFE_TRACKED_STATE_LOST = 2,
  SFE_TRACKED_STATE_REMOVED = 3,
};

Function Documentation

sfeDetect()

SFEError sfeDetect	(	SFESolver	solver,
		SFEImageView	image,
		float	threshold,
		SFEDetection *	out_detections,
		size_t *	in_out_detection_count
	)

Detect objects in the source image using unified detection API.

Parameters

[in]	solver	Detection solver (can be face, iris, palm, object, tattoo, or person solver)
[in]	image	Source image
[in]	threshold	Detection confidence threshold - range <0,1>
[out]	out_detections	Pointer to an array of detected objects
[in,out]	in_out_detection_count	IN: maximum number of detections to return OUT: real number of detected objects

Returns

Error in case the detection fails.

Examples

example_face_demographic_attributes.cpp, example_face_identify.cpp, example_face_identify_entity.cpp, example_face_liveness.cpp, example_face_track.cpp, example_iris_identify.cpp, example_palm_attributes.cpp, example_palm_identify.cpp, and example_palm_liveness.cpp.

sfeDetectionTrackerCreate()

SFEError sfeDetectionTrackerCreate	(	float	new_track_threshold,
		float	track_high_threshold,
		float	track_low_threshold,
		float	match_threshold,
		uint64_t	max_time_lost,
		SFETracker *	out_tracker
	)

Create a new tracker.

Parameters

[in]	new_track_threshold	Minimum confidence score required to initialize a new track
[in]	track_high_threshold	High threshold for tracking
[in]	track_low_threshold	Low threshold for tracking
[in]	match_threshold	Match threshold
[in]	max_time_lost	Maximum time lost
[out]	out_tracker	OUT: pointer to the created tracker

Examples

example_face_track.cpp.

sfeDetectionTrackerFree()

void sfeDetectionTrackerFree

(

SFETracker

tracker

)

Free the tracker.

Parameters

[in]

tracker

Tracker to free

Examples

example_face_track.cpp.

sfeDetectionTrackerLost()

SFEError sfeDetectionTrackerLost	(	SFETracker	tracker,
		SFEEntity *	out_entities,
		size_t *	in_out_entities_count
	)

Get lost entities after update.

Parameters

[in]	tracker	Tracker to get lost entities from
[out]	out_entities	OUT: pointer to the array of lost entities
[in,out]	in_out_entities_count	IN: Available space in out_entities OUT: number of lost entities

Returns

Error in case of failed lost entities retrieval

Examples

example_face_track.cpp.

sfeDetectionTrackerRemoved()

SFEError sfeDetectionTrackerRemoved	(	SFETracker	tracker,
		SFEEntity *	out_entities,
		size_t *	in_out_entities_count
	)

Get removed entities after update.

Parameters

[in]	tracker	Tracker to get removed entities from
[out]	out_entities	OUT: pointer to the array of removed entities
[in,out]	in_out_entities_count	IN: Available space in out_entities OUT: number of removed entities

Returns

Error in case of failed removed entities retrieval

Examples

example_face_track.cpp.

sfeDetectionTrackerUpdate()

SFEError sfeDetectionTrackerUpdate	(	SFETracker	tracker,
		const SFEDetection *	detections,
		size_t	detections_count,
		SFETracked *	out_tracked,
		size_t *	in_out_tracked_count
	)

Update the tracker.

Parameters

[in]	tracker	Tracker to update
[in]	detections	Detections to update the tracker with (can be NULL if detections_count is 0)
[in]	detections_count	Number of detections
[out]	out_tracked	OUT: pointer to the array of tracked entities (can be NULL if only count is needed)
[in,out]	in_out_tracked_count	IN: Available space in out_tracked (if out_tracked is not NULL) OUT: Number of tracked entities. Can be NULL if out_tracked is NULL.

Returns

Error in case of failed update

Examples

example_face_track.cpp.

sfeErrorFree()

void sfeErrorFree

(

SFEError

error

)

Free memory associated with SFEError.

Parameters

[in]

error

Error to free.

sfeErrorMessage()

const char * sfeErrorMessage

(

SFEError

error

)

Get error message.

Parameters

[in]

error

Error to get message from.

Returns

NULL terminated C string containing the error message.

Warning

The returned C string is only valid as long as sfeErrorFree was not called for the given error.

sfeHwidGet()

SFEError sfeHwidGet	(	char *	out_hwid,
		size_t *	in_out_hwid_len,
		SFEHwidMethod	method
	)

Get Hardware ID (HWID) of the current machine.

Note

Some methods for HWID computation are not supported on some platforms. If unsure, use SFE_HWID_METHOD_AUTO that will choose a default method for the current platform.

Parameters

[out]	out_hwid	Pointer to a buffer where the HWID will be stored. Providing a null pointer will determine the necessary buffer size.
[in,out]	in_out_hwid_len	IN: Total size of the out_hwid buffer. OUT: Actual size of the data written to the out_hwid buffer.
[in]	method	A method to use for HWID computation.

Returns

Error in case the HWID computation fails or an invalid parameter is provided (e.g. buffer length is smaller than the size of the HWID).

sfeImageColorTranspose()

SFEError sfeImageColorTranspose	(	SFEImageView	image,
		SFEImage *	out_image
	)

Transpose RGB<->BGR color channel order.

Parameters

[in]	image	Image to color transpose.
[out]	out_image	Output image with transposed color channels.

Returns

Error

sfeImageDecode()

SFEError sfeImageDecode	(	const unsigned char *	data,
		size_t	data_len,
		SFEImage *	out_image
	)

Decode SFEImage from raw image data of various formats. Eg. PNG, JPEG ..

Parameters

[in]	data	Image data to decode image from.
[in]	data_len	Size of the image data in bytes.
[out]	out_image	Raw raster image.

Returns

Error in case of unknown image type.

Warning

The returned SFEImage retains ownership of the image data, call sfeImageFree to release the associated memory.

Examples

example_face_demographic_attributes.cpp, example_face_identify.cpp, example_face_identify_entity.cpp, example_face_liveness.cpp, example_face_track.cpp, example_iris_identify.cpp, example_palm_attributes.cpp, example_palm_identify.cpp, and example_palm_liveness.cpp.

sfeImageEncode()

SFEError sfeImageEncode	(	SFEImageView	image,
		SFEImageFormat	image_format,
		unsigned char *	out_data,
		size_t *	in_out_data_len
	)

Encode SFEImage into a buffer with specified image_format.

Parameters

[in]	image	Image to encode.
[in]	image_format	Image format to encode to.
[out]	out_data	Image data to encode image into.
[in,out]	in_out_data_len	IN: Total size of the out_data buffer. OUT: Actual size of the data written to the buffer.

Returns

Error in image format conversion or in case the buffer size is too low.

Examples

example_face_identify.cpp, example_face_liveness.cpp, and example_palm_liveness.cpp.

sfeImageFree()

void sfeImageFree

(

SFEImage

image

)

Free memory associated with SFEImage.

Parameters

[in]

image

Image to free.

Examples

example_face_demographic_attributes.cpp, example_face_identify.cpp, example_face_identify_entity.cpp, example_face_liveness.cpp, example_face_track.cpp, example_iris_identify.cpp, example_palm_attributes.cpp, example_palm_identify.cpp, and example_palm_liveness.cpp.

sfeImageInfo()

SFEError sfeImageInfo	(	const unsigned char *	data,
		size_t	data_len,
		SFEImageInfo *	out_image_info
	)

Try to get information from image data without fully decoding it.

Parameters

[in]	data	Image data to get information from.
[in]	data_len	Size of the image data in bytes.
[out]	out_image_info	Image information structure.

Returns

Error in case of unknown image type.

sfeImageResize()

SFEError sfeImageResize	(	SFEImageView	image,
		size_t	width,
		size_t	height,
		SFEImage *	out_image
	)

Resize image.

Parameters

[in]	image	Source image view to resize.
[in]	width	Target resize width.
[in]	height	Target resize height.
[out]	out_image	Resized image.

Returns

Error

Examples

example_face_identify.cpp, example_face_identify_entity.cpp, example_face_liveness.cpp, and example_face_track.cpp.

sfeImageResizeWithAspectRatio()

SFEError sfeImageResizeWithAspectRatio	(	SFEImageView	image,
		size_t	width,
		size_t	height,
		SFEImage *	out_image
	)

Resize image with maintaining aspect ratio. Whole resized image will be fitted and centered inside output image with black edges.

Parameters

[in]	image	Source image view to resize.
[in]	width	Target resize width.
[in]	height	Target resize height.
[out]	out_image	Resized image.

Returns

Error

sfeLicenseSet()

void sfeLicenseSet	(	const unsigned char *	data,
		const size_t	data_len
	)

Set the license data via environment variable. The environment variable that will be set: ILICENSE_DATA. The provided data will be converted into a base64 string internally since the ILICENSE_DATA environment variable expects data in this format.

Parameters

[in]	data	License data.
[in]	data_len	Length of the license data.

sfeLicenseType()

SFEError sfeLicenseType

(

SFELicenseType *

out_license_type

)

Get license type. This function returns the type of license that is currently active without performing full license validation.

Parameters

[out]

out_license_type

Pointer to a SFELicenseType to receive the license type.

Returns

Error in case the license type is not available.

sfeLicenseValidate()

SFEError sfeLicenseValidate

(

void

)

Validate a license for this product. This process conducts checks to confirm the license's validity for this product and the current machine. Upon successful validation, the product is ready for use.

Returns

Upon failure, the returned error will contain a descriptive message for the reason behind the failure.

Note

Use sfeLicenseType() to get the license type after validation.

sfeSolverCreate()

SFEError sfeSolverCreate	(	const char *	solver_file,
		const SFESolverParameter *	solver_parameters,
		size_t	solver_parameters_count,
		SFESolver *	out_solver
	)

Create new solver from solver file.

Parameters

[in]	solver_file	Solver file to create the solver from.
[in]	solver_parameters	Pointer to collection of solver parameters.
[in]	solver_parameters_count	Number of solver parameters.
[out]	out_solver	New solver.

Returns

Error in case the solver fails to load.

Examples

example_face_demographic_attributes.cpp, example_face_identify.cpp, example_face_identify_entity.cpp, example_face_liveness.cpp, example_face_track.cpp, example_iris_identify.cpp, example_palm_attributes.cpp, example_palm_identify.cpp, and example_palm_liveness.cpp.

sfeSolverFree()

void sfeSolverFree

(

SFESolver

solver

)

Free memory associated with SFESolver.

Parameters

[in]

solver

Solver to free.

Examples

example_face_demographic_attributes.cpp, example_face_identify.cpp, example_face_identify_entity.cpp, example_face_liveness.cpp, example_face_track.cpp, example_iris_identify.cpp, example_palm_attributes.cpp, example_palm_identify.cpp, and example_palm_liveness.cpp.

sfeVersion()

const char *const sfeVersion

(

)

Get version of the toolkit library.

Note

The returned pointer is statically allocated, don't free it.

Returns

NULL terminated C string containing the version.