perClass Documentation
development version 3.1.2 (22-Dec-2011)
Content

Comments? Ideas? Compliments?

Your email (only if you wish to be contacted)

perClass runtime Application Programing Interface

Table of contents

FREFLOCAL:

1. Initialization and releasing the library ↩

1.1. sd_InitKernel ↩

prkernel* sd_InitKernel(char* lic_path)

Input

  • lic_path string path to the license file. Use NULL for searching the directory where the library binary is located

Output

  • pointer to the prkernel structure or NULL when library initialization failed. Use sd_GetErrorMsg to obtain detailed description of the problem.

1.2. sd_InitKernelLicString ↩

prkernel* sd_InitKernelLicString(char* lic);

Input

  • lic pointer to a buffer with with license string

Output

  • pointer to the prkernel structure or NULL when library initialization failed. Use sd_GetErrorMsg to obtain detailed description of the problem.

1.3. sd_LicenseCheck ↩

int sd_LicenseCheck(prkernel* pk);

Input

  • pk pointer to the prkernel structure

Output

  • status of the license (SD_OK or SD_ERROR)

Description

The perClass deployment license is checked when executing the pipeline using the sd_Execute function. Because each license check incurs a small time delay (typically 30ms), the library does not perform the check for each pipeline execution but only after few tens of sd_Execute invocations. The user may call sd_LicenseCheck manually to perform the license validation before a time-critical section to avoid the delay.

1.4. sd_ReleaseKernel ↩

void sd_ReleaseKernel(prkernel* pk);

Input

  • pk pointer to the prkernel structure

Description Call sd_ReleaseKernel to release all memory allocated by the perClass runtime (all loaded pipelines and buffers allocated through library interface calls). The user is responsible for freeing all memory buffers allocated outside perClass runtime.

2. Status and error reporting ↩

2.1. sd_GetErrorMsg ↩

const char* sd_GetErrorMsg(prkernel* pk);

Input

  • pk pointer to the prkernel structure

Output

  • string with detailed description of the last error

Description

sd_GetErrorMsg returns copyritght message and version number after the runtime initialization call using either sd_InitKernel or sd_InitKernelLicString.

2.2. sd_GetErrorCode ↩

int sd_GetErrorCode(prkernel* pk);

Input

  • pk pointer to the prkernel structure

Output

  • code of the last error reported by perClass runtime

Description The error codes and messages are listed here

2.3. perClass runtime error messages ↩

2.4. #define SD_OK 0

2.5. #define SD_ERROR -1

2.6. #define SD_YES 1

2.7. #define SD_NO 0

3. Loading and releasing pipelines ↩

3.1. sd_LoadPipeline ↩

int sd_LoadPipeline(prkernel* pk, char* filename);

Input

  • pk pointer to the prkernel structure
  • filename string buffer with name of the pipeline binary file saved using sdexport command from Matlab

Output

  • zero-based pipeline index pind if successful or SD_ERROR

Description

Multiple pipelines may be loaded into one perClass runtime session (using single pk structure). The user may execute, for example, a feature extractor in one part of the application and several different classifiers in the other. The pipelines may be loaded into the perClass runtime session once and then used multiple times. All pipeline specific functions take both pk pointer structure and the pipeline index pind as the first two input arguments.

3.2. sd_LoadPipelineFromBuffer ↩

int sd_LoadPipelineFromBuffer(prkernel* pk, const char* buf);

Input

  • pk pointer to the prkernel structure
  • buf buffer with pipeline data

Output

  • zero-based pipeline index pind if successful or SD_ERROR

Description

Pipeline may be loaded from in-memory buffer. In this way, pipelines may be stored in application resources or sent over network.

3.3. sd_GetPipelineCount ↩

int sd_GetPipelineCount(prkernel* pk);

Input

  • pk pointer to the prkernel structure

Output

  • number of pipelines loaded in the perClass runtime kernel pk.

3.4. sd_GetDecName ↩

const char* sd_GetDecName(prkernel* pk,int pind,int dcode);

Input

  • pk pointer to the prkernel structure
  • pind pipeline index
  • dcode decision code

Output

  • pointer to the decision name given the decision code

4. Operations on a specific loaded pipeline ↩

4.1. sd_GetPipelineName ↩

char* sd_GetPipelineName(prkernel* pk,int pind);

Input

  • pk pointer to the prkernel structure
  • pind pipeline index

Output

  • Name of pipeline pind, set using the setname method of sdppl object

4.2. sd_GetInputFc ↩

int sd_GetInputFc(prkernel* pk,int pind);

Input

  • pk pointer to the prkernel structure
  • pind pipeline index

Output

  • input feature count for a given pipeline

4.3. sd_GetOutputFc ↩

int sd_GetOutputFc(prkernel* pk,int pind);

Input

  • pk pointer to the prkernel structure
  • pind pipeline index

Output

  • output feature count for a given pipeline

4.4. sd_GetDecCount ↩

int sd_GetDecCount(prkernel* pk,int pind);

Input

  • pk pointer to the prkernel structure
  • pind pipeline index

Output

  • number of pipeline decisions (zero for pipelines, such as feature extractors, returning general data)

4.5. sd_GetDecName ↩

const char* sd_GetDecName(prkernel* pk,int pind,int dcode);

Input

  • pk pointer to the prkernel structure
  • pind pipeline index
  • dcode decision code

Output

  • pointer to the decision name given the decision code

5. Attaching and detaching application memory to/from the pipeline ↩

5.1. sd_AttachMemToInput - Attach memory chunk allocated by the application to the pipeline input ↩

int sd_AttachMemToInput(prkernel* pk,int pind,double* ptr,int sc,int fc);

Input

  • pk pointer to the prkernel structure
  • pind pipeline index
  • ptr pointer to externally allocated data buffer
  • sc sample count
  • fc feature count

Output

  • status code (SD_OK or SD_ERROR)

Description

sd_AttachMemToInput connects the externally-allocated buffer with input data to the pipeline input. perClass 3.0 assumes sample-per-sample memory ordering where all features of the same sample are stored together in memory. In other words, offset to next feature is 1 and to next sample is fc. Sample and feature offsets, used in PRSD Studio 1.x and 2.x are not needed by sd_AttachMemToInput.

5.2. sd_AttachMemToOutput - Attach memory chunk allocated by the application to the pipeline input ↩

int sd_AttachMemToOutput(prkernel* pk,int pind,double* ptr,int sc,int fc);

Input

  • pk pointer to the prkernel structure
  • pind pipeline index
  • ptr pointer to externally allocated data buffer
  • sc sample count
  • fc feature count

Output

  • status code (SD_OK or SD_ERROR)

Description

sd_AttachMemToOutput connects the externally-allocated results buffer to the pipeline output.

The function assumes that memory represents a set of data samples stored in such a way that the offset to the next feature is 1 and offset to the next sample is fc (the number of features).

5.3. sd_BufAttachToInput - Attach buffer object to the pipeline input (see below for data buffer object) ↩

int sd_BufAttachToInput(prkernel* pk,int pind,prbuf* pb);

Input

  • pk pointer to the prkernel structure
  • pind pipeline index
  • pb pointer to the prbuf object

Output

  • status code (SD_OK or SD_ERROR)

Description sd_BufAttachToInput connects the externally-allocated input buffer object pb to the pipeline input. The buffer may be detached from the pipeline using sd_DetachInput.

5.4. sd_BufAttachToOutput - Attach buffer object to the pipeline output (see below for data buffer object) ↩

int sd_BufAttachToOutput(prkernel* pk,int pind,prbuf* pb);

Input

  • pk pointer to the prkernel structure
  • pind pipeline index
  • pb pointer to the prbuf object

Output

  • status code (SD_OK or SD_ERROR)

Description

sd_BufAttachToOutput connects the externally-allocated buffer object pb to the pipeline output. The buffer may be detached from the pipeline using sd_DetachInput.

5.5. sd_DetachInput - Detach memory attached to the pipeline input ↩

int sd_DetachInput(prkernel* pk,int pind);

Input

  • pk pointer to the prkernel structure
  • pind pipeline index

Output

  • status code (SD_OK or SD_ERROR)

Description

sd_DetachInput disconnects the memory attached to the pipeline input. User is responsible for freeing the memory he/she allocated.

5.6. sd_DetachOutput - Detach memory attached to the pipeline input ↩

int sd_DetachOutput(prkernel* pk,int pind);

Input

  • pk pointer to the prkernel structure
  • pind pipeline index

Output

  • status code (SD_OK or SD_ERROR)

Description

sd_DetachOutput disconnects the memory attached to the pipeline output. User is responsible for freeing the memory he/she allocated.

6. Pipeline execution ↩

6.1. sd_IsReadyToExecute ↩

int sd_IsReadyToExecute(prkernel* pk,int pind);

Input

  • pk pointer to the prkernel structure
  • pind pipeline index

Output

  • SD_YES or SD_NO indicating whether pipeline is connected to application input and output buffers.

Description

Call sd_IsReadyToExecute to test if some input and output application buffers are connected to the pipeline.

6.2. sd_Execute ↩

int sd_Execute(prkernel* pk,int pind);

Input

  • pk pointer to the prkernel structure
  • pind pipeline index

Output

  • SD_OK if successful

Description

sd_Execute runs the pipeline pind on the data from application buffer attached to pipeline input and places results into the result buffer attached to pipeline output. In order to execute on new batch of data, it is sufficient to place new values into the input buffer and re-run sd_Execute (the attach routines are not needed if the input/output buffers don't change)

6.3. sd_SetOp Set classifier to a specific operating point ↩

int sd_SetOp(prkernel* pk,int pind,int cind,int opind);

Input

  • pk pointer to the prkernel structure
  • pind pipeline index
  • cind index of a classifier within the pipeline pind
  • opind index of an operating point in the classifier cind

Output

  • status (SD_OK or SD_ERROR)

Description

sd_SetOp allows one to change operating points in a pipeline between sd_Execute calls. Single pipeline may contain multiple classifiers each with its own set of operating points (e.g. the cascade pipeline with a detector and discriminant).

7. Data buffers ↩

7.1. sd_BufNew Allocate memory buffer ↩

prbuf* sd_BufNew(int type,int sc,int fc);

Input

  • type of data (SDDOUBLE, SDSINGLE or SD_INT)
  • sc number of allocated samples
  • fc number of features

Output

  • pb pointer to a prbuf buffer object

7.2. sd_BufNewReferringTo - Create buffer refering to existing application memory chunk ↩

prbuf* sd_BufNewReferringTo(int type, void* data,int sc,int fc,int so,int fo);

Input

  • type of data (SDDOUBLE, SDSINGLE, SD_INT)
  • data pointer to data buffer
  • sc number of samples
  • fc number of features

Output

  • pb pointer to a prbuf buffer object

Description

sd_BufNewReferringTo constructs a buffer object representing a memory area allocated by the application. Releasing this memory after destructing the buffer object using sd_BufFree is user's responsibility. The function assumes sample-per-sample memory scheme (all features of the same sample are stored together).

7.3. sd_BufLoadFromCSVFile - Allocate a buffer and fill it with data from a comma-separated file ↩

prbuf* sd_BufLoadFromCSVFile(char* filename);

Input

  • filename pointer to string buffer with file name

Output

  • pb pointer to a prbuf buffer object

Description

sd_BufLoadFromCSVFile constructs a buffer object from comma-separated file.

7.4. sd_BufFree - Free a buffer ↩

void sd_BufFree(prbuf* pb);

Input

  • pb a buffer object

Description

sd_BufFree releases the buffer object. The underlying memory area is freed only if it was allocated by the perClass runtime. This holds for buffers created using sd_BufNew and sd_BufLoadFromCSVFile functions. It is user's responsibility to free the memory passed to the sd_BufNewReferringTo call.

7.5. sd_BufGetSc - Return the number of samples in a buffer ↩

int sd_BufGetSc(prbuf* pb);

Input

  • pb a buffer object

Output

  • number of samples in the buffer

Description sd_BufGetSc returns the number of samples stored in the buffer pb. By default, this is the allocated number of samples. User may, set the actual number of buffer samples using sd_BufSetSc.

7.6. sd_BufSetSc - Set the number of actual samples in the allocated buffer ↩

Input

  • pb a buffer object
  • sc actual number of samples

Output

  • status (SD_OK or SD_ERROR)

Description

sd_BufSetSc allows one to set the number of actual samples stored in the buffer which is smaller or equal than the allocated number of samples.

7.7. sd_BufGetFc - Return the number of features in a buffer ↩

int sd_BufGetFc(prbuf* pb)

Input

  • pb a buffer object

Output

  • number of buffer features

8. Getting/Setting values in a buffer ↩

8.1. sd_BufGetValueDouble ↩

double sd_BufGetValueDouble(prbuf* pb,int sample,int feature)

Input

  • pb a buffer object
  • sample index
  • feature index

Output

  • value from the buffer object

8.2. sd_BufGetValueSingle ↩

double sd_BufGetValueSingle(prbuf* pb,int sample,int feature)

Input

  • pb a buffer object
  • sample index
  • feature index

Output

  • value from the buffer object

8.3. sd_BufGetValueInt ↩

double sd_BufGetValueInt(prbuf* pb,int sample,int feature)

Input

  • pb a buffer object
  • sample index
  • feature index

Output

  • value from the buffer object

8.4. sd_BufSetValueDouble ↩

void sd_BufSetValueDouble(prbuf* pb,int sample,int feature,double value)

Input

  • pb a buffer object
  • sample index
  • feature index
  • value

8.5. sd_BufSetValueSingle ↩

void sd_BufSetValueSingle(prbuf* pb,int sample,int feature,float value)

Input

  • pb a buffer object
  • sample index
  • feature index
  • value

8.6. sd_BufSetValueInt ↩

void sd_BufSetValueInt(prbuf* pb,int sample,int feature,int value)

Input

  • pb a buffer object
  • sample index
  • feature index
  • value

9. Cross-platform precision timers ↩

9.1. sd_Tic - Start precision timer ↩

void sd_Tic(prkernel* pk)

Input

  • pk pointer to the prkernel structure

sd_Tic starts a precision timer. Subsequent call to sd_Toc returns the time in seconds. Precision timer is used for each supported platform. The sd_Tic and sd_Toc calls are not reentrant i.e. should not be nested or called cuncurently from different threads.

9.2. sd_Toc - Stop precision timer ↩

double sd_Toc(prkernel* pk)

Input

  • pk pointer to the prkernel structure

Output

  • time in seconds since last cal of sd_Tic
(c) 2007-2011, PR Sys Design