SOD C/C++ API - Convolutional/Recurrent Neural Networks (CNN/RNN)

Syntax

int sod_cnn_create(sod_cnn **ppOut, const char *zArch, const char *zModelPath,const char **pzErr);

Description

This routine allocate, initialize, parse and load any model associated within a particular network architecture. A sod_cnn handle is usually returned in *ppOut but, if the parser is unable to allocate memory to hold the entire network or any other issues (i.e. syntax errors, invalid models, etc.), a NULL will be written into *ppOut and pzErr should describe the issue. The life of this handle is described here.
You are aware that a CNN is a memory & CPU hog. The smallest CNN detection model consume about 75 ~ 160MB of RAM at run-time so expect to handle memory failure on devices with limited resources (i.e low-end mobile devices).
This routine is often the first API call that an application makes and is a prerequisite in order to work with the CNN interfaces.

Parameters

sod_cnn    **ppOut

OUT: On success, a fresh sod_cnn handle is written into this pointer and the network is ready to perform prediction via sod_cnn_predict(). The life of this handle is described here.

const char    *zArch

Desired network architecture. 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 input this parameter process can take the following forms:

  • Disk Path: Relative or full path to a text file (i.e net.cfg, arch.txt, etc.) describing the network architecture (darknet format).
  • Buffer: In-memory buffer holding the network architecture instead of a file on disk.
  • Magic words: Pre-ready to use architectures available via magic words (they starts with a colon). This is the recommended case for most apps. You only need the associated SOD model downloadable from pixlab.io/downloads. As of this release, the following magic words are exported (See gist below for an usage example):
    Magic Word # of classes SOD model Description
    :face 1 face_cnn.sod Real-time, robust & scale invariant (i.e. frontal, inclined, small, etc.) human face detector.
    :voc 20 tiny20.sod Smallest & fastest object detection architecture pre-trained on the Pascal VOC dataset that is able to detect 20 classes of different objects including car, person, dog, bicycle, and so forth.
    :fast 20 tiny20.sod Alias for :voc
    :coco 80 tiny80.sod Small & fast object detection architecture pre-trained on the MS COCO dataset that is able to detect 80 classes of different objects including car, person, dog, bicycle, and so forth.
    :tiny80 80 tiny80.sod Alias for :coco
    :full 80 full.sod Most accurate but largest & slowest (compared to :voc or :coco) object detection architecture pre-trained on the MS COCO dataset that is able to detect 80 classes of different objects including car, person, dog, bicycle, and so forth.
    :yolo 80 full.sod Alias for :full
    :rnn - RNN models Default RNN architecture for text generation tasks. Require a text consumer callback to be installed via sod_cnn_config().
    RAM consumption, run-time performance of all the architectures exported by SOD (and many others) are described in details in the download page at pixlab.io/downloads.

const char    *zModelPath

Path to the target SOD model to be associated with the specified network architecture. A sod model is always a single file with .sod extension. Production-ready SOD models for object detection & classification, text generation, face detection, recognition & landmarks extraction, nsfw classification and so forth are available to download from pixlab.io/downloads.

const char    **pzErr

OUT/Optional: If something goes wrong during parsing, loading model or any other issue, a human readable error message is written into this pointer.

Return Value

SOD_OK is returned on success. Any other code indicates failure and pzErr should describe the issue.

Example

Checkout the introduction course, the C/C++ samples on the download page or refer to the SOD Github Repository.

See also

sod_cnn_predictsod_cnn_configsod_cnn_prepare_imagesod_cnn_get_network_sizesod_img_load_from_filesod_cnn_destroy.


Back