rs_device.h File Reference

Exposes RealSense device functionality for C compilers. More...

#include "rs_types.h"
#include "rs_sensor.h"

Go to the source code of this file.

Macros
#define	RS2_UNSIGNED_UPDATE_MODE_UPDATE   0
#define	RS2_UNSIGNED_UPDATE_MODE_READ_ONLY   1
#define	RS2_UNSIGNED_UPDATE_MODE_FULL   2

Typedefs
typedef enum rs2_calibration_type	rs2_calibration_type
typedef enum rs2_calibration_status	rs2_calibration_status
typedef struct rs2_calibration_change_callback	rs2_calibration_change_callback
typedef void(*	rs2_calibration_change_callback_ptr) (rs2_calibration_status, void *arg)

Enumerations
enum	rs2_calibration_type { RS2_CALIBRATION_AUTO_DEPTH_TO_RGB, RS2_CALIBRATION_MANUAL_DEPTH_TO_RGB, RS2_CALIBRATION_THERMAL, RS2_CALIBRATION_TYPE_COUNT }
enum	rs2_calibration_status {   RS2_CALIBRATION_TRIGGERED = 0, RS2_CALIBRATION_SPECIAL_FRAME = 1, RS2_CALIBRATION_STARTED = 2, RS2_CALIBRATION_NOT_NEEDED = 3,   RS2_CALIBRATION_SUCCESSFUL = 4, RS2_CALIBRATION_RETRY = -1, RS2_CALIBRATION_FAILED = -2, RS2_CALIBRATION_SCENE_INVALID = -3,   RS2_CALIBRATION_BAD_RESULT = -4, RS2_CALIBRATION_BAD_CONDITIONS = -5, RS2_CALIBRATION_STATUS_FIRST = -5, RS2_CALIBRATION_STATUS_LAST = 4,   RS2_CALIBRATION_STATUS_COUNT = RS2_CALIBRATION_STATUS_LAST - RS2_CALIBRATION_STATUS_FIRST + 1 }

Functions
int	rs2_get_device_count (const rs2_device_list *info_list, rs2_error **error)
void	rs2_delete_device_list (rs2_device_list *info_list)
int	rs2_device_list_contains (const rs2_device_list *info_list, const rs2_device *device, rs2_error **error)
rs2_device *	rs2_create_device (const rs2_device_list *info_list, int index, rs2_error **error)
void	rs2_delete_device (rs2_device *device)
int	rs2_device_is_connected (const rs2_device *device, rs2_error **error)
const char *	rs2_get_device_info (const rs2_device *device, rs2_camera_info info, rs2_error **error)
int	rs2_supports_device_info (const rs2_device *device, rs2_camera_info info, rs2_error **error)
void	rs2_hardware_reset (const rs2_device *device, rs2_error **error)
const rs2_raw_data_buffer *	rs2_build_debug_protocol_command (rs2_device *device, unsigned opcode, unsigned param1, unsigned param2, unsigned param3, unsigned param4, void *data, unsigned size_of_data, rs2_error **error)
const rs2_raw_data_buffer *	rs2_send_and_receive_raw_data (rs2_device *device, void *raw_data_to_send, unsigned size_of_raw_data_to_send, rs2_error **error)
int	rs2_is_device_extendable_to (const rs2_device *device, rs2_extension extension, rs2_error **error)
rs2_sensor_list *	rs2_query_sensors (const rs2_device *device, rs2_error **error)
void	rs2_loopback_enable (const rs2_device *device, const char *from_file, rs2_error **error)
void	rs2_loopback_disable (const rs2_device *device, rs2_error **error)
int	rs2_loopback_is_enabled (const rs2_device *device, rs2_error **error)
void	rs2_connect_tm2_controller (const rs2_device *device, const unsigned char *mac_addr, rs2_error **error)
void	rs2_disconnect_tm2_controller (const rs2_device *device, int id, rs2_error **error)
void	rs2_reset_to_factory_calibration (const rs2_device *device, rs2_error **e)
void	rs2_write_calibration (const rs2_device *device, rs2_error **e)
void	rs2_update_firmware_cpp (const rs2_device *device, const void *fw_image, int fw_image_size, rs2_update_progress_callback *callback, rs2_error **error)
void	rs2_update_firmware (const rs2_device *device, const void *fw_image, int fw_image_size, rs2_update_progress_callback_ptr callback, void *client_data, rs2_error **error)
const rs2_raw_data_buffer *	rs2_create_flash_backup_cpp (const rs2_device *device, rs2_update_progress_callback *callback, rs2_error **error)
const rs2_raw_data_buffer *	rs2_create_flash_backup (const rs2_device *device, rs2_update_progress_callback_ptr callback, void *client_data, rs2_error **error)
void	rs2_update_firmware_unsigned_cpp (const rs2_device *device, const void *fw_image, int fw_image_size, rs2_update_progress_callback *callback, int update_mode, rs2_error **error)
int	rs2_check_firmware_compatibility (const rs2_device *device, const void *fw_image, int fw_image_size, rs2_error **error)
void	rs2_update_firmware_unsigned (const rs2_device *device, const void *fw_image, int fw_image_size, rs2_update_progress_callback_ptr callback, void *client_data, int update_mode, rs2_error **error)
void	rs2_enter_update_state (const rs2_device *device, rs2_error **error)
const rs2_raw_data_buffer *	rs2_run_on_chip_calibration_cpp (rs2_device *device, const void *json_content, int content_size, float *health, rs2_update_progress_callback *progress_callback, int timeout_ms, rs2_error **error)
const rs2_raw_data_buffer *	rs2_run_on_chip_calibration (rs2_device *device, const void *json_content, int content_size, float *health, rs2_update_progress_callback_ptr callback, void *client_data, int timeout_ms, rs2_error **error)
const rs2_raw_data_buffer *	rs2_run_tare_calibration_cpp (rs2_device *dev, float ground_truth_mm, const void *json_content, int content_size, float *health, rs2_update_progress_callback *progress_callback, int timeout_ms, rs2_error **error)
const rs2_raw_data_buffer *	rs2_process_calibration_frame (rs2_device *dev, const rs2_frame *f, float *const health, rs2_update_progress_callback *progress_callback, int timeout_ms, rs2_error **error)
const char *	rs2_calibration_type_to_string (rs2_calibration_type)
const char *	rs2_calibration_status_to_string (rs2_calibration_status)
void	rs2_register_calibration_change_callback (rs2_device *dev, rs2_calibration_change_callback_ptr callback, void *user, rs2_error **error)
void	rs2_register_calibration_change_callback_cpp (rs2_device *dev, rs2_calibration_change_callback *callback, rs2_error **error)
void	rs2_trigger_device_calibration (rs2_device *dev, rs2_calibration_type type, rs2_error **error)
const rs2_raw_data_buffer *	rs2_run_tare_calibration (rs2_device *dev, float ground_truth_mm, const void *json_content, int content_size, float *health, rs2_update_progress_callback_ptr callback, void *client_data, int timeout_ms, rs2_error **error)
const rs2_raw_data_buffer *	rs2_get_calibration_table (const rs2_device *dev, rs2_error **error)
void	rs2_set_calibration_table (const rs2_device *device, const void *calibration, int calibration_size, rs2_error **error)
rs2_raw_data_buffer *	rs2_serialize_json (rs2_device *dev, rs2_error **error)
void	rs2_load_json (rs2_device *dev, const void *json_content, unsigned content_size, rs2_error **error)
const rs2_raw_data_buffer *	rs2_run_focal_length_calibration_cpp (rs2_device *device, rs2_frame_queue *left_queue, rs2_frame_queue *right_queue, float target_width, float target_height, int adjust_both_sides, float *ratio, float *angle, rs2_update_progress_callback *progress_callback, rs2_error **error)
const rs2_raw_data_buffer *	rs2_run_focal_length_calibration (rs2_device *device, rs2_frame_queue *left_queue, rs2_frame_queue *right_queue, float target_width, float target_height, int adjust_both_sides, float *ratio, float *angle, rs2_update_progress_callback_ptr callback, void *client_data, rs2_error **error)
const rs2_raw_data_buffer *	rs2_run_uv_map_calibration_cpp (rs2_device *device, rs2_frame_queue *left_queue, rs2_frame_queue *color_queue, rs2_frame_queue *depth_queue, int py_px_only, float *health, int health_size, rs2_update_progress_callback *progress_callback, rs2_error **error)
const rs2_raw_data_buffer *	rs2_run_uv_map_calibration (rs2_device *device, rs2_frame_queue *left_queue, rs2_frame_queue *color_queue, rs2_frame_queue *depth_queue, int py_px_only, float *health, int health_size, rs2_update_progress_callback_ptr callback, void *client_data, rs2_error **error)
float	rs2_calculate_target_z_cpp (rs2_device *device, rs2_frame_queue *queue1, rs2_frame_queue *queue2, rs2_frame_queue *queue3, float target_width, float target_height, rs2_update_progress_callback *callback, rs2_error **error)
float	rs2_calculate_target_z (rs2_device *device, rs2_frame_queue *queue1, rs2_frame_queue *queue2, rs2_frame_queue *queue3, float target_width, float target_height, rs2_update_progress_callback_ptr progress_callback, void *client_data, rs2_error **error)
void	rs2_get_calibration_config (rs2_device *device, rs2_calibration_config *calib_config, rs2_error **error)
void	rs2_set_calibration_config (rs2_device *device, rs2_calibration_config const *calib_config, rs2_error **error)
void	rs2_json_string_to_calibration_config (rs2_device *device, const char *json_str, rs2_calibration_config *calib_config, rs2_error **error)
const rs2_raw_data_buffer *	rs2_calibration_config_to_json_string (rs2_device *device, rs2_calibration_config const *calib_config, rs2_error **error)

Detailed Description

Exposes RealSense device functionality for C compilers.

Macro Definition Documentation

RS2_UNSIGNED_UPDATE_MODE_FULL

#define RS2_UNSIGNED_UPDATE_MODE_FULL   2

RS2_UNSIGNED_UPDATE_MODE_READ_ONLY

#define RS2_UNSIGNED_UPDATE_MODE_READ_ONLY   1

RS2_UNSIGNED_UPDATE_MODE_UPDATE

#define RS2_UNSIGNED_UPDATE_MODE_UPDATE   0

Typedef Documentation

rs2_calibration_change_callback

typedef struct rs2_calibration_change_callback rs2_calibration_change_callback

rs2_calibration_change_callback_ptr

typedef void(* rs2_calibration_change_callback_ptr) (rs2_calibration_status, void *arg)

rs2_calibration_status

typedef enum rs2_calibration_status rs2_calibration_status

Used in device_calibration with rs2_calibration_change_callback

rs2_calibration_type

typedef enum rs2_calibration_type rs2_calibration_type

Used in device_calibration; enumerates the different calibration types available for that extension.

Enumeration Type Documentation

rs2_calibration_status

enum rs2_calibration_status

Used in device_calibration with rs2_calibration_change_callback

Enumerator
RS2_CALIBRATION_TRIGGERED
RS2_CALIBRATION_SPECIAL_FRAME
RS2_CALIBRATION_STARTED
RS2_CALIBRATION_NOT_NEEDED
RS2_CALIBRATION_SUCCESSFUL
RS2_CALIBRATION_RETRY
RS2_CALIBRATION_FAILED
RS2_CALIBRATION_SCENE_INVALID
RS2_CALIBRATION_BAD_RESULT
RS2_CALIBRATION_BAD_CONDITIONS
RS2_CALIBRATION_STATUS_FIRST
RS2_CALIBRATION_STATUS_LAST
RS2_CALIBRATION_STATUS_COUNT

rs2_calibration_type

enum rs2_calibration_type

Used in device_calibration; enumerates the different calibration types available for that extension.

Enumerator
RS2_CALIBRATION_AUTO_DEPTH_TO_RGB
RS2_CALIBRATION_MANUAL_DEPTH_TO_RGB
RS2_CALIBRATION_THERMAL
RS2_CALIBRATION_TYPE_COUNT

Function Documentation

rs2_build_debug_protocol_command()

const rs2_raw_data_buffer* rs2_build_debug_protocol_command	(	rs2_device *	device,
		unsigned	opcode,
		unsigned	param1,
		unsigned	param2,
		unsigned	param3,
		unsigned	param4,
		void *	data,
		unsigned	size_of_data,
		rs2_error **	error
	)

Build debug_protocol raw data command from opcode, parameters and data. The result can be used as raw_data_to_send parameter in send_and_receive_raw_data

Parameters

[in]	device	RealSense device to send data to
[in]	opcode	Commad opcode
[in]	param1	First input parameter
[in]	param2	Second parameter
[in]	param3	Third parameter
[in]	param4	Fourth parameter
[in]	data	Input Data (up to 1024 bytes)
[in]	size_of_data	Size of input data in bytes
[out]	error	If non-null, receives any error that occurs during this call, otherwise, errors are ignored

Returns

rs2_raw_data_buffer which includes raw command

rs2_calculate_target_z()

float rs2_calculate_target_z	(	rs2_device *	device,
		rs2_frame_queue *	queue1,
		rs2_frame_queue *	queue2,
		rs2_frame_queue *	queue3,
		float	target_width,
		float	target_height,
		rs2_update_progress_callback_ptr	progress_callback,
		void *	client_data,
		rs2_error **	error
	)

Calculate Z for calibration target - distance to the target's plane

Parameters

[in]	queue1-3	A frame queue of raw images used to calculate and extract the distance to a predefined target pattern. For D400 the indexes 1-3 correspond to Left IR, Right IR and Depth with only the Left IR being used
[in]	target_width	Expected target's horizontal dimension in mm
[in]	target_height	Expected target's vertical dimension in mm
[in]	callback	Optional callback for reporting progress status
[in]	client_data	Optional client data for the callback

Returns

Calculated distance (Z) to target in millimeter, or negative number if failed

rs2_calculate_target_z_cpp()

float rs2_calculate_target_z_cpp	(	rs2_device *	device,
		rs2_frame_queue *	queue1,
		rs2_frame_queue *	queue2,
		rs2_frame_queue *	queue3,
		float	target_width,
		float	target_height,
		rs2_update_progress_callback *	callback,
		rs2_error **	error
	)

Calculate Z for calibration target - distance to the target's plane

Parameters

[in]	queue1-3	A frame queue of raw images used to calculate and extract the distance to a predefined target pattern. For D400 the indexes 1-3 correspond to Left IR, Right IR and Depth with only the Left IR being used
[in]	target_width	Expected target's horizontal dimension in mm
[in]	target_height	Expected target's vertical dimension in mm
[in]	callback	Optional callback for reporting progress status

Returns

Calculated distance (Z) to target in millimeter, or negative number if failed

rs2_calibration_config_to_json_string()

const rs2_raw_data_buffer* rs2_calibration_config_to_json_string	(	rs2_device *	device,
		rs2_calibration_config const *	calib_config,
		rs2_error **	error
	)

rs2_calibration_config_to_json_string

Parameters

[in]	device	The device
[in]	calib_config	Calibration config to convert
[out]	error	If non-null, receives any error that occurs during this call, otherwise, errors are ignored

Returns

JSON string representing the calibration config as rs2_raw_data_buffer

rs2_calibration_status_to_string()

const char* rs2_calibration_status_to_string

(

rs2_calibration_status

)

rs2_calibration_type_to_string()

const char* rs2_calibration_type_to_string

(

rs2_calibration_type

)

rs2_check_firmware_compatibility()

int rs2_check_firmware_compatibility	(	const rs2_device *	device,
		const void *	fw_image,
		int	fw_image_size,
		rs2_error **	error
	)

Checks if the device and the provided firmware image are compatible

Parameters

[in]	device	Device to update
[in]	fw_image	Firmware image buffer
[in]	fw_image_size	Firmware image buffer size in bytes
[out]	error	If non-null, receives any error that occurs during this call, otherwise, errors are ignored

Returns

Non-zero if the firmware is compatible with the device and 0 otherwise

rs2_connect_tm2_controller()

void rs2_connect_tm2_controller	(	const rs2_device *	device,
		const unsigned char *	mac_addr,
		rs2_error **	error
	)

Connects to a given tm2 controller

Parameters

[in]	device	Device to connect to the controller
[in]	mac_addr	The MAC address of the desired controller
[out]	error	If non-null, receives any error that occurs during this call, otherwise, errors are ignored

rs2_create_device()

rs2_device* rs2_create_device	(	const rs2_device_list *	info_list,
		int	index,
		rs2_error **	error
	)

Creates a device by index. The device object represents a physical camera and provides the means to manipulate it.

Parameters

[in]	info_list	the list containing the device to retrieve
[in]	index	The zero based index of device to retrieve
[out]	error	If non-null, receives any error that occurs during this call, otherwise, errors are ignored

Returns

The requested device, should be released by rs2_delete_device

rs2_create_flash_backup()

const rs2_raw_data_buffer* rs2_create_flash_backup	(	const rs2_device *	device,
		rs2_update_progress_callback_ptr	callback,
		void *	client_data,
		rs2_error **	error
	)

Create backup of camera flash memory. Such backup does not constitute valid firmware image, and cannot be loaded back to the device, but it does contain all calibration and device information.

Parameters

[in]	device	Device to update
[in]	callback	Optional callback for update progress notifications, the progress value is normailzed to 1
[in]	client_data	Optional client data for the callback
[out]	error	If non-null, receives any error that occurs during this call, otherwise, errors are ignored

rs2_create_flash_backup_cpp()

const rs2_raw_data_buffer* rs2_create_flash_backup_cpp	(	const rs2_device *	device,
		rs2_update_progress_callback *	callback,
		rs2_error **	error
	)

Create backup of camera flash memory. Such backup does not constitute valid firmware image, and cannot be loaded back to the device, but it does contain all calibration and device information.

Parameters

[in]	device	Device to update
[in]	callback	Optional callback for update progress notifications, the progress value is normailzed to 1
[out]	error	If non-null, receives any error that occurs during this call, otherwise, errors are ignored

rs2_delete_device()

void rs2_delete_device

(

rs2_device *

device

)

Delete RealSense device

Parameters

[in]

device

Realsense device to delete

rs2_delete_device_list()

void rs2_delete_device_list

(

rs2_device_list *

info_list

)

Deletes device list, any devices created using this list will remain unaffected.

Parameters

[in]

info_list

List to delete

rs2_device_is_connected()

int rs2_device_is_connected	(	const rs2_device *	device,
		rs2_error **	error
	)

Parameters

[in]

device

Realsense device to query

Returns

True if device is still present in the system

rs2_device_list_contains()

int rs2_device_list_contains	(	const rs2_device_list *	info_list,
		const rs2_device *	device,
		rs2_error **	error
	)

Checks if a specific device is contained inside a device list.

Parameters

[in]	info_list	The list of devices to check in
[in]	device	RealSense device to check for
[out]	error	If non-null, receives any error that occurs during this call, otherwise, errors are ignored

Returns

True if the device is in the list and false otherwise

rs2_disconnect_tm2_controller()

void rs2_disconnect_tm2_controller	(	const rs2_device *	device,
		int	id,
		rs2_error **	error
	)

Disconnects a given tm2 controller

Parameters

[in]	device	Device to disconnect the controller from
[in]	id	The ID of the desired controller
[out]	error	If non-null, receives any error that occurs during this call, otherwise, errors are ignored

rs2_enter_update_state()

void rs2_enter_update_state	(	const rs2_device *	device,
		rs2_error **	error
	)

Enter the device to update state, this will cause the updatable device to disconnect and reconnect as update device.

Parameters

[in]	device	Device to update
[out]	error	If non-null, receives any error that occurs during this call, otherwise, errors are ignored

rs2_get_calibration_config()

void rs2_get_calibration_config	(	rs2_device *	device,
		rs2_calibration_config *	calib_config,
		rs2_error **	error
	)

rs2_get_calibration_config

Parameters

[in]	device	The device
[out]	calib_config	Calibration Configuration struct to be filled
[out]	error	If non-null, receives any error that occurs during this call, otherwise, errors are ignored

rs2_get_calibration_table()

const rs2_raw_data_buffer* rs2_get_calibration_table	(	const rs2_device *	dev,
		rs2_error **	error
	)

Read current calibration table from flash.

Returns

Calibration table

rs2_get_device_count()

int rs2_get_device_count	(	const rs2_device_list *	info_list,
		rs2_error **	error
	)

Determines number of devices in a list.

Parameters

[in]	info_list	The list of connected devices captured using rs2_query_devices
[out]	error	If non-null, receives any error that occurs during this call, otherwise, errors are ignored

Returns

Device count

rs2_get_device_info()

const char* rs2_get_device_info	(	const rs2_device *	device,
		rs2_camera_info	info,
		rs2_error **	error
	)

Retrieve camera specific information, like versions of various internal components.

Parameters

[in]	device	The RealSense device
[in]	info	Camera info type to retrieve
[out]	error	If non-null, receives any error that occurs during this call, otherwise, errors are ignored

Returns

The requested camera info string, in a format specific to the device model

rs2_hardware_reset()

void rs2_hardware_reset	(	const rs2_device *	device,
		rs2_error **	error
	)

Send hardware reset request to the device. The actual reset is asynchronous. Note: Invalidates all handles to this device.

Parameters

[in]	device	The RealSense device to reset
[out]	error	If non-null, receives any error that occurs during this call, otherwise, errors are ignored

rs2_is_device_extendable_to()

int rs2_is_device_extendable_to	(	const rs2_device *	device,
		rs2_extension	extension,
		rs2_error **	error
	)

Test if the given device can be extended to the requested extension.

Parameters

[in]	device	Realsense device
[in]	extension	The extension to which the device should be tested if it is extendable
[out]	error	If non-null, receives any error that occurs during this call, otherwise, errors are ignored

Returns

Non-zero value iff the device can be extended to the given extension

rs2_json_string_to_calibration_config()

void rs2_json_string_to_calibration_config	(	rs2_device *	device,
		const char *	json_str,
		rs2_calibration_config *	calib_config,
		rs2_error **	error
	)

rs2_json_string_to_calibration_config

Parameters

[in]	device	The device
[in]	json_str	JSON string to convert
[out]	calib_config	Calibration config struct result
[out]	error	If non-null, receives any error that occurs during this call, otherwise, errors are ignored

rs2_load_json()

void rs2_load_json	(	rs2_device *	dev,
		const void *	json_content,
		unsigned	content_size,
		rs2_error **	error
	)

rs2_loopback_disable()

void rs2_loopback_disable	(	const rs2_device *	device,
		rs2_error **	error
	)

Restores the given device into normal operation mode

Parameters

[in]	device	Device to restore to normal operation mode
[out]	error	If non-null, receives any error that occurs during this call, otherwise, errors are ignored

rs2_loopback_enable()

void rs2_loopback_enable	(	const rs2_device *	device,
		const char *	from_file,
		rs2_error **	error
	)

Enter the given device into loopback operation mode that uses the given file as input for raw data

Parameters

[in]	device	Device to enter into loopback operation mode
[in]	from_file	Path to bag file with raw data for loopback
[out]	error	If non-null, receives any error that occurs during this call, otherwise, errors are ignored

rs2_loopback_is_enabled()

int rs2_loopback_is_enabled	(	const rs2_device *	device,
		rs2_error **	error
	)

Checks if the device is in loopback mode or not

Parameters

[in]	device	Device to check for operation mode
[out]	error	If non-null, receives any error that occurs during this call, otherwise, errors are ignored

Returns

true if the device is in loopback operation mode

rs2_process_calibration_frame()

const rs2_raw_data_buffer* rs2_process_calibration_frame	(	rs2_device *	dev,
		const rs2_frame *	f,
		float *const	health,
		rs2_update_progress_callback *	progress_callback,
		int	timeout_ms,
		rs2_error **	error
	)

During host assisted calibration (Tare or on-chip), this is used to pump new depth frames until calibration is done.

Parameters

[in]	f	The next frame.
[in]	timeout_ms	Timeout in ms (use 5000 msec unless instructed otherwise)
[out]	health	The health check numbers before and after calibration

Returns

New calibration table

rs2_query_sensors()

rs2_sensor_list* rs2_query_sensors	(	const rs2_device *	device,
		rs2_error **	error
	)

Create a static snapshot of all connected sensors within a specific device.

Parameters

[in]	device	Specific RealSense device
[out]	error	If non-null, receives any error that occurs during this call, otherwise, errors are ignored

Returns

The list of sensors, should be released by rs2_delete_sensor_list

rs2_register_calibration_change_callback()

void rs2_register_calibration_change_callback	(	rs2_device *	dev,
		rs2_calibration_change_callback_ptr	callback,
		void *	user,
		rs2_error **	error
	)

Adds a callback for a sensor that gets called when calibration (intrinsics) changes, e.g. due to auto-calibration

Parameters

[in]	sensor	the sensor
[in]	callback	the C callback function that gets called
[in]	user	user argument that gets passed to the callback function
[out]	error	if non-null, receives any error that occurs during this call, otherwise, errors are ignored

rs2_register_calibration_change_callback_cpp()

void rs2_register_calibration_change_callback_cpp	(	rs2_device *	dev,
		rs2_calibration_change_callback *	callback,
		rs2_error **	error
	)

Adds a callback for a sensor that gets called when calibration (intrinsics) changes, e.g. due to auto-calibration

Parameters

[in]	sensor	the sensor
[in]	callback	the C++ callback interface that gets called
[out]	error	if non-null, receives any error that occurs during this call, otherwise, errors are ignored

rs2_reset_to_factory_calibration()

void rs2_reset_to_factory_calibration	(	const rs2_device *	device,
		rs2_error **	e
	)

Reset device to factory calibration

Parameters

[in]	device	The RealSense device
[out]	error	If non-null, receives any error that occurs during this call, otherwise, errors are ignored

rs2_run_focal_length_calibration()

const rs2_raw_data_buffer* rs2_run_focal_length_calibration	(	rs2_device *	device,
		rs2_frame_queue *	left_queue,
		rs2_frame_queue *	right_queue,
		float	target_width,
		float	target_height,
		int	adjust_both_sides,
		float *	ratio,
		float *	angle,
		rs2_update_progress_callback_ptr	callback,
		void *	client_data,
		rs2_error **	error
	)

Run target-based focal length calibration

Parameters

[in]	device	device to calibrate
[in]	left_queue	container for left IR frames with resoluton of 1280x720 and the target in the center of 320x240 pixels ROI.
[in]	right_queue	container for right IR frames with resoluton of 1280x720 and the target in the center of 320x240 pixels ROI
[in]	target_width	the rectangle width in mm on the target
[in]	target_height	the rectangle height in mm on the target
[in]	adjust_both_sides	1 for adjusting both left and right camera calibration tables, and 0 for adjusting right camera calibraion table only
[out]	ratio	the corrected ratio from the calibration
[out]	angle	the target's tilt angle
[in]	callback	Optional callback for update progress notifications, the progress value is normailzed to 1
[in]	client_data	Optional client data for the callback

Returns

New calibration table

rs2_run_focal_length_calibration_cpp()

const rs2_raw_data_buffer* rs2_run_focal_length_calibration_cpp	(	rs2_device *	device,
		rs2_frame_queue *	left_queue,
		rs2_frame_queue *	right_queue,
		float	target_width,
		float	target_height,
		int	adjust_both_sides,
		float *	ratio,
		float *	angle,
		rs2_update_progress_callback *	progress_callback,
		rs2_error **	error
	)

Run target-based focal length calibration

Parameters

[in]	device	device to calibrate
[in]	left_queue	container for left IR frames with resoluton of 1280x720 and the target in the center of 320x240 pixels ROI.
[in]	right_queue	container for right IR frames with resoluton of 1280x720 and the target in the center of 320x240 pixels ROI
[in]	target_width	the rectangle width in mm on the target
[in]	target_height	the rectangle height in mm on the target
[in]	adjust_both_sides	1 for adjusting both left and right camera calibration tables, and 0 for adjusting right camera calibraion table only
[out]	ratio	the corrected ratio from the calibration
[out]	angle	the target's tilt angle
[in]	callback	Optional callback for update progress notifications, the progress value is normailzed to 1

Returns

New calibration table

rs2_run_on_chip_calibration()

const rs2_raw_data_buffer* rs2_run_on_chip_calibration	(	rs2_device *	device,
		const void *	json_content,
		int	content_size,
		float *	health,
		rs2_update_progress_callback_ptr	callback,
		void *	client_data,
		int	timeout_ms,
		rs2_error **	error
	)

This will improve the depth noise.

Parameters

[in]	json_content	Json string to configure regular speed on chip calibration parameters: { "calib type" : 0, "speed": 3, "scan parameter": 0, "adjust both sides": 0, "white wall mode": 0, "host assistance": 0 } calib_type - calibraton type: 0 = regular, 1 = focal length, 2 = both regular and focal length in order 30 = regular for version 3, 31 = focal length for version 3, 32 = both regular and focal length in order for version 3, 33 = regular for second part of version 3 speed - for regular calibration, value can be one of: Very fast = 0, Fast = 1, Medium = 2, Slow = 3, White wall = 4, default is Slow for type 0 and Fast for type 2 scan_parameter - for regular calibration. value can be one of: Py scan (default) = 0, Rx scan = 1 adjust_both_sides - for focal length calibration. value can be one of: 0 = adjust right only, 1 = adjust both sides white_wall_mode - white wall mode: 0 for normal mode and 1 for white wall mode host_assistance: 0 for no assistance, 1 for starting with assistance, 2 for first part feeding host data to firmware, 3 for second part of feeding host data to firmware (calib_type 2 only) if json is nullptr it will be ignored and calibration will use the default parameters
[out]	health	The absolute value of regular calibration Health-Check captures how far camera calibration is from the optimal one [0, 0.25) - Good [0.25, 0.75) - Can be Improved [0.75, ) - Requires Calibration The absolute value of focal length calibration Health-Check captures how far camera calibration is from the optimal one [0, 0.15) - Good [0.15, 0.75) - Can be Improved [0.75, ) - Requires Calibration The two health numbers are encoded in one integer as follows for calib_type 2: Regular health number times 1000 are bits 0 to 11 Regular health number is negative if bit 24 is 1 Focal length health number times 1000 are bits 12 to 23 Focal length health number is negative if bit 25 is 1
[in]	callback	Optional callback for update progress notifications, the progress value is normailzed to 1
[in]	client_data	Optional client data for the callback
[in]	timeout_ms	Timeout in ms (use 5000 msec unless instructed otherwise)

Returns

New calibration table

rs2_run_on_chip_calibration_cpp()

const rs2_raw_data_buffer* rs2_run_on_chip_calibration_cpp	(	rs2_device *	device,
		const void *	json_content,
		int	content_size,
		float *	health,
		rs2_update_progress_callback *	progress_callback,
		int	timeout_ms,
		rs2_error **	error
	)

This will improve the depth noise.

Parameters

[in]	json_content	Json string to configure regular speed on chip calibration parameters: { "calib type" : 0, "speed": 3, "scan parameter": 0, "adjust both sides": 0, "white wall mode": 0, "host assistance": 0 } calib_type - calibraton type: 0 = regular, 1 = focal length, 2 = both regular and focal length in order, speed - for regular calibration. value can be one of: Very fast = 0, Fast = 1, Medium = 2, Slow = 3, White wall = 4, default is Slow for type 0 and Fast for type 2 scan_parameter - for regular calibration. value can be one of: Py scan (default) = 0, Rx scan = 1 adjust_both_sides - for focal length calibration. value can be one of: 0 = adjust right only, 1 = adjust both sides host_assistance: 0 for no assistance, 1 for starting with assistance, 2 for first part feeding host data to firmware, 3 for second part of feeding host data to firmware (calib_type 2 only) white_wall_mode - white wall mode: 0 for normal mode and 1 for white wall mode if json is nullptr it will be ignored and calibration will use the default parameters
[out]	health	The absolute value of regular calibration Health-Check captures how far camera calibration is from the optimal one [0, 0.25) - Good [0.25, 0.75) - Can be Improved [0.75, ) - Requires Calibration The absolute value of focal length calibration Health-Check captures how far camera calibration is from the optimal one [0, 0.15) - Good [0.15, 0.75) - Can be Improved [0.75, ) - Requires Calibration The two health numbers are encoded in one integer as follows for calib_type 2: Regular health number times 1000 are bits 0 to 11 Regular health number is negative if bit 24 is 1 Focal length health number times 1000 are bits 12 to 23 Focal length health number is negative if bit 25 is 1
[in]	callback	Optional callback to get progress notifications
[in]	timeout_ms	Timeout in ms (use 5000 msec unless instructed otherwise)

Returns

New calibration table

rs2_run_tare_calibration()

const rs2_raw_data_buffer* rs2_run_tare_calibration	(	rs2_device *	dev,
		float	ground_truth_mm,
		const void *	json_content,
		int	content_size,
		float *	health,
		rs2_update_progress_callback_ptr	callback,
		void *	client_data,
		int	timeout_ms,
		rs2_error **	error
	)

This will adjust camera absolute distance to flat target. User needs to enter the known ground truth.

Parameters

[in]	ground_truth_mm	Ground truth in mm must be between 60 and 10000
[in]	json_content	Json string to configure tare calibration parameters: { "average_step_count": 20, "step count": 20, "accuracy": 2, "scan parameter": 0, "data sampling": 0, "host assistance": 0, "depth": 0 } average step count - number of frames to average, must be between 1 - 30, default = 20 step count - max iteration steps, must be between 5 - 30, default = 10 accuracy - Subpixel accuracy level, value can be one of: Very high = 0 (0.025%), High = 1 (0.05%), Medium = 2 (0.1%), Low = 3 (0.2%), Default = Very high (0.025%), default is Medium scan_parameter - value can be one of: Py scan (default) = 0, Rx scan = 1 data_sampling - value can be one of:polling data sampling = 0, interrupt data sampling = 1 host_assistance: 0 for no assistance, 1 for starting with assistance, 2 for feeding host data to firmware depth: 0 for not relating to depth, > 0 for feeding depth from host to firmware, -1 for ending to feed depth from host to firmware if json is nullptr it will be ignored and calibration will use the default parameters
[in]	content_size	Json string size if its 0 the json will be ignored and calibration will use the default parameters
[in]	callback	Optional callback for update progress notifications, the progress value is normailzed to 1
[in]	client_data	Optional client data for the callback
[in]	timeout_ms	Timeout in ms (use 5000 msec unless instructed otherwise)
[out]	health	The health check numbers before and after calibration

Returns

New calibration table

rs2_run_tare_calibration_cpp()

const rs2_raw_data_buffer* rs2_run_tare_calibration_cpp	(	rs2_device *	dev,
		float	ground_truth_mm,
		const void *	json_content,
		int	content_size,
		float *	health,
		rs2_update_progress_callback *	progress_callback,
		int	timeout_ms,
		rs2_error **	error
	)

This will adjust camera absolute distance to flat target. User needs to enter the known ground truth.

Parameters

[in]	ground_truth_mm	Ground truth in mm must be between 60 and 10000
[in]	json_content	Json string to configure tare calibration parameters: { "average step count": 20, "step count": 20, "accuracy": 2, "scan parameter": 0, "data sampling": 0, "host assistance": 0, "depth" : 0 } average step count - number of frames to average, must be between 1 - 30, default = 20 step count - max iteration steps, must be between 5 - 30, default = 10 accuracy - Subpixel accuracy level, value can be one of: Very high = 0 (0.025%), High = 1 (0.05%), Medium = 2 (0.1%), Low = 3 (0.2%), Default = Very high (0.025%), default is Medium scan_parameter - value can be one of: Py scan (default) = 0, Rx scan = 1 data_sampling - value can be one of:polling data sampling = 0, interrupt data sampling = 1 host_assistance: 0 for no assistance, 1 for starting with assistance, 2 for feeding host data to firmware depth: 0 for not relating to depth, > 0 for feeding depth from host to firmware, -1 for ending to feed depth from host to firmware if json is nullptr it will be ignored and calibration will use the default parameters
[in]	content_size	Json string size if its 0 the json will be ignored and calibration will use the default parameters
[out]	health	The absolute value of regular calibration Health-Check captures how far camera calibration is from the optimal one [0, 0.25) - Good [0.25, 0.75) - Can be Improved [0.75, ) - Requires Calibration
[in]	callback	Optional callback to get progress notifications
[in]	timeout_ms	Timeout in ms (use 5000 msec unless instructed otherwise)
[out]	health	The health check numbers before and after calibration

Returns

New calibration table

rs2_run_uv_map_calibration()

const rs2_raw_data_buffer* rs2_run_uv_map_calibration	(	rs2_device *	device,
		rs2_frame_queue *	left_queue,
		rs2_frame_queue *	color_queue,
		rs2_frame_queue *	depth_queue,
		int	py_px_only,
		float *	health,
		int	health_size,
		rs2_update_progress_callback_ptr	callback,
		void *	client_data,
		rs2_error **	error
	)

Depth-RGB UV-Map calibration. Applicable for D400 cameras

Parameters

[in]	device	device to calibrate
[in]	left_queue	the frame queue for left IR frames with resoluton of 1280x720 and the target captured in the center of 320x240 pixels ROI.
[in]	color_queue	the frame queue for RGB frames with resoluton of 1280x720 and the target in the center of 320x240 pixels ROI
[in]	depth_queue	the frame queue for Depth frames with resoluton of 1280x720
[in]	py_px_only	1 for calibrating color camera py and px only, 1 for calibrating color camera py, px, fy, and fx.
[out]	health	The four health check numbers in order of px, py, fx, fy for the calibration
[in]	health_size	number of health check numbers, which is 4 by default
[in]	callback	Optional callback for update progress notifications, the progress value is normailzed to 1
[in]	client_data	Optional client data for the callback

Returns

New calibration table

rs2_run_uv_map_calibration_cpp()

const rs2_raw_data_buffer* rs2_run_uv_map_calibration_cpp	(	rs2_device *	device,
		rs2_frame_queue *	left_queue,
		rs2_frame_queue *	color_queue,
		rs2_frame_queue *	depth_queue,
		int	py_px_only,
		float *	health,
		int	health_size,
		rs2_update_progress_callback *	progress_callback,
		rs2_error **	error
	)

Depth-RGB UV-Map calibration. Applicable for D400 cameras

Parameters

[in]	device	device to calibrate
[in]	left_queue	the frame queue for left IR frames with resoluton of 1280x720 and the target captured in the center of 320x240 pixels ROI.
[in]	color_queue	the frame queue for RGB frames with resoluton of 1280x720 and the target in the center of 320x240 pixels ROI
[in]	depth_queue	the frame queue for Depth frames with resoluton of 1280x720
[in]	py_px_only	1 for calibrating color camera py and px only, 1 for calibrating color camera py, px, fy, and fx.
[out]	health	The four health check numbers in order of px, py, fx, fy for the calibration
[in]	health_size	number of health check numbers, which is 4 by default
[in]	callback	Optional callback for update progress notifications, the progress value is normailzed to 1

Returns

New calibration table

rs2_send_and_receive_raw_data()

const rs2_raw_data_buffer* rs2_send_and_receive_raw_data	(	rs2_device *	device,
		void *	raw_data_to_send,
		unsigned	size_of_raw_data_to_send,
		rs2_error **	error
	)

Send raw data to device

Parameters

[in]	device	RealSense device to send data to
[in]	raw_data_to_send	Raw data to be sent to device
[in]	size_of_raw_data_to_send	Size of raw_data_to_send in bytes
[out]	error	If non-null, receives any error that occurs during this call, otherwise, errors are ignored

Returns

Device's response in a rs2_raw_data_buffer, which should be released by rs2_delete_raw_data

rs2_serialize_json()

rs2_raw_data_buffer* rs2_serialize_json	(	rs2_device *	dev,
		rs2_error **	error
	)

rs2_set_calibration_config()

void rs2_set_calibration_config	(	rs2_device *	device,
		rs2_calibration_config const *	calib_config,
		rs2_error **	error
	)

rs2_set_calibration_config

Parameters

[in]	device	The device
[in]	calib_config	Calibration Configuration struct to set
[out]	error	If non-null, receives any error that occurs during this call, otherwise, errors are ignored

rs2_set_calibration_table()

void rs2_set_calibration_table	(	const rs2_device *	device,
		const void *	calibration,
		int	calibration_size,
		rs2_error **	error
	)

Set current table to dynamic area.

Parameters

[in]

Calibration

table

rs2_supports_device_info()

int rs2_supports_device_info	(	const rs2_device *	device,
		rs2_camera_info	info,
		rs2_error **	error
	)

Check if a camera supports a specific camera info type.

Parameters

[in]	device	The RealSense device to check
[in]	info	The parameter to check for support
[out]	error	If non-null, receives any error that occurs during this call, otherwise, errors are ignored

Returns

True if the parameter both exist and well-defined for the specific device

rs2_trigger_device_calibration()

void rs2_trigger_device_calibration	(	rs2_device *	dev,
		rs2_calibration_type	type,
		rs2_error **	error
	)

Triggers calibration of the given type

Parameters

[in]	dev	the device
[in]	type	the type of calibration requested
[out]	error	if non-null, receives any error that occurs during this call, otherwise, errors are ignored

rs2_update_firmware()

void rs2_update_firmware	(	const rs2_device *	device,
		const void *	fw_image,
		int	fw_image_size,
		rs2_update_progress_callback_ptr	callback,
		void *	client_data,
		rs2_error **	error
	)

Update device to the provided firmware, the device must be extendable to RS2_EXTENSION_UPDATABLE. This call is executed on the caller's thread and it supports progress notifications via the optional callback.

Parameters

[in]	device	Device to update
[in]	fw_image	Firmware image buffer
[in]	fw_image_size	Firmware image buffer size
[in]	callback	Optional callback for update progress notifications, the progress value is normailzed to 1
[in]	client_data	Optional client data for the callback
[out]	error	If non-null, receives any error that occurs during this call, otherwise, errors are ignored

rs2_update_firmware_cpp()

void rs2_update_firmware_cpp	(	const rs2_device *	device,
		const void *	fw_image,
		int	fw_image_size,
		rs2_update_progress_callback *	callback,
		rs2_error **	error
	)

Update device to the provided firmware, the device must be extendable to RS2_EXTENSION_UPDATABLE. This call is executed on the caller's thread and it supports progress notifications via the optional callback.

Parameters

[in]	device	Device to update
[in]	fw_image	Firmware image buffer
[in]	fw_image_size	Firmware image buffer size
[in]	callback	Optional callback for update progress notifications, the progress value is normailzed to 1
[out]	error	If non-null, receives any error that occurs during this call, otherwise, errors are ignored

rs2_update_firmware_unsigned()

void rs2_update_firmware_unsigned	(	const rs2_device *	device,
		const void *	fw_image,
		int	fw_image_size,
		rs2_update_progress_callback_ptr	callback,
		void *	client_data,
		int	update_mode,
		rs2_error **	error
	)

Update device to the provided firmware by writing raw data directly to the flash, this command can be executed only on unlocked camera. The device must be extendable to RS2_EXTENSION_UPDATABLE. This call is executed on the caller's thread and it supports progress notifications via the optional callback.

Parameters

[in]	device	Device to update
[in]	fw_image	Firmware image buffer
[in]	fw_image_size	Firmware image buffer size
[in]	callback	Optional callback for update progress notifications, the progress value is normailzed to 1
[in]	client_data	Optional client data for the callback
[in]	update_mode	Select one of RS2_UNSIGNED_UPDATE_MODE, WARNING!!! setting to any option other than RS2_UNSIGNED_UPDATE_MODE_UPDATE will make this call unsafe and might damage the camera
[out]	error	If non-null, receives any error that occurs during this call, otherwise, errors are ignored

rs2_update_firmware_unsigned_cpp()

void rs2_update_firmware_unsigned_cpp	(	const rs2_device *	device,
		const void *	fw_image,
		int	fw_image_size,
		rs2_update_progress_callback *	callback,
		int	update_mode,
		rs2_error **	error
	)

Update device to the provided firmware by writing raw data directly to the flash, this command can be executed only on unlocked camera. The device must be extendable to RS2_EXTENSION_UPDATABLE. This call is executed on the caller's thread and it supports progress notifications via the optional callback.

Parameters

[in]	device	Device to update
[in]	fw_image	Firmware image buffer
[in]	fw_image_size	Firmware image buffer size
[in]	callback	Optional callback for update progress notifications, the progress value is normailzed to 1
[in]	update_mode	Select one of RS2_UNSIGNED_UPDATE_MODE, WARNING!!! setting to any option other than RS2_UNSIGNED_UPDATE_MODE_UPDATE will make this call unsafe and might damage the camera
[out]	error	If non-null, receives any error that occurs during this call, otherwise, errors are ignored

rs2_write_calibration()

void rs2_write_calibration	(	const rs2_device *	device,
		rs2_error **	e
	)

Write calibration to device's EEPROM

Parameters

[in]	device	The RealSense device
[out]	error	If non-null, receives any error that occurs during this call, otherwise, errors are ignored