/* License: Apache 2.0. See LICENSE file in root directory. Copyright(c) 2015 Intel Corporation. All Rights Reserved. */ #ifndef LIBREALSENSE_RS_H #define LIBREALSENSE_RS_H #ifdef __cplusplus extern "C" { #endif #define RS_API_VERSION 4 typedef enum rs_stream { RS_STREAM_DEPTH = 0, /**< Native stream of depth data produced by RealSense device */ RS_STREAM_COLOR = 1, /**< Native stream of color data captured by RealSense device */ RS_STREAM_INFRARED = 2, /**< Native stream of infrared data captured by RealSense device */ RS_STREAM_INFRARED2 = 3, /**< Native stream of infrared data captured from a second viewpoint by RealSense device */ RS_STREAM_POINTS = 4, /**< Synthetic stream containing point cloud data generated by deprojecting the depth image */ RS_STREAM_RECTIFIED_COLOR = 5, /**< Synthetic stream containing undistorted color data with no extrinsic rotation from the depth stream */ RS_STREAM_COLOR_ALIGNED_TO_DEPTH = 6, /**< Synthetic stream containing color data but sharing intrinsics of depth stream */ RS_STREAM_INFRARED2_ALIGNED_TO_DEPTH = 7, /**< Synthetic stream containing second viewpoint infrared data but sharing intrinsics of depth stream */ RS_STREAM_DEPTH_ALIGNED_TO_COLOR = 8, /**< Synthetic stream containing depth data but sharing intrinsics of color stream */ RS_STREAM_DEPTH_ALIGNED_TO_RECTIFIED_COLOR = 9, /**< Synthetic stream containing depth data but sharing intrinsics of rectified color stream */ RS_STREAM_DEPTH_ALIGNED_TO_INFRARED2 = 10, /**< Synthetic stream containing depth data but sharing intrinsics of second viewpoint infrared stream */ RS_STREAM_COUNT = 11, RS_STREAM_MAX_ENUM = 0x7FFFFFFF } rs_stream; typedef enum rs_format { RS_FORMAT_ANY = 0, RS_FORMAT_Z16 = 1, /**< 16 bit linear depth values. The depth is meters is equal to depth scale * pixel value */ RS_FORMAT_DISPARITY16 = 2, /**< 16 bit linear disparity values. The depth in meters is equal to depth scale / pixel value */ RS_FORMAT_XYZ32F = 3, /**< 32 bit floating point 3D coordinates. */ RS_FORMAT_YUYV = 4, RS_FORMAT_RGB8 = 5, RS_FORMAT_BGR8 = 6, RS_FORMAT_RGBA8 = 7, RS_FORMAT_BGRA8 = 8, RS_FORMAT_Y8 = 9, RS_FORMAT_Y16 = 10, RS_FORMAT_RAW10 = 11, /**< Four 10-bit luminance values encoded into a 5-byte macropixel */ RS_FORMAT_COUNT = 12, RS_FORMAT_MAX_ENUM = 0x7FFFFFFF } rs_format; typedef enum rs_preset { RS_PRESET_BEST_QUALITY = 0, RS_PRESET_LARGEST_IMAGE = 1, RS_PRESET_HIGHEST_FRAMERATE = 2, RS_PRESET_COUNT = 3, RS_PRESET_MAX_ENUM = 0x7FFFFFFF } rs_preset; typedef enum rs_distortion { RS_DISTORTION_NONE = 0, /**< Rectilinear images, no distortion compensation required */ RS_DISTORTION_MODIFIED_BROWN_CONRADY = 1, /**< Equivalent to Brown-Conrady distortion, except that tangential distortion is applied to radially distorted points */ RS_DISTORTION_INVERSE_BROWN_CONRADY = 2, /**< Equivalent to Brown-Conrady distortion, except undistorts image instead of distorting it */ RS_DISTORTION_COUNT = 3, RS_DISTORTION_MAX_ENUM = 0x7FFFFFFF } rs_distortion; typedef enum rs_option { RS_OPTION_COLOR_BACKLIGHT_COMPENSATION = 0, RS_OPTION_COLOR_BRIGHTNESS = 1, RS_OPTION_COLOR_CONTRAST = 2, RS_OPTION_COLOR_EXPOSURE = 3, /**< Controls exposure time of color camera. Setting any value will disable auto exposure. */ RS_OPTION_COLOR_GAIN = 4, RS_OPTION_COLOR_GAMMA = 5, RS_OPTION_COLOR_HUE = 6, RS_OPTION_COLOR_SATURATION = 7, RS_OPTION_COLOR_SHARPNESS = 8, RS_OPTION_COLOR_WHITE_BALANCE = 9, /**< Controls white balance of color image. Setting any value will disable auto white balance. */ RS_OPTION_COLOR_ENABLE_AUTO_EXPOSURE = 10, /**< Set to 1 to enable automatic exposure control, or 0 to return to manual control */ RS_OPTION_COLOR_ENABLE_AUTO_WHITE_BALANCE = 11, /**< Set to 1 to enable automatic white balance control, or 0 to return to manual control */ RS_OPTION_F200_LASER_POWER = 12, /**< 0 - 15 */ RS_OPTION_F200_ACCURACY = 13, /**< 0 - 3 */ RS_OPTION_F200_MOTION_RANGE = 14, /**< 0 - 100 */ RS_OPTION_F200_FILTER_OPTION = 15, /**< 0 - 7 */ RS_OPTION_F200_CONFIDENCE_THRESHOLD = 16, /**< 0 - 15 */ RS_OPTION_SR300_DYNAMIC_FPS = 17, /**< {2, 5, 15, 30, 60} */ RS_OPTION_SR300_AUTO_RANGE_ENABLE_MOTION_VERSUS_RANGE = 18, RS_OPTION_SR300_AUTO_RANGE_ENABLE_LASER = 19, RS_OPTION_SR300_AUTO_RANGE_MIN_MOTION_VERSUS_RANGE = 20, RS_OPTION_SR300_AUTO_RANGE_MAX_MOTION_VERSUS_RANGE = 21, RS_OPTION_SR300_AUTO_RANGE_START_MOTION_VERSUS_RANGE = 22, RS_OPTION_SR300_AUTO_RANGE_MIN_LASER = 23, RS_OPTION_SR300_AUTO_RANGE_MAX_LASER = 24, RS_OPTION_SR300_AUTO_RANGE_START_LASER = 25, RS_OPTION_SR300_AUTO_RANGE_UPPER_THRESHOLD = 26, RS_OPTION_SR300_AUTO_RANGE_LOWER_THRESHOLD = 27, RS_OPTION_SR300_WAKEUP_DEV_PHASE1_PERIOD = 28, RS_OPTION_SR300_WAKEUP_DEV_PHASE1_FPS = 29, RS_OPTION_SR300_WAKEUP_DEV_PHASE2_PERIOD = 30, RS_OPTION_SR300_WAKEUP_DEV_PHASE2_FPS = 31, RS_OPTION_SR300_WAKEUP_DEV_RESET = 32, RS_OPTION_SR300_WAKE_ON_USB_REASON = 33, RS_OPTION_SR300_WAKE_ON_USB_CONFIDENCE = 34, RS_OPTION_R200_LR_AUTO_EXPOSURE_ENABLED = 35, /**< {0, 1} */ RS_OPTION_R200_LR_GAIN = 36, /**< 100 - 1600 (Units of 0.01) */ RS_OPTION_R200_LR_EXPOSURE = 37, /**< > 0 (Units of 0.1 ms) */ RS_OPTION_R200_EMITTER_ENABLED = 38, /**< {0, 1} */ RS_OPTION_R200_DEPTH_UNITS = 39, /**< micrometers per increment in integer depth values, 1000 is default (mm scale) */ RS_OPTION_R200_DEPTH_CLAMP_MIN = 40, /**< {0 - USHORT_MAX}. Can only be set before streaming starts. */ RS_OPTION_R200_DEPTH_CLAMP_MAX = 41, /**< {0 - USHORT_MAX}. Can only be set before streaming starts. */ RS_OPTION_R200_DISPARITY_MULTIPLIER = 42, /**< {0 - 1000}. The increments in integer disparity values corresponding to one pixel of disparity. Can only be set before streaming starts. */ RS_OPTION_R200_DISPARITY_SHIFT = 43, /**< {0 - 512}. Can only be set before streaming starts. */ RS_OPTION_R200_AUTO_EXPOSURE_MEAN_INTENSITY_SET_POINT = 44, RS_OPTION_R200_AUTO_EXPOSURE_BRIGHT_RATIO_SET_POINT = 45, RS_OPTION_R200_AUTO_EXPOSURE_KP_GAIN = 46, RS_OPTION_R200_AUTO_EXPOSURE_KP_EXPOSURE = 47, RS_OPTION_R200_AUTO_EXPOSURE_KP_DARK_THRESHOLD = 48, RS_OPTION_R200_AUTO_EXPOSURE_TOP_EDGE = 49, RS_OPTION_R200_AUTO_EXPOSURE_BOTTOM_EDGE = 50, RS_OPTION_R200_AUTO_EXPOSURE_LEFT_EDGE = 51, RS_OPTION_R200_AUTO_EXPOSURE_RIGHT_EDGE = 52, RS_OPTION_R200_DEPTH_CONTROL_ESTIMATE_MEDIAN_DECREMENT = 53, RS_OPTION_R200_DEPTH_CONTROL_ESTIMATE_MEDIAN_INCREMENT = 54, RS_OPTION_R200_DEPTH_CONTROL_MEDIAN_THRESHOLD = 55, RS_OPTION_R200_DEPTH_CONTROL_SCORE_MINIMUM_THRESHOLD = 56, RS_OPTION_R200_DEPTH_CONTROL_SCORE_MAXIMUM_THRESHOLD = 57, RS_OPTION_R200_DEPTH_CONTROL_TEXTURE_COUNT_THRESHOLD = 58, RS_OPTION_R200_DEPTH_CONTROL_TEXTURE_DIFFERENCE_THRESHOLD = 59, RS_OPTION_R200_DEPTH_CONTROL_SECOND_PEAK_THRESHOLD = 60, RS_OPTION_R200_DEPTH_CONTROL_NEIGHBOR_THRESHOLD = 61, RS_OPTION_R200_DEPTH_CONTROL_LR_THRESHOLD = 62, RS_OPTION_COUNT = 63, RS_OPTION_MAX_ENUM = 0x7FFFFFFF } rs_option; typedef struct rs_intrinsics { int width; /* width of the image in pixels */ int height; /* height of the image in pixels */ float ppx; /* horizontal coordinate of the principal point of the image, as a pixel offset from the left edge */ float ppy; /* vertical coordinate of the principal point of the image, as a pixel offset from the top edge */ float fx; /* focal length of the image plane, as a multiple of pixel width */ float fy; /* focal length of the image plane, as a multiple of pixel height */ rs_distortion model; /* distortion model of the image */ float coeffs[5]; /* distortion coefficients */ } rs_intrinsics; typedef struct rs_extrinsics { float rotation[9]; /* column-major 3x3 rotation matrix */ float translation[3]; /* 3 element translation vector, in meters */ } rs_extrinsics; typedef struct rs_context rs_context; typedef struct rs_device rs_device; typedef struct rs_error rs_error; rs_context * rs_create_context(int api_version, rs_error ** error); void rs_delete_context(rs_context * context, rs_error ** error); /** * determine number of connected devices * \param[out] error if non-null, receives any error that occurs during this call, otherwise, errors are ignored * \return the count of devices */ int rs_get_device_count(const rs_context * context, rs_error ** error); /** * retrieve connected device by index * \param[in] index the zero based index of device to retrieve * \param[out] error if non-null, receives any error that occurs during this call, otherwise, errors are ignored * \return the requested device */ rs_device * rs_get_device(rs_context * context, int index, rs_error ** error); /** * retrieve a human readable device model string * \param[out] error if non-null, receives any error that occurs during this call, otherwise, errors are ignored * \return the model string, such as "Intel RealSense F200" or "Intel RealSense R200" */ const char * rs_get_device_name(const rs_device * device, rs_error ** error); /** * retrieve the unique serial number of the device * \param[out] error if non-null, receives any error that occurs during this call, otherwise, errors are ignored * \return the serial number, in a format specific to the device model */ const char * rs_get_device_serial(const rs_device * device, rs_error ** error); /** * retrieve the version of the firmware currently installed on the device * \param[out] error if non-null, receives any error that occurs during this call, otherwise, errors are ignored * \return firmware version string, in a format is specific to device model */ const char * rs_get_device_firmware_version(const rs_device * device, rs_error ** error); /** * retrieve extrinsic transformation between the viewpoints of two different streams * \param[in] from_stream stream whose coordinate space we will transform from * \param[in] to_stream stream whose coordinate space we will transform to * \param[out] extrin the transformation between the two streams * \param[out] error if non-null, receives any error that occurs during this call, otherwise, errors are ignored */ void rs_get_device_extrinsics(const rs_device * device, rs_stream from_stream, rs_stream to_stream, rs_extrinsics * extrin, rs_error ** error); /** * retrieve mapping between the units of the depth image and meters * \param[out] error if non-null, receives any error that occurs during this call, otherwise, errors are ignored * \return depth in meters corresponding to a depth value of 1 */ float rs_get_device_depth_scale(const rs_device * device, rs_error ** error); /** * determine if the device allows a specific option to be queried and set * \param[in] option the option to check for support * \param[out] error if non-null, receives any error that occurs during this call, otherwise, errors are ignored * \return true if the option can be queried and set */ int rs_device_supports_option(const rs_device * device, rs_option option, rs_error ** error); /** * determine the number of streaming modes available for a given stream * \param[in] stream the stream whose modes will be enumerated * \param[out] error if non-null, receives any error that occurs during this call, otherwise, errors are ignored * \return the count of available modes */ int rs_get_stream_mode_count(const rs_device * device, rs_stream stream, rs_error ** error); /** * determine the properties of a specific streaming mode * \param[in] stream the stream whose mode will be queried * \param[in] index the zero based index of the streaming mode * \param[out] width the width of a frame image in pixels * \param[out] height the height of a frame image in pixels * \param[out] format the pixel format of a frame image * \param[out] framerate the number of frames which will be streamed per second * \param[out] error if non-null, receives any error that occurs during this call, otherwise, errors are ignored */ void rs_get_stream_mode(const rs_device * device, rs_stream stream, int index, int * width, int * height, rs_format * format, int * framerate, rs_error ** error); /** * enable a specific stream and request specific properties * \param[in] stream the stream to enable * \param[in] width the desired width of a frame image in pixels, or 0 if any width is acceptable * \param[in] height the desired height of a frame image in pixels, or 0 if any height is acceptable * \param[in] format the pixel format of a frame image, or ANY if any format is acceptable * \param[in] framerate the number of frames which will be streamed per second, or 0 if any framerate is acceptable * \param[out] error if non-null, receives any error that occurs during this call, otherwise, errors are ignored */ void rs_enable_stream(rs_device * device, rs_stream stream, int width, int height, rs_format format, int framerate, rs_error ** error); /** * enable a specific stream and request properties using a preset * \param[in] stream the stream to enable * \param[in] preset the preset to use to enable the stream * \param[out] error if non-null, receives any error that occurs during this call, otherwise, errors are ignored */ void rs_enable_stream_preset(rs_device * device, rs_stream stream, rs_preset preset, rs_error ** error); /** * disable a specific stream * \param[in] stream the stream to disable * \param[out] error if non-null, receives any error that occurs during this call, otherwise, errors are ignored */ void rs_disable_stream(rs_device * device, rs_stream stream, rs_error ** error); /** * determine if a specific stream is enabled * \param[in] stream the stream to check * \param[out] error if non-null, receives any error that occurs during this call, otherwise, errors are ignored * \return true if the stream is currently enabled */ int rs_is_stream_enabled(const rs_device * device, rs_stream stream, rs_error ** error); /** * retrieve the width in pixels of a specific stream, equivalent to the width field from the stream's intrinsics * \param[in] stream the stream whose width to retrieve * \param[out] error if non-null, receives any error that occurs during this call, otherwise, errors are ignored * \return the width in pixels of images from this stream */ int rs_get_stream_width(const rs_device * device, rs_stream stream, rs_error ** error); /** * retrieve the height in pixels of a specific stream, equivalent to the height field from the stream's intrinsics * \param[in] stream the stream whose height to retrieve * \param[out] error if non-null, receives any error that occurs during this call, otherwise, errors are ignored * \return the height in pixels of images from this stream */ int rs_get_stream_height(const rs_device * device, rs_stream stream, rs_error ** error); /** * retrieve the pixel format for a specific stream * \param[in] stream the stream whose format to retrieve * \param[out] error if non-null, receives any error that occurs during this call, otherwise, errors are ignored * \return the pixel format of the stream */ rs_format rs_get_stream_format(const rs_device * device, rs_stream stream, rs_error ** error); /** * retrieve the framerate for a specific stream * \param[in] stream the stream whose framerate to retrieve * \param[out] error if non-null, receives any error that occurs during this call, otherwise, errors are ignored * \return the framerate of the stream, in frames per second */ int rs_get_stream_framerate(const rs_device * device, rs_stream stream, rs_error ** error); /** * retrieve intrinsic camera parameters for a specific stream * \param[in] stream the stream whose parameters to retrieve * \param[out] intrin the intrinsic parameters of the stream * \param[out] error if non-null, receives any error that occurs during this call, otherwise, errors are ignored */ void rs_get_stream_intrinsics(const rs_device * device, rs_stream stream, rs_intrinsics * intrin, rs_error ** error); /** * begin streaming on all enabled streams for this device * \param[out] error if non-null, receives any error that occurs during this call, otherwise, errors are ignored */ void rs_start_device(rs_device * device, rs_error ** error); /** * end streaming on all streams for this device * \param[out] error if non-null, receives any error that occurs during this call, otherwise, errors are ignored */ void rs_stop_device(rs_device * device, rs_error ** error); /** * determine if the device is currently streaming * \param[out] error if non-null, receives any error that occurs during this call, otherwise, errors are ignored * \return true if the device is currently streaming */ int rs_is_device_streaming(const rs_device * device, rs_error ** error); /** * retrieve the available range of values of a supported option * \param[in] option the option whose range should be queried * \param[out] min the minimum value which will be accepted for this option * \param[out] max the maximum value which will be accepted for this option * \param[out] step the granularity of options which accept discrete values, or zero if the option accepts continuous values * \param[out] error if non-null, receives any error that occurs during this call, otherwise, errors are ignored */ void rs_get_device_option_range(rs_device * device, rs_option option, double * min, double * max, double * step, rs_error ** error); /** * efficiently retrieve the value of an arbitrary number of options, using minimal hardware IO * \param[in] options the array of options which should be queried * \param[in] count the length of the options and values arrays * \param[out] values the array which will receive the values of the queried options * \param[out] error if non-null, receives any error that occurs during this call, otherwise, errors are ignored */ void rs_get_device_options(rs_device * device, const rs_option * options, int count, double * values, rs_error ** error); /** * efficiently set the value of an arbitrary number of options, using minimal hardware IO * \param[in] options the array of options which should be set * \param[in] count the length of the options and values arrays * \param[in] values the array of values to which the options should be set * \param[out] error if non-null, receives any error that occurs during this call, otherwise, errors are ignored */ void rs_set_device_options(rs_device * device, const rs_option * options, int count, const double * values, rs_error ** error); /** * retrieve the current value of a single option * \param[in] option the option whose value should be retrieved * \param[out] error if non-null, receives any error that occurs during this call, otherwise, errors are ignored * \return the value of the option */ double rs_get_device_option(rs_device * device, rs_option option, rs_error ** error); /** * set the current value of a single option * \param[in] option the option whose value should be set * \param[in] value the value of the option * \param[out] error if non-null, receives any error that occurs during this call, otherwise, errors are ignored */ void rs_set_device_option(rs_device * device, rs_option option, double value, rs_error ** error); /** * block until new frames are available * \param[out] error if non-null, receives any error that occurs during this call, otherwise, errors are ignored */ void rs_wait_for_frames(rs_device * device, rs_error ** error); /** * check if new frames are available, without blocking * \param[out] error if non-null, receives any error that occurs during this call, otherwise, errors are ignored * \return 1 if new frames are available, 0 if no new frames have arrived */ int rs_poll_for_frames(rs_device * device, rs_error ** error); /** * retrieve the time at which the latest frame on a stream was captured * \param[in] stream the stream whose latest frame we are interested in * \param[out] error if non-null, receives any error that occurs during this call, otherwise, errors are ignored * \return the timestamp of the frame, in milliseconds since the device was started */ int rs_get_frame_timestamp(const rs_device * device, rs_stream stream, rs_error ** error); /** * retrieve the contents of the latest frame on a stream * \param[in] stream the stream whose latest frame we are interested in * \param[out] error if non-null, receives any error that occurs during this call, otherwise, errors are ignored * \return the pointer to the start of the frame data */ const void * rs_get_frame_data(const rs_device * device, rs_stream stream, rs_error ** error); const char * rs_get_failed_function (const rs_error * error); const char * rs_get_failed_args (const rs_error * error); const char * rs_get_error_message (const rs_error * error); void rs_free_error (rs_error * error); const char * rs_stream_to_string (rs_stream stream); const char * rs_format_to_string (rs_format format); const char * rs_preset_to_string (rs_preset preset); const char * rs_distortion_to_string (rs_distortion distortion); const char * rs_option_to_string (rs_option option); typedef enum { RS_LOG_SEVERITY_DEBUG = 0, /* Detailed information about ordinary operations */ RS_LOG_SEVERITY_INFO = 1, /* Terse information about ordinary operations */ RS_LOG_SEVERITY_WARN = 2, /* Indication of possible failure */ RS_LOG_SEVERITY_ERROR = 3, /* Indication of definite failure */ RS_LOG_SEVERITY_FATAL = 4, /* Indication of unrecoverable failure */ RS_LOG_SEVERITY_NONE = 5, /* No logging will occur */ RS_LOG_SEVERITY_MAX_ENUM = 0x7FFFFFFF } rs_log_severity; void rs_log_to_console(rs_log_severity min_severity, rs_error ** error); void rs_log_to_file(rs_log_severity min_severity, const char * file_path, rs_error ** error); #ifdef __cplusplus } #endif #endif