# 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.

## Module Functions

### nel_tracker_get_sdk_version

```c
NELVersion nel_tracker_get_sdk_version();
```

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

**Returns:** version of the SDK

### nel_tracker_get_sdk_version_string

```c
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().

## Tracker Functions

### Constructor/Destructor

#### nel_tracker_new

```c
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

#### nel_tracker_free

```c
void nel_tracker_free(NELTracker* tracker);
```

Destructor

**Parameters:**
- `tracker` - pointer to the Tracker instance to free

### Tracking

#### nel_tracker_track

```c
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

#### NELTrackCallback

```c
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

### Query Functions

#### nel_tracker_get_emotion_ids

```c
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().

#### nel_tracker_get_emotion_names

```c
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().

#### nel_tracker_get_model_name

```c
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().

#### nel_tracker_get_concurrent_calculations

```c
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.

### Configuration

#### nel_tracker_is_emotion_enabled

```c
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

#### nel_tracker_set_emotion_enabled

```c
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

#### nel_tracker_is_face_tracking_enabled

```c
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

#### nel_tracker_set_face_tracking_enabled

```c
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

#### nel_tracker_get_minimum_face_ratio

```c
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

#### nel_tracker_set_minimum_face_ratio

```c
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

#### nel_tracker_reset_tracking

```c
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

## Data Types

### Enumerations

#### NELImageFormat

```c
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_

#### NELEmotionID

```c
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`

### Structures

#### Version

##### NELVersion

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

Semantic version number for the SDK

**Members:**
- `int major`
- `int minor`
- `int patch`

#### Image

##### NELImageHeader

```c
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

#### Points

##### NELPoint2d

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

Point2d struct

**Members:**
- `double x` - x coordinate
- `double y` - y coordinate

##### NELPoint3d

```c
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

##### NELPoint2dArray

```c
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

##### NELPoint3dArray

```c
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

#### Results

##### NELResultType

```c
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

##### NELLandmarkData

```c
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

##### NELEmotionData

```c
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

##### NELEmotionResults

```c
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

#### Arrays

##### NELEmotionIDArray

```c
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

##### NELStringArray

```c
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

### Opaque Types

#### NELTracker

```c
typedef struct NELTracker NELTracker;
```

Opaque type for the Tracker instance