This page define the C-language interface to SOD. This is not a tutorial. The API documentation is designed to be precise. Not easy to read. For a tutorial introduction, please refer to:

• The Getting Started Guide - A quick introduction to programming with the SOD Embedded C/C API.
• The C/C code samples available to consult at the samples page and downloadable as a whole archive from the download page or the SOD GitHub repository.
• Finally, take a look at the support page if you have any trouble integrating SOD in your project.

This version of the C-language interface reference is broken down into small pages for easy viewing.

C/C Exported Functions

C/C Exported Objects

This is a list of all abstract objects and datatypes exported by the SOD library. There are few objects, but most applications only use a handful.

• sod_cnn

typedef struct sod_cnn sod_cnn;

An instance of the opaque sod_cnn structure hold all layers of a standard Convolutional Neural Network (CNN) or Recurrent Neural Network (RNN). The syntax is based on the darknet framework and the task vary depending on the specified architecture (i.e. object detection & classification for CNN, text generation for RNN). The life of a sod_cnn instance goes something like this:

1. Obtain a new sod_cnn handle via sod_cnn_create(). This routine expect you to specify the desired network architecture and a SOD weight file downloadable here. Built-in magic words such as :face :tiny :full :voc :rnn, etc. are aliases for pre-ready to use CNN or RNN architectures for object detection and text generation purposes. These magic words and their expected SOD weight files are documented here. This routine is often the first API call that an application makes and is a prerequisite in order to work with the CNN/RNN layer.
2. Optionally, configure the network via sod_cnn_config() where you can tune its parameters, specify a RNN consumer callback, detection threshold values, temperatures and so forth.
3. Prepare the input data for prediction. This step is only mandatory for object detection tasks and is performed via sod_cnn_prepare_image().
4. Perform the network prediction via sod_cnn_predict().
5. Consume the network output which vary depending on the specified architecture (i.e. bounding boxes, generated text/code, etc.). You are invited to take a look at the introduction course for additional information.
6. Destroy the sod_cnn instance via sod_cnn_destroy().

• sod_realnet

typedef struct sod_realnet sod_realnet;

RealNets are simple container for multiple neural networks architecture and were introduced to the public in the first release of SOD. By taking advantage of each network architecture since most of them are specialized (i.e. CNNs for object classification, ANNs for pattern extraction and so forth) and stack one network on top of another, one could achieve amazing results. For example detecting & extracting facial shapes has never been easier and quick (few milliseconds) by stacking up together in a RealNets container a set of decision trees and a simple Artificial Neural Network. The life of a sod_realnet instance goes something like this:

1. Obtain a new sod_realnet handle via sod_realnet_create(). This routine is often the first API call that an application makes and is a prerequisite in order to work with the RealNets layer.
2. Register one or more RealNets models via sod_realnet_load_model_from_disk() or sod_realnet_load_model_from_mem(). You can already rely on pre-trained models available to download from pixlab.io/downloads or train your own RealNets models on your CPU via the training interfaces.
3. Optionally, configure your models via sod_realnet_model_config() where you can tune parameters like detection threshold values, minimum & maximum window size, scale & stride factors and so on.
4. Optionally, prepare the input grayscale sod_img object holding the target image or video frame for detection via sod_image_to_blob().
5. Perform Real-time detection via sod_realnet_detect().
6. Consume the network output which is returned as an array of bounding boxes via an instance of sod_box. You are invited to take a look at the introduction course for additional information.
7. Finally, release the sod_realnet handle via sod_realnet_destroy().

Notice that RealNets are designed to analyze & extract useful information from video stream rather than static images thanks to their fast processing speed (less than 10 milliseconds on 1920*1080 HD stream) and low memory footprint making them suitable for use on mobile devices. You are encouraged to connect the RealNets APIs with the OpenCV Video capture interfaces or any proprietary Video capture API to see them in action.

• sod_img

typedef struct sod_img sod_img;
struct sod_img {
	int h;   /* Image/frame height */
	int w;   /* Image/frame width */
	int c;   /* Image depth/Total number of color channels e.g. 1 for grayscale images, 3 RGB, etc. */
	float *data; /* Blob */
};

Internally, each in-memory representation of an input image or video frame is kept in an instance of the sod_img structure. Basically, a sod_img is just a record of the width, height and number of color channels in an image, and also the pixel values for every pixel. Images pixels are arranged in CHW format. This means in a 3 channel image with width 400 and height 300, the first 400 values are the 1st row of the 1st channel of the image. The second 400 pixels are the 2nd row. after 120,000 values we get to pixels in the 2nd channel, and so forth.

Practically, all the exported interfaces deal with a sod_img instance and over 70 interfaces provide advanced image/frame processing routines. These includes sod_canny_edge_image(), sod_hilditch_thin_image(), sod_hough_lines_detect() , sod_image_find_blobs(), sod_otsu_binarize_image(), sod_crop_image(), sod_resize_image(), sod_dilate_image(), sod_image_draw_bbox() and so forth. You are invited to take a look at the list of image processing interfaces for their complete documentation.

A sod_img can be loaded from disk via sod_img_load_from_file(), from memory (i.e. network socket) using sod_img_load_from_mem() or dynamically created via sod_make_image(). An OpenCV compile-time directive is provided to help you integrate OpenCV with SOD. When enabled, primitives such as sod_img_load_cv_ipl(), sod_img_load_from_cv_stream() and so on are available to call. This let you record video frames from external sources such as your Webcam, CCTV , etc. and convert them back to a working sod_img instance.

Raw pixels values can be manipulated via a set of public interfaces such as sod_img_add_pixel(), sod_img_get_pixel(), sod_img_set_pixel(), etc. or directly via the data pointer member of this structure. In that case, you have to be careful of the target pixel location that must be in range unlike the exposed public interfaces that take care of checking range location for you.

• sod_box

typedef struct sod_box sod_box;
struct sod_box {
	int x;  /* The x-coordinate of the upper-left corner of the rectangle */
	int y;  /* The y-coordinate of the upper-left corner of the rectangle */
	int w;  /* Rectangle width */
	int h;  /* Rectangle height */
	float score;       /* Confidence threshold. A value between 0..1 */
	const char *zName; /* Detected object name. I.e. person, face, dog, car, plane, cat, bicycle, etc. */
	void *pUserData;   /* External pointer used by some modules such as the face landmarks, NSFW classifier, pose estimator, etc. */
};

A bounding box or bbox for short is represented by an instance of the sod_box structure. A sod_box instance always store the coordinates of a rectangle obtained from a prior successful call to one of the object detection routines of a sod_cnn or sod_realnet handle such as sod_cnn_predict() or from the connected component labeling interface sod_image_find_blobs(). Besides the rectangle coordinates, the zName and score fields member of this structure hold useful information about the object it surround.

Finally, the drawing interfaces sod_image_draw_bbox(), sod_image_draw_bbox_width(), sod_image_draw_box(), sod_image_draw_box_grayscale() or sod_crop_image() let you draw/extract a rectangle on/from an input image using the sod_box coordinates.

• sod_pts

typedef struct sod_pts sod_pts;
struct sod_pts {
	int x; /* The x-coordinate, in logical units of the point offset. */
	int y; /* The y-coordinate, in logical units of the point offset. */
};

An instance of the sod_pts structure describe a 2D point in space with integer coordinates (usually zero-based). This structure is rarely manipulated by SOD and is used mostly by the Hough line detection interface sod_hough_lines_detect() and line drawing routine sod_image_draw_line().

• sod_realnet_trainer

typedef struct sod_realnet_trainer sod_realnet_trainer;

An instance of sod_realnet_trainer is used for training RealNet models on a modern CPU. The life of this handle goes as follows:

• Prepare your dataset (positive, negative and test samples) for example for a standard object detection purpose.
• Allocate and initialize a new sod_realnet_trainer instance via sod_realnet_train_init().
• Configure this instance via sod_realnet_train_config() by specifying a log consumer callback and the path where the RealNet output model should be stored.
• Start the training phase via sod_realnet_train_start() and pass your training instructions (i.e. where the dataset is located, minimal tree depth and so on).
• Finally, depending on how big your dataset is, wait some days until training is complete and release this instance via sod_realnet_train_release().

• sod_realnet_model_handle

typedef unsigned int sod_realnet_model_handle;

Since Realnets are just container for various neural networks architecture, each loaded & registered network is given an unique ID returned via calls to sod_realnet_load_model_from_mem() or sod_realnet_load_model_from_disk(). With this in hand, you can configure your network via sod_realnet_model_config() by passing the handle ID which uniquely identify the target network to configure.

Compile-Time Directives

For most purposes, SOD can be built just fine using the default compilation options. However, if required, the compile-time options documented below can be used to omit SOD features such as the CNN/RNN layer which consume a lot of memory or to integrate SOD with other libraries such as OpenCV. Every effort has been made to ensure that the various combinations of compilation options work harmoniously and produce a working library.

• SOD_NO_MMAP

Introduced in version 1.1.9
If this directive is defined, memory mapping is omitted from the build. This is particularly useful for restricted embedded devices lacking memory mapping.

• SOD_DISABLE_REALNET

Introduced in version 1.1.9
If this directive is defined, the entire RealNets interfaces are omitted from the build.

• OS_OTHER

Introduced in version 1.1.9
Define this directive if you are targeting a non Windows/UNIX (Linux, Mac, BSD, etc.) Operating System.

• SOD_ENABLE_OPENCV

If this directive is defined, built-in OpenCV integration interfaces such as sod_img_load_cv_ipl(), sod_img_load_from_cv(), sod_img_load_from_cv_stream(), sod_img_fill_from_cv_stream(), sod_img_save_to_cv_jpg() are included in the build. In which case, you need to link your code against OpenCV and adjust the OpenCV include paths accordingly.

• SOD_DISABLE_IMG_READER

If this directive is defined, all built-in image reading interfaces such as sod_img_load_from_file(), sod_img_load_from_mem(), sod_img_set_load_from_directory(), etc. are omitted from the build. In which case, you have to rely on your own code to read images from external sources and convert them back to a working sod_img object.

• SOD_DISABLE_IMG_WRITER

If this directive is defined, all built-in image writing interfaces such as sod_img_save_as_png() or sod_img_blob_save_as_png() are omitted from the build. In which case, you have to rely on your own code (take a look at the OpenCV integration interfaces) to write a sod_img object back to an external source.

• SOD_DISABLE_CNN

If this directive is defined, the entire CNN/RNN layer and its exported interfaces such as sod_cnn_create(), sod_cnn_predict(), etc. are completely omitted from the build. You are aware that a CNN is a memory & CPU hog. The smallest CNN detection model consume about 75 ~ 160MB of RAM unlike the RealNet architecture which is memory efficient. In some cases where resources is limited, this directive is of particular interest if you want a small library footprint.

• SOD_ENABLE_NET_TRAIN

If this directive is defined, the RealNet training interfaces are included in the build. You'll be able to train your own RealNet models on the CPU using just few calls and your training dataset. RealNets training interfaces are documented here.