DUO Dense3D API

Overview

DUO Dense3D API - Depth Extraction Middleware

Part of the DUO SDK, The DUO Dense3D API provides high level algorithms for depth reconstruction. This document outlines all functionality of the DUO Dense3D API via the Dense3D library which provides a C interface paired with C++ samples.

Here is a overview of the key methods available in this API:

// Dense3D initialization
bool Dense3DOpen(Dense3DInstance *dense3D);
bool Dense3DClose(Dense3DInstance dense3D);

// Dense3D error code
bool Dense3DGetErrorCode();

// Dense3D library version
char* Dense3DGetLibVersion();

// Dense3D processing
bool Dense3DGetDepth(Dense3DInstance dense3D, uint8_t *leftImage, uint8_t *rightImage, float *disparityData, PDense3DDepth depthData);

// Dense3D exporting
bool Dense3DSavePLY(Dense3DInstance dense3D, char *plyFile);

// Get Dense3D parameters
bool GetDense3DImageSize(Dense3DInstance dense3D, uint32_t *w, uint32_t *h);
bool GetDense3DScale(Dense3DInstance dense3D, uint32_t *scale);
bool GetDense3DMode(Dense3DInstance dense3D, uint32_t *mode);
bool GetDense3DPreFilterCap(Dense3DInstance dense3D, uint32_t *val);
bool GetDense3DNumDisparities(Dense3DInstance dense3D, uint32_t *val);
bool GetDense3DSADWindowSize(Dense3DInstance dense3D, uint32_t *val);
bool GetDense3DUniqunessRatio(Dense3DInstance dense3D, uint32_t *val)
bool GetDense3DSpeckleWindowSize(Dense3DInstance dense3D, uint32_t *val);
bool GetDense3DSpeckleRange(Dense3DInstance dense3D, uint32_t *val);

// Set Dense3D parameters
bool SetDense3DLicense(Dense3DInstance dense3D, const char *val);
bool SetDense3DImageSize(Dense3DInstance dense3D, uint32_t w, uint32_t h);
bool SetDense3DCalibration(Dense3DInstance dense3D, void *stereo);
bool SetDense3DScale(Dense3DInstance dense3D, uint32_t scale);
bool SetDense3DMode(Dense3DInstance dense3D, uint32_t mode);
bool SetDense3DPreFilterCap(Dense3DInstance dense3D, uint32_t val);
bool SetDense3DNumDisparities(Dense3DInstance dense3D, uint32_t val);
bool SetDense3DSADWindowSize(Dense3DInstance dense3D, uint32_t val);
bool SetDense3DUniquenessRatio(Dense3DInstance dense3D, uint32_t val);
bool SetDense3DSpeckleWindowSize(Dense3DInstance dense3D, uint32_t val);
bool SetDense3DSpeckleRange(Dense3DInstance dense3D, uint32_t val);

Dense3DInstance

The Dense3D processor instance is a handle filled by the Dense3DOpen() and used in subsequent API calls.

void *Dense3DInstance

Methods

Dense3DOpen

Opens the Dense3D processor and fills the pointer with the Dense3DInstance handle. This function must be called before using any API functions that require Dense3DInstance parameter. (All subsequent calls use Dense3DInstance to access the processor.) The function returns true on success.

bool Dense3DOpen(Dense3DInstance *dense3D)

Dense3DClose

Closes the Dense3D processor. The function returns true on success.

bool Dense3DClose(Dense3DInstance dense3D)

Dense3DGetErrorCode

Returns the current status of the processor with errors from the Dense3DErrorCode structure.

Dense3DErrorCode *Dense3DGetErrorCode()

Dense3DGetLibVersion

Retrieves the library version as a string.

char *Dense3DGetLibVersion()

Dense3DGetDepth

Fills the user allocated Dense3DDepth array pointer with processed depth map. Requires passing of the rectified image pointers. The function returns true on success.

bool Dense3DGetDepth(Dense3DInstance dense3D, uint8_t *leftImage, uint8_t *rightImage, float *disparityData, PDense3DDepth depthData)

Dense3DSavePLY

Saves the current depth map to the user supplied plyFile file in the PLY (Polygon File Format) format. The function returns true on success.

bool Dense3DSavePLY(Dense3DInstance dense3D, char *plyFile)

Parameters

Get Parameter Functions

Used to get various parameter values from the library.

GetDense3DImageSize

Returns the width and height of the processed image. The function returns true on success.

bool GetDense3DImageSize(Dense3DInstance dense3D, uint32_t *width, uint32_t *height)

GetDense3DScale

Returns the image pre-scaling before Dense3D is being calculated. The return value is within range [0, 3] representing the following:

0 - No Scale
1 - Scale X (subsample by 2 along X)
2 - Scale Y (subsample by 2 along Y)
3 - Scale X&Y (subsample by 2 along X&Y)

The function returns true on success.

bool GetDense3DScale(dense3D, uint32_t *scale)

GetDense3DMode

Returns the Dense3D processing algorithm. The return value is within range [0, 3] representing the following:

0 - Simple block matching algorithm
1 - Semi-Global block matching algorithm
2 - Simple block matching algorithm with advanced post processing
3 - Semi-Global block matching algorithm with advanced post processing

The function returns true on success.

bool GetDense3DMode(Dense3DInstance dense3D, uint32_t *mode)

GetDense3DPreFilterCap

Fills the user supplied variable with the value used in Dense3D pre-filtering step. The function returns true on success.

bool GetDense3DPreFilterCap(Dense3DInstance dense3D, uint32_t *val)

GetDense3DNumDisparities

Fills the user supplied variable with current number of disparities. The function returns true on success.

bool GetDense3DNumDisparities(Dense3DInstance dense3D, uint32_t *val)

GetDense3DSADWindowSize

Fills the user supplied variable with current SAD window size. The function returns true on success.

bool GetDense3DSADWindowSize(Dense3DInstance dense3D, uint32_t *val)

GetDense3DUniqunessRatio

Fills the user supplied variable with current uniqueness ratio value. The function returns true on success.

bool GetDense3DUniqunessRatio(Dense3DInstance dense3D, uint32_t *val)

GetDense3DSpeckleWindowSize

Fills the user supplied variable with speckle window size. The function returns true on success.

bool GetDense3DSpeckleWindowSize(Dense3DInstance dense3D, uint32_t *val)

GetDense3DSpeckleRange

Fills the user supplied variable with current speckle range. The function returns true on success.

bool GetDense3DSpeckleRange(Dense3DInstance dense3D, uint32_t *val)

Set Parameter Functions

Used to set various parameter values from the library.

SetDense3DLicense

Set your license after calling Dense3DOpen. The function returns true on success.

bool SetDense3DLicense(Dense3DInstance dense3D, const char *val)

SetDense3DImageSize

Sets the processed image size. The function returns true on success.

bool SetDense3DImageSize(Dense3DInstance dense3D, uint32_t width, uint32_t height)

SetDense3DCalibration

Sets the active calibration data. The value that is passed here is the DUO_STEREO structure. The function returns true on success.

bool SetDense3DCalibration(Dense3DInstance dense3D, void *stereo)

SetDense3DScale

Sets the image pre-scaling. The value is within range [0, 3] representing the following:

0 - No Scale
1 - Scale X (subsample by 2 along X)
2 - Scale Y (subsample by 2 along Y)
3 - Scale X&Y (subsample by 2 along X&Y)

bool SetDense3DScale(Dense3DInstance dense3D, uint32_t scale)

SetDense3DMode

Sets the Dense3D processing algorithm. The value is within range [0, 3] representing the following:

0 - Simple block matching algorithm
1 - Semi-Global block matching algorithm
2 - Simple block matching algorithm with post processing
3 - Semi-Global block matching algorithm with post processing

bool SetDense3DMode(Dense3DInstance dense3D, uint32_t mode)

SetDense3DPreFilterCap

Set pre-filter value (range [1, 63]) The function returns true on success.

bool SetDense3DPreFilterCap(Dense3DInstance dense3D, uint32_t val)

SetDense3DNumDisparities

Sets the number of disparity steps (range [2, 16], resulting in actual [32, 256] disparity levels) The function returns true on success.

bool SetDense3DNumDisparities(Dense3DInstance dense3D, uint32_t val)

SetDense3DSADWindowSize

Set the SAD window size (range [2, 10] resulting in actual [5, 21] window sizes) The function returns true on success.

bool SetDense3DSADWindowSize(Dense3DInstance dense3D, uint32_t val)

SetDense3DUniquenessRatio

Set uniqueness ratio post-processing value (range [1, 100]) The function returns true on success.

bool SetDense3DUniquenessRatio(Dense3DInstance dense3D, uint32_t val)

SetDense3DSpeckleWindowSize

Set speckle window size post-processing value (range [0, 256]) The function returns true on success.

bool SetDense3DSpeckleWindowSize(Dense3DInstance dense3D, uint32_t val)

SetDense3DSpeckleRange

Set speckle range post-processing value (range [0, 32]) The function returns true on success.

bool SetDense3DSpeckleRange(Dense3DInstance dense3D, uint32_t val)

Structures

Dense3DDepth

Contains coordinates as floats representing the depth data (x,y,z).

typedef struct  
{
    float x;
    float y;
    float z;
}Dense3DDepth, *PDense3DDepth;

Dense3DErrorCode

Contains standard status error codes for debugging and troubleshooting.

// Dense3D error codes
enum Dense3DErrorCode
{
    DENSE3D_NO_ERROR,
    DENSE3D_INVALID_DENSE3D_INSTANCE,
    DENSE3D_ERROR_CREATING_DENSE3D_INSTANCE,
    DENSE3D_INVALID_LICENSE,
    DENSE3D_INVALID_PARAMETER,
    DENSE3D_INVALD_IMAGE_POINTER,
    DENSE3D_INVALD_DEPTH_DATA_POINTER,
    DENSE3D_INVALID_IMAGE_SIZE,
    DENSE3D_INVALD_PLY_FILE_NAME,
    DENSE3D_ERROR_EXPORTING_PLY_FILE
};

Sample Usage

You can easily integrate Dense3D into application or system by using a portable C interface that allows for full access and control to the processor.

View the sample code for creating your first application with Dense3D.

Review the samples provided with the SDK:

Generating a depth map with Dense3D Middleware

Resources

Tips

Generate your calibration files using the DUO Dashboard Calibration App.
Most API calls return a true or false if the action was successful.
Make sure you USB Hub meets requirements stated in the requirements.
Always make sure you have the latest DUO SDK, Dashboard and Driver.

Relevant articles and links: