Version
中文 | English

5.3.7. SDK JSON Import and Export for Gemini 330 Series

This document describes how to import and export SDK JSON configuration files for Gemini 330 series cameras in ROS2.

SDK JSON files can be used to restore or migrate camera configuration. The JSON file can come from the SDK, OrbbecViewer, or a configuration exported by ROS. The ROS2 node passes the file path to the SDK, triggers import or export, and reads back the final camera configuration after initialization.

5.3.7.1. Scope

This document only covers SDK JSON import and export for the Gemini 330 series. Prefer the dedicated launch file:

gemini_330_series_sdk_json.launch.py

This launch file is designed for SDK JSON workflows. It keeps only the parameters required for ROS2 runtime and device management, reducing the chance that default camera parameters from launch override the JSON configuration.

Full launch files such as gemini_330_series.launch.py and gemini_330_series_low_cpu.launch.py also provide load_config_json_file_path, but they contain many camera parameters. When parameters conflict, launch or YAML parameters that have already been passed to the node take precedence over the corresponding configuration in the JSON file.

5.3.7.2. Partial Import

SDK JSON supports partial import. You can remove modules and parameters that are not needed and keep only the content to be imported. Configuration items omitted from the JSON file are not modified by that JSON import; their final values are still determined by launch / YAML parameters, the current device state, or defaults.

It is recommended to minimize the JSON file for the actual use case. This reduces duplicate configuration and override relationships between JSON and launch / YAML parameters. For example, if only a depth preset and one depth post-processing filter are required, other sensor, point cloud, and unrelated filter configuration can be removed.

After removing modules or parameters, the file must remain valid JSON, and the hierarchy and field names that remain must conform to the SDK JSON format supported by the current device and firmware. Re-import the minimized file and verify the final effective configuration as described below.

5.3.7.3. Parameter Priority

When SDK JSON and ROS2 launch / YAML parameters configure the same item, use the following rule to understand the final effective value:

launch / YAML parameters passed to the node > same configuration in SDK JSON

“Passed to the node” includes default parameter values written by the launch file. Therefore, when using full launch files such as gemini_330_series.launch.py, some camera parameters may already be passed to the node even if the user did not explicitly set them on the command line, and those values may override the corresponding JSON configuration.

SDK JSON modules such as application_config, parameters.sensor_depth, and parameters.sensor_color can all contain configuration that corresponds to ROS2 parameters. Regardless of which module a field belongs to, if it controls the same configuration item as a launch / YAML parameter, use the priority rule above to determine the final effective value.

For example, if the JSON file sets color_brightness=10, but launch or YAML passes color_brightness=0, the camera finally uses 0. The final effective value is reflected by startup logs such as Config final readback ....

Therefore:

  • To restore configuration from JSON as much as possible, use gemini_330_series_sdk_json.launch.py.

  • If you must use a full launch file, leave parameters that conflict with JSON empty or unset, or set them to the expected values.

For available depth preset names, see Predefined Presets. To flash or upgrade a preset file, see firmware_update_tool Device Maintenance Tool.

5.3.7.4. Import an SDK JSON File

Use load_config_json_file_path to specify the SDK JSON file to import:

ros2 launch orbbec_camera gemini_330_series_sdk_json.launch.py \
  load_config_json_file_path:=/path/to/camera_config.json

The file path can be an absolute path, a relative path, or start with ~. Relative paths are resolved to absolute paths based on the current working directory.

When import succeeds, the log contains:

Config JSON loaded file=/path/to/camera_config.json

If the file does not exist, the log contains:

Config JSON load skip file=/path/to/camera_config.json reason=file_not_found

If the SDK fails to load the JSON file, the log contains:

Config JSON load failed file=/path/to/camera_config.json error="..."

5.3.7.5. Confirm the Final Effective Configuration

After importing JSON, the node reads back the final camera configuration during initialization and prints logs similar to:

Config final readback [depth] device_preset=Default
Config final readback [color] color_brightness=0
Config final readback [filter.depth.DecimationFilter] scale=2

These logs show the final effective camera configuration. If imported JSON conflicts with launch / YAML parameters, the readback logs reflect the overridden final values.

For depth filters, you can also check the current enabled state and parameters from the status topic:

ros2 topic echo /camera/depth_filters/status

5.3.7.7. Export an SDK JSON File

After the camera node is running, use the /camera/export_config_json service to export the current configuration:

ros2 service call /camera/export_config_json orbbec_camera_msgs/srv/SetString "{data: '/tmp/orbbec_camera_config.json'}"

After a successful call, the specified path contains an SDK JSON configuration file. The file can be imported later with load_config_json_file_path.

The export path can be an absolute path, a relative path, or start with ~. If the parent directory does not exist, the node creates it automatically.

When export succeeds, the service response and log contain:

Exported config json file path: /tmp/orbbec_camera_config.json

If the path is empty or export fails, the service returns failure information and the log contains the error reason.

5.3.7.8. Condensed Field Mapping

The table below lists common SDK JSON fields and their related ROS2 parameters. It is intended to help understand conflicts and overrides; it does not mean every field should be configured through launch.

SDK JSON field Related ROS2 parameters Description
application_config.sensors.Color.profile.* enable_color, color_width, color_height, color_fps, color_format, enable_color_undistortion Color stream enable state, resolution, frame rate, format, and undistortion.
application_config.sensors.Depth.profile.* enable_depth, depth_width, depth_height, depth_fps, depth_format, enable_depth_undistortion Depth stream enable state, resolution, frame rate, format, and undistortion.
application_config.sensors.LeftIR.profile.* enable_left_ir, left_ir_width, left_ir_height, left_ir_fps, left_ir_format, enable_left_ir_undistortion Left IR stream configuration.
application_config.sensors.RightIR.profile.* enable_right_ir, right_ir_width, right_ir_height, right_ir_fps, right_ir_format, enable_right_ir_undistortion Right IR stream configuration.
application_config.sensors.Accel.profile.* enable_accel, accel_rate, accel_range Accelerometer enable state, sample rate, and range.
application_config.sensors.Gyro.profile.* enable_gyro, gyro_rate, gyro_range Gyroscope enable state, sample rate, and range.
application_config.point_cloud.* enable_point_cloud, enable_colored_point_cloud, point_cloud_decimation_filter_factor, depth_registration, align_mode, align_target_stream, enable_frame_sync, frame_aggregate_mode Point cloud, colored point cloud, alignment, frame sync, and frame aggregation.
application_config.hdr_merge.* enable_hdr_merge HDR merge configuration.
application_config.device_decimation.* preset_resolution_config Device-level decimation configuration.
parameters.sensor_depth.depth_preset device_preset Depth preset. When importing JSON with a full launch file, set the device_preset passed through launch / YAML to an empty value so that it does not override JSON.
Exposure, gain, AE ROI, depth unit, laser, disparity, and image orientation fields under parameters.sensor_depth depth_exposure, depth_gain, enable_ir_auto_exposure, ir_ae_max_exposure, depth_ae_roi_*, depth_precision, enable_laser, laser_energy_level, disparity_to_depth_mode, disparity_range_mode, disparity_search_offset, depth_rotation, depth_flip, depth_mirror, etc. Depth-related device configuration.
parameters.sensor_depth.frame_interleave.* interleave_frame_enable, interleave_ae_mode, interleave_skip_index, hdr_index*_*, laser_index*_* HDR / laser interleave configuration.
parameters.sensor_depth.post_processing_filter.* enable_*_filter and related filter parameters Depth post-processing filter configuration. Detailed FalsePositiveFilter parameters are configured through JSON or /camera/set_filter filter_config.
Exposure, white balance, brightness, sharpness, anti-flicker, AE ROI, and image orientation fields under parameters.sensor_color enable_color_auto_exposure, color_exposure, color_gain, enable_color_auto_white_balance, color_white_balance, color_brightness, color_sharpness, color_powerline_freq, color_ae_roi_*, color_rotation, color_flip, color_mirror, etc. Color-related device configuration.
parameters.sensor_color.post_processing_filter.DecimationFilter enable_color_decimation_filter, color_decimation_filter_scale Color decimation filter configuration.
parameters.sensor_left_ir / parameters.sensor_right_ir left_ir_rotation, right_ir_rotation, enable_left_ir_sequence_id_filter, enable_right_ir_sequence_id_filter, left_ir_sequence_id_filter_id, right_ir_sequence_id_filter_id, etc. Left and right IR image orientation and sequence id filter configuration.

5.3.7.9. FAQ

5.3.7.9.1. JSON import does not take effect

Check the following:

  • Whether load_config_json_file_path points to an existing file.

  • Whether the log contains Config JSON loaded file=....

  • Whether a full launch file passed the same launch / YAML parameter and overrode the JSON configuration.

  • Whether the current device and firmware support the fields in the JSON file.

5.3.7.9.2. Should I use the dedicated launch file or the full launch file?

If the goal is to restore configuration from JSON as much as possible, use gemini_330_series_sdk_json.launch.py.

If you want to keep the larger set of parameter controls from a launch file, you can continue to use full launch files such as gemini_330_series.launch.py, but you need to know which parameters will override JSON.

5.3.7.9.3. Does the exported JSON contain the final configuration?

The exported JSON is based on the current final camera state. Before export, the node syncs current ROS2-side sensor, point cloud, and HDR merge configuration to the SDK application_config, and then calls the SDK JSON export.

If JSON was imported at startup and some configuration was overridden by launch / YAML, the exported file contains the overridden final configuration.