From 1cdd122dd9d164d06b85a69ad576dc7dfc22e95b Mon Sep 17 00:00:00 2001 From: SamerKhshiboun Date: Sun, 26 Mar 2023 01:23:13 +0300 Subject: [PATCH 1/8] reorder README.md --- README.md | 642 +++++++++++++++++++++++++++++++++++++++--------------- 1 file changed, 470 insertions(+), 172 deletions(-) diff --git a/README.md b/README.md index 6659fdb6957..55d2b7498a6 100644 --- a/README.md +++ b/README.md @@ -1,15 +1,47 @@ -# ROS2 Wrapper for Intel® RealSense™ Devices -These are packages for using Intel RealSense cameras (D400, L500 and SR300 cameras) with ROS2. - -This version supports ROS2 Dashing, Eloquent, Foxy, Galactic and Rolling. - -LibRealSense supported version: v2.51.1 (see [realsense2_camera release notes](https://github.com/IntelRealSense/realsense-ros/releases)) - - -## For LibRS ROS1 Wrapper please refer to [ROS1-legacy branch](https://github.com/IntelRealSense/realsense-ros/tree/ros1-legacy) - -## Please notice: if you are moving from RealSense [ROS2-legacy branch](https://github.com/IntelRealSense/realsense-ros/tree/ros2-legacy) to ROS2-development: -- **Changed Parameters**: +

+ Intel® RealSense™ +

+ +

+ ROS2 packages for using Intel RealSense D400 cameras.
+ Supported ROS2 Distros: Dashing, Eloquent, Foxy, Humble and Rolling.
+ Latest release notes +

+ +
+ +## Table of contents + * [ROS1 and ROS2 legacy](#legacy) + * [Installation](#installation) + * [Usage](#usage) + * [Starting the camera node](#start-camera-node) + * [Parameters](#parameters) + * [Topics](#topics) + * [Metadata Topic](#metadata) + * [Post-Processing Filters](#filters) + * [Available Services](#services) + * [Efficient intra-process communication](#intra-process) + * [Contributing](#contributing) + * [License](#license) + +

+ Legacy +

+ +
+ + Intel RealSense ROS1 Wrapper + + Intel Realsense ROS1 Wrapper is not supported anymore, since our developers team are focusing on ROS2 distro.
+ For ROS1 wrapper, go to ros1-legacy branch +
+ +
+ + Moving from ros2-legacy to ros2-development + + +* Changed Parameters: - **"stereo_module"**, **"l500_depth_sensor"** are replaced by **"depth_module"** - For video streams: **\.profile** replaces **\_width**, **\_height**, **\_fps** - **ROS2-legacy (Old)**: @@ -26,45 +58,75 @@ LibRealSense supported version: v2.51.1 (see [realsense2_camera release notes](h - **unite_imu_method** parameter is now changeable in runtime. - **enable_sync** parameter is now changeable in runtime. - - -## Installation Instructions - - ### Step 1: Install the ROS2 distribution - - #### Ubuntu 22.04: - - [ROS2 Humble](https://docs.ros.org/en/humble/Installation/Ubuntu-Install-Debians.html) - - #### Ubuntu 20.04: - - [ROS2 Foxy](https://docs.ros.org/en/foxy/Installation/Ubuntu-Install-Debians.html) - - [ROS2 Galactic](https://docs.ros.org/en/galactic/Installation/Ubuntu-Install-Debians.html) - - #### Ubuntu 18.04 : - - [ROS2 Dashing](https://docs.ros.org/en/dashing/Installation/Ubuntu-Install-Debians.html) - - [ROS2 Eloquent](https://docs.ros.org/en/eloquent/Installation/Linux-Install-Debians.html) - - -### Step 2: Install the latest Intel® RealSense™ SDK 2.0 - -- #### Option 1: Install librealsense2 debian package (Not supported in Ubuntu 22.04 yet) - - Jetson users - use the [Jetson Installation Guide](https://github.com/IntelRealSense/librealsense/blob/master/doc/installation_jetson.md) - - Otherwise, install from [Linux Debian Installation Guide](https://github.com/IntelRealSense/librealsense/blob/master/doc/distribution_linux.md#installing-the-packages) - - In this case treat yourself as a developer: make sure to follow the instructions to also install librealsense2-dev and librealsense2-dkms packages - -- #### Option 2: Build from source - - Download the latest [Intel® RealSense™ SDK 2.0](https://github.com/IntelRealSense/librealsense/releases/tag/v2.51.1) +
+ + +

+ Installation +

+ +
+ + Step 1: Install the ROS2 distribution + + +- #### Ubuntu 22.04: + - [ROS2 Humble](https://docs.ros.org/en/humble/Installation/Ubuntu-Install-Debians.html) +- #### Ubuntu 20.04: + - [ROS2 Foxy](https://docs.ros.org/en/foxy/Installation/Ubuntu-Install-Debians.html) + - [ROS2 Galactic](https://docs.ros.org/en/galactic/Installation/Ubuntu-Install-Debians.html) +- #### Ubuntu 18.04 : + - [ROS2 Dashing](https://docs.ros.org/en/dashing/Installation/Ubuntu-Install-Debians.html) + - [ROS2 Eloquent](https://docs.ros.org/en/eloquent/Installation/Linux-Install-Debians.html) + +
+ +
+ + Step 2: Install latest Intel® RealSense™ SDK 2.0 + + +- #### Option 1: Install librealsense2 debian package from Intel servers + - Jetson users - use the [Jetson Installation Guide](https://github.com/IntelRealSense/librealsense/blob/master/doc/installation_jetson.md) + - Otherwise, install from [Linux Debian Installation Guide](https://github.com/IntelRealSense/librealsense/blob/master/doc/distribution_linux.md#installing-the-packages) + - In this case treat yourself as a developer: make sure to follow the instructions to also install librealsense2-dev and librealsense2-dkms packages + +- #### Option 2: Install librealsense2 (without graphical tools and examples) debian package from ROS servers: + - [Configure](http://wiki.ros.org/Installation/Ubuntu/Sources) your Ubuntu repositories + - Install all realsense ROS packages by ```sudo apt install ros--librealsense2*``` + - For example, for Humble distro: ```sudo apt install ros-humble-librealsense2*``` + +- #### Option 3: Build from source + - Download the latest [Intel® RealSense™ SDK 2.0](https://github.com/IntelRealSense/librealsense/releases/tag/v2.53.1) - Follow the instructions under [Linux Installation](https://github.com/IntelRealSense/librealsense/blob/master/doc/installation.md) - -### Step 3: Install Intel® RealSense™ ROS2 wrapper from sources - - Create a ROS2 workspace +
+ +
+ + Step 3: Install Intel® RealSense™ ROS2 wrapper + + +#### Option 1: Install debian package from ROS servers + - [Configure](http://wiki.ros.org/Installation/Ubuntu/Sources) your Ubuntu repositories + - Install all realsense ROS packages by ```sudo apt install ros--realsense2-*``` + - For example, for Humble distro: ```sudo apt install ros-humble-realsense2-*``` + +#### Option 2: Install from source + + - Create a ROS2 workspace ```bash mkdir -p ~/ros2_ws/src cd ~/ros2_ws/src/ ``` - - Clone the latest ROS2 Intel® RealSense™ wrapper from [here](https://github.com/IntelRealSense/realsense-ros.git) into '~/ros2_ws/src/' + + - Clone the latest ROS2 Intel® RealSense™ wrapper from [here](https://github.com/IntelRealSense/realsense-ros.git) into '~/ros2_ws/src/' ```bashrc git clone https://github.com/IntelRealSense/realsense-ros.git -b ros2-development cd ~/ros2_ws ``` -### Step 4: Install dependencies + + - Install dependencies ```bash sudo apt-get install python3-rosdep -y sudo rosdep init # "sudo rosdep init --include-eol-distros" for Eloquent and earlier @@ -72,43 +134,98 @@ LibRealSense supported version: v2.51.1 (see [realsense2_camera release notes](h rosdep install -i --from-path src --rosdistro $ROS_DISTRO --skip-keys=librealsense2 -y ``` -### Step 5: Build + - Build ```bash colcon build ``` -### Step 6: Terminal environment + - Source environment ```bash ROS_DISTRO= # set your ROS_DISTRO: humble, galactic, foxy, eloquent, dashing source /opt/ros/$ROS_DISTRO/setup.bash cd ~/ros2_ws . install/local_setup.bash ``` + +
+ +

+ Usage +

+ +

+ Start the camera node +

+ + #### with ros2 run: + ros2 run realsense2_camera realsense2_camera_node + # or, with parameters, for example - temporal and spatial filters are enabled: + ros2 run realsense2_camera realsense2_camera_node --ros-args -p enable_color:=false -p spatial_filter.enable:=true -p temporal_filter.enable:=true + + #### with ros2 launch: + ros2 launch realsense2_camera rs_launch.py + ros2 launch realsense2_camera rs_launch.py depth_module.profile:=1280x720x30 pointcloud.enable:=true + +

+ Parameters +

+ +### Sensor Parameters: +Each sensor has a unique set of parameters. +Video sensors, such as depth_module or rgb_camera have, at least, the 'profile' parameter.
+It is a string of the following format: \X\X\ (The deviding character can be X, x or ",". Spaces are ignored.) -  +Since infra1, infra2 and depth are all streams of the depth_module, their width, height and fps are defined by their common sensor. +If the specified combination of parameters is not available by the device, the default configuration will be used.
-## Usage Instructions +### Available Parameters: +For the entire list of parameters type `ros2 param list`. +For reading a parameter value use `ros2 param get ` for instance: `ros2 param get /camera/camera depth_module.emitter_on_off` +For setting a new value for a parameter use `ros2 param set ` i.e. `ros2 param set /camera/camera depth_module.emitter_on_off true` -### Start the camera node -To start the camera node in ROS: +#### Parameters that can be modified during runtime: +- All of the filters and sensors inner parameters. +- **enable_****: Choose whether to enable a specified stream or not. Default is true for images and false for orientation streams. can be any of *infra1, infra2, color, depth, fisheye, fisheye1, fisheye2, gyro, accel, pose*. +- **enable_sync**: gathers closest frames of different sensors, infra red, color and depth, to be sent with the same timetag. This happens automatically when such filters as pointcloud are enabled. +- ****_qos**: can be any of *infra, color, fisheye, depth, gyro, accel, pose*. Sets the QoS by which the topic is published. Available values are the following strings: SYSTEM_DEFAULT, DEFAULT, PARAMETER_EVENTS, SERVICES_DEFAULT, PARAMETERS, SENSOR_DATA. +- **Notice:** ****_info_qos** refers to both camera_info topics and metadata topics. +- **tf_publish_rate**: double, positive values mean dynamic transform publication with specified rate, all other values mean static transform publication. Defaults to 0 -```bash -ros2 launch realsense2_camera rs_launch.py -``` -or, with parameters, for example - temporal and spatial filters are enabled: -```bash -ros2 run realsense2_camera realsense2_camera_node --ros-args -p enable_color:=false -p spatial_filter.enable:=true -p temporal_filter.enable:=true -``` +#### Parameters that cannot be changed in runtime: +- **serial_no**: will attach to the device with the given serial number (*serial_no*) number. Default, attach to the first (in an inner list) RealSense device. + - Note: serial number can also be defined with "_" prefix. For instance, serial number 831612073525 can be set in command line as `serial_no:=_831612073525`. That is a workaround until a better method will be found to ROS2's auto conversion of strings containing only digits into integers. +- **usb_port_id**: will attach to the device with the given USB port (*usb_port_id*). i.e 4-1, 4-2 etc. Default, ignore USB port when choosing a device. +- **device_type**: will attach to a device whose name includes the given *device_type* regular expression pattern. Default, ignore device type. For example, device_type:=d435 will match d435 and d435i. device_type=d435(?!i) will match d435 but not d435i. +- **reconnect_timeout**: When the driver cannot connect to the device try to reconnect after this timeout (in seconds). +- **wait_for_device_timeout**: If the specified device is not found, will wait *wait_for_device_timeout* seconds before exits. Defualt, *wait_for_device_timeout < 0*, will wait indefinitely. +- **rosbag_filename**: Publish topics from rosbag file. There are two ways for loading rosbag file: + * Command line - ```ros2 run realsense2_camera realsense2_camera_node -p rosbag_filename:="/full/path/to/rosbag.bag"``` + * Launch file - set ```rosbag_filename``` parameter with rosbag full path (see ```realsense2_camera/launch/rs_launch.py``` as reference) -or, with a launch file: -```bash -ros2 launch realsense2_camera rs_launch.py -ros2 launch realsense2_camera rs_launch.py depth_module.profile:=1280x720x30 pointcloud.enable:=true -``` +- **initial_reset**: On occasions the device was not closed properly and due to firmware issues needs to reset. If set to true, the device will reset prior to usage. -This will stream all camera sensors and publish on the appropriate ROS topics. +- ****_frame_id**, ****_optical_frame_id**, **aligned_depth_to_**_frame_id**: Specify the different frame_id for the different frames. Especially important when using multiple cameras. -### Published Topics +- **base_frame_id**: defines the frame_id all static transformations refers to. +- **odom_frame_id**: defines the origin coordinate system in ROS convention (X-Forward, Y-Left, Z-Up). pose topic defines the pose relative to that system. + +- **unite_imu_method**: The D435i camera has built in IMU components which produce 2 unrelated streams: *gyro* - which shows angular velocity and *accel* which shows linear acceleration. Each with it's own frequency. By default, 2 corresponding topics are available, each with only the relevant fields of the message sensor_msgs::Imu are filled out. +Setting *unite_imu_method* creates a new topic, *imu*, that replaces the default *gyro* and *accel* topics. The *imu* topic is published at the rate of the gyro. All the fields of the Imu message under the *imu* topic are filled out. `unite_imu_method` parameter supported values are [0-2] meaning: [0 -> None, 1 -> Copy, 2 -> Linear_ interpolation] when: + - **linear_interpolation**: Every gyro message is attached by the an accel message interpolated to the gyro's timestamp. + - **copy**: Every gyro message is attached by the last accel message. +- **clip_distance**: remove from the depth image all values above a given value (meters). Disable by giving negative value (default) +- **linear_accel_cov**, **angular_velocity_cov**: sets the variance given to the Imu readings. +- **hold_back_imu_for_frames**: Images processing takes time. Therefor there is a time gap between the moment the image arrives at the wrapper and the moment the image is published to the ROS environment. During this time, Imu messages keep on arriving and a situation is created where an image with earlier timestamp is published after Imu message with later timestamp. If that is a problem, setting *hold_back_imu_for_frames* to *true* will hold the Imu messages back while processing the images and then publish them all in a burst, thus keeping the order of publication as the order of arrival. Note that in either case, the timestamp in each message's header reflects the time of it's origin. +- **publish_tf**: boolean, publish or not TF at all. Defaults to True. +- **diagnostics_period**: double, positive values set the period between diagnostics updates on the `/diagnostics` topic. 0 or negative values mean no diagnostics topic is published. Defaults to 0.
+The `/diagnostics` topic includes information regarding the device temperatures and actual frequency of the enabled streams. + +- **publish_odom_tf**: If True (default) publish TF from odom_frame to pose_frame. + +

+ Published Topics +

+ The published topics differ according to the device and parameters. After running the above command with D435i attached, the following list of topics will be available (This is a partial list. For full one type `ros2 topic list`): - /camera/aligned_depth_to_color/camera_info @@ -127,8 +244,9 @@ After running the above command with D435i attached, the following list of topic - /rosout - /tf_static +This will stream relevant camera sensors and publish on the appropriate ROS topics. -Enabling accel and gyro is achieved either by adding the following parameters to the command line:
+ Enabling accel and gyro is achieved either by adding the following parameters to the command line:
`ros2 launch realsense2_camera rs_launch.py pointcloud.enable:=true enable_gyro:=true enable_accel:=true`
or in runtime using the following commands: ``` @@ -146,117 +264,57 @@ Enabling stream adds matching topics. For instance, enabling the gyro and accel - /camera/gyro/metadata - /camera/gyro/sample - ->Using an L515 device the list differs a little by adding a 4-bit confidence grade (published as a mono8 image): ->- /camera/confidence/camera_info ->- /camera/confidence/image_rect_raw -> ->It also replaces the 2 infrared topic sets with the single available one: ->- /camera/infra/camera_info ->- /camera/infra/image_raw - -To turn them off: `ros2 param set /camera/camera enable_infra false` -The "/camera" prefix is the namesapce specified in the given launch file. -When using D435 or D415, the gyro and accel topics wont be available. - -### The metadata topic: +

+ Metadata topic +

+ The metadata messages store the camera's available metadata in a *json* format. To learn more, a dedicated script for echoing a metadata topic in runtime is attached. For instance, use the following command to echo the camera/depth/metadata topic: ``` python3 src/realsense-ros/realsense2_camera/scripts/echo_metadada.py /camera/depth/metadata ``` - -### Post processing blocks - i.e. filters: -The following processing blocks are available: + +

+ Post-Processing Filters +

+ +The following post processing filters are available: - ```align_depth```: If enabled, will publish the depth image aligned to the color image on the topic `/camera/aligned_depth_to_color/image_raw`.
The pointcloud, if created, will be based on the aligned depth image. - - ```colorizer```: will color the depth image. On the depth topic an RGB image will be published, instead of the 16bit depth values . - ```pointcloud```: will add a pointcloud topic `/camera/depth/color/points`. * The texture of the pointcloud can be modified using the `pointcloud.stream_filter` parameter.
* The depth FOV and the texture FOV are not similar. By default, pointcloud is limited to the section of depth containing the texture. You can have a full depth to pointcloud, coloring the regions beyond the texture with zeros, by setting `pointcloud.allow_no_texture_points` to true. * pointcloud is of an unordered format by default. This can be changed by setting `pointcloud.ordered_pc` to true. - - ```hdr_merge```: Allows depth image to be created by merging the information from 2 consecutive frames, taken with different exposure and gain values. The way to set exposure and gain values for each sequence in runtime is by first selecting the sequence id, using the `depth_module.sequence_id` parameter and then modifying the `depth_module.gain`, and `depth_module.exposure`.
To view the effect on the infrared image for each sequence id use the `sequence_id_filter.sequence_id` parameter.
To initialize these parameters in start time use the following parameters:
`depth_module.exposure.1`, `depth_module.gain.1`, `depth_module.exposure.2`, `depth_module.gain.2`
\* For in-depth review of the subject please read the accompanying [white paper](https://dev.intelrealsense.com/docs/high-dynamic-range-with-stereoscopic-depth-cameras). - - The following filters have detailed descriptions in : https://github.com/IntelRealSense/librealsense/blob/master/doc/post-processing-filters.md - - ```disparity_filter``` - convert depth to disparity before applying other filters and back. - - ```spatial_filter``` - filter the depth image spatially. - - ```temporal_filter``` - filter the depth image temporally. - - ```hole_filling_filter``` - apply hole-filling filter. - - ```decimation_filter``` - reduces depth scene complexity. + - The following filters have detailed descriptions in : https://github.com/IntelRealSense/librealsense/blob/master/doc/post-processing-filters.md + - ```disparity_filter``` - convert depth to disparity before applying other filters and back. + - ```spatial_filter``` - filter the depth image spatially. + - ```temporal_filter``` - filter the depth image temporally. + - ```hole_filling_filter``` - apply hole-filling filter. + - ```decimation_filter``` - reduces depth scene complexity. Each of the above filters have it's own parameters, following the naming convention of `.` including a `.enable` parameter to enable/disable it. -### Sensor Parameters: -Each sensor has a unique set of parameters. -Video sensors, such as depth_module or rgb_camera have, at least, the 'profile' parameter.
-It is a string of the following format: \X\X\ (The deviding character can be X, x or ",". Spaces are ignored.) - -Since infra1, infra2 and depth are all streams of the depth_module, their width, height and fps are defined by their common sensor. -The same rule applies in L515 for the depth, infra and confidence streams which all share the parameters of their common depth_module. -If the specified combination of parameters is not available by the device, the default configuration will be used.
- -### Available Parameters: -For the entire list of parameters type `ros2 param list`. -For reading a parameter value use `ros2 param get ` for instance: `ros2 param get /camera/camera depth_module.emitter_on_off` -For setting a new value for a parameter use `ros2 param set ` i.e. `ros2 param set /camera/camera depth_module.emitter_on_off true` - -#### Parameters that can be modified during runtime: -- All of the filters and sensors inner parameters. -- **enable_****: Choose whether to enable a specified stream or not. Default is true for images and false for orientation streams. can be any of *infra1, infra2, color, depth, fisheye, fisheye1, fisheye2, gyro, accel, pose*. -- **enable_sync**: gathers closest frames of different sensors, infra red, color and depth, to be sent with the same timetag. This happens automatically when such filters as pointcloud are enabled. -- ****_qos**: can be any of *infra, color, fisheye, depth, gyro, accel, pose*. Sets the QoS by which the topic is published. Available values are the following strings: SYSTEM_DEFAULT, DEFAULT, PARAMETER_EVENTS, SERVICES_DEFAULT, PARAMETERS, SENSOR_DATA. -- **Notice:** ****_info_qos** refers to both camera_info topics and metadata topics. -- **tf_publish_rate**: double, positive values mean dynamic transform publication with specified rate, all other values mean static transform publication. Defaults to 0 - - - -#### Parameters that cannot be changed in runtime: -- **serial_no**: will attach to the device with the given serial number (*serial_no*) number. Default, attach to the first (in an inner list) RealSense device. - - Note: serial number can also be defined with "_" prefix. For instance, serial number 831612073525 can be set in command line as `serial_no:=_831612073525`. That is a workaround until a better method will be found to ROS2's auto conversion of strings containing only digits into integers. -- **usb_port_id**: will attach to the device with the given USB port (*usb_port_id*). i.e 4-1, 4-2 etc. Default, ignore USB port when choosing a device. -- **device_type**: will attach to a device whose name includes the given *device_type* regular expression pattern. Default, ignore device type. For example, device_type:=d435 will match d435 and d435i. device_type=d435(?!i) will match d435 but not d435i. -- **reconnect_timeout**: When the driver cannot connect to the device try to reconnect after this timeout (in seconds). -- **wait_for_device_timeout**: If the specified device is not found, will wait *wait_for_device_timeout* seconds before exits. Defualt, *wait_for_device_timeout < 0*, will wait indefinitely. -- **rosbag_filename**: Publish topics from rosbag file. There are two ways for loading rosbag file: - * Command line - ```ros2 run realsense2_camera realsense2_camera_node -p rosbag_filename:="/full/path/to/rosbag.bag"``` - * Launch file - set ```rosbag_filename``` parameter with rosbag full path (see ```realsense2_camera/launch/rs_launch.py``` as reference) - -- **initial_reset**: On occasions the device was not closed properly and due to firmware issues needs to reset. If set to true, the device will reset prior to usage. - -- ****_frame_id**, ****_optical_frame_id**, **aligned_depth_to_**_frame_id**: Specify the different frame_id for the different frames. Especially important when using multiple cameras. - -- **base_frame_id**: defines the frame_id all static transformations refers to. -- **odom_frame_id**: defines the origin coordinate system in ROS convention (X-Forward, Y-Left, Z-Up). pose topic defines the pose relative to that system. - -- **unite_imu_method**: The D435i camera has built in IMU components which produce 2 unrelated streams: *gyro* - which shows angular velocity and *accel* which shows linear acceleration. Each with it's own frequency. By default, 2 corresponding topics are available, each with only the relevant fields of the message sensor_msgs::Imu are filled out. -Setting *unite_imu_method* creates a new topic, *imu*, that replaces the default *gyro* and *accel* topics. The *imu* topic is published at the rate of the gyro. All the fields of the Imu message under the *imu* topic are filled out. `unite_imu_method` parameter supported values are [0-2] meaning: [0 -> None, 1 -> Copy, 2 -> Linear_ interpolation] when: - - **linear_interpolation**: Every gyro message is attached by the an accel message interpolated to the gyro's timestamp. - - **copy**: Every gyro message is attached by the last accel message. -- **clip_distance**: remove from the depth image all values above a given value (meters). Disable by giving negative value (default) -- **linear_accel_cov**, **angular_velocity_cov**: sets the variance given to the Imu readings. -- **hold_back_imu_for_frames**: Images processing takes time. Therefor there is a time gap between the moment the image arrives at the wrapper and the moment the image is published to the ROS environment. During this time, Imu messages keep on arriving and a situation is created where an image with earlier timestamp is published after Imu message with later timestamp. If that is a problem, setting *hold_back_imu_for_frames* to *true* will hold the Imu messages back while processing the images and then publish them all in a burst, thus keeping the order of publication as the order of arrival. Note that in either case, the timestamp in each message's header reflects the time of it's origin. -- **publish_tf**: boolean, publish or not TF at all. Defaults to True. -- **diagnostics_period**: double, positive values set the period between diagnostics updates on the `/diagnostics` topic. 0 or negative values mean no diagnostics topic is published. Defaults to 0.
-The `/diagnostics` topic includes information regarding the device temperatures and actual frequency of the enabled streams. - -- **publish_odom_tf**: If True (default) publish TF from odom_frame to pose_frame. - -### Available services: +

+ Available services +

+ - device_info : retrieve information about the device - serial_number, firmware_version etc. Type `ros2 interface show realsense2_camera_msgs/srv/DeviceInfo` for the full list. Call example: `ros2 service call /camera/device_info realsense2_camera_msgs/srv/DeviceInfo` - Note that for **ROS2 Dashing** the command is `ros2 srv show realsense2_camera_msgs/srv/DeviceInfo` - -## Efficient intra-process communication: - +

+ Efficient intra-process communication: +

+ Our ROS2 Wrapper node supports zero-copy communications if loaded in the same process as a subscriber node. This can reduce copy times on image topics (not point-cloud or others), especially with big frame resolutions and high FPS. You will need to launch a component container and launch our node as a component together with other component nodes. Further details on "Composing multiple nodes in a single process" can be found [here](https://docs.ros.org/en/rolling/Tutorials/Composition.html). Further details on efficient intra-process communication can be found [here](https://docs.ros.org/en/foxy/Tutorials/Intra-Process-Communication.html#efficient-intra-process-communication). -### Example + ### Example #### Manually loading multiple components into the same process * Start the component: ```bash @@ -290,37 +348,277 @@ The launch file accepts a parameter, `intra_process_comms`, controlling whether ros2 launch realsense2_camera rs_intra_process_demo_launch.py intra_process_comms:=true ``` +
+ +

+ Contributing +

+ + # How to Contribute -## Still in the pipeline: +This project welcomes third-party code via GitHub pull requests. +You are welcome to propose and discuss enhancements using project [issues](https://github.com/IntelRealSense/realsense-ros/issues). -* Migrate infra_rgb option. +> **Branching Policy**: +> The `ros2-development` branch is considered stable, at all times. +> If you plan to propose a patch, please commit into the `ros2-development` branch, or its own feature branch. -### Unit tests: -Unit-tests are based on bag files saved on S3 server. These can be downloaded using the following commands: -```bash -cd ros2_ws -wget "http://realsense-hw-public.s3.amazonaws.com/rs-tests/TestData/outdoors.bag" -P "records/" -wget "http://realsense-hw-public.s3-eu-west-1.amazonaws.com/rs-tests/D435i_Depth_and_IMU_Stands_still.bag" -P "records/" -``` -Then, unit-tests can be run using the following command (use either python or python3): -```bash -python3 src/realsense-ros/realsense2_camera/scripts/rs2_test.py --all -``` +In addition, please run `pr_check.sh` under `scripts` directory. This scripts verify compliance with project's standards: -## License -Copyright 2022 Intel Corporation +1. Every example / source file must refer to [LICENSE](https://github.com/IntelRealSense/realsense-ros/blob/ros2-development/LICENSE) +2. Every example / source file must include correct copyright notice +3. For indentation we are using spaces and not tabs +4. Line-endings must be Unix and not DOS style -Licensed under the Apache License, Version 2.0 (the "License"); -you may not use this project except in compliance with the License. -You may obtain a copy of the License at +Most common issues can be automatically resolved by running `./pr_check.sh --fix` - http://www.apache.org/licenses/LICENSE-2.0 +Please familirize yourself with the [Apache License 2.0](https://github.com/IntelRealSense/realsense-ros/blob/ros2-development/LICENSE) before contributing. -Unless required by applicable law or agreed to in writing, software -distributed under the License is distributed on an "AS IS" BASIS, -WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. -See the License for the specific language governing permissions and -limitations under the License. +## Step-by-Step -**Other names and brands may be claimed as the property of others* +1. Make sure you have `git` and `cmake` installed on your system. On Windows we recommend using [Git Extensions](https://github.com/gitextensions/gitextensions/releases) for git bash. +2. Run `git clone https://github.com/IntelRealSense/realsense-ros.git` and `cd realsense-ros` +3. To align with latest status of the ros2-development branch, run: +``` +git fetch origin +git checkout ros2-development +git reset --hard origin/ros2-development +``` +4. `git checkout -b name_of_your_contribution` to create a dedicated branch +5. Make your changes to the local repository +6. Make sure your local git user is updated, or run `git config --global user.email "email@example.com"` and `git config --global user.user "user"` to set it up. This is the user & email that will appear in GitHub history. +7. `git add -p` to select the changes you wish to add +8. `git commit -m "Description of the change"` +9. Make sure you have a GitHub user and [fork realsense-ros](https://github.com/IntelRealSense/realsense-ros#fork-destination-box) +10. `git remote add fork https://github.com/username/realsense-ros.git` with your GitHub `username` +11. `git fetch fork` +12. `git push fork` to push `name_of_your_contribution` branch to your fork +13. Go to your fork on GitHub at `https://github.com/username/realsense-ros` +14. Click the `New pull request` button +15. For `base` combo-box select `ros2-development`, since you want to submit a PR to that branch +16. For `compare` combo-box select `name_of_your_contribution` with your commit +17. Review your changes and click `Create pull request` +18. Wait for all automated checks to pass +19. The PR will be approved / rejected after review from the team and the community + +To continue to new change, goto step 3. +To return to your PR (in order to make more changes): +1. `git stash` +2. `git checkout name_of_your_contribution` +3. Repeat items 5-8 from the previous list +4. `git push fork` +The pull request will be automatically updated + +
+ +
+ +

+ License +

+ + + Apache License + Version 2.0, January 2004 + http://www.apache.org/licenses/ + + TERMS AND CONDITIONS FOR USE, REPRODUCTION, AND DISTRIBUTION + + 1. Definitions. + + "License" shall mean the terms and conditions for use, reproduction, + and distribution as defined by Sections 1 through 9 of this document. + + "Licensor" shall mean the copyright owner or entity authorized by + the copyright owner that is granting the License. + + "Legal Entity" shall mean the union of the acting entity and all + other entities that control, are controlled by, or are under common + control with that entity. For the purposes of this definition, + "control" means (i) the power, direct or indirect, to cause the + direction or management of such entity, whether by contract or + otherwise, or (ii) ownership of fifty percent (50%) or more of the + outstanding shares, or (iii) beneficial ownership of such entity. + + "You" (or "Your") shall mean an individual or Legal Entity + exercising permissions granted by this License. + + "Source" form shall mean the preferred form for making modifications, + including but not limited to software source code, documentation + source, and configuration files. + + "Object" form shall mean any form resulting from mechanical + transformation or translation of a Source form, including but + not limited to compiled object code, generated documentation, + and conversions to other media types. + + "Work" shall mean the work of authorship, whether in Source or + Object form, made available under the License, as indicated by a + copyright notice that is included in or attached to the work + (an example is provided in the Appendix below). + + "Derivative Works" shall mean any work, whether in Source or Object + form, that is based on (or derived from) the Work and for which the + editorial revisions, annotations, elaborations, or other modifications + represent, as a whole, an original work of authorship. For the purposes + of this License, Derivative Works shall not include works that remain + separable from, or merely link (or bind by name) to the interfaces of, + the Work and Derivative Works thereof. + + "Contribution" shall mean any work of authorship, including + the original version of the Work and any modifications or additions + to that Work or Derivative Works thereof, that is intentionally + submitted to Licensor for inclusion in the Work by the copyright owner + or by an individual or Legal Entity authorized to submit on behalf of + the copyright owner. For the purposes of this definition, "submitted" + means any form of electronic, verbal, or written communication sent + to the Licensor or its representatives, including but not limited to + communication on electronic mailing lists, source code control systems, + and issue tracking systems that are managed by, or on behalf of, the + Licensor for the purpose of discussing and improving the Work, but + excluding communication that is conspicuously marked or otherwise + designated in writing by the copyright owner as "Not a Contribution." + + "Contributor" shall mean Licensor and any individual or Legal Entity + on behalf of whom a Contribution has been received by Licensor and + subsequently incorporated within the Work. + + 2. Grant of Copyright License. Subject to the terms and conditions of + this License, each Contributor hereby grants to You a perpetual, + worldwide, non-exclusive, no-charge, royalty-free, irrevocable + copyright license to reproduce, prepare Derivative Works of, + publicly display, publicly perform, sublicense, and distribute the + Work and such Derivative Works in Source or Object form. + + 3. Grant of Patent License. Subject to the terms and conditions of + this License, each Contributor hereby grants to You a perpetual, + worldwide, non-exclusive, no-charge, royalty-free, irrevocable + (except as stated in this section) patent license to make, have made, + use, offer to sell, sell, import, and otherwise transfer the Work, + where such license applies only to those patent claims licensable + by such Contributor that are necessarily infringed by their + Contribution(s) alone or by combination of their Contribution(s) + with the Work to which such Contribution(s) was submitted. If You + institute patent litigation against any entity (including a + cross-claim or counterclaim in a lawsuit) alleging that the Work + or a Contribution incorporated within the Work constitutes direct + or contributory patent infringement, then any patent licenses + granted to You under this License for that Work shall terminate + as of the date such litigation is filed. + + 4. Redistribution. You may reproduce and distribute copies of the + Work or Derivative Works thereof in any medium, with or without + modifications, and in Source or Object form, provided that You + meet the following conditions: + + (a) You must give any other recipients of the Work or + Derivative Works a copy of this License; and + + (b) You must cause any modified files to carry prominent notices + stating that You changed the files; and + + (c) You must retain, in the Source form of any Derivative Works + that You distribute, all copyright, patent, trademark, and + attribution notices from the Source form of the Work, + excluding those notices that do not pertain to any part of + the Derivative Works; and + + (d) If the Work includes a "NOTICE" text file as part of its + distribution, then any Derivative Works that You distribute must + include a readable copy of the attribution notices contained + within such NOTICE file, excluding those notices that do not + pertain to any part of the Derivative Works, in at least one + of the following places: within a NOTICE text file distributed + as part of the Derivative Works; within the Source form or + documentation, if provided along with the Derivative Works; or, + within a display generated by the Derivative Works, if and + wherever such third-party notices normally appear. The contents + of the NOTICE file are for informational purposes only and + do not modify the License. You may add Your own attribution + notices within Derivative Works that You distribute, alongside + or as an addendum to the NOTICE text from the Work, provided + that such additional attribution notices cannot be construed + as modifying the License. + + You may add Your own copyright statement to Your modifications and + may provide additional or different license terms and conditions + for use, reproduction, or distribution of Your modifications, or + for any such Derivative Works as a whole, provided Your use, + reproduction, and distribution of the Work otherwise complies with + the conditions stated in this License. + + 5. Submission of Contributions. Unless You explicitly state otherwise, + any Contribution intentionally submitted for inclusion in the Work + by You to the Licensor shall be under the terms and conditions of + this License, without any additional terms or conditions. + Notwithstanding the above, nothing herein shall supersede or modify + the terms of any separate license agreement you may have executed + with Licensor regarding such Contributions. + + 6. Trademarks. This License does not grant permission to use the trade + names, trademarks, service marks, or product names of the Licensor, + except as required for reasonable and customary use in describing the + origin of the Work and reproducing the content of the NOTICE file. + + 7. Disclaimer of Warranty. Unless required by applicable law or + agreed to in writing, Licensor provides the Work (and each + Contributor provides its Contributions) on an "AS IS" BASIS, + WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or + implied, including, without limitation, any warranties or conditions + of TITLE, NON-INFRINGEMENT, MERCHANTABILITY, or FITNESS FOR A + PARTICULAR PURPOSE. You are solely responsible for determining the + appropriateness of using or redistributing the Work and assume any + risks associated with Your exercise of permissions under this License. + + 8. Limitation of Liability. In no event and under no legal theory, + whether in tort (including negligence), contract, or otherwise, + unless required by applicable law (such as deliberate and grossly + negligent acts) or agreed to in writing, shall any Contributor be + liable to You for damages, including any direct, indirect, special, + incidental, or consequential damages of any character arising as a + result of this License or out of the use or inability to use the + Work (including but not limited to damages for loss of goodwill, + work stoppage, computer failure or malfunction, or any and all + other commercial damages or losses), even if such Contributor + has been advised of the possibility of such damages. + + 9. Accepting Warranty or Additional Liability. While redistributing + the Work or Derivative Works thereof, You may choose to offer, + and charge a fee for, acceptance of support, warranty, indemnity, + or other liability obligations and/or rights consistent with this + License. However, in accepting such obligations, You may act only + on Your own behalf and on Your sole responsibility, not on behalf + of any other Contributor, and only if You agree to indemnify, + defend, and hold each Contributor harmless for any liability + incurred by, or claims asserted against, such Contributor by reason + of your accepting any such warranty or additional liability. + + END OF TERMS AND CONDITIONS + + APPENDIX: How to apply the Apache License to your work. + + To apply the Apache License to your work, attach the following + boilerplate notice, with the fields enclosed by brackets "[]" + replaced with your own identifying information. (Don't include + the brackets!) The text should be enclosed in the appropriate + comment syntax for the file format. We also recommend that a + file or class name and description of purpose be included on the + same "printed page" as the copyright notice for easier + identification within third-party archives. + + Copyright 2023 Intel Corporation. All Rights Reserved. + + Licensed under the Apache License, Version 2.0 (the "License"); + you may not use this file except in compliance with the License. + You may obtain a copy of the License at + + http://www.apache.org/licenses/LICENSE-2.0 + + Unless required by applicable law or agreed to in writing, software + distributed under the License is distributed on an "AS IS" BASIS, + WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. + See the License for the specific language governing permissions and + limitations under the License. + +
From e130f9ff4d329f8684d9609074ff5fb630b7a7ce Mon Sep 17 00:00:00 2001 From: SamerKhshiboun Date: Thu, 6 Apr 2023 01:29:33 +0300 Subject: [PATCH 2/8] remove license and contributing content from the README.md, but point this to relative files --- README.md | 319 ++++++++---------------------------------------------- 1 file changed, 44 insertions(+), 275 deletions(-) diff --git a/README.md b/README.md index 55d2b7498a6..841d076e360 100644 --- a/README.md +++ b/README.md @@ -4,12 +4,30 @@

ROS2 packages for using Intel RealSense D400 cameras.
- Supported ROS2 Distros: Dashing, Eloquent, Foxy, Humble and Rolling.
Latest release notes

+
+ +[![rolling][rolling-badge]][rolling] +[![humble][humble-badge]][humble] +[![foxy][foxy-badge]][foxy] +[![galactic][galactic-badge]][galactic] +[![eloquent][eloquent-badge]][eloquent] +[![dashing][dashing-badge]][dashing] +[![ubuntu22][ubuntu22-badge]][ubuntu22] +[![ubuntu20][ubuntu20-badge]][ubuntu20] +[![ubuntu18][ubuntu18-badge]][ubuntu18] + +![GitHubWorkflowStatus](https://img.shields.io/github/actions/workflow/status/IntelRealSense/realsense-ros/main.yml?logo=github&style=flat-square) +![GitHubcontributors](https://img.shields.io/github/contributors/IntelRealSense/realsense-ros?style=flat-square) +![License](https://img.shields.io/github/license/IntelRealSense/realsense-ros?style=flat-square) + +
+ + ## Table of contents * [ROS1 and ROS2 legacy](#legacy) * [Installation](#installation) @@ -21,8 +39,8 @@ * [Post-Processing Filters](#filters) * [Available Services](#services) * [Efficient intra-process communication](#intra-process) - * [Contributing](#contributing) - * [License](#license) + * [Contributing](CONTRIBUTING.md) + * [License](LICENSE)

Legacy @@ -348,277 +366,28 @@ The launch file accepts a parameter, `intra_process_comms`, controlling whether ros2 launch realsense2_camera rs_intra_process_demo_launch.py intra_process_comms:=true ``` -
- -

- Contributing -

- - # How to Contribute - -This project welcomes third-party code via GitHub pull requests. - -You are welcome to propose and discuss enhancements using project [issues](https://github.com/IntelRealSense/realsense-ros/issues). - -> **Branching Policy**: -> The `ros2-development` branch is considered stable, at all times. -> If you plan to propose a patch, please commit into the `ros2-development` branch, or its own feature branch. - -In addition, please run `pr_check.sh` under `scripts` directory. This scripts verify compliance with project's standards: - -1. Every example / source file must refer to [LICENSE](https://github.com/IntelRealSense/realsense-ros/blob/ros2-development/LICENSE) -2. Every example / source file must include correct copyright notice -3. For indentation we are using spaces and not tabs -4. Line-endings must be Unix and not DOS style - -Most common issues can be automatically resolved by running `./pr_check.sh --fix` - -Please familirize yourself with the [Apache License 2.0](https://github.com/IntelRealSense/realsense-ros/blob/ros2-development/LICENSE) before contributing. - -## Step-by-Step - -1. Make sure you have `git` and `cmake` installed on your system. On Windows we recommend using [Git Extensions](https://github.com/gitextensions/gitextensions/releases) for git bash. -2. Run `git clone https://github.com/IntelRealSense/realsense-ros.git` and `cd realsense-ros` -3. To align with latest status of the ros2-development branch, run: -``` -git fetch origin -git checkout ros2-development -git reset --hard origin/ros2-development -``` -4. `git checkout -b name_of_your_contribution` to create a dedicated branch -5. Make your changes to the local repository -6. Make sure your local git user is updated, or run `git config --global user.email "email@example.com"` and `git config --global user.user "user"` to set it up. This is the user & email that will appear in GitHub history. -7. `git add -p` to select the changes you wish to add -8. `git commit -m "Description of the change"` -9. Make sure you have a GitHub user and [fork realsense-ros](https://github.com/IntelRealSense/realsense-ros#fork-destination-box) -10. `git remote add fork https://github.com/username/realsense-ros.git` with your GitHub `username` -11. `git fetch fork` -12. `git push fork` to push `name_of_your_contribution` branch to your fork -13. Go to your fork on GitHub at `https://github.com/username/realsense-ros` -14. Click the `New pull request` button -15. For `base` combo-box select `ros2-development`, since you want to submit a PR to that branch -16. For `compare` combo-box select `name_of_your_contribution` with your commit -17. Review your changes and click `Create pull request` -18. Wait for all automated checks to pass -19. The PR will be approved / rejected after review from the team and the community - -To continue to new change, goto step 3. -To return to your PR (in order to make more changes): -1. `git stash` -2. `git checkout name_of_your_contribution` -3. Repeat items 5-8 from the previous list -4. `git push fork` -The pull request will be automatically updated -
-
- -

- License -

- - - Apache License - Version 2.0, January 2004 - http://www.apache.org/licenses/ - - TERMS AND CONDITIONS FOR USE, REPRODUCTION, AND DISTRIBUTION - - 1. Definitions. - - "License" shall mean the terms and conditions for use, reproduction, - and distribution as defined by Sections 1 through 9 of this document. - - "Licensor" shall mean the copyright owner or entity authorized by - the copyright owner that is granting the License. - - "Legal Entity" shall mean the union of the acting entity and all - other entities that control, are controlled by, or are under common - control with that entity. For the purposes of this definition, - "control" means (i) the power, direct or indirect, to cause the - direction or management of such entity, whether by contract or - otherwise, or (ii) ownership of fifty percent (50%) or more of the - outstanding shares, or (iii) beneficial ownership of such entity. - - "You" (or "Your") shall mean an individual or Legal Entity - exercising permissions granted by this License. - - "Source" form shall mean the preferred form for making modifications, - including but not limited to software source code, documentation - source, and configuration files. - - "Object" form shall mean any form resulting from mechanical - transformation or translation of a Source form, including but - not limited to compiled object code, generated documentation, - and conversions to other media types. - - "Work" shall mean the work of authorship, whether in Source or - Object form, made available under the License, as indicated by a - copyright notice that is included in or attached to the work - (an example is provided in the Appendix below). - - "Derivative Works" shall mean any work, whether in Source or Object - form, that is based on (or derived from) the Work and for which the - editorial revisions, annotations, elaborations, or other modifications - represent, as a whole, an original work of authorship. For the purposes - of this License, Derivative Works shall not include works that remain - separable from, or merely link (or bind by name) to the interfaces of, - the Work and Derivative Works thereof. - - "Contribution" shall mean any work of authorship, including - the original version of the Work and any modifications or additions - to that Work or Derivative Works thereof, that is intentionally - submitted to Licensor for inclusion in the Work by the copyright owner - or by an individual or Legal Entity authorized to submit on behalf of - the copyright owner. For the purposes of this definition, "submitted" - means any form of electronic, verbal, or written communication sent - to the Licensor or its representatives, including but not limited to - communication on electronic mailing lists, source code control systems, - and issue tracking systems that are managed by, or on behalf of, the - Licensor for the purpose of discussing and improving the Work, but - excluding communication that is conspicuously marked or otherwise - designated in writing by the copyright owner as "Not a Contribution." - - "Contributor" shall mean Licensor and any individual or Legal Entity - on behalf of whom a Contribution has been received by Licensor and - subsequently incorporated within the Work. - - 2. Grant of Copyright License. Subject to the terms and conditions of - this License, each Contributor hereby grants to You a perpetual, - worldwide, non-exclusive, no-charge, royalty-free, irrevocable - copyright license to reproduce, prepare Derivative Works of, - publicly display, publicly perform, sublicense, and distribute the - Work and such Derivative Works in Source or Object form. - - 3. Grant of Patent License. Subject to the terms and conditions of - this License, each Contributor hereby grants to You a perpetual, - worldwide, non-exclusive, no-charge, royalty-free, irrevocable - (except as stated in this section) patent license to make, have made, - use, offer to sell, sell, import, and otherwise transfer the Work, - where such license applies only to those patent claims licensable - by such Contributor that are necessarily infringed by their - Contribution(s) alone or by combination of their Contribution(s) - with the Work to which such Contribution(s) was submitted. If You - institute patent litigation against any entity (including a - cross-claim or counterclaim in a lawsuit) alleging that the Work - or a Contribution incorporated within the Work constitutes direct - or contributory patent infringement, then any patent licenses - granted to You under this License for that Work shall terminate - as of the date such litigation is filed. - - 4. Redistribution. You may reproduce and distribute copies of the - Work or Derivative Works thereof in any medium, with or without - modifications, and in Source or Object form, provided that You - meet the following conditions: - - (a) You must give any other recipients of the Work or - Derivative Works a copy of this License; and - - (b) You must cause any modified files to carry prominent notices - stating that You changed the files; and - - (c) You must retain, in the Source form of any Derivative Works - that You distribute, all copyright, patent, trademark, and - attribution notices from the Source form of the Work, - excluding those notices that do not pertain to any part of - the Derivative Works; and - - (d) If the Work includes a "NOTICE" text file as part of its - distribution, then any Derivative Works that You distribute must - include a readable copy of the attribution notices contained - within such NOTICE file, excluding those notices that do not - pertain to any part of the Derivative Works, in at least one - of the following places: within a NOTICE text file distributed - as part of the Derivative Works; within the Source form or - documentation, if provided along with the Derivative Works; or, - within a display generated by the Derivative Works, if and - wherever such third-party notices normally appear. The contents - of the NOTICE file are for informational purposes only and - do not modify the License. You may add Your own attribution - notices within Derivative Works that You distribute, alongside - or as an addendum to the NOTICE text from the Work, provided - that such additional attribution notices cannot be construed - as modifying the License. - - You may add Your own copyright statement to Your modifications and - may provide additional or different license terms and conditions - for use, reproduction, or distribution of Your modifications, or - for any such Derivative Works as a whole, provided Your use, - reproduction, and distribution of the Work otherwise complies with - the conditions stated in this License. - - 5. Submission of Contributions. Unless You explicitly state otherwise, - any Contribution intentionally submitted for inclusion in the Work - by You to the Licensor shall be under the terms and conditions of - this License, without any additional terms or conditions. - Notwithstanding the above, nothing herein shall supersede or modify - the terms of any separate license agreement you may have executed - with Licensor regarding such Contributions. - - 6. Trademarks. This License does not grant permission to use the trade - names, trademarks, service marks, or product names of the Licensor, - except as required for reasonable and customary use in describing the - origin of the Work and reproducing the content of the NOTICE file. - - 7. Disclaimer of Warranty. Unless required by applicable law or - agreed to in writing, Licensor provides the Work (and each - Contributor provides its Contributions) on an "AS IS" BASIS, - WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or - implied, including, without limitation, any warranties or conditions - of TITLE, NON-INFRINGEMENT, MERCHANTABILITY, or FITNESS FOR A - PARTICULAR PURPOSE. You are solely responsible for determining the - appropriateness of using or redistributing the Work and assume any - risks associated with Your exercise of permissions under this License. - - 8. Limitation of Liability. In no event and under no legal theory, - whether in tort (including negligence), contract, or otherwise, - unless required by applicable law (such as deliberate and grossly - negligent acts) or agreed to in writing, shall any Contributor be - liable to You for damages, including any direct, indirect, special, - incidental, or consequential damages of any character arising as a - result of this License or out of the use or inability to use the - Work (including but not limited to damages for loss of goodwill, - work stoppage, computer failure or malfunction, or any and all - other commercial damages or losses), even if such Contributor - has been advised of the possibility of such damages. - - 9. Accepting Warranty or Additional Liability. While redistributing - the Work or Derivative Works thereof, You may choose to offer, - and charge a fee for, acceptance of support, warranty, indemnity, - or other liability obligations and/or rights consistent with this - License. However, in accepting such obligations, You may act only - on Your own behalf and on Your sole responsibility, not on behalf - of any other Contributor, and only if You agree to indemnify, - defend, and hold each Contributor harmless for any liability - incurred by, or claims asserted against, such Contributor by reason - of your accepting any such warranty or additional liability. - - END OF TERMS AND CONDITIONS - - APPENDIX: How to apply the Apache License to your work. - - To apply the Apache License to your work, attach the following - boilerplate notice, with the fields enclosed by brackets "[]" - replaced with your own identifying information. (Don't include - the brackets!) The text should be enclosed in the appropriate - comment syntax for the file format. We also recommend that a - file or class name and description of purpose be included on the - same "printed page" as the copyright notice for easier - identification within third-party archives. - - Copyright 2023 Intel Corporation. All Rights Reserved. - - Licensed under the Apache License, Version 2.0 (the "License"); - you may not use this file except in compliance with the License. - You may obtain a copy of the License at - - http://www.apache.org/licenses/LICENSE-2.0 - - Unless required by applicable law or agreed to in writing, software - distributed under the License is distributed on an "AS IS" BASIS, - WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. - See the License for the specific language governing permissions and - limitations under the License. - -
+ +[supporteddistros-badge]: https://img.shields.io/badge/-Supported%20ROS2%20Distros-lightgrey?style=flat-square&logo=ros +[supporteddistro]: https://docs.ros.org/en/rolling/Releases.html +[rolling-badge]: https://img.shields.io/badge/-ROLLING-blue?style=flat-square&logo=ros +[rolling]: https://docs.ros.org/en/rolling/Releases.html +[humble-badge]: https://img.shields.io/badge/-HUMBLE-blue?style=flat-square&logo=ros +[humble]: https://docs.ros.org/en/rolling/Releases/Release-Humble-Hawksbill.html +[foxy-badge]: https://img.shields.io/badge/-FOXY-blue?style=flat-square&logo=ros +[foxy]: https://docs.ros.org/en/rolling/Releases/Release-Foxy-Fitzroy.html +[galactic-badge]: https://img.shields.io/badge/-GALACTIC-blue?style=flat-square&logo=ros +[galactic]: https://docs.ros.org/en/galactic/Releases/Release-Foxy-Fitzroy.html +[eloquent-badge]: https://img.shields.io/badge/-ELOQUENT-blue?style=flat-square&logo=ros +[eloquent]: https://docs.ros.org/en/eloquent/Releases/Release-Foxy-Fitzroy.html +[dashing-badge]: https://img.shields.io/badge/-DASHING-blue?style=flat-square&logo=ros +[dashing]: https://docs.ros.org/en/dashing/Releases/Release-Foxy-Fitzroy.html +[supported-ubuntu-badge]: https://img.shields.io/badge/-Supported%20Ubuntu%20Releases-lightgrey?style=flat-square&logo=ubuntu&logoColor=white +[supported-ubuntu]: https://wiki.ubuntu.com/Releases +[ubuntu22-badge]: https://img.shields.io/badge/-UBUNTU%2022%2E04-blue?style=flat-square&logo=ubuntu&logoColor=white +[ubuntu22]: https://releases.ubuntu.com/jammy/ +[ubuntu20-badge]: https://img.shields.io/badge/-UBUNTU%2020%2E04-blue?style=flat-square&logo=ubuntu&logoColor=white +[ubuntu20]: https://releases.ubuntu.com/focal/ +[ubuntu18-badge]: https://img.shields.io/badge/-UBUNTU%2018%2E04-blue?style=flat-square&logo=ubuntu&logoColor=white +[ubuntu18]: https://releases.ubuntu.com/18.04/ \ No newline at end of file From c7bdec8ce190012a3f9cffe881d137326fa18f00 Mon Sep 17 00:00:00 2001 From: SamerKhshiboun Date: Fri, 7 Apr 2023 00:41:33 +0300 Subject: [PATCH 3/8] remove ubuntu 18.04 and eloquent and dashing from readme --- README.md | 106 ++++++++++++++++++++++++++++++++++++++++++------------ 1 file changed, 84 insertions(+), 22 deletions(-) diff --git a/README.md b/README.md index 841d076e360..577eabb2e05 100644 --- a/README.md +++ b/README.md @@ -9,23 +9,19 @@
-
[![rolling][rolling-badge]][rolling] [![humble][humble-badge]][humble] [![foxy][foxy-badge]][foxy] [![galactic][galactic-badge]][galactic] -[![eloquent][eloquent-badge]][eloquent] -[![dashing][dashing-badge]][dashing] [![ubuntu22][ubuntu22-badge]][ubuntu22] [![ubuntu20][ubuntu20-badge]][ubuntu20] -[![ubuntu18][ubuntu18-badge]][ubuntu18] ![GitHubWorkflowStatus](https://img.shields.io/github/actions/workflow/status/IntelRealSense/realsense-ros/main.yml?logo=github&style=flat-square) ![GitHubcontributors](https://img.shields.io/github/contributors/IntelRealSense/realsense-ros?style=flat-square) ![License](https://img.shields.io/github/license/IntelRealSense/realsense-ros?style=flat-square) -
+
## Table of contents @@ -34,6 +30,12 @@ * [Usage](#usage) * [Starting the camera node](#start-camera-node) * [Parameters](#parameters) + * [ROS2-vs-Optical Coordination Systems](#coordination) + * [Point Of View](#point-of-view) + * [ROS (Robot) Coordinates](#ros-coordination) + * [Optical (Camera) Coordinates](#optical-coordination) + * [TFs](#tfs) + * [Extrinsics](#extrinsics) * [Topics](#topics) * [Metadata Topic](#metadata) * [Post-Processing Filters](#filters) @@ -42,6 +44,8 @@ * [Contributing](CONTRIBUTING.md) * [License](LICENSE) +
+

Legacy

@@ -93,9 +97,6 @@ - #### Ubuntu 20.04: - [ROS2 Foxy](https://docs.ros.org/en/foxy/Installation/Ubuntu-Install-Debians.html) - [ROS2 Galactic](https://docs.ros.org/en/galactic/Installation/Ubuntu-Install-Debians.html) -- #### Ubuntu 18.04 : - - [ROS2 Dashing](https://docs.ros.org/en/dashing/Installation/Ubuntu-Install-Debians.html) - - [ROS2 Eloquent](https://docs.ros.org/en/eloquent/Installation/Linux-Install-Debians.html) @@ -159,7 +160,7 @@ - Source environment ```bash - ROS_DISTRO= # set your ROS_DISTRO: humble, galactic, foxy, eloquent, dashing + ROS_DISTRO= # set your ROS_DISTRO: humble, galactic, foxy source /opt/ros/$ROS_DISTRO/setup.bash cd ~/ros2_ws . install/local_setup.bash @@ -167,6 +168,8 @@ +
+

Usage

@@ -183,7 +186,9 @@ #### with ros2 launch: ros2 launch realsense2_camera rs_launch.py ros2 launch realsense2_camera rs_launch.py depth_module.profile:=1280x720x30 pointcloud.enable:=true - + +
+

Parameters

@@ -239,7 +244,67 @@ Setting *unite_imu_method* creates a new topic, *imu*, that replaces the default The `/diagnostics` topic includes information regarding the device temperatures and actual frequency of the enabled streams. - **publish_odom_tf**: If True (default) publish TF from odom_frame to pose_frame. - + +
+ + +

+ ROS2(Robot) vs Optical(Camera) Coordination Systems: +

+ +

+ Point Of View: +

+ +- Imagine we are standing behind of the camera, and looking forward. +- Always use this point of view when talking about coordinates, left vs right IRs, position of sensor, etc.. + +

+ ROS2 Coordinate System: +

+ +ROS2 Coordinate System (X: Forward, Y:Left, Z: Up) + +

+ Camera Optical Coordinate System: +

+ +Camera Optical Coordinate System (X: Right, Y: Down, Z: Forward). + +

+ TF from coordinate A to coordinate B: +

+ +- TF msg expresses a transform from coordinate frame "header.frame_id" (source) to the coordinate frame child_frame_id (destination) [Reference](http://docs.ros.org/en/noetic/api/geometry_msgs/html/msg/Transform.html) +- In RealSense cameras, the origin point (0,0,0) is taken from the left IR (infra1) position and named as "camera_link" frame +- Depth, left IR and "camera_link" coordinates converge together. +- Our wrapper provide TFs between each sensor coordinate to the camera base (camera_link) +- Also, it provides TFs from each sensor ROS coordinates to its corrosponding optical coordinates. + +

+ Extrinsics from sensor A to sensor B: +

+ +- Extrinsic from sensor A to sensor B means the position and orientation of sensor A relative to sensor B. +- Imagine that B is the origin (0,0,0), then the Extrensics(A->B) describes where is sensor A relative to sensor B. +- For example, depth_to_color, in D435i: + - If we look from behind of the D435i, extrinsic from depth to color, means, where is the depth in relative to the color. + - If we just look at the X coordinates, in the optical coordiantes (again, from behind) and assume that COLOR(RGB) sensor is (0,0,0), we can say that DEPTH sensor is on the right of RGB by 0.0148m (1.48cm). + +``` +administrator@perclnx466 ~/ros2_humble $ ros2 topic echo /camera/extrinsics/depth_to_color +rotation: +... +translation: +- 0.01485931035131216 +- 0.0010161789832636714 +- 0.0005317096947692335 +--- +``` +![image](https://user-images.githubusercontent.com/99127997/230220297-e392f0fc-63bf-4bab-8001-af1ddf0ed00e.png) + +
+

Published Topics

@@ -282,6 +347,8 @@ Enabling stream adds matching topics. For instance, enabling the gyro and accel - /camera/gyro/metadata - /camera/gyro/sample +
+

Metadata topic

@@ -291,6 +358,8 @@ The metadata messages store the camera's available metadata in a *json* format. python3 src/realsense-ros/realsense2_camera/scripts/echo_metadada.py /camera/depth/metadata ``` +
+

Post-Processing Filters

@@ -315,12 +384,15 @@ The following post processing filters are available: Each of the above filters have it's own parameters, following the naming convention of `.` including a `.enable` parameter to enable/disable it. +
+

Available services

- device_info : retrieve information about the device - serial_number, firmware_version etc. Type `ros2 interface show realsense2_camera_msgs/srv/DeviceInfo` for the full list. Call example: `ros2 service call /camera/device_info realsense2_camera_msgs/srv/DeviceInfo` - - Note that for **ROS2 Dashing** the command is `ros2 srv show realsense2_camera_msgs/srv/DeviceInfo` + +

Efficient intra-process communication: @@ -369,8 +441,6 @@ ros2 launch realsense2_camera rs_intra_process_demo_launch.py intra_process_comm -[supporteddistros-badge]: https://img.shields.io/badge/-Supported%20ROS2%20Distros-lightgrey?style=flat-square&logo=ros -[supporteddistro]: https://docs.ros.org/en/rolling/Releases.html [rolling-badge]: https://img.shields.io/badge/-ROLLING-blue?style=flat-square&logo=ros [rolling]: https://docs.ros.org/en/rolling/Releases.html [humble-badge]: https://img.shields.io/badge/-HUMBLE-blue?style=flat-square&logo=ros @@ -379,15 +449,7 @@ ros2 launch realsense2_camera rs_intra_process_demo_launch.py intra_process_comm [foxy]: https://docs.ros.org/en/rolling/Releases/Release-Foxy-Fitzroy.html [galactic-badge]: https://img.shields.io/badge/-GALACTIC-blue?style=flat-square&logo=ros [galactic]: https://docs.ros.org/en/galactic/Releases/Release-Foxy-Fitzroy.html -[eloquent-badge]: https://img.shields.io/badge/-ELOQUENT-blue?style=flat-square&logo=ros -[eloquent]: https://docs.ros.org/en/eloquent/Releases/Release-Foxy-Fitzroy.html -[dashing-badge]: https://img.shields.io/badge/-DASHING-blue?style=flat-square&logo=ros -[dashing]: https://docs.ros.org/en/dashing/Releases/Release-Foxy-Fitzroy.html -[supported-ubuntu-badge]: https://img.shields.io/badge/-Supported%20Ubuntu%20Releases-lightgrey?style=flat-square&logo=ubuntu&logoColor=white -[supported-ubuntu]: https://wiki.ubuntu.com/Releases [ubuntu22-badge]: https://img.shields.io/badge/-UBUNTU%2022%2E04-blue?style=flat-square&logo=ubuntu&logoColor=white [ubuntu22]: https://releases.ubuntu.com/jammy/ [ubuntu20-badge]: https://img.shields.io/badge/-UBUNTU%2020%2E04-blue?style=flat-square&logo=ubuntu&logoColor=white [ubuntu20]: https://releases.ubuntu.com/focal/ -[ubuntu18-badge]: https://img.shields.io/badge/-UBUNTU%2018%2E04-blue?style=flat-square&logo=ubuntu&logoColor=white -[ubuntu18]: https://releases.ubuntu.com/18.04/ \ No newline at end of file From 42fb45abef43eeed1da9e3cfb6d6a952f642ab00 Mon Sep 17 00:00:00 2001 From: SamerKhshiboun Date: Fri, 7 Apr 2023 01:55:24 +0300 Subject: [PATCH 4/8] rearrange --- README.md | 179 ++++++++++++++++++++++++++++++++++-------------------- 1 file changed, 112 insertions(+), 67 deletions(-) diff --git a/README.md b/README.md index 577eabb2e05..e0d519af5d9 100644 --- a/README.md +++ b/README.md @@ -18,12 +18,11 @@ [![ubuntu20][ubuntu20-badge]][ubuntu20] ![GitHubWorkflowStatus](https://img.shields.io/github/actions/workflow/status/IntelRealSense/realsense-ros/main.yml?logo=github&style=flat-square) -![GitHubcontributors](https://img.shields.io/github/contributors/IntelRealSense/realsense-ros?style=flat-square) -![License](https://img.shields.io/github/license/IntelRealSense/realsense-ros?style=flat-square) +[![GitHubcontributors](https://img.shields.io/github/contributors/IntelRealSense/realsense-ros?style=flat-square)](CONTRIBUTING.md) +[![License](https://img.shields.io/github/license/IntelRealSense/realsense-ros?style=flat-square)](LICENSE)
- ## Table of contents * [ROS1 and ROS2 legacy](#legacy) * [Installation](#installation) @@ -31,11 +30,8 @@ * [Starting the camera node](#start-camera-node) * [Parameters](#parameters) * [ROS2-vs-Optical Coordination Systems](#coordination) - * [Point Of View](#point-of-view) - * [ROS (Robot) Coordinates](#ros-coordination) - * [Optical (Camera) Coordinates](#optical-coordination) - * [TFs](#tfs) - * [Extrinsics](#extrinsics) + * [TF from coordinate A to coordinate B](#tfs) + * [Extrinsics from sensor A to sensor B](#extrinsics) * [Topics](#topics) * [Metadata Topic](#metadata) * [Post-Processing Filters](#filters) @@ -194,96 +190,136 @@

### Sensor Parameters: -Each sensor has a unique set of parameters. -Video sensors, such as depth_module or rgb_camera have, at least, the 'profile' parameter.
-It is a string of the following format: \X\X\ (The deviding character can be X, x or ",". Spaces are ignored.) +- Each sensor has a unique set of parameters. +- Video sensors, such as depth_module or rgb_camera have, at least, the 'profile' parameter.
+ - The profile parameter is a string of the following format: \X\X\ (The deviding character can be X, x or ",". Spaces are ignored.) + - For example: ```depth_module.profile:=640x480x30``` +- Since infra1, infra2 and depth are all streams of the depth_module, their width, height and fps are defined by their common sensor. +- If the specified combination of parameters is not available by the device, the default configuration will be used. -Since infra1, infra2 and depth are all streams of the depth_module, their width, height and fps are defined by their common sensor. -If the specified combination of parameters is not available by the device, the default configuration will be used.
+
### Available Parameters: -For the entire list of parameters type `ros2 param list`. -For reading a parameter value use `ros2 param get ` for instance: `ros2 param get /camera/camera depth_module.emitter_on_off` -For setting a new value for a parameter use `ros2 param set ` i.e. `ros2 param set /camera/camera depth_module.emitter_on_off true` +- For the entire list of parameters type `ros2 param list`. +- For reading a parameter value use `ros2 param get ` + - For example: `ros2 param get /camera/camera depth_module.emitter_on_off` +- For setting a new value for a parameter use `ros2 param set ` + - For example: `ros2 param set /camera/camera depth_module.emitter_on_off true` #### Parameters that can be modified during runtime: - All of the filters and sensors inner parameters. -- **enable_****: Choose whether to enable a specified stream or not. Default is true for images and false for orientation streams. can be any of *infra1, infra2, color, depth, fisheye, fisheye1, fisheye2, gyro, accel, pose*. -- **enable_sync**: gathers closest frames of different sensors, infra red, color and depth, to be sent with the same timetag. This happens automatically when such filters as pointcloud are enabled. -- ****_qos**: can be any of *infra, color, fisheye, depth, gyro, accel, pose*. Sets the QoS by which the topic is published. Available values are the following strings: SYSTEM_DEFAULT, DEFAULT, PARAMETER_EVENTS, SERVICES_DEFAULT, PARAMETERS, SENSOR_DATA. +- **enable_****: + - Choose whether to enable a specified stream or not. Default is true for images and false for orientation streams. + - can be any of *infra1, infra2, color, depth, fisheye, fisheye1, fisheye2, gyro, accel, pose*. + - For example: ```enable_infra1:=true enable_color:=false``` +- **enable_sync**: + - gathers closest frames of different sensors, infra red, color and depth, to be sent with the same timetag. + - This happens automatically when such filters as pointcloud are enabled. +- ****_qos**: + - Sets the QoS by which the topic is published. + - can be any of *infra, color, fisheye, depth, gyro, accel, pose*. + - Available values are the following strings: `SYSTEM_DEFAULT`, `DEFAULT`, `PARAMETER_EVENTS`, `SERVICES_DEFAULT`, `PARAMETERS`, `SENSOR_DATA`. + - For example: ```depth_qos:=SENSOR_DATA``` + - Reference: [ROS2 QoS profiles formal documentation](https://docs.ros.org/en/rolling/Concepts/About-Quality-of-Service-Settings.html#qos-profiles) - **Notice:** ****_info_qos** refers to both camera_info topics and metadata topics. - **tf_publish_rate**: double, positive values mean dynamic transform publication with specified rate, all other values mean static transform publication. Defaults to 0 #### Parameters that cannot be changed in runtime: -- **serial_no**: will attach to the device with the given serial number (*serial_no*) number. Default, attach to the first (in an inner list) RealSense device. - - Note: serial number can also be defined with "_" prefix. For instance, serial number 831612073525 can be set in command line as `serial_no:=_831612073525`. That is a workaround until a better method will be found to ROS2's auto conversion of strings containing only digits into integers. -- **usb_port_id**: will attach to the device with the given USB port (*usb_port_id*). i.e 4-1, 4-2 etc. Default, ignore USB port when choosing a device. -- **device_type**: will attach to a device whose name includes the given *device_type* regular expression pattern. Default, ignore device type. For example, device_type:=d435 will match d435 and d435i. device_type=d435(?!i) will match d435 but not d435i. -- **reconnect_timeout**: When the driver cannot connect to the device try to reconnect after this timeout (in seconds). -- **wait_for_device_timeout**: If the specified device is not found, will wait *wait_for_device_timeout* seconds before exits. Defualt, *wait_for_device_timeout < 0*, will wait indefinitely. -- **rosbag_filename**: Publish topics from rosbag file. There are two ways for loading rosbag file: +- **serial_no**: + - will attach to the device with the given serial number (*serial_no*) number. + - Default, attach to the first (in an inner list) RealSense device. + - Note: serial number should be defined with "_" prefix. + - That is a workaround until a better method will be found to ROS2's auto conversion of strings containing only digits into integers. + - Example: serial number 831612073525 can be set in command line as `serial_no:=_831612073525`. +- **usb_port_id**: + - will attach to the device with the given USB port (*usb_port_id*). + - For example: `usb_port_id:=4-1` or `usb_port_id:=4-2` + - Default, ignore USB port when choosing a device. +- **device_type**: + - will attach to a device whose name includes the given *device_type* regular expression pattern. + - Default, ignore device type. + - For example: + - `device_type:=d435` will match d435 and d435i. + - `device_type=d435(?!i)` will match d435 but not d435i. +- **reconnect_timeout**: + - When the driver cannot connect to the device try to reconnect after this timeout (in seconds). + - For Example: `reconnect_timeout:=10` +- **wait_for_device_timeout**: + - If the specified device is not found, will wait *wait_for_device_timeout* seconds before exits. + - Defualt, *wait_for_device_timeout < 0*, will wait indefinitely. + - For example: `wait_for_device_timeout:=60` +- **rosbag_filename**: + - Publish topics from rosbag file. There are two ways for loading rosbag file: * Command line - ```ros2 run realsense2_camera realsense2_camera_node -p rosbag_filename:="/full/path/to/rosbag.bag"``` * Launch file - set ```rosbag_filename``` parameter with rosbag full path (see ```realsense2_camera/launch/rs_launch.py``` as reference) - -- **initial_reset**: On occasions the device was not closed properly and due to firmware issues needs to reset. If set to true, the device will reset prior to usage. - +- **initial_reset**: + - On occasions the device was not closed properly and due to firmware issues needs to reset. + - If set to true, the device will reset prior to usage. + - For example: `initial_reset:=true` - ****_frame_id**, ****_optical_frame_id**, **aligned_depth_to_**_frame_id**: Specify the different frame_id for the different frames. Especially important when using multiple cameras. - - **base_frame_id**: defines the frame_id all static transformations refers to. - **odom_frame_id**: defines the origin coordinate system in ROS convention (X-Forward, Y-Left, Z-Up). pose topic defines the pose relative to that system. -- **unite_imu_method**: The D435i camera has built in IMU components which produce 2 unrelated streams: *gyro* - which shows angular velocity and *accel* which shows linear acceleration. Each with it's own frequency. By default, 2 corresponding topics are available, each with only the relevant fields of the message sensor_msgs::Imu are filled out. -Setting *unite_imu_method* creates a new topic, *imu*, that replaces the default *gyro* and *accel* topics. The *imu* topic is published at the rate of the gyro. All the fields of the Imu message under the *imu* topic are filled out. `unite_imu_method` parameter supported values are [0-2] meaning: [0 -> None, 1 -> Copy, 2 -> Linear_ interpolation] when: - - **linear_interpolation**: Every gyro message is attached by the an accel message interpolated to the gyro's timestamp. - - **copy**: Every gyro message is attached by the last accel message. -- **clip_distance**: remove from the depth image all values above a given value (meters). Disable by giving negative value (default) +- **unite_imu_method**: + - D400 cameras have built in IMU components which produce 2 unrelated streams, each with it's own frequency: + - *gyro* - which shows angular velocity + - *accel* which shows linear acceleration. + - By default, 2 corresponding topics are available, each with only the relevant fields of the message sensor_msgs::Imu are filled out. + - Setting *unite_imu_method* creates a new topic, *imu*, that replaces the default *gyro* and *accel* topics. + - The *imu* topic is published at the rate of the gyro. + - All the fields of the Imu message under the *imu* topic are filled out. + - `unite_imu_method` parameter supported values are [0-2] meaning: [0 -> None, 1 -> Copy, 2 -> Linear_ interpolation] when: + - **linear_interpolation**: Every gyro message is attached by the an accel message interpolated to the gyro's timestamp. + - **copy**: Every gyro message is attached by the last accel message. +- **clip_distance**: + - Remove from the depth image all values above a given value (meters). Disable by giving negative value (default) + - For example: `clip_distance:=1.5` - **linear_accel_cov**, **angular_velocity_cov**: sets the variance given to the Imu readings. - **hold_back_imu_for_frames**: Images processing takes time. Therefor there is a time gap between the moment the image arrives at the wrapper and the moment the image is published to the ROS environment. During this time, Imu messages keep on arriving and a situation is created where an image with earlier timestamp is published after Imu message with later timestamp. If that is a problem, setting *hold_back_imu_for_frames* to *true* will hold the Imu messages back while processing the images and then publish them all in a burst, thus keeping the order of publication as the order of arrival. Note that in either case, the timestamp in each message's header reflects the time of it's origin. -- **publish_tf**: boolean, publish or not TF at all. Defaults to True. -- **diagnostics_period**: double, positive values set the period between diagnostics updates on the `/diagnostics` topic. 0 or negative values mean no diagnostics topic is published. Defaults to 0.
+- **publish_tf**: + - boolean, publish or not TF at all. + - Defaults to True. +- **diagnostics_period**: + - double, positive values set the period between diagnostics updates on the `/diagnostics` topic. + - 0 or negative values mean no diagnostics topic is published. Defaults to 0.
The `/diagnostics` topic includes information regarding the device temperatures and actual frequency of the enabled streams. - **publish_odom_tf**: If True (default) publish TF from odom_frame to pose_frame.
-

ROS2(Robot) vs Optical(Camera) Coordination Systems:

-

- Point Of View: -

- -- Imagine we are standing behind of the camera, and looking forward. -- Always use this point of view when talking about coordinates, left vs right IRs, position of sensor, etc.. - -

- ROS2 Coordinate System: -

+- Point Of View: + - Imagine we are standing behind of the camera, and looking forward. + - Always use this point of view when talking about coordinates, left vs right IRs, position of sensor, etc.. -ROS2 Coordinate System (X: Forward, Y:Left, Z: Up) +![image](https://user-images.githubusercontent.com/99127997/230150735-bc31fedf-d715-4e35-b462-fe2c338832c3.png) -

- Camera Optical Coordinate System: -

+- ROS2 Coordinate System: (X: Forward, Y:Left, Z: Up) +- Camera Optical Coordinate System: (X: Right, Y: Down, Z: Forward) -Camera Optical Coordinate System (X: Right, Y: Down, Z: Forward). +
-

+

TF from coordinate A to coordinate B: -

+

- TF msg expresses a transform from coordinate frame "header.frame_id" (source) to the coordinate frame child_frame_id (destination) [Reference](http://docs.ros.org/en/noetic/api/geometry_msgs/html/msg/Transform.html) - In RealSense cameras, the origin point (0,0,0) is taken from the left IR (infra1) position and named as "camera_link" frame - Depth, left IR and "camera_link" coordinates converge together. -- Our wrapper provide TFs between each sensor coordinate to the camera base (camera_link) +- Our wrapper provide static TFs between each sensor coordinate to the camera base (camera_link) - Also, it provides TFs from each sensor ROS coordinates to its corrosponding optical coordinates. +- Example of static TFs of RGB sensor and Infra2 (right infra) sensor of D435i module as it shown in rviz2: +![example](https://user-images.githubusercontent.com/99127997/230148106-0f79cbdb-c401-4d09-b386-a366af18e5f7.png) + +
-

+

Extrinsics from sensor A to sensor B: -

+

- Extrinsic from sensor A to sensor B means the position and orientation of sensor A relative to sensor B. - Imagine that B is the origin (0,0,0), then the Extrensics(A->B) describes where is sensor A relative to sensor B. @@ -291,6 +327,8 @@ Camera Optical Coordinate System (X: Right, Y: Down, Z: Forward). - If we look from behind of the D435i, extrinsic from depth to color, means, where is the depth in relative to the color. - If we just look at the X coordinates, in the optical coordiantes (again, from behind) and assume that COLOR(RGB) sensor is (0,0,0), we can say that DEPTH sensor is on the right of RGB by 0.0148m (1.48cm). +![d435i](https://user-images.githubusercontent.com/99127997/230220297-e392f0fc-63bf-4bab-8001-af1ddf0ed00e.png) + ``` administrator@perclnx466 ~/ros2_humble $ ros2 topic echo /camera/extrinsics/depth_to_color rotation: @@ -301,7 +339,7 @@ translation: - 0.0005317096947692335 --- ``` -![image](https://user-images.githubusercontent.com/99127997/230220297-e392f0fc-63bf-4bab-8001-af1ddf0ed00e.png) +
@@ -365,15 +403,22 @@ python3 src/realsense-ros/realsense2_camera/scripts/echo_metadada.py /camera/dep

The following post processing filters are available: - - ```align_depth```: If enabled, will publish the depth image aligned to the color image on the topic `/camera/aligned_depth_to_color/image_raw`.
The pointcloud, if created, will be based on the aligned depth image. + - ```align_depth```: If enabled, will publish the depth image aligned to the color image on the topic `/camera/aligned_depth_to_color/image_raw`. + - The pointcloud, if created, will be based on the aligned depth image. - ```colorizer```: will color the depth image. On the depth topic an RGB image will be published, instead of the 16bit depth values . - ```pointcloud```: will add a pointcloud topic `/camera/depth/color/points`. * The texture of the pointcloud can be modified using the `pointcloud.stream_filter` parameter.
* The depth FOV and the texture FOV are not similar. By default, pointcloud is limited to the section of depth containing the texture. You can have a full depth to pointcloud, coloring the regions beyond the texture with zeros, by setting `pointcloud.allow_no_texture_points` to true. * pointcloud is of an unordered format by default. This can be changed by setting `pointcloud.ordered_pc` to true. - - ```hdr_merge```: Allows depth image to be created by merging the information from 2 consecutive frames, taken with different exposure and gain values. The way to set exposure and gain values for each sequence in runtime is by first selecting the sequence id, using the `depth_module.sequence_id` parameter and then modifying the `depth_module.gain`, and `depth_module.exposure`.
To view the effect on the infrared image for each sequence id use the `sequence_id_filter.sequence_id` parameter.
To initialize these parameters in start time use the following parameters:
- `depth_module.exposure.1`, `depth_module.gain.1`, `depth_module.exposure.2`, `depth_module.gain.2`
- \* For in-depth review of the subject please read the accompanying [white paper](https://dev.intelrealsense.com/docs/high-dynamic-range-with-stereoscopic-depth-cameras). + - ```hdr_merge```: Allows depth image to be created by merging the information from 2 consecutive frames, taken with different exposure and gain values. + - The way to set exposure and gain values for each sequence in runtime is by first selecting the sequence id, using the `depth_module.sequence_id` parameter and then modifying the `depth_module.gain`, and `depth_module.exposure`. + - To view the effect on the infrared image for each sequence id use the `sequence_id_filter.sequence_id` parameter. + - To initialize these parameters in start time use the following parameters: + - `depth_module.exposure.1` + - `depth_module.gain.1` + - `depth_module.exposure.2` + - `depth_module.gain.2` + - For in-depth review of the subject please read the accompanying [white paper](https://dev.intelrealsense.com/docs/high-dynamic-range-with-stereoscopic-depth-cameras). - The following filters have detailed descriptions in : https://github.com/IntelRealSense/librealsense/blob/master/doc/post-processing-filters.md - ```disparity_filter``` - convert depth to disparity before applying other filters and back. @@ -441,13 +486,13 @@ ros2 launch realsense2_camera rs_intra_process_demo_launch.py intra_process_comm -[rolling-badge]: https://img.shields.io/badge/-ROLLING-blue?style=flat-square&logo=ros +[rolling-badge]: https://img.shields.io/badge/-ROLLING-orange?style=flat-square&logo=ros [rolling]: https://docs.ros.org/en/rolling/Releases.html -[humble-badge]: https://img.shields.io/badge/-HUMBLE-blue?style=flat-square&logo=ros +[humble-badge]: https://img.shields.io/badge/-HUMBLE-orange?style=flat-square&logo=ros [humble]: https://docs.ros.org/en/rolling/Releases/Release-Humble-Hawksbill.html -[foxy-badge]: https://img.shields.io/badge/-FOXY-blue?style=flat-square&logo=ros +[foxy-badge]: https://img.shields.io/badge/-FOXY-orange?style=flat-square&logo=ros [foxy]: https://docs.ros.org/en/rolling/Releases/Release-Foxy-Fitzroy.html -[galactic-badge]: https://img.shields.io/badge/-GALACTIC-blue?style=flat-square&logo=ros +[galactic-badge]: https://img.shields.io/badge/-GALACTIC-orange?style=flat-square&logo=ros [galactic]: https://docs.ros.org/en/galactic/Releases/Release-Foxy-Fitzroy.html [ubuntu22-badge]: https://img.shields.io/badge/-UBUNTU%2022%2E04-blue?style=flat-square&logo=ubuntu&logoColor=white [ubuntu22]: https://releases.ubuntu.com/jammy/ From 5a3f9a4c01e585d29596b031acdc4de4bba1c0c6 Mon Sep 17 00:00:00 2001 From: SamerKhshiboun Date: Mon, 10 Apr 2023 00:18:54 +0300 Subject: [PATCH 5/8] add deprecated msg to galactic --- README.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/README.md b/README.md index e0d519af5d9..cfeace86aa8 100644 --- a/README.md +++ b/README.md @@ -92,7 +92,7 @@ - [ROS2 Humble](https://docs.ros.org/en/humble/Installation/Ubuntu-Install-Debians.html) - #### Ubuntu 20.04: - [ROS2 Foxy](https://docs.ros.org/en/foxy/Installation/Ubuntu-Install-Debians.html) - - [ROS2 Galactic](https://docs.ros.org/en/galactic/Installation/Ubuntu-Install-Debians.html) + - [ROS2 Galactic](https://docs.ros.org/en/galactic/Installation/Ubuntu-Install-Debians.html) (deprecated) From a1a8255181b9caa825d18590ba09cb18ab4285ab Mon Sep 17 00:00:00 2001 From: SamerKhshiboun Date: Mon, 10 Apr 2023 00:24:02 +0300 Subject: [PATCH 6/8] add summary/details pans for TFs and Extrinsics --- README.md | 22 ++++++++++++++++------ 1 file changed, 16 insertions(+), 6 deletions(-) diff --git a/README.md b/README.md index cfeace86aa8..614bc844737 100644 --- a/README.md +++ b/README.md @@ -303,9 +303,12 @@ The `/diagnostics` topic includes information regarding the device temperatures
-

- TF from coordinate A to coordinate B: -

+
+ +

+ TF from coordinate A to coordinate B: +

+ - TF msg expresses a transform from coordinate frame "header.frame_id" (source) to the coordinate frame child_frame_id (destination) [Reference](http://docs.ros.org/en/noetic/api/geometry_msgs/html/msg/Transform.html) - In RealSense cameras, the origin point (0,0,0) is taken from the left IR (infra1) position and named as "camera_link" frame @@ -315,11 +318,17 @@ The `/diagnostics` topic includes information regarding the device temperatures - Example of static TFs of RGB sensor and Infra2 (right infra) sensor of D435i module as it shown in rviz2: ![example](https://user-images.githubusercontent.com/99127997/230148106-0f79cbdb-c401-4d09-b386-a366af18e5f7.png) +
+
-

- Extrinsics from sensor A to sensor B: -

+
+ +

+ Extrinsics from sensor A to sensor B: +

+ + - Extrinsic from sensor A to sensor B means the position and orientation of sensor A relative to sensor B. - Imagine that B is the origin (0,0,0), then the Extrensics(A->B) describes where is sensor A relative to sensor B. @@ -340,6 +349,7 @@ translation: --- ``` +
From 48b362b2151fbce1a781a2bc774e9a077b3490d9 Mon Sep 17 00:00:00 2001 From: SamerKhshiboun Date: Mon, 10 Apr 2023 13:05:57 +0300 Subject: [PATCH 7/8] remove collapses from TFs and Extrinsics, and edit links of ROS2 Distros --- README.md | 30 ++++++++++-------------------- 1 file changed, 10 insertions(+), 20 deletions(-) diff --git a/README.md b/README.md index 614bc844737..4be3949c30c 100644 --- a/README.md +++ b/README.md @@ -303,12 +303,9 @@ The `/diagnostics` topic includes information regarding the device temperatures
-
- -

- TF from coordinate A to coordinate B: -

- +

+ TF from coordinate A to coordinate B: +

- TF msg expresses a transform from coordinate frame "header.frame_id" (source) to the coordinate frame child_frame_id (destination) [Reference](http://docs.ros.org/en/noetic/api/geometry_msgs/html/msg/Transform.html) - In RealSense cameras, the origin point (0,0,0) is taken from the left IR (infra1) position and named as "camera_link" frame @@ -318,16 +315,11 @@ The `/diagnostics` topic includes information regarding the device temperatures - Example of static TFs of RGB sensor and Infra2 (right infra) sensor of D435i module as it shown in rviz2: ![example](https://user-images.githubusercontent.com/99127997/230148106-0f79cbdb-c401-4d09-b386-a366af18e5f7.png) -
-
-
- -

- Extrinsics from sensor A to sensor B: -

- +

+ Extrinsics from sensor A to sensor B: +

- Extrinsic from sensor A to sensor B means the position and orientation of sensor A relative to sensor B. @@ -349,8 +341,6 @@ translation: --- ``` -
-

@@ -497,13 +487,13 @@ ros2 launch realsense2_camera rs_intra_process_demo_launch.py intra_process_comm [rolling-badge]: https://img.shields.io/badge/-ROLLING-orange?style=flat-square&logo=ros -[rolling]: https://docs.ros.org/en/rolling/Releases.html +[rolling]: https://docs.ros.org/en/rolling/index.html [humble-badge]: https://img.shields.io/badge/-HUMBLE-orange?style=flat-square&logo=ros -[humble]: https://docs.ros.org/en/rolling/Releases/Release-Humble-Hawksbill.html +[humble]: https://docs.ros.org/en/humble/index.html [foxy-badge]: https://img.shields.io/badge/-FOXY-orange?style=flat-square&logo=ros -[foxy]: https://docs.ros.org/en/rolling/Releases/Release-Foxy-Fitzroy.html +[foxy]: https://docs.ros.org/en/foxy/index.html [galactic-badge]: https://img.shields.io/badge/-GALACTIC-orange?style=flat-square&logo=ros -[galactic]: https://docs.ros.org/en/galactic/Releases/Release-Foxy-Fitzroy.html +[galactic]: https://docs.ros.org/en/galactic/index.html [ubuntu22-badge]: https://img.shields.io/badge/-UBUNTU%2022%2E04-blue?style=flat-square&logo=ubuntu&logoColor=white [ubuntu22]: https://releases.ubuntu.com/jammy/ [ubuntu20-badge]: https://img.shields.io/badge/-UBUNTU%2020%2E04-blue?style=flat-square&logo=ubuntu&logoColor=white From 9d21262cba527391a004dc8074452dbde9ee3639 Mon Sep 17 00:00:00 2001 From: SamerKhshiboun Date: Mon, 10 Apr 2023 13:09:25 +0300 Subject: [PATCH 8/8] add REP references for CS --- README.md | 1 + 1 file changed, 1 insertion(+) diff --git a/README.md b/README.md index 4be3949c30c..7bd8cf56259 100644 --- a/README.md +++ b/README.md @@ -300,6 +300,7 @@ The `/diagnostics` topic includes information regarding the device temperatures - ROS2 Coordinate System: (X: Forward, Y:Left, Z: Up) - Camera Optical Coordinate System: (X: Right, Y: Down, Z: Forward) +- References: [REP-0103](https://www.ros.org/reps/rep-0103.html#coordinate-frame-conventions) [REP-0105](https://www.ros.org/reps/rep-0105.html#coordinate-frames)