DEEPCRAFT™ Studio 5.2 has arrived. Read more →

Edge API

When you create an Edge project and run Build Edge in Studio, your AI model is converted into a self contained C (.c) file and Header (.h) file. This section specifies the API for interacting with the Edge model.

Using the model

Before calling any other functions,initialize the model.

// Initialize the model before calling any other functions.
void IMAI_Init();

Input data into the model

See IMAI_Compute() and IMAI_Enqueue() definitions below.

Get output from the model

See IMAI_Compute() and IMAI_Dequeue() definitions below.

💡

If the Queue API is used, IMAI_Dequeue() should be called right after every call to IMAI_Enqueue()

Additional information

The API generated depends on the preprocessing functions and the timestamp API.

Requested API with TimestampsRequested API without Timestamps
Zero Queue layers existFunction APIFunction API
One or more queue layers existQueue APIQueue No Time API

Function API

#define IMAI_API_FUNCTION
 
// Input data and get output (prediction) from the model
// @param data_in is a pointer to one data point to input to the model
// @param data_out contains the output from the model after the function 
// returns. 
//data_out[0] contains the confidence value output by the model for class 0.
void IMAI_compute(const float *data_in, float *data_out);

Queue API

#define IMAI_API_QUEUE
 
// Input data and time into the model
// @param data_in is a pointer to one data point to input to the model
// @param time_in is a pointer to one (1) timestamp to input to the model
// Time is expressed as floats where the integer part represent seconds. 
// The fractional part represents fractions of a second.
int IMAI_enqueue(const float *data_in, const float *time_in);
 
// Get output (predictions) from the model
// @param data_out contains the output from the model after the function 
// returns.
// data_out[0] contains the confidence value output by the model for class 0.
//
// @param time_out is a pointer to the timestamp(s) belonging to the input that produced the output from the model.
// Time is expressed as floats where the integer part represent seconds. 
// The fractional part represents fractions of a second. Time out typically has two values were 
// time_out[0] contains the start time and time_out[1] represents the end time of the input 
// generating the prediciton.
int IMAI_dequeue(float *data_out, float *time_out);

Queue No Time API

#define IMAI_API_QUEUE_NO_TIMESTAMPS
 
// Input data into the model
// @param data_in is a pointer to one data point to input to the model
int IMAI_enqueue(const float *data_in);
 
// Get output from the model
// data_out[0] contains the confidence value output by the model for class 0.
int IMAI_dequeue(float *data_out);

Queue API Return Codes

When utilizing the Queue API, either with or without the time feature, it is crucial to always consider the return codes. The possible return codes are outlined below:

#define IMAI_RET_SUCCESS 0    // Operation was successful.
#define IMAI_RET_NODATA -1    // No data is available.
#define IMAI_RET_NOMEM -2     // Memory allocation issue or buffer full.

int IMAI_enqueue(...) This function is responsible for pushing data into the model.
Return Values:

  • IMAI_RET_SUCCESS (0): Data was successfully pushed to the model.
  • IMAI_RET_NOMEM (-2): The buffer is full. Consider increasing the size by adjusting the BufferMultiplier option.

int IMAI_dequeue(...) This function retrieves data from the model. On successful retrieval, data will be written to the provided pointers.
Return Values:

  • IMAI_RET_SUCCESS (0): Data was successfully retrieved from the model.
  • IMAI_RET_NODATA (-1): No data is currently available. Ensure you have pushed input data using IMAI_enqueue() before trying to dequeue.
  • IMAI_RET_NOMEM (-2): An internal memory allocation error occurred.