Skip to content

Commit

Permalink
Merge branch 'IntelRealSense:ros2-development' into ros2
Browse files Browse the repository at this point in the history
  • Loading branch information
@masf7g
masf7g authored Oct 30, 2023
2 parents 71961d2 + 8834e34 commit 9aeb75e
Show file tree
Hide file tree
Showing 59 changed files with 2,433 additions and 966 deletions.
71 changes: 0 additions & 71 deletions .travis.yml
View file

This file was deleted.

107 changes: 35 additions & 72 deletions README.md
View file
Original file line number Diff line number Diff line change
Expand Up @@ -23,29 +23,27 @@
<hr>

## Table of contents
* [ROS1 and ROS2 legacy](#legacy)
* [ROS1 and ROS2 legacy](#ros1-and-ros2-legacy)
* [Installation](#installation)
* [Usage](#usage)
* [Starting the camera node](#start-camera-node)
* [Camera name and namespace](#camera-name-and-namespace)
* [Starting the camera node](#start-the-camera-node)
* [Camera name and namespace](#camera-name-and-camera-namespace)
* [Parameters](#parameters)
* [ROS2-vs-Optical Coordination Systems](#coordination)
* [TF from coordinate A to coordinate B](#tfs)
* [Extrinsics from sensor A to sensor B](#extrinsics)
* [Topics](#topics)
* [RGBD Topic](#rgbd)
* [Metadata Topic](#metadata)
* [Post-Processing Filters](#filters)
* [Available Services](#services)
* [Efficient intra-process communication](#intra-process)
* [ROS2-vs-Optical Coordination Systems](#ros2robot-vs-opticalcamera-coordination-systems)
* [TF from coordinate A to coordinate B](#tf-from-coordinate-a-to-coordinate-b)
* [Extrinsics from sensor A to sensor B](#extrinsics-from-sensor-a-to-sensor-b)
* [Topics](#published-topics)
* [RGBD Topic](#rgbd-topic)
* [Metadata Topic](#metadata-topic)
* [Post-Processing Filters](#post-processing-filters)
* [Available Services](#available-services)
* [Efficient intra-process communication](#efficient-intra-process-communication)
* [Contributing](CONTRIBUTING.md)
* [License](LICENSE)

<hr>

<h2 id="legacy">
Legacy
</h2>
# ROS1 and ROS2 Legacy

<details>
<summary>
Expand Down Expand Up @@ -80,9 +78,7 @@
</details>


<h2 id="installation">
Installation
</h2>
# Installation

<details>
<summary>
Expand Down Expand Up @@ -143,8 +139,8 @@
- Install dependencies
```bash
sudo apt-get install python3-rosdep -y
sudo rosdep init # "sudo rosdep init --include-eol-distros" for Eloquent and earlier
rosdep update # "sudo rosdep update --include-eol-distros" for Eloquent and earlier
sudo rosdep init # "sudo rosdep init --include-eol-distros" for Foxy and earlier
rosdep update # "sudo rosdep update --include-eol-distros" for Foxy and earlier
rosdep install -i --from-path src --rosdistro $ROS_DISTRO --skip-keys=librealsense2 -y
```

Expand All @@ -165,13 +161,9 @@

<hr>

<h2 id="usage">
Usage
</h2>
# Usage

<h3 id="start-camera-node">
Start the camera node
</h3>
## Start the camera node

#### with ros2 run:
ros2 run realsense2_camera realsense2_camera_node
Expand All @@ -184,11 +176,8 @@

<hr>

<h3 id="camera-name-and-namespace">
Camera Name And Camera Namespace
</h3>
## Camera Name And Camera Namespace

### Usage
User can set the camera name and camera namespace, to distinguish between cameras and platforms, which helps identifying the right nodes and topics to work with.

### Example
Expand All @@ -203,7 +192,7 @@ User can set the camera name and camera namespace, to distinguish between camera

```ros2 launch realsense2_camera rs_launch.py camera_namespace:=robot1 camera_name:=D455_1```

- With ros2 run (using remapping mechanisim [Reference](https://docs.ros.org/en/foxy/How-To-Guides/Node-arguments.html)):
- With ros2 run (using remapping mechanisim [Reference](https://docs.ros.org/en/humble/How-To-Guides/Node-arguments.html)):

```ros2 run realsense2_camera realsense2_camera_node --ros-args -r __node:=D455_1 -r __ns:=robot1```

Expand Down Expand Up @@ -248,13 +237,9 @@ User can set the camera name and camera namespace, to distinguish between camera
/camera/camera/device_info
```


<hr>


<h3 id="parameters">
Parameters
<h3>
## Parameters

### Available Parameters:
- For the entire list of parameters type `ros2 param list`.
Expand All @@ -269,13 +254,13 @@ User can set the camera name and camera namespace, to distinguish between camera
- They have, at least, the **profile** parameter.
- The profile parameter is a string of the following format: \<width>X\<height>X\<fps> (The dividing character can be X, x or ",". Spaces are ignored.)
- For example: ```depth_module.profile:=640x480x30 rgb_camera.profile:=1280x720x30```
- Since infra, infra1, infra2, fisheye, fisheye1, fisheye2 and depth are all streams of the depth_module, their width, height and fps are defined by the same param **depth_module.profile**
- Since infra, infra1, infra2 and depth are all streams of the depth_module, their width, height and fps are defined by the same param **depth_module.profile**
- If the specified combination of parameters is not available by the device, the default or previously set configuration will be used.
- Run ```ros2 param describe <your_node_name> <param_name>``` to get the list of supported profiles.
- Note: Should re-enable the stream for the change to take effect.
- ***<stream_name>*_format**
- This parameter is a string used to select the stream format.
- <stream_name> can be any of *infra, infra1, infra2, color, depth, fisheye, fisheye1, fisheye2*.
- <stream_name> can be any of *infra, infra1, infra2, color, depth*.
- For example: ```depth_module.depth_format:=Z16 depth_module.infra1_format:=y8 rgb_camera.color_format:=RGB8```
- This parameter supports both lower case and upper case letters.
- If the specified parameter is not available by the stream, the default or previously set configuration will be used.
Expand All @@ -286,14 +271,14 @@ User can set the camera name and camera namespace, to distinguish between camera
- Run ```rs-enumerate-devices``` command to know the list of profiles supported by the connected sensors.
- **enable_*<stream_name>***:
- Choose whether to enable a specified stream or not. Default is true for images and false for orientation streams.
- <stream_name> can be any of *infra, infra1, infra2, color, depth, fisheye, fisheye1, fisheye2, gyro, accel, pose*.
- <stream_name> can be any of *infra, infra1, infra2, color, depth, gyro, accel*.
- 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.
- ***<stream_type>*_qos**:
- Sets the QoS by which the topic is published.
- <stream_type> can be any of *infra, infra1, infra2, color, depth, fisheye, fisheye1, fisheye2, gyro, accel, pose*.
- <stream_type> can be any of *infra, infra1, infra2, color, depth, gyro, accel*.
- 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)
Expand Down Expand Up @@ -354,7 +339,6 @@ User can set the camera name and camera namespace, to distinguish between camera
- If set to true, the device will reset prior to usage.
- For example: `initial_reset:=true`
- **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.
- **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`
Expand All @@ -371,13 +355,9 @@ User can set the camera name and camera namespace, to distinguish between camera
- 0 or negative values mean no diagnostics topic is published. Defaults to 0.</br>
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.

<hr>

<h3 id="coordination">
ROS2(Robot) vs Optical(Camera) Coordination Systems:
</h3>
## ROS2(Robot) vs Optical(Camera) Coordination Systems:

- Point Of View:
- Imagine we are standing behind of the camera, and looking forward.
Expand All @@ -393,9 +373,7 @@ The `/diagnostics` topic includes information regarding the device temperatures

<hr>

<h3 id="tfs">
TF from coordinate A to coordinate B:
</h3>
## 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
Expand All @@ -407,10 +385,7 @@ The `/diagnostics` topic includes information regarding the device temperatures

<hr>

<h3 id="extrinsics">
Extrinsics from sensor A to sensor B:
</h3>

## 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.
Expand Down Expand Up @@ -445,9 +420,7 @@ translation:

<hr>

<h3 id="topics">
Published Topics
</h3>
## 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`):
Expand Down Expand Up @@ -489,9 +462,7 @@ Enabling stream adds matching topics. For instance, enabling the gyro and accel

<hr>

<h3 id="rgbd">
RGBD Topic
</h3>
## RGBD Topic

RGBD new topic, publishing [RGB + Depth] in the same message (see RGBD.msg for reference). For now, works only with depth aligned to color images, as color and depth images are synchronized by frame time tag.

Expand All @@ -511,9 +482,7 @@ ros2 launch realsense2_camera rs_launch.py enable_rgbd:=true enable_sync:=true a

<hr>

<h3 id="metadata">
Metadata topic
</h3>
## 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:
```
Expand All @@ -522,10 +491,8 @@ python3 src/realsense-ros/realsense2_camera/scripts/echo_metadada.py /camera/cam

<hr>

<h3 id="filters">
Post-Processing Filters
</h3>

## 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/camera/aligned_depth_to_color/image_raw`.
- The pointcloud, if created, will be based on the aligned depth image.
Expand Down Expand Up @@ -555,17 +522,13 @@ Each of the above filters have it's own parameters, following the naming convent

<hr>

<h3 id="services">
Available services
</h3>
## 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/camera/device_info realsense2_camera_msgs/srv/DeviceInfo`

<hr>

<h3 id="intra-process">
Efficient intra-process communication:
</h3>
## 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/pointcloud topics, especially with big frame resolutions and high FPS.

Expand Down
Loading

0 comments on commit 9aeb75e

Please sign in to comment.