# C API Documentation

The C API provides a C interface to the Native Emotions Library, allowing integration with C projects and other languages that support C bindings.

NELVersion nel_tracker_get_sdk_version();

Returns the version of the SDK (and not the model)

Returns: version of the SDK

char* nel_tracker_get_sdk_version_string();

Returns the version string of the SDK (and not the model)

Returns: version string of the SDK. The caller is responsible for freeing the returned string using free().

NELTracker* nel_tracker_new(const char* model_file, int max_concurrency, char** error_message);

Tracker constructor: loads model file, sets up the processing.

Parameters:

• model_file - path for the used model
• max_concurrency - maximum allowed concurrency, 0 means automatic (using all cores), default: 0
• error_message - pointer to a char* that will be set to an error message string on failure, or NULL on success. The caller is responsible for freeing the string using free(). If error_message is a NULL pointer, no error message will be returned.

Returns: pointer to the new Tracker instance, or NULL on failure

void nel_tracker_free(NELTracker* tracker);

Destructor

Parameters:

• tracker - pointer to the Tracker instance to free

void nel_tracker_track(NELTracker* tracker, const NELImageHeader* image_header,
                       int64_t timestamp_ms, NELTrackCallback callback, void* user_data);

Tracks the given frame asynchronously with a callback API.

Note: The given ImageHeader doesn't own the image data, and it is safe to delete the data after the call, a copy is happening internally. See NELImageHeader for details.

Note: Calling this function is non-blocking, so calling it again with the next frame without waiting for the result is possible. Also see nel_tracker_get_concurrent_calculations().

Note: This API is not thread-safe. Do not call any tracker functions from multiple threads simultaneously.

Parameters:

• tracker - pointer to the Tracker instance
• image_header - image descriptor
• timestamp_ms - timestamp of the image in milliseconds
• callback - callback to call with the result
• user_data - user data to pass to the callback

typedef void (*NELTrackCallback)(void* user_data, NELResultType* result, const char* error_msg);

Callback for track function

Parameters:

• user_data - user data passed to the function
• result - tracked landmarks and emotions. The result and its contents are owned by the library and are valid only during the callback.
• error_msg - error message if any, otherwise NULL

NELEmotionIDArray* nel_tracker_get_emotion_ids(const NELTracker* tracker);

Returns the emotion IDs provided by the loaded model. The order is the same as in the NELEmotionResults.

See also: NELEmotionResults

Parameters:

• tracker - pointer to the Tracker instance

Returns: pointer to NELEmotionIDArray. The caller is responsible for freeing the returned array using free().

NELStringArray* nel_tracker_get_emotion_names(const NELTracker* tracker);

Returns the emotion names provided by the loaded model. The order is the same as in the NELEmotionResults.

See also: NELEmotionResults

Parameters:

• tracker - pointer to the Tracker instance

Returns: pointer to NELStringArray. The caller is responsible for freeing the returned array using free().

char* nel_tracker_get_model_name(const NELTracker* tracker);

Returns the name (version etc) of the loaded model.

Parameters:

• tracker - pointer to the Tracker instance

Returns: name of the model. The caller is responsible for freeing the returned string using free().

uint16_t nel_tracker_get_concurrent_calculations(const NELTracker* tracker);

Returns the value of the atomic counter for the number of calculations currently running concurrently. You can use this to limit the number of concurrent calculations.

Parameters:

• tracker - pointer to the Tracker instance

Returns: The (approximate) number of calculations currently in-flight.

bool nel_tracker_is_emotion_enabled(const NELTracker* tracker, NELEmotionID emotion_id);

Returns wether the specified emotion is enabled

Parameters:

• tracker - pointer to the Tracker instance
• emotion_id - emotion to query

Returns: true if enabled, false otherwise

void nel_tracker_set_emotion_enabled(NELTracker* tracker, NELEmotionID emotion_id, bool enable);

Sets the specified emotion to enabled or disabled

Parameters:

• tracker - pointer to the Tracker instance
• emotion_id - emotion to set
• enable - boolean to set to

bool nel_tracker_is_face_tracking_enabled(const NELTracker* tracker);

Returns wether the face tracker is enabled

Parameters:

• tracker - pointer to the Tracker instance

Returns: true if enabled, false otherwise

void nel_tracker_set_face_tracking_enabled(NELTracker* tracker, bool enable);

Sets the face tracker to be enabled or disabled

Parameters:

• tracker - pointer to the Tracker instance
• enable - boolean to set to

float nel_tracker_get_minimum_face_ratio(const NELTracker* tracker);

Gets the current minimum face ratio

See also: nel_tracker_set_minimum_face_ratio

Parameters:

• tracker - pointer to the Tracker instance

Returns: current minimum face size as a ratio of the smaller image dimension

void nel_tracker_set_minimum_face_ratio(NELTracker* tracker, float minimum_face_ratio);

Sets the minimum face ratio

The minimum face ratio defines the minimum face size the algorithm is looking for. The actual size is calculated from the smaller image dimension multiplied by the set minimum face ratio. If the value is 1/4.8, then in case of VGA resolution input (640x480), the minimum face size is 100x100.

Warning: The shape alignment and classifier performance can degrade in case of low resolution, tracking faces smaller than 75x75 is ill advised.

Parameters:

• tracker - pointer to the Tracker instance
• minimum_face_ratio - new minimum face size as a ratio of the smaller image dimension

void nel_tracker_reset_tracking(NELTracker* tracker);

Resets the internal tracking state. Should be called when a new video sequence starts.

Parameters:

• tracker - pointer to the Tracker instance

typedef enum NELImageFormat {
    NELImageFormatGrayscale = 0,
    NELImageFormatRGB  = 1,
    NELImageFormatRGBA = 2,
    NELImageFormatBGR  = 3,
    NELImageFormatBGRA = 4,
} NELImageFormat;

Image format enum

Values:

• NELImageFormatGrayscale = 0 - 8-bit grayscale
• NELImageFormatRGB = 1 - 24-bit RGB
• NELImageFormatRGBA = 2 - 32-bit RGBA or 32-bit RGB_
• NELImageFormatBGR = 3 - 24-bit BGR
• NELImageFormatBGRA = 4 - 32-bit BGRA or 32-bit BGR_

typedef enum NELEmotionID {
    NELEmotionIDConfusion = 0,
    NELEmotionIDContempt = 1,
    NELEmotionIDDisgust = 2,
    NELEmotionIDFear = 3,
    NELEmotionIDHappy = 4,
    NELEmotionIDEmpathy = 5,
    NELEmotionIDSurprise = 6,
    NELEmotionIDAttention = 100,
    NELEmotionIDPresence = 101,
    NELEmotionIDEyesOnScreen = 102,
    NELEmotionIDFaceDetection = 103,
} NELEmotionID;

IDs for the supported emotions/behaviours

Values:

• NELEmotionIDConfusion = 0
• NELEmotionIDContempt = 1
• NELEmotionIDDisgust = 2
• NELEmotionIDFear = 3
• NELEmotionIDHappy = 4
• NELEmotionIDEmpathy = 5
• NELEmotionIDSurprise = 6
• NELEmotionIDAttention = 100
• NELEmotionIDPresence = 101
• NELEmotionIDEyesOnScreen = 102
• NELEmotionIDFaceDetection = 103

typedef struct NELVersion {
    int major;
    int minor;
    int patch;
} NELVersion;

Semantic version number for the SDK

Members:

• int major
• int minor
• int patch

typedef struct NELImageHeader {
    const uint8_t* data;
    int width;
    int height;
    int stride;
    NELImageFormat format;
} NELImageHeader;

Descriptor class for image data (non-owning)

Members:

• const uint8_t* data - pointer to the byte array of the image
• int width - width of the image in pixels
• int height - height of the image in pixels
• int stride - length of one row of pixels in bytes (e.g: 3*width + padding)
• NELImageFormat format - image format

typedef struct NELPoint2d {
    double x;
    double y;
} NELPoint2d;

Point2d struct

Members:

• double x - x coordinate
• double y - y coordinate

typedef struct NELPoint3d {
    double x;
    double y;
    double z;
} NELPoint3d;

Point3d struct

Members:

• double x - x coordinate
• double y - y coordinate
• double z - z coordinate

typedef struct NELPoint2dArray {
    int count;
    NELPoint2d* points;
} NELPoint2dArray;

Array of Point2d

Members:

• int count - number of points
• NELPoint2d* points - pointer to the array of points

typedef struct NELPoint3dArray {
    int count;
    NELPoint3d* points;
} NELPoint3dArray;

Array of Point3d

Members:

• int count - number of points
• NELPoint3d* points - pointer to the array of points

typedef struct NELResultType {
    NELLandmarkData* landmarks;
    NELEmotionResults* emotions;
} NELResultType;

Result type for the track function

Members:

• NELLandmarkData* landmarks - pointer to landmark data, or NULL if no face was detected
• NELEmotionResults* emotions - pointer to emotion results, or NULL if no face was detected

typedef struct NELLandmarkData {
    double scale;
    double roll;
    double yaw;
    double pitch;
    NELPoint2d translate;
    NELPoint2dArray* landmarks2d;
    NELPoint3dArray* landmarks3d;
    bool isGood;
} NELLandmarkData;

Landmark data for a tracked face

Members:

• double scale - scale of the face
• double roll - roll angle in radians
• double yaw - yaw angle in radians
• double pitch - pitch angle in radians
• NELPoint2d translate - translation of the face
• NELPoint2dArray* landmarks2d - pointer to 2D landmarks array
• NELPoint3dArray* landmarks3d - pointer to 3D landmarks array
• bool isGood - whether the tracking is good

typedef struct NELEmotionData {
    double probability;
    bool isActive;
    bool isDetectionSuccessful;
    NELEmotionID emotionID;
} NELEmotionData;

Emotion data for a single emotion

Members:

• double probability - probability of the emotion
• bool isActive - whether the emotion is active
• bool isDetectionSuccessful - whether the detection was successful
• NELEmotionID emotionID - ID of the emotion

typedef struct NELEmotionResults {
    int count;
    NELEmotionData* emotions;
} NELEmotionResults;

Array of emotion results

Members:

• int count - number of emotions
• NELEmotionData* emotions - pointer to the array of emotion data

typedef struct NELEmotionIDArray {
    int count;
    NELEmotionID* ids;
} NELEmotionIDArray;

Array of emotion IDs

Members:

• int count - number of emotion IDs
• NELEmotionID* ids - pointer to the array of emotion IDs

typedef struct NELStringArray {
    int count;
    char** strings;
} NELStringArray;

Array of strings

Members:

• int count - number of strings
• char** strings - pointer to the array of string pointers

typedef struct NELTracker NELTracker;

Opaque type for the Tracker instance