Dali: Vision -- C API

Header Files

#include <dvmvision.h>

Constants

Return Code

These represent the possible return values from Dali vision functions. DVM_VISION_OK is returned if all goes well. The error codes are included below.

    #define DVM_VISION_OK 0
    #define DVM_NOT_BYTE_ALLIGNED -1
    #define DVM_NOT_DIFFERENT_SIZES -2
    #define DVM_BAD_HEIGHT -3
    #define DVM_USE_ALLIGN -4
    #define DVM_BAD_BLOCK_SIZE -5
    #define DVM_BAD_THRESHOLD -6
    #define DVM_BAD_NUM_PASSES -7
    #define DVM_BAD_PERCENT -8
    #define DVM_SCRATCH_SIZE_TOO_SMALL -9
    #define DVM_BAD_LOW_VAL -11
  

Miscellaneous

To avoid excessive calls to malloc and free, several vision functions allocate a scratch buffer of this size on the stack. This size works for all the currently implemented algorithms.

    #define SCRATCHSIZE 10000
  

Operators

Thresholding

int BitAdaptiveThreshold8(ByteImage *src, BitImage *dest, int blockw, int blockh, int maxVariance, int allWhite, int lowVal);

Adaptively thresholds the ByteImage src and fills in the byte aligned BitImage dest. The width and height of the window around each pixel that is examined to determine the value of the pixel are given by blockw and blockh. maxVariance is the maximum allowed variation in the pixel values beyond which pixel value distribution is considered to be bimodal. allWhite specifies the threshold such that a unimodal distribution with a mean pixel value of less than allWhite is mapped to black, otherwise to white. Finally, the lowVal is the pixel value in the bit image for pixels in the source image that are considered to be black after the thresholding. Returns DVM_BAD_THRESHOLD if allWhite does not lie between 0 and 255. Returns DVM_BAD_LOWVAL if lowVal is not 0 or 1. Returns DVM_NOT_BYTE_ALIGNED if the dest BitImage is not byte aligned.

int ByteComputeThreshold (ByteImage *srcBuf, int percent);

Return the threshold for which percent of the pixels fall below this threshold.

int BitMakeFromThreshold8 (ByteImage *src, BitImage *dest, int threshold);

Create a BitImage dest from ByteImage src, consisting of the values 0 for each pixel in src that falls below threshold, and 1 for each pixel in src that is greater than or equal to threshold. Returns NOT_BYTE_ALLIGNED if dest is not byte alligned.

int ByteMakeFromThreshold8 (ByteImage *src, ByteImage *dest, int threshold, int lowVal);

Functionally the dame as BitMakeFromThreshold8, except the destination is a ByteImage, and lowVal is either 0 or 255.

int ByteMakefromBit8 (BitImage *src, ByteImage *dest)

Converts the BitImage src to the ByteImage dest, mapping 0 to 0 and 1 to 255. Returns DVM_NOT_BYTE_ALIGNED if src is not byte aligned.

Smoothing

int ByteSmooth(ByteImage *srcBuf, ByteImage *destBuf, int numPasses)

Smooth the content of buffer srcBuf by applying the Gaussian numPasses times and write the results into destBuf. For efficiency, ByteSmooth allocates space on the stack instead of the heap, meaning a constant amount must be allocated. The constant SCRATCHSIZE defines this amount, and may need to be changed for very large byte images.

int ByteSmoothGaussian (ByteImage *src, ByteImage *dest, double sigma)

Performs a Gaussian smooth on the source ByteImage src, with a radius of sigma, and write the results to the ByteImage dest.

Edge Detection

int ByteEdgeDetectSobel (ByteImage *srcBuf, ByteImage *dest1Buf, ByteImage *dest2Buf, int percent, int *thresh1, int *thresh2)

Apply a row vector and column vector of the form [-1 0 1] to ByteImage srcBuf. The results of the row vector are written into ByteImage dest1Buf and the results of the column vector are written into dest2Buf. Output a pair of thresholds; thresh1 corresponds to the percent of pixels in dest1Buf, and thresh2 corresponds to the percent of pixels in dest2Buf.

int ByteEdgeDetectCanny(ByteImage *src, int thresh1, int thresh2, ByteImage *dest)

Apply the Canny edge detection algorithm to ByteImage src and write the results to ByteImage dest.

Morphology Operations

int BitDilateHorizontal8 (BitImage *src, BitImage *dest)

For every pixel that is set (has value 1) in the image src, the corresponding pixel in dest is set along with its left and right neighboring pixel. Returns DVM_NOT_NYTE_ALIGNED if either src or dest are not byte aligned.

int BitDilateVertical8 (BitImage *src, BitImage *dest)

Same as BitDilateHorizontal8 except the top and bottom neighbors of every pixel in src are set in dest, instead of the left and right neighbors.

int BitDilate8 (BitImage *src, BitImage *dest);

For every pixel with a value of 1 in BitImage src, set its neighboring pixels to 1, and write the results to BitImage dest. Returns NOT_BYTE_ALLIGNED if both BitImages are not byte alligned. For efficiency, BitDilate8 allocates space on the stack instead of the heap, meaning a constant amount must be allocated. The constant SCRATCHSIZE defines this amount, and may need to be changed for very large bit images.

int BitErode8 (BitImage *src, BitImage *dest)

The inverse of the dilation operation. Every pixel that is set in src, but is NOT completely surrounded by set pixels, is unset in dest. Returns DVM_NOT_BYTE_ALIGNED if either src or dest are not byte aligned.