Tizen Native API  7.0
Media Vision 3D

3D Depth and PointCloud Process.

Required Header

#include <mv_3d.h>

Related Features

This API is related with the following features:

  • http://tizen.org/feature/vision.3d
  • http://tizen.org/feature/vision.3d.depth
  • http://tizen.org/feature/vision.3d.pointcloud

It is recommended to design feature related codes in your application for reliability.
You can check if a device supports the related features for this API by using System Information, thereby controlling the procedure of your application.
To ensure your application is only running on the device with specific features, please define the features in your manifest file using the manifest editor in the SDK.
More details on featuring your application can be found from Feature Element.

Overview

Media Vision 3D contains mv_3d_h handle to perform Depth and PointCloud process. 3D handle should be created with mv_3d_create() function and destroyed with mv_3d_destroy() function. mv_3d_h should be configured by calling mv_3d_configure() function. After configuration, callback functions for depth and pointcloud should be set to mv_3d_h. To get depth, callback mv_3d_depth_cb() should be set by mv_3d_set_depth_cb() function. To get pointcloud, callback mv_3d_pointcloud_cb() should be set by mv_3d_set_pointcloud_cb() function. After setting callbacks, mv_3d_h should be prepared by calling mv_3d_prepare() function which initializes depth and pointcloud process. After preparation, mv_3d_run() has to be called to process synchronously depth or pointcloud from mv_source_h, and callback functions will be invoked with processed depth or pointcloud. Module also contains mv_3d_run_async() functions to process depth or pointcloud asynchronously.

Functions

int mv_3d_create (mv_3d_h *mv3d)
 Creates mv3d handle.
int mv_3d_destroy (mv_3d_h mv3d)
 Destroys mv3d handle and release all its resources.
int mv_3d_configure (mv_3d_h mv3d, mv_engine_config_h engine_config)
 Configures handle.
int mv_3d_prepare (mv_3d_h mv3d)
 Prepares handle.
int mv_3d_set_depth_cb (mv_3d_h mv3d, mv_3d_depth_cb depth_cb, void *user_data)
 Sets mv_3d_depth_cb() callback.
int mv_3d_set_pointcloud_cb (mv_3d_h mv3d, mv_3d_pointcloud_cb pointcloud_cb, void *user_data)
 Sets mv_3d_pointcloud_cb() callback.
int mv_3d_run (mv_3d_h mv3d, mv_source_h source, mv_source_h source_extra, mv_source_h color)
 Gets depth or pointcloud synchronously from given source or source_extra.
int mv_3d_run_async (mv_3d_h mv3d, mv_source_h source, mv_source_h source_extra, mv_source_h color)
 Gets depth or pointcloud asynchronously from given source or source_extra.
int mv_3d_pointcloud_write_file (mv_3d_h mv3d, mv_3d_pointcloud_h pointcloud, mv_3d_pointcloud_type_e type, char *filename)
 Writes pointcloud data to a file.

Typedefs

typedef void(* mv_3d_depth_cb )(mv_source_h source, unsigned short *depth, unsigned int width, unsigned int height, void *user_data)
 Invoked when depth is ready.
typedef void(* mv_3d_pointcloud_cb )(mv_source_h source, mv_3d_pointcloud_h pointcloud, void *user_data)
 Invoked when pointcloud is ready.
typedef void * mv_3d_h
 The mv3d handle.
typedef void * mv_3d_pointcloud_h
 The pointcloud result handle.

Defines

#define MV_3D_DEPTH_MODE   "MV_3D_DEPTH_MODE"
 Defines MV_3D_DEPTH_MODE to set the engine configuration. Use mv_3d_depth_mode_e for a value.
#define MV_3D_DEPTH_WIDTH   "MV_3D_DEPTH_WIDTH"
 Defines MV_3D_DEPTH_WIDTH to set the engine configuration.
#define MV_3D_DEPTH_HEIGHT   "MV_3D_DEPTH_HEIGHT"
 Defines MV_3D_DEPTH_HEIGHT to set the engine configuration.
#define MV_3D_DEPTH_MIN_DISPARITY   "MV_3D_DEPTH_MIN_DISPARITY"
 Defines MV_3D_DEPTH_MIN_DISPARITY to set the engine configuration.
#define MV_3D_DEPTH_MAX_DISPARITY   "MV_3D_DEPTH_MAX_DISPARITY"
 Defines MV_3D_DEPTH_MAX_DISPARITY to set the engine configuration.
#define MV_3D_DEPTH_STEREO_CONFIG_FILE_PATH   "MV_3D_DEPTH_STEREO_CONFIG_FILE_PATH"
 Defines MV_3D_DEPTH_STEREO_CONFIG_FILE_PATH to set the stereo configuration file path to the engine configuration.
#define MV_3D_POINTCLOUD_OUTPUT_FILE_PATH   "MV_3D_POINTCLOUD_OUTPUT_FILE_PATH"
 Defines MV_3D_POINTCLOUD_OUTPUT_FILE_PATH to set the output file path to the engine configuration.
#define MV_3D_POINTCLOUD_SAMPLING_RATIO   "MV_3D_POINTCLOUD_SAMPLING_RATIO"
 Defines MV_3D_POINTCLOUD_SAMPLING_RATIO to set the downsampling ratio to the engine configuration.
#define MV_3D_POINTCLOUD_OUTLIER_REMOVAL_POINTS   "MV_3D_POINTCLOUD_OUTLIER_REMOVAL_POINTS"
 Defines MV_3D_POINTCLOUD_OUTLIER_REMOVAL_POINTS to set the criteria number of outlier removal points to the engine configuration.
#define MV_3D_POINTCLOUD_OUTLIER_REMOVAL_RADIUS   "MV_3D_POINTCLOUD_OUTLIER_REMOVAL_RADIUS"
 Defines MV_3D_POINTCLOUD_OUTLIER_REMOVAL_RADIUS to set the outlier removal radius to the engine configuration.

Define Documentation

#define MV_3D_DEPTH_HEIGHT   "MV_3D_DEPTH_HEIGHT"

Defines MV_3D_DEPTH_HEIGHT to set the engine configuration.

Since :
7.0
#define MV_3D_DEPTH_MAX_DISPARITY   "MV_3D_DEPTH_MAX_DISPARITY"

Defines MV_3D_DEPTH_MAX_DISPARITY to set the engine configuration.

Since :
7.0
#define MV_3D_DEPTH_MIN_DISPARITY   "MV_3D_DEPTH_MIN_DISPARITY"

Defines MV_3D_DEPTH_MIN_DISPARITY to set the engine configuration.

Since :
7.0
#define MV_3D_DEPTH_MODE   "MV_3D_DEPTH_MODE"

Defines MV_3D_DEPTH_MODE to set the engine configuration. Use mv_3d_depth_mode_e for a value.

Since :
7.0
#define MV_3D_DEPTH_STEREO_CONFIG_FILE_PATH   "MV_3D_DEPTH_STEREO_CONFIG_FILE_PATH"

Defines MV_3D_DEPTH_STEREO_CONFIG_FILE_PATH to set the stereo configuration file path to the engine configuration.

Since :
7.0
#define MV_3D_DEPTH_WIDTH   "MV_3D_DEPTH_WIDTH"

Defines MV_3D_DEPTH_WIDTH to set the engine configuration.

Since :
7.0
#define MV_3D_POINTCLOUD_OUTLIER_REMOVAL_POINTS   "MV_3D_POINTCLOUD_OUTLIER_REMOVAL_POINTS"

Defines MV_3D_POINTCLOUD_OUTLIER_REMOVAL_POINTS to set the criteria number of outlier removal points to the engine configuration.

Since :
7.0
#define MV_3D_POINTCLOUD_OUTLIER_REMOVAL_RADIUS   "MV_3D_POINTCLOUD_OUTLIER_REMOVAL_RADIUS"

Defines MV_3D_POINTCLOUD_OUTLIER_REMOVAL_RADIUS to set the outlier removal radius to the engine configuration.

Since :
7.0
#define MV_3D_POINTCLOUD_OUTPUT_FILE_PATH   "MV_3D_POINTCLOUD_OUTPUT_FILE_PATH"

Defines MV_3D_POINTCLOUD_OUTPUT_FILE_PATH to set the output file path to the engine configuration.

Since :
7.0
#define MV_3D_POINTCLOUD_SAMPLING_RATIO   "MV_3D_POINTCLOUD_SAMPLING_RATIO"

Defines MV_3D_POINTCLOUD_SAMPLING_RATIO to set the downsampling ratio to the engine configuration.

Since :
7.0

Typedef Documentation

typedef void(* mv_3d_depth_cb)(mv_source_h source, unsigned short *depth, unsigned int width, unsigned int height, void *user_data)

Invoked when depth is ready.

This callback is invoked each time when mv_3d_run() or mv3d_run_async() is called to report estimated depth from given source(s).

Since :
7.0
Remarks:
The source is available until it is released by mv_destroy_source(). The depth can be used only in the callback. To use outside, make a copy. The depth is managed by the platform and should not be freed.
Parameters:
[in]sourceThe handle to the source of the media where the depth data comes from
[in]depthThe pointer of the depth data
[in]widthThe width of depth
[in]heightThe height of depth
[in]user_dataThe user data passed from callback invoking code
Precondition:
Call mv_3d_run() or mv_3d_run_async() function to get depth data and to invoke this callback as a result
See also:
mv_3d_run()
mv_3d_run_async()
typedef void* mv_3d_h

The mv3d handle.

Since :
7.0
typedef void(* mv_3d_pointcloud_cb)(mv_source_h source, mv_3d_pointcloud_h pointcloud, void *user_data)

Invoked when pointcloud is ready.

This callback is invoked each time when mv_3d_run() or mv3d_run_async() is called to report estimated pointcloud from given source(s).

Since :
7.0
Remarks:
The source is available until it is released by mv_destroy_source(). The pointcloud can be used only in the callback. To use outside, make a copy. The pointcloud is managed by the platform and should not be freed.
Parameters:
[in]sourceThe handle to the source of the media where the pointcloud data comes from
[in]pointcloudThe pointer of the pointcloud result
[in]user_dataThe user data passed from callback invoking code
Precondition:
Call mv_3d_run() or mv_3d_run_async() function to get pointcloud data and to invoke this callback as a result
See also:
mv_3d_run()
mv_3d_run_async()
typedef void* mv_3d_pointcloud_h

The pointcloud result handle.

Since :
7.0

Enumeration Type Documentation

Enumeration for mv3d depth mode.

Since :
7.0
Enumerator:
MV_3D_DEPTH_MODE_NONE 

NONE

MV_3D_DEPTH_MODE_STEREO 

Stereo images are used

Enumeration for mv3d pointcloud file format type.

Since :
7.0
Enumerator:
MV_3D_POINTCLOUD_TYPE_PCD_TXT 

PointCloudData format as text

MV_3D_POINTCLOUD_TYPE_PCD_BIN 

PointCloudData format as binary

MV_3D_POINTCLOUD_TYPE_PLY_TXT 

Polygon format as text

MV_3D_POINTCLOUD_TYPE_PLY_BIN 

Polygon format as binary


Function Documentation

int mv_3d_configure ( mv_3d_h  mv3d,
mv_engine_config_h  engine_config 
)

Configures handle.

Use this function to configure parameters of the mv3d which is set to engine_config.

Since :
7.0
Parameters:
[in]mv3dThe handle to the mv3d
[in]engine_configThe handle to the configuration of engine
Returns:
0 on success, otherwise a negative error value
Return values:
MEDIA_VISION_ERROR_NONESuccessful
MEDIA_VISION_ERROR_NOT_SUPPORTEDNot supported
MEDIA_VISION_ERROR_INVALID_PARAMETERInvalid parameter
Precondition:
Create mv3d handle by using mv_3d_create()
Create engine_config handle by using mv_create_engine_config()
See also:
mv_3d_create()
mv_create_engine_config()
int mv_3d_create ( mv_3d_h mv3d)

Creates mv3d handle.

Since :
7.0
Remarks:
The mv3d should be released using mv_3d_destroy() if there is no more usage of mv3d.
Parameters:
[out]mv3dThe created mv3d handle
Returns:
0 on success, otherwise a negative error value
Return values:
MEDIA_VISION_ERROR_NONESuccessful
MEDIA_VISION_ERROR_NOT_SUPPORTEDNot supported
MEDIA_VISION_ERROR_INVALID_PARAMETERInvalid parameter
See also:
mv_3d_destroy()
int mv_3d_destroy ( mv_3d_h  mv3d)

Destroys mv3d handle and release all its resources.

Since :
7.0
Parameters:
[in]mv3dThe handle to the mv3d to be destroyed
Returns:
0 on success, otherwise a negative error value
Return values:
MEDIA_VISION_ERROR_NONESuccessful
MEDIA_VISION_ERROR_NOT_SUPPORTEDNot supported
MEDIA_VISION_ERROR_INVALID_PARAMETERInvalid parameter
Precondition:
Create mv3d handle by using mv_3d_create()
See also:
mv_3d_create()
int mv_3d_pointcloud_write_file ( mv_3d_h  mv3d,
mv_3d_pointcloud_h  pointcloud,
mv_3d_pointcloud_type_e  type,
char *  filename 
)

Writes pointcloud data to a file.

Use this function to write pointcloud data to a file.

Since :
7.0
Remarks:
The mediastorage privilege http://tizen.org/privilege/mediastorage is needed if filename is relevant to media storage.
The externalstorage privilege http://tizen.org/privilege/externalstorage is needed if filename is relevant to external storage.
Parameters:
[in]mv3dThe handle to the mv3d
[in]pointcloudThe handle to the pointcloud
[in]typeThe file format type to be written
[in]filenameThe filename to save pointcloud
Returns:
0 on success, otherwise a negative error value
Return values:
MEDIA_VISION_ERROR_NONESuccessful
MEDIA_VISION_ERROR_NOT_SUPPORTEDNot supported
MEDIA_VISION_ERROR_INVALID_PARAMETERInvalid parameter
MEDIA_VISION_ERROR_PERMISSION_DENIEDPermission denied
MEDIA_VISION_ERROR_INVALID_PATHInvalid path
Precondition:
Create mv3d handle by using mv_3d_create()
Create engine_config handle by using mv_create_engine_config()
Configure mv3d handle by using mv_3d_configure()
See also:
mv_3d_create()
mv_create_engine_config()
mv_3d_configure()
int mv_3d_prepare ( mv_3d_h  mv3d)

Prepares handle.

Since :
7.0
Parameters:
[in]mv3dThe handle to the mv3d
Returns:
0 on success, otherwise a negative error value
Return values:
MEDIA_VISION_ERROR_NONESuccessful
MEDIA_VISION_ERROR_NOT_SUPPORTEDNot supported
MEDIA_VISION_ERROR_INVALID_PARAMETERInvalid parameter
MEDIA_VISION_ERROR_INVALID_OPERATIONInvalid operation
Precondition:
Configure mv3d handle by using mv_3d_configure()
See also:
mv_3d_configure()
int mv_3d_run ( mv_3d_h  mv3d,
mv_source_h  source,
mv_source_h  source_extra,
mv_source_h  color 
)

Gets depth or pointcloud synchronously from given source or source_extra.

Use this function to get depth data. source_extra can be null if source is a stereoscopic format media, for example a left and a right media are concatenated as a side-by-side format and then it should be given to source but source_extra should be null. source_extra should not be null if source is a mono format media or a single side/channel of a stereoscopic format, for example a left and a right media are separated and then they should be given to source and source_extra, respectively. color may not be null if pointcloud data includes color.

Since :
7.0
Parameters:
[in]mv3dThe handle to the mv3d
[in]sourceThe handle to the source of the media
[in]source_extraThe handle to the extra source of the media
[in]colorThe handle to the color of the media
Returns:
0 on success, otherwise a negative error value
Return values:
MEDIA_VISION_ERROR_NONESuccessful
MEDIA_VISION_ERROR_NOT_SUPPORTEDNot supported
MEDIA_VISION_ERROR_INVALID_PARAMETERInvalid parameter
Precondition:
Create a source handle by using mv_create_source()
Create a source_extra handle by using mv_create_source()
Create a mv3d handle by using mv_3d_create()
Configure a mv3d handle by using mv_3d_configure()
Set depth callback to a depth handle by using mv_3d_set_depth_cb()
Prepare a mv3d handle by using mv_3d_prepare()
Postcondition:
Callback which is set by mv_3d_set_depth_cb() will be invoked to provide depth data
See also:
mv_3d_set_depth_cb()
mv_3d_depth_cb()
int mv_3d_run_async ( mv_3d_h  mv3d,
mv_source_h  source,
mv_source_h  source_extra,
mv_source_h  color 
)

Gets depth or pointcloud asynchronously from given source or source_extra.

Use this function to get depth data. source_extra can be null if source is a stereoscopic format media, for example a left and a right media are concatenated as a side-by-side format and then it should be given to source but source_extra should be null. source_extra should not be null if source is a mono format media or a single side/channel of a stereoscopic format, for example a left and a right media are separated and then they should be given to source and source_extra, respectively. color may not be null if pointcloud data includes color.

Since :
7.0
Parameters:
[in]mv3dThe handle to the mv3d
[in]sourceThe handle to the source of the media
[in]source_extraThe handle to the extra source of the media
[in]colorThe handle to the color of the media
Returns:
0 on success, otherwise a negative error value
Return values:
MEDIA_VISION_ERROR_NONESuccessful
MEDIA_VISION_ERROR_NOT_SUPPORTEDNot supported
MEDIA_VISION_ERROR_INVALID_PARAMETERInvalid parameter
Precondition:
Create a source handle by using mv_create_source()
Create a source_extra handle by using mv_create_source()
Create a mv3d handle by using mv_3d_create()
Configure a mv3d handle by using mv_3d_configure()
Set depth callback to a depth handle by using mv_3d_set_depth_cb()
Prepare a mv3d handle by using mv_3d_prepare()
Postcondition:
Callback which is set by mv_3d_set_depth_cb() will be invoked to provide depth data
See also:
mv_3d_set_depth_cb()
mv_3d_depth_cb()
int mv_3d_set_depth_cb ( mv_3d_h  mv3d,
mv_3d_depth_cb  depth_cb,
void *  user_data 
)

Sets mv_3d_depth_cb() callback.

Use this function to set mv_3d_depth_cb() callback.

Since :
7.0
Parameters:
[in]mv3dThe handle to the mv3d
[in]depth_cbThe callback which will be invoked for getting depth data
[in]user_dataThe user data passed from the code where mv_3d_run() or mv_3d_run_async() is invoked. This data will be accessible in depth_cb callback
Returns:
0 on success, otherwise a negative error value
Return values:
MEDIA_VISION_ERROR_NONESuccessful
MEDIA_VISION_ERROR_NOT_SUPPORTEDNot supported
MEDIA_VISION_ERROR_INVALID_PARAMETERInvalid parameter
Precondition:
Create mv3d handle by using mv_3d_create()
Create engine_config handle by using mv_create_engine_config()
Configure mv3d handle by using mv_3d_configure()
See also:
mv_3d_create()
mv_create_engine_config()
mv_3d_configure()
int mv_3d_set_pointcloud_cb ( mv_3d_h  mv3d,
mv_3d_pointcloud_cb  pointcloud_cb,
void *  user_data 
)

Sets mv_3d_pointcloud_cb() callback.

Use this function to set mv_3d_pointcloud_cb() callback.

Since :
7.0
Parameters:
[in]mv3dThe handle to the mv3d
[in]pointcloud_cbThe callback which will be invoked for getting pointcloud data
[in]user_dataThe user data passed from the code where mv_3d_run() or mv_3d_run_async() is invoked. This data will be accessible in pointcloud_cb callback
Returns:
0 on success, otherwise a negative error value
Return values:
MEDIA_VISION_ERROR_NONESuccessful
MEDIA_VISION_ERROR_NOT_SUPPORTEDNot supported
MEDIA_VISION_ERROR_INVALID_PARAMETERInvalid parameter
Precondition:
Create mv3d handle by using mv_3d_create()
Create engine_config handle by using mv_create_engine_config()
Configure mv3d handle by using mv_3d_configure()
See also:
mv_3d_create()
mv_create_engine_config()
mv_3d_configure()