DUO Dense3DMT API - Depth Extraction Middleware
Part of the DUO SDK, The DUO Dense3DMT API provides high level, multi-threaded implementation of algorithms for depth reconstruction. This document outlines all functionality of the DUO Dense3DMT API via the Dense3DMT 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(Dense3DMTInstance *dense3D, uint32_t index = 0); bool Dense3DClose(Dense3DMTInstance dense3D); // Dense3D error code bool Dense3DGetErrorCode(); // Dense3D library version char* Dense3DGetLibVersion(); // Returns the DUO instance associated with Dense3D DUOInstance GetDUOInstance(Dense3DMTInstance dense3d); // Dense3D frame callback function // NOTE: This function is called in the context of the Dense3D thread. // To prevent any dropped frames, this function must return as soon as possible. typedef void (CALLBACK *Dense3DFrameCallback)(const PDense3DFrame pFrameData, void *pUserData); // Dense3D capture control bool Dense3DStart(Dense3DMTInstance dense3D, Dense3DFrameCallback frameCallback, void *pUserData); bool Dense3DStop(Dense3DMTInstance dense3D); // Dense3D exporting bool Dense3DSavePLY(Dense3DMTInstance dense3D, char *plyFile, const PDense3DFrame pFrameData); // Get Dense3D parameters bool GetDense3DImageInfo(Dense3DMTInstance dense3D, uint32_t *width, uint32_t *height, double *fps); bool GetDense3Params(Dense3DMTInstance dense3D, Dense3DParams *params); // Set Dense3D parameters bool SetDense3DLicense(Dense3DMTInstance dense3D, const char *val); bool SetDense3DImageInfo(Dense3DMTInstance dense3D, uint32_t width, uint32_t height, double fps); bool SetDense3Params(Dense3DMTInstance dense3D, Dense3DParams params); bool SetDense3DProcessing(Dense3DMTInstance dense3d, bool enable);
The Dense3DMT processor instance is a handle filled by the Dense3DOpen() and used in subsequent API calls.
void *Dense3DMTInstance
Opens the Dense3D processor and fills the pointer with the Dense3DMTInstance handle. This function must be called before using any API functions that require Dense3DMTInstance parameter. The index parameter specifies the zero based index of the camera to be opened (in case of using multiple DUO devices). (All subsequent calls use Dense3DMTInstance to access the processor.) Internally this function will open an instance of DUO. You can get the associated DUOInstance by calling GetDUOInstance().
The function returns true on success.
bool Dense3DOpen(Dense3DMTInstance *dense3D, uint32_t index = 0)
Closes the Dense3D processor. The function returns true on success.
bool Dense3DClose(Dense3DMTInstance dense3D)
Returns the current status of the processor with errors from the Dense3DErrorCode structure.
Dense3DErrorCode *Dense3DGetErrorCode()
Retrieves the library version as a string.
char *Dense3DGetLibVersion()
User defined callback function that is called by Demse3DMT framework on every processed frame. The function passes Dense3DFrame pointer to the user. The Dense3DFrame contains the resulting disparity and depth data as well as the corresponding DUOFrame.
bool Dense3DFrameCallback(const PDense3DFrame pFrameData, void *pUserData)
Starts the Dense3DMT processor. The user passes the callback function as well as the optional pUserData pointer that will be passed back to user via Dense3DFrameCallback function. The function returns true on success.
bool Dense3DStart(Dense3DMTInstance dense3D, Dense3DFrameCallback frameCallback, void *pUserData)
Stops the Dense3DMT processor. The function returns true on success.
bool Dense3DStop(Dense3DMTInstance dense3D)
Saves the PDense3DFrame depth map to the user supplied plyFile file in the PLY (Polygon File Format) format. The function returns true on success.
bool Dense3DSavePLY(Dense3DMTInstance dense3D, char *plyFile, const PDense3DFrame pFrameData);
Returns the DUOInstance assiciated with Dense3DMTInstance. The function returns NULL on error.
DUOInstance GetDUOInstance(Dense3DMTInstance dense3D);
Used to get various parameter values from the library.
Returns the selected width, height and frame rate. The function returns true on success.
bool GetDense3DImageSize(Dense3DMTInstance dense3D, uint32_t *width, uint32_t *height, double *fps)
Fills the user provided Dense3DParams structure with current Dense3DMT values. The function returns true on success.
bool GetDense3Params(Dense3DMTInstance dense3D, Dense3DParams *params)
Used to set various parameter values from the library.
Set your license after calling Dense3DOpen. The function returns true on success.
bool SetDense3DLicense(Dense3DMTInstance dense3D, const char *license)
Sets the DUO and Dense3DMT image size and frame rate. The function returns true on success.
bool SetDense3DImageInfo(Dense3DMTInstance dense3D, uint32_t width, uint32_t height, double fps)
Sets the Dense3DParams parameters values used in Dense3D processing. The function returns true on success.
bool SetDense3Params(Dense3DMTInstance dense3D, Dense3DParams params)
Enables the Dense3D processing (enabled by default). The function returns true on success.
bool SetDense3Params(Dense3DMTInstance dense3D, bool enable)
Contains coordinates as floats representing the depth data (x,y,z).
typedef struct
{
float x;
float y;
float z;
}Dense3DDepth, *PDense3DDepth;
Contains the resulting data of Dense3D processing as well as corresponding DUOFrame.
typedef struct
{
PDUOFrame duoFrame; // Pointer to DUOFrame
bool dense3dDataValid; // True is Dense3D disparity and depth is valid
float *disparityData; // Dense3D disparity data
PDense3DDepth depthData; // Dense3D depth data
}Dense3DFrame, *PDense3DFrame;
Contains Dense3D processor parameters values used in Dense3D processing
typedef struct
{
uint32_t scale; // [0, 3] - [No Scale, Scale X, Scale Y, Scale X&Y]
uint32_t mode; // [0, 3] - [BM, SGBM, BM_HQ, SGBM_HQ]
uint32_t preFilterCap; // [1, 63]
uint32_t numDisparities; // [2, 16]
uint32_t sadWindowSize; // [2, 10]
uint32_t uniqenessRatio; // [1, 100]
uint32_t speckleWindowSize; // [0, 256]
uint32_t speckleRange; // [0, 32]
}Dense3DParams, *PDense3DParams;
The scale value represents the following:
The mode value represents the following:
Contains standard status error codes for debugging and troubleshooting.
// Dense3D error codes
enum Dense3DErrorCode
{
DENSE3D_NO_ERROR,
DENSE3D_ERROR_INVALID_DUO3D_INSTANCE,
DENSE3D_ERROR_COULD_NOT_START_DUO,
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
};
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:
Relevant articles and links: