Skip to content

API Changes

Jump to bottom
Eran edited this page Aug 20, 2024 · 72 revisions

Version 2.56.1 beta

Please note that API changes in beta versions may not be final.

  • added RS2_OPTION_REGION_OF_INTEREST and its type, RS2_OPTION_TYPE_RECT and rs2_option_rect
  • New APIs
    • rs2_start_collecting_fw_logs and rs2_stop_collecting_fw_logs to start/stop FW logging for a specific device, with C++ rs2::device::start_collecting() and stop_collecting()
    • rs2_get_fw_log_parsed_module_name to get the FW log parsed message module name
    • rs2_pipeline_set_device to set the device used by the pipeline, with C++ rs2::pipeline::set_device()
    • rs2_get_calibration_config and rs2_set_calibration_config to get & set calibration configuration using JSON
    • rs2::motion_frame::get_combined_motion_data() can be used for access to the plain motion data used with RS2_STREAM_MOTION and RS2_FORMAT_COMBINED_MOTION

Version 2.55.1

  • RS2_FRAME_METADATA_ACTUAL_FPS better reflects actual HW FPS (based on timestamp & frame counts; same as shown in the Viewer as "Hardware FPS") but with better precision, with each unit being 0.001 FPS (see #12326)
  • When a context is deleted any callback set with rs2_set_devices_changed_callback will no longer get called (see #12275)
  • In the Python wrapper, config.enable_stream() no longer has default arguments (see #11861)
  • New APIs
    • rs2_create_context_ex accepts a JSON configuration to use (see #10386), which can override the default one now loaded from RS2_CONFIG_FILENAME (realsense-config.json already used by the Viewer; see #12432)
    • rs2_device_is_connected is the same as rs2_device_hub_is_device_connected, but does not need a rs2_device_hub (see #12240)
    • Added options-changed callbacks via rs2_set_options_changed_callback, periodically (by default, every second) querying all options in the sensor and triggering a callback (see 12483)
      • The resulting rs2_options_list can then be used with rs2_get_option_value_from_list, returning rs2_option_value comprising an (id, type, and value) (see #12616)
      • Options IDs can now be queried by name via rs2_option_from_string, the reverse of rs2_option_to_string (see #12163)
      • Related APIs include rs2_get_option_value, rs2_delete_option_value, rs2_set_option_value, rs2_option_type_to_string
      • Related types include rs2_option_type enum, rs2_option_value
    • Added rs2_gyro_sensitivity_to_string, RS2_OPTION_GYRO_SENSITIVITY, rs2_gyro_sensitivity enum
    • C++ (rs2::)
      • Added context( uninitialized ) constructor syntax to verbosely construct an uninitialized context
      • Added context( char const * json_settings ) constructor to go with rs2_create_context_ex
      • Added context::operator bool()
      • Added device::get_type(), ::get_description() to somewhat "standardize" how devices are reported in a common place
      • Added device::operator<() to properly order devices
      • Added device::is_connected(), calling rs2_device_is_connected
      • Added try-catch block inside calibration_change_callback::on_calibration_change
      • Added option_value class managing rs2_option_value lifetime
      • Added options_list class managing rs2_options_list lifetime, iteration over which results in option_value
      • Added options::get_option_value() and ::set_option_value(), calling rs2_get_option_value and rs2_set_option_value
      • Added options::get_supported_option_values(), similar to get_supported_options() but returning an options_list rather than a vector of option-IDs
      • Added options::on_options_changed, making use of new options_changed_callback
      • Added rs2_frame_callback_sptr, rs2_frame_processor_callback_sptr, rs2_notifications_callback_sptr, rs2_software_device_destruction_callback_sptr, rs2_log_callback_sptr, rs2_calibration_change_callback_sptr, rs2_devices_changed_callback_sptr, rs2_playback_status_changed_callback_sptr, rs2_update_progress_callback_sptr, rs2_options_changed_callback struct and rs2_options_changed_callback_sptr shared_ptr typedefs
  • Removed APIs
    • rs2_get_dsm_params & rs2_override_dsm_params, both of which were never really in use, alogside rs2_dsm_params, rs2_dsm_correction_model
    • Removed rs2::zero_order_invalidation filter
    • Removed rs2::calibrated_sensor class
  • Added RS2_CONFIG_FILENAME define containing the filename of the RealSense configuration file (under AppData for Windows, and hidden under the user's home directory with Linux)

Version 2.54.1

  • Firmware versions reported by librealsense will no longer have leading zeros; i.e., 05.14.0.0 will now be 5.14.0.0
  • Sqlite, originally meant for use in internal unit-tests, has not been in used for a while and has been removed, and with it rs2::recording_context and rs2::mock_context

Version 2.53.1

Functionality:

  • OCC/Tare Host-Assistance (HA) mode
    • Calibration algorithms used in both regular and HA modes are similar, however the differences in implementation require minor API adaptation:
    • HA mode shall be applied for RealSense MIPI cameras only; RealSense USB camera shall continue to use existing (on-chip) calibration mode
    • The selection of the HA/Regular calibration mode is done via calibration Json file via a new attribute
      • The presence of host-assistance parameter is not mandatory for USB cameras
    • Modified Tare calibration routine now also extracts the camera health metric before and after the calibration, to facilitate the user decision and provision for unattended execution/automation
    • OCC/Tare calibration routines the camera shall be configured as following:
      • Depth 1280X720@30FPS
    • Tare calibration API rs2_run_tare_calibration arguments have changed and therefore break backwards compatibility

Version 2.51.1

Functionality:

Version 2.50.0

Functionality:

  • rs2_run_focal_length_calibration_cpp - [UCAL] Perform Target-based Focal Length calibration (UCAL). The API call expect to receive Y8 frames gathered from Left and Right IR/Intensity sensors, to find and extract the targets captured by the camera, and then to readjust the focal length of the lef/right sensors. The output is the new calibration table ready to be flashed to the device. The user can pass on a callback that will get the algorithm processing status in percentage. Follow the Release Notes for v2.50.0 and read the accompanying White Paper for in-depth discussion of the camera intrinsic properties and the provided calibration methods
  • rs2_run_focal_length_calibration - [UCAL] C-language version of the above call
  • rs2_run_uv_map_calibration_cpp - [UCAL] UV-Mapping calibration is a provisional API for future enhancements (UCAL).
  • rs2_run_uv_map_calibration - [UCAL] UV-Mapping calibration is a provisional API for future enhancements.
  • rs2_calculate_target_z_cpp - [UCAL] The API call accepts frame collected by the Left sensor that include Y8 stream data, extracts the target that was captured by the camera and provides the estimated distance to the target's plane. Note that the accuracy of the algorithm is bounded by the precision of the target dimensions measured and provided by the customer
  • rs2_calculate_target_z - C-language API call for the above algorithm
  • rs2_frame_queue_size - Retrieve the number of frames that the queue holds.
  • rs2_matchers_to_string -Auxiliary function utilized by the Python wrapper

Enumerations:

Options:

  • RS2_OPTION_AUTO_EXPOSURE_LIMIT_TOGGLE - Toggles D400 series Auto-exposure limit on/off. When both this and Auto-Exposure controls are set on, changing the value of RS2_OPTION_AUTO_EXPOSURE_LIMIT would set the upper bound of exposure values in FW, allowing to keep the required FPS rate.
  • RS2_OPTION_AUTO_GAIN_LIMIT_TOGGLE - Toggles D400 series Auto-gain limit on/off. When both this and Auto-Exposure controls are set on, changing the value of RS2_OPTION_AUTO_GAIN_LIMIT would set the upper bound of digital gain values in FW, preventing over-saturation.

Version 2.47.0

Functionality:

  • rs2_check_firmware_compatibility - Check the FW image provided by the users and the target device. Prevent flashing devices with incompatible FW images to prevent bricking and malfunctioning. In case of incompatible match a user warning is issued and the DFU process is interrupted. Note that the protection is not invoked to devices that were originally enumerated in recovery (DFU) mode

New options:

Version 2.45.0

Documentation updates only

Version 2.43.0

Class:

  • calibration_change_device - is the new base class that separates calibration updates observer and calibration invocation. Casting device to the type allows to utilize the extension interface and register to thermal adjustment notifications.
  • video_stream_profile - Adding comparison operator for video_profile that takes into account stream resolution

Types:

  • RS2_CALIBRATION_THERMAL - [D400] Calibration type supported by selected Realsense Stereo devices.
  • RS2_EXTENSION_CALIBRATION_CHANGE_DEVICE [D400] - Extension API allowing to register user-defined callbacks for notifications of Thermal adjustments invocation. These callbacks are informative in their nature and can be used for environmental monitoring.

Version 2.42.0

Functions:

  • rs2_reset_logger - Cleanup logger selection.
  • rs2_enable_rolling_log_file - Upon reaching a certain limit close and remove the old log and start writing to a new file. Requires permissions to remove/rename files in log file directory.

Options:

Version 2.41.0

Functions:

Version 2.40.0

Functions:

Types:

Version 2.39.0

Functions:

Options:

Enumerations:

Extension types:

Version 2.38.1

Calibration APIs

Version 2.37.0

Version 2.36.0

Calibration APIs

Types:

API Calls:

Version 2.35.0

D400

Version 2.34.0

Device over Ethernet:

  • rs2_create_net_device - Establish connection to a hosts that runs Realsense server application and create a proxy camera class. The proxy then can be injected to Librealsense context and retrieved and queried as any other device instance (e.g query_devices()).

  • RS2_CAMERA_INFO_IP_ADDRESS - Stores the IP address of the remote server. The attribute is applicable for IP device only.

Software Device

Depth Camera

  • rs2_depth_frame_get_units - Retrieves the Raw Depth -> Metric Depth scaling factor that was previously availabel only via the depth sensor's API.
  • RS2_OPTION_EMITTER_ALWAYS_ON - Enable the projector to remain constantly on. Applies to D400 Global Shutter models (D43x) only.

Version 2.33.1

Configuration Serialization:

Logging enhancement:

L500-specific:

Controls:

Presets: /** \brief For L500 devices: provides optimized settings (presets) for specific types of usage. */

Option characterization:

Enum to string convenience APIs

Version 2.32.1

Version 2.31.0

D4xx Calibration routines: https://github.com/IntelRealSense/librealsense/commit/e89e4d6477e619291789d5b2be141e55303687e5

Metadata attributes:

Options:

Raw Streaming Formats:

PLY Exporter customization

Version 2.30.0

  • RS2_NOTIFICATION_CATEGORY_POSE_RELOCALIZATION - category added to rs2_notification_category. The notification designates T265 performing relocalization event, i.e. finding a match between the current position and a previously recorded map.

Version 2.29.0

Changed enum RS2_CAMERA_INFO_FIRMWARE_UPDATE_SERIAL_NUMBER to RS2_CAMERA_INFO_FIRMWARE_UPDATE_ID

Version 2.27.0

  • T265 Calibration Write APIs: Allow custom calibration to be provided to the device and committed to device flash memory. There is also a mechanism to roll-back to factory calibration. Currently these APIs are only implemented for the T265, but similar scheme is likely to be used for other families

  • rs2_clone_video_stream_profile - Utility function used when developing custom processing blocks that modify video stream resolution

Version 2.26.0

Firmware Update with non Digitally-signed images:

Version 2.25.0

Introduce T265-specific options

  • RS2_OPTION_ENABLE_MAPPING - Enable internal mapping generation required for location correction (feedback). Turning this option off will result in device running in an open loop.
  • RS2_OPTION_ENABLE_RELOCALIZATION - Allow the device ti utilize the internal/stored map to correct the current location based on previously recorded data.
  • RS2_OPTION_ENABLE_POSE_JUMPING - Allow the device to correct the location by making a discontinuous transformation (jump)
  • RS2_OPTION_ENABLE_DYNAMIC_CALIBRATION Read more in the above link

Version 2.24.0

  • Firmware Update functionality
  • Switch SR300 and D400 camera into DFU (Firmware Update) mode rs2_enter_update_state. When applied, the D400 camera will disconnect from host and reconnect as boot-loader device with a different VID/PID.
  • Perform Firmware Upgrade for D400/SR300 device rs2_update_firmware. The functionality requires a digitally-signed image to be provided as an input
  • Perform Firmware Upgrade for D400/SR300 device, report progress to user-provided callback rs2_update_firmware_cpp
  • Generate a firmware image copy rs2_create_flash_backup. Note that the generated backup image format is different from the file required in rs2_update_firmware/rs2_update_firmware_cpp and cannot be used with these APIs.
  • Generate a firmware image copy, report progress to user-provided callback rs2_create_flash_backup_cpp. The limitations are similar to rs2_create_flash_backup

Version 2.23.0

  • Depth linearity enhancement - Mitigate the half-pixel disparity issue by adjusting the Amplitude factor in the modulation funciton ()

Version 2.22.0

  • Global Camera Timestamp:
  • Add rs2_timestamp_domain::RS2_TIMESTAMP_DOMAIN_GLOBAL_TIME enumeration type that will be used as default when the HW timestamp is available via the appropriate metadata attribute.
  • Add rs2_sensor* rs2_get_frame_sensor function
  • Add RS2_OPTION_GLOBAL_TIME_ENABLED option
  • Depth units transformation - Processing block

  • rs2_processing_block* rs2_create_units_transform function

  • Add rs2_format::RS2_FORMAT_DISTANCE synthetic stream format

  • Add units_transform class

  • Add rs2_error * rs2_create_error functionality

  • Add pose_stream_profile class to handle T265 pose sensor.

  • Add frame::get_sensor() functionality

  • Add sensor_from_frame(frame f) functionality

  • GLSL Processing Blocks Module:

Version 2.20.0 to 2.21.0

New IR format introduced to D415 - W10:

  • Rectified, 10 bit per-pixels (packed) IR stream
  • FullHD configuration only 30 fps
  • Can be configured for use in conjunction with Depth stream (which is limited to 720p)
  • Available as:

Version 2.19.0 to 2.20.0

New Lens distortion model support added for T265 optical sensors -
RS2_DISTORTION_KANNALA_BRANDT4.
The model is utilized in Project/Deproject routines

rs2_send_wheel_odometry - Wheel odometer API velocity type updated from angular to linear.

From version 2.19.0 to 2.19.1

No API changes

From version 2.18.0 to 2.19.0

Added

Processing blocks/filters:

  1. rs2_get_recommended_processing_blocks Retrieving an ordered list of processing blocks/filters that are recommended to be used for a specific sensor. For instance, for the Depth sensor the list may include (Decimation->Disparity->Spatial->Temporal->HoleFilling->Disparity``) sequence.
  2. rs2_get_recommended_processing_blocks_count Retrieving the number of elements on the processing blocks list
  3. rs2_get_processing_block Extracting a specific processing block from the list
  4. rs2_delete_recommended_processing_blocks Deleting the processing blocks list. The function shall be used in conjunction with rs2_get_recommended_processing_blocks mentioned above to explicitly release the allocated resources.
  5. rs2_supports_processing_block_info Test for attribute availbility without throwing exception
  6. rs2_get_processing_block_info Retrieve processing block attribute
  7. rs2_is_processing_block_extendable_to Check API extension support
  8. rs2_create_zero_order_invalidation_block Adding zero order invalidation processing block

Options API:

  1. rs2_get_options_list Dynamic discovery of the options supported by a librealsense entity (sensor/processing_block/etc`).
  2. rs2_get_options_list_size Retrieve the number of elements in the options list.
  3. rs2_get_option_name Return human-readable option's name attribute.
  4. rs2_get_option_from_list Return an indexed element from the lsit
  5. rs2_delete_options_list Deleting the processing blocks list. The function shall be used in conjunction with rs2_get_options_list to explicitly release previously allocated resources.
  6. Extending RS2_OPTIONS enumeration list with:
    RS2_OPTION_ZERO_ORDER_POINT_X, RS2_OPTION_ZERO_ORDER_POINT_Y, RS2_OPTION_LLD_TEMPERATURE, RS2_OPTION_MC_TEMPERATURE, RS2_OPTION_MA_TEMPERATURE

Device management

  1. rs2_get_stereo_baseline Retrieve Stereo-based Depth sensor baseline
  2. rs2_context_add_software_device Inject a software (mockup) device into the SDK's context to be discoverable via query_devices API call.

T265-specific APIs

  1. rs2_context_unload_tracking_module Unload all perviously acquired tracking device instances. A device query for T265 will automatically take ownership of the connected device. This new API allows to explicitly release the devices so that they will be available for use by external processes.
  2. rs2_export_localization_map Advanced feature that allows to export the localization map for later reuse.
  3. rs2_import_localization_map Import previously-obtained localization map into device.
  4. rs2_set_static_node Add a positional bookmark (name&location) for positional referencing.
  5. rs2_get_static_node Retrieve previously stored bookmark position.
  6. rs2_load_wheel_odometry_config Load the robot platform configuration and calibration data into device. The data includes the rigid body transformation as well as calibration parameters.
  7. rs2_send_wheel_odometry Feed odometer data generated by a third-party sensor into the tracking device.

To be deprecated

  1. rs2_option_to_string - For existing options it will return option name, but for future API additions the user should call rs2_get_option_name instead

From version 2.17.0 to 2.18.0

Added

  1. rs2_create_yuy_decoder Adding YUY2 to RGB processing block #3056 :
  2. rs2_create_error Exposing librealsense error to avoid cross-boundary new/delete operations:
  3. rs2_create_threshold Adding depth min/max clamp filter (processing block):
  4. RS2_OPTION_EMITTER_ON_OFF - adding RS2_OPTION_EMITTER_ON_OFF to options enumeration
  5. rs2_processing_block_register_simple_option - adding ability to register custom processing block options
  6. Adding save_to_ply and save_single_frameset processing blocks to C++ headers only (staging to be added to the API) under rs_export.hpp.

Removed

  1. set_devices_changed_callback - was removed from C++ header files

From version 2.16.0 to 2.17.0

Added

  • #2773 introduced asynchronous pipeline API (recommended for high frequency data such as IMU). This change is limited to adding new overloads to pipeline.start method:
  1. rs2_pipeline_start_with_callback - pipeline start with C function pointer and user data, similar to sensor.start
  2. rs2_pipeline_start_with_callback_cpp - pipeline start with C++ frame callback object, similar to sensor.start
  3. rs2_pipeline_start_with_config_and_callback - pipeline start with callback and config
  4. rs2_pipeline_start_with_config_and_callback_cpp - pipeline start with callback and config (C++ frame callback object)
  • #2687 introduces new API to control recording compression:
  1. rs2_create_record_device_ex - create recorder and explicitly enable or disable compression. By default, compression will be enabled based on device type. D435i and T265 devices that provide high FPS streams disable compression by default to avoid frame drops during recording.
  • #2673 adds API to generate IMU and pose data with software_device:

Added support for IMU stream and recording IMU frames in software sensor:

  • stream_profile add_motion_stream(rs2_motion_stream motion_stream)
  • rs2_stream_profile* rs2_software_sensor_add_motion_stream(rs2_sensor* sensor, rs2_motion_stream motion_stream, rs2_error** error);
  • void on_motion_frame(rs2_software_motion_frame frame)
  • void rs2_software_sensor_on_motion_frame(rs2_sensor* sensor, rs2_software_motion_frame frame, rs2_error** error);

Added support for pose stream and recording pose frames in software sensor:

  • stream_profile add_pose_stream(rs2_pose_stream pose_stream)
  • rs2_stream_profile* rs2_software_sensor_add_pose_stream(rs2_sensor* sensor, rs2_pose_stream pose_stream, rs2_error** error);
  • void on_pose_frame(rs2_software_pose_frame frame)
  • void rs2_software_sensor_on_pose_frame(rs2_sensor* sensor, rs2_software_pose_frame frame, rs2_error** error);

Renamed

  • #2757 is splitting C++ processing_block class into processing_block and filter classes, with filter being derived from processing_block. processing_block abstraction offers start and invoke operations and does not guaranty results will be immediately available (processing_block can chose to delay frames). filter is special type of processing block that performs its operation immediately. This lets users compose filters using apply_filter operation.

From version 2.15.0 to 2.16.0

Added

Removed

  • processing_block::operator()(frame f) const was removed to reduce the overall ways processing block can be invoked. All processing blocks still contain invoke method for async processing (that sends the results to callback), and can be applied using added apply_filter method, in addition to helper methods like colorize and calculate specific to each block.

From version 2.14.0 to 2.15.0

Added

  • rs2_query_devices_ex - provide a list of connected devices with user-specified mask. This allows to cherry-pick specific types (e.g D400/SR300) during device acquisition stage.

Version 2.14.0 vs 2.13.1

Added

Version 2.13.0 (vs 2.11.1)

Added

  • rs2_option::RS2_OPTION_INTER_CAM_SYNC_MODE - Master/Slave control for multi-cam setup synchronization.

  • rs2_frame_metadata_value - Extending available attributes:

    • Depth Sensor:
      • Laser Power, Laser Power Mode, Exposure Priority, Exposure ROI.
    • RGB Sensor:
      • Brightness, Contrast, Saturation, Sharpness, Backlight_Compensation, Hue, Gamma, White_Balance_Mode & Temperature, Powerline Frequency and Low Light Compensation.

From 2.11.0 to 2.11.1

Modified

From 2.10.4 to 2.11.0

Added

  • rs2_create_processing_block_fptr - Allows to create custom processing blocks using C-bindings (C, LabView, .NET)
  • rs2_start_processing_fptr - Allows to start a processing block with a callback
  • rs2_config_enable_device_from_file_repeat_option - Allows to configure pipeline to play from recording while controlling playback-repeat behavior
  • rs2_create_hole_filling_filter_block - Hole-Filling filter supports three modes of operation:
    • Fill from left - fill the hole by the value from an immediate left neighbor
    • Fill from Far - select one of the up/down/left/right pixel neighbors farthest away from the camera
    • Fill from Near - select one of the up/down/left/right neighbors closest to the camera.
      It is recommended to use this post-processing block last in the filters chain. The functionality is integrated and can be reviewed in realsense-viewer/post-processing section

From 2.10.3 to 2.10.4

No API changes

From 2.10.2 to 2.10.3

Modified

Adding RS2_CAMERA_INFO_USB_TYPE_DESCRIPTOR enumeration to detect USB2 vs USB3 mode (when supported by the firmware).

From 2.10.1 to 2.10.2

Modified

Adding RS2_OPTION_AUTO_EXPOSURE_CONVERGE_STEP enumeration to control the FishEye Auto-Exposure algorithm The option is available for TM1-enabled devices only.

From 2.10.0 to 2.10.1

No API changes

From 2.9.1 to 2.10.0

Added

Changed

  • Fixed rs2_set_devices_changed_callback - missing const specifier and void** user parameter were added.
  • Change the 'Holes Filling' control for Temporal Post-Processing filter to be activated with RS2_OPTION_HOLES_FILL instead of RS2_OPTION_FILTER_MAGNITUDE

From 2.9.0 to 2.9.1

Added

  • rs2_keep_frame - this function can be used to preserve specific frame for longer processing. Calling it signals the intention to not return this frame to the pool within next 100ms.

From 2.8.3 to 2.9.0

Added

  • rs2_create_disparity_transform_block A depth data conversion class that transforms depth data info/from disparity domain for stereo-based depth sensors (D400 series). This functionality allows to run post-processing filters in disparity domain to enhance the filtered outcome.

  • rs2_depth_stereo_frame_get_baseline Retrieve the stereoscopic baseline in mm for stereo-based depth camera.

  • rs2_export_to_ply Making the export functionality publicly available, also addressing #862

From 2.8.2 to 2.8.3

Added

  • rs2_log - Usability function that allows the user to add logs to librealsense internal logger. The feature is useful in debugging and profiling scenarios.

Post-processing depth filters:

The filters have been integrated into the realsense-viewer and depth-quality tools.

From 2.8.1 to 2.8.2

No API changes introduced

From 2.8.0 to 2.8.1

Added

  • rs2_start_processing_queue - convenience function that lets the user target the output of a processing block (for example align) directly into a frame_queue. This helps in languages where function pointers are not available, such as LabView

Signature of rs2_is_option_read_only, rs2_get_option, rs2_set_option, rs2_supports_option, rs2_get_option_description and rs2_get_option_value_description was changed. First parameter used to be pointer to rs2_sensor and now is pointer to rs2_options. However, it is 100% safe to cast pointer to rs2_sensor to pointer to rs2_options.

From 2.7.9 to 2.8.0

Moved

See Pipeline Changes pull-request for explanation

Added

Removed

From 2.7.7 to 2.7.9

Moved

Added

Removed

Signature Changed

Intel® RealSense™ SDK Wiki

Help

Clone this wiki locally