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]	source	The handle to the source of the media where the depth data comes from
[in]	depth	The pointer of the depth data
[in]	width	The width of depth
[in]	height	The height of depth
[in]	user_data	The 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]	source	The handle to the source of the media where the pointcloud data comes from
[in]	pointcloud	The pointer of the pointcloud result
[in]	user_data	The 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

enum mv_3d_depth_mode_e

Enumeration for mv3d depth mode.

Since :: 7.0

Enumerator:

MV_3D_DEPTH_MODE_NONE	NONE
MV_3D_DEPTH_MODE_STEREO	Stereo images are used

enum mv_3d_pointcloud_type_e

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]	mv3d	The handle to the mv3d
[in]	engine_config	The handle to the configuration of engine

Returns:: 0 on success, otherwise a negative error value

Return values:

MEDIA_VISION_ERROR_NONE	Successful
MEDIA_VISION_ERROR_NOT_SUPPORTED	Not supported
MEDIA_VISION_ERROR_INVALID_PARAMETER	Invalid 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] mv3d The created mv3d handle

Returns:: 0 on success, otherwise a negative error value

Return values:

MEDIA_VISION_ERROR_NONE	Successful
MEDIA_VISION_ERROR_NOT_SUPPORTED	Not supported
MEDIA_VISION_ERROR_INVALID_PARAMETER	Invalid 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] mv3d The handle to the mv3d to be destroyed

Returns:: 0 on success, otherwise a negative error value

Return values:

MEDIA_VISION_ERROR_NONE	Successful
MEDIA_VISION_ERROR_NOT_SUPPORTED	Not supported
MEDIA_VISION_ERROR_INVALID_PARAMETER	Invalid 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]	mv3d	The handle to the mv3d
[in]	pointcloud	The handle to the pointcloud
[in]	type	The file format type to be written
[in]	filename	The filename to save pointcloud

Returns:: 0 on success, otherwise a negative error value

Return values:

MEDIA_VISION_ERROR_NONE	Successful
MEDIA_VISION_ERROR_NOT_SUPPORTED	Not supported
MEDIA_VISION_ERROR_INVALID_PARAMETER	Invalid parameter
MEDIA_VISION_ERROR_PERMISSION_DENIED	Permission denied
MEDIA_VISION_ERROR_INVALID_PATH	Invalid 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] mv3d The handle to the mv3d

Returns:: 0 on success, otherwise a negative error value

Return values:

MEDIA_VISION_ERROR_NONE	Successful
MEDIA_VISION_ERROR_NOT_SUPPORTED	Not supported
MEDIA_VISION_ERROR_INVALID_PARAMETER	Invalid parameter
MEDIA_VISION_ERROR_INVALID_OPERATION	Invalid 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]	mv3d	The handle to the mv3d
[in]	source	The handle to the source of the media
[in]	source_extra	The handle to the extra source of the media
[in]	color	The handle to the color of the media

Returns:: 0 on success, otherwise a negative error value

Return values:

MEDIA_VISION_ERROR_NONE	Successful
MEDIA_VISION_ERROR_NOT_SUPPORTED	Not supported
MEDIA_VISION_ERROR_INVALID_PARAMETER	Invalid 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]	mv3d	The handle to the mv3d
[in]	source	The handle to the source of the media
[in]	source_extra	The handle to the extra source of the media
[in]	color	The handle to the color of the media

Returns:: 0 on success, otherwise a negative error value

Return values:

MEDIA_VISION_ERROR_NONE	Successful
MEDIA_VISION_ERROR_NOT_SUPPORTED	Not supported
MEDIA_VISION_ERROR_INVALID_PARAMETER	Invalid 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]	mv3d	The handle to the mv3d
[in]	depth_cb	The callback which will be invoked for getting depth data
[in]	user_data	The 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_NONE	Successful
MEDIA_VISION_ERROR_NOT_SUPPORTED	Not supported
MEDIA_VISION_ERROR_INVALID_PARAMETER	Invalid 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]	mv3d	The handle to the mv3d
[in]	pointcloud_cb	The callback which will be invoked for getting pointcloud data
[in]	user_data	The 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_NONE	Successful
MEDIA_VISION_ERROR_NOT_SUPPORTED	Not supported
MEDIA_VISION_ERROR_INVALID_PARAMETER	Invalid 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()

Required Header

Related Features

Overview

Functions

Typedefs

Defines

Define Documentation

Typedef Documentation

Enumeration Type Documentation

Function Documentation