Skip to content

Commit e6e2b14

Browse files
MarqRazzMarqRazz
authored
General gz camera (#5)
1 parent 20ea55e commit e6e2b14

29 files changed

+1734
-203
lines changed

‎README.md‎

Lines changed: 79 additions & 36 deletions
Original file line numberDiff line numberDiff line change
@@ -1,43 +1,60 @@
1-
# Realsense Gazebo description
1+
# Gazebo Sensor Descriptions
22

3-
[![Format Status](https://github.com/MarqRazz/realsense2_gz_description/actions/workflows/format.yaml/badge.svg)](https://github.com/MarqRazz/realsense2_gz_description/actions/workflows/format.yaml)
3+
[![Format Status](https://github.com/locusrobotics/gz_sensor_descriptions/actions/workflows/format.yaml/badge.svg)](https://github.com/locusrobotics/gz_sensor_descriptions/actions/workflows/format.yaml)
44

5-
Description: This ROS 2 package is designed to be used in unison with [realsense2_description](https://github.com/IntelRealSense/realsense-ros/tree/ros2-master/realsense2_description) and allows for easy definition of Realsense cameras that can be simulated in Gazebo Fortress and newer. It may support other versions of Gazebo but this has not been tested.
5+
This repo is designed to make it easy to simulate Gazebo sensors and use/define them in your robots URDF.
6+
It includes ROS2 URDF xacro's that properly define and configure the sensors for Gazebo.
7+
Currently cameras (RGB, Depth or RGBD) are the only sensors supported but more will be added.
68

7-
## Running Example Launch
9+
This repo also offers convenient packages of common off the shelf sensors to make it easy to switch between simulation and hardware for the supported devices. If you would like your sensor added here please feel free to make a PR.
810

9-
This package includes a launch file to start Gazebo, bridge the data to ROS 2 and display the simulated camera data in Rviz.
11+
Example Realsense multi-camera simulation bridged to ROS 2:
12+
<img src="doc/realsense_gazebo.png" >
1013

11-
Once you have built this package and sourced your workspace you can run
12-
```bash
13-
ros2 launch realsense2_gz_description example_realsense_gazebo.launch.py
14-
```
14+
The repo is divided up into 3 packages:
15+
- [Generic Gazebo Camera macros](gz_camera_macros/README.md) includes generic ROS xacro's that can be used to make a supported camera types
16+
- [Realsense2 Gazebo Camera macros](realsense2_gz_description/README.md) includes xacros to define cameras in Gazebo that emulate a Realsense device available in `realsense2_description`
17+
- [Orbbec Gazebo Camera macros](orbbec_gz_description/README.md) includes xacros to define cameras in Gazebo that emulate a Orbbec device available in the `orbbec_description` package on the [locus](https://github.com/locusrobotics/OrbbecSDK_ROS2/tree/locus) branch
1518

16-
> Note: you can specify `headless:=false` and it will also open the Gazebo GUI.
19+
In the [package.xml](gz_camera_macros/package.xml) of the generic macros or even a specific camera like the [Realsense](realsense2_gz_description/package.xml)
20+
they do not require Gazebo be installed because they are just xacro definitions.
21+
You need the following packages available if you would like to run the simulator and example launch files.
22+
```xml
23+
<depend>robot_state_publisher</depend>
24+
<depend>image_proc</depend>
25+
<depend>ros_gz_bridge</depend>
26+
<depend>ros_gz_sim</depend>
27+
<depend>rviz2</depend>
28+
```
1729

18-
Which should start a simulated camera in Gazebo with a few objects in front of it. In the Rviz window that launches you can see the RGB images streaming along with the point cloud in the main view.
30+
# Known Issues
31+
Gazebo parameter [optical_frame_id](https://github.com/gazebosim/gz-sensors/blob/fc8692c075001e9379d1ffe84c19149f49b43da5/src/CameraSensor.cc#L715-L716) is deprecated and will be removed at some point.
32+
Attempting to use the `<sensor>`/`<gz_frame_id>` parameter to correct the frame_id for the camera_info topic does not to play nice and results in lots of
33+
`XML Element[gz_frame_id], child of element[sensor], not defined in SDF. Copying[gz_frame_id] as children of [sensor].`
34+
warnings printed for each camera instance.
1935

20-
<img src="doc/realsense_gazebo.png" width="50%" >
36+
The RGBD camera does NOT use the parameter `optical_frame_id` correctly any more and publishes the data with an incorrect frame_id.
2137

38+
### Usage
2239

23-
# Example Usage in URDF
40+
In your robots URDF....
2441

25-
In your robots urdf.xacro include the desired Realsense model along with its Gazebo description.
42+
1. Include and run your camera's description xacro:
2643
```xml
2744
<xacro:include filename="$(find realsense2_description)/urdf/_d415.urdf.xacro" />
28-
<xacro:include filename="$(find realsense2_gz_description)/urdf/_d415.gazebo.xacro" />
29-
30-
```
31-
Then call the xacros and specify the same `name` and other optional arguments.
32-
```xml
33-
<!-- URDF xacro-->
34-
<xacro:sensor_d415 parent="world" name="$(arg camera_name)" ...>
35-
<origin xyz="0 0 0" rpy="0 0 0"/>
45+
...
46+
<xacro:sensor_d415 parent="my_robots_camera_mount_link" name="$(arg camera_name)">
47+
<origin xyz="0 0 0" rpy="0 0 0"/> <!-- This robot's camera mount is aligned with the camera base -->
3648
</xacro:sensor_d415>
37-
<!-- Gazebo xacro-->
38-
<xacro:gazebo_d415 name="$(arg camera_name)" .../>
3949
```
4050

51+
2. Selectivly include Gz xacro with `if(sim_gazebo)` if you don't want the definition included when running with hardware:
52+
```xml
53+
<xacro:if value="${sim_gazebo}">
54+
<xacro:include filename="$(find realsense2_gz_description)/urdf/_d415.gazebo.xacro" />
55+
<xacro:gazebo_d415 name="$(arg camera_name)" gz_topic_name="$(arg camera_name)" type="rgbd" fps="15"/>
56+
</xacro:if>
57+
```
4158
> Note: Gazebo plugins can only be included once so the xacros in this repo assume that a parent will include/run the required Sensors plugin when starting simulation.
4259
This plugin can be started from your URDF or world.sdf file.
4360
```xml
@@ -48,18 +65,44 @@ This plugin can be started from your URDF or world.sdf file.
4865
</gazebo>
4966
```
5067

51-
you can also refer to the the [example.urdf.xacro](./urdf/example_d415_gazebo.urdf.xacro) included.
52-
53-
## Gazebo only features
54-
55-
Gazebo offers a triggered based RGB camera that can be enabled by passing `triggered="true"` to the Gazebo description xacro.
56-
Currently this feature does not appear to not work with the RGBD sensor, but will hopefully be added soon.
57-
Switching the camera to only `trigger` when requested allows developers to better control the computation load required by each sensor.
58-
Note triggering is not a feature the Realsense hardware offers unfortunately.
59-
60-
To trigger the camera from the command line you can publish on the Gazebo topic `camera_name/trigger`.
61-
```bash
62-
ign topic -t "/name/trigger" -m Boolean -p "data: true" -n 1
68+
3. When simulating add to your robot's Gazebo launch file to start and configure the bridge `Node` so that you can see the simulated data as ROS topics:
69+
```python
70+
# Bridge
71+
gazebo_bridge = Node(
72+
package="ros_gz_bridge",
73+
executable="parameter_bridge",
74+
parameters=[{"use_sim_time": True}],
75+
arguments=[
76+
"/wrist_camera/image@sensor_msgs/msg/Image[gz.msgs.Image",
77+
"/wrist_camera/depth_image@sensor_msgs/msg/Image[gz.msgs.Image",
78+
"/wrist_camera/points@sensor_msgs/msg/PointCloud2[gz.msgs.PointCloudPacked",
79+
"/wrist_camera/camera_info@sensor_msgs/msg/CameraInfo[gz.msgs.CameraInfo",
80+
"/clock@rosgraph_msgs/msg/Clock[gz.msgs.Clock",
81+
],
82+
remappings=[
83+
(
84+
"/wrist_camera/image",
85+
"/wrist/camera/color/image_raw",
86+
),
87+
(
88+
"/wrist_camera/depth_image",
89+
"/wrist/camera/depth_registered/image_rect",
90+
),
91+
(
92+
"/wrist_camera/points",
93+
"/wrist/camera/depth/color/points",
94+
),
95+
(
96+
"/wrist_camera/camera_info",
97+
"/wrist/camera/color/camera_info",
98+
),
99+
(
100+
"/wrist_camera/camera_info",
101+
"/wrist/camera/depth_registered/camera_info",
102+
)
103+
],
104+
output="screen",
105+
)
63106
```
64107

65108
## Contributing

‎doc/realsense_gazebo.png‎

261 KB
Loading

‎gz_camera_macros/CMakeLists.txt‎

Lines changed: 12 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,12 @@
1+
cmake_minimum_required(VERSION 3.5)
2+
project(gz_camera_macros)
3+
4+
# find dependencies
5+
find_package(ament_cmake REQUIRED)
6+
7+
install(
8+
DIRECTORY urdf
9+
DESTINATION share/${PROJECT_NAME}
10+
)
11+
12+
ament_package()

‎gz_camera_macros/README.md‎

Lines changed: 58 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,58 @@
1+
# Gazebo Camera Macro's
2+
3+
### Example Usage in URDF
4+
5+
In your robot or camera's urdf.xacro include the desired macro.
6+
```xml
7+
<xacro:include filename="$(find gz_camera_macros)/urdf/rgb_camera.gazebo.xacro" />
8+
<xacro:include filename="$(find gz_camera_macros)/urdf/rgbd_camera.gazebo.xacro" />
9+
10+
```
11+
Then call the desired macro and specify the same `name` and camera properties.
12+
```xml
13+
<xacro:if value="${type == 'rgbd'}">
14+
<xacro:gazebo_rgbd name="${name}"
15+
fps="${fps}"
16+
gz_topic_name="${gz_topic_name}"
17+
image_width="${image_width}"
18+
image_height="${image_height}"
19+
h_fov="${camera_h_fov}"
20+
v_fov="${camera_v_fov}"
21+
min_depth="${min_depth}"
22+
max_depth="${max_depth}"/>
23+
</xacro:if>
24+
<xacro:if value="${type == 'rgb'}">
25+
<xacro:gazebo_rgb name="${name}"
26+
fps="${fps}"
27+
gz_topic_name="${gz_topic_name}"
28+
image_width="${image_width}"
29+
image_height="${image_height}"
30+
h_fov="${camera_h_fov}"
31+
v_fov="${camera_v_fov}"
32+
triggered="${triggered}"/>
33+
</xacro:if>
34+
```
35+
36+
> Note: Gazebo plugins can only be included once so the xacros in this repo assume that a parent will include/run the required Sensors plugin when starting simulation.
37+
This plugin can be started from your URDF or world.sdf file.
38+
```xml
39+
<gazebo>
40+
<plugin filename="gz-sim-sensors-system" name="gz::sim::systems::Sensors">
41+
<render_engine>ogre2</render_engine>
42+
</plugin>
43+
</gazebo>
44+
```
45+
46+
you can also refer to the the [example.urdf.xacro](./urdf/example_d415_gazebo.urdf.xacro) included.
47+
48+
## Triggering RGB camera
49+
50+
Gazebo offers a triggered based RGB camera that can be enabled by passing `triggered="true"` to the Gazebo description xacro.
51+
Currently this feature does not work with the RGBD sensor in Gazebo, but will hopefully be added soon.
52+
Switching the camera to only `trigger` when requested allows developers to better control the computation load required by each sensor.
53+
Note triggering on some hardware plarforms is not available.
54+
55+
To trigger the camera from the command line you can publish on the Gazebo topic `camera_name/trigger`.
56+
```bash
57+
ign topic -t "/name/trigger" -m Boolean -p "data: true" -n 1
58+
```

‎gz_camera_macros/package.xml‎

Lines changed: 17 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,17 @@
1+
<?xml version="1.0"?>
2+
<?xml-model href="http://download.ros.org/schema/package_format3.xsd" schematypens="http://www.w3.org/2001/XMLSchema"?>
3+
<package format="3">
4+
<name>gz_camera_macros</name>
5+
<version>0.0.1</version>
6+
<description>URDF xacro macros for Cameras in Gazebo</description>
7+
<maintainer email="[email protected]">Marq Rasmussen</maintainer>
8+
<license>BSD</license>
9+
10+
<buildtool_depend>ament_cmake</buildtool_depend>
11+
12+
<depend>xacro</depend>
13+
14+
<export>
15+
<build_type>ament_cmake</build_type>
16+
</export>
17+
</package>

‎gz_camera_macros/urdf/depth_camera.gazebo.xacro‎

Lines changed: 66 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,66 @@
1+
<?xml version="1.0"?>
2+
<robot name="gazebo_depth" xmlns:xacro="http://www.ros.org/wiki/xacro" xmlns:gz="http://gazebosim.org/schema">
3+
4+
<!--
5+
Gazebo plugins can only be included once so this xacro assumes that a parent will include and configure them.
6+
This xacro requires Gazebo plugin:
7+
- gz::sim::systems::Sensors
8+
to publish simulated depth camera data
9+
10+
For example:
11+
<gazebo>
12+
<plugin filename="gz-sim-sensors-system" name="gz::sim::systems::Sensors">
13+
<render_engine>ogre2</render_engine>
14+
</plugin>
15+
</gazebo>
16+
-->
17+
<xacro:macro name="gazebo_depth" params="
18+
name:=camera
19+
fps:=15
20+
triggered:=false
21+
triggered:=false
22+
gz_topic_name:=camera
23+
image_width:=1280
24+
image_height:=720
25+
h_fov
26+
v_fov">
27+
28+
<!--
29+
We need to assume the data is coming from the `_color_optical_frame`
30+
(i.e. registered in the same location as the RGB sensor)
31+
because the depth camera is not publishing camera_info.
32+
Note you will need to use `camera_info` from the RGB camera so settings should match.
33+
-->
34+
35+
<gazebo reference="${name}_color_frame">
36+
<sensor name="${name}_depth" type="depth_camera">
37+
<camera>
38+
<!-- TODO the depth camera_info is not working and does not publish to this topic -->
39+
<camera_info_topic>${gz_topic_name}/depth/camera_info</camera_info_topic>
40+
<horizontal_fov>${h_fov}</horizontal_fov>
41+
<image>
42+
<width>${image_width}</width>
43+
<height>${image_height}</height>
44+
</image>
45+
<clip>
46+
<near>0.1</near>
47+
<far>10</far>
48+
</clip>
49+
<!-- TODO this term is deprecated but behaves better than setting
50+
'<gz_frame_id>${name}_color_optical_frame</gz_frame_id>'
51+
in the <sensor> namespace -->
52+
<optical_frame_id>${name}_color_optical_frame</optical_frame_id>
53+
<triggered>${triggered}</triggered>
54+
<trigger_topic>${name}/trigger</trigger_topic>
55+
</camera>
56+
<!-- TODO once camera_info is working make this frame configurable -->
57+
<!-- <gz_frame_id>${name}_color_optical_frame</gz_frame_id> -->
58+
<always_on>1</always_on>
59+
<update_rate>${fps}</update_rate>
60+
<topic>${gz_topic_name}/depth_image</topic>
61+
<enable_metrics>false</enable_metrics>
62+
</sensor>
63+
</gazebo>
64+
65+
</xacro:macro>
66+
</robot>

‎gz_camera_macros/urdf/rgb_camera.gazebo.xacro‎

Lines changed: 75 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,75 @@
1+
<?xml version="1.0"?>
2+
<robot name="gazebo_rgb" xmlns:xacro="http://www.ros.org/wiki/xacro" xmlns:gz="http://gazebosim.org/schema">
3+
4+
<!--
5+
Gazebo plugins can only be included once so this xacro assumes that a parent will include and configure them.
6+
This xacro requires Gazebo plugin:
7+
- gz::sim::systems::Sensors
8+
to publish simulated RGB camera data
9+
10+
For example:
11+
<gazebo>
12+
<plugin filename="gz-sim-sensors-system" name="gz::sim::systems::Sensors">
13+
<render_engine>ogre2</render_engine>
14+
</plugin>
15+
</gazebo>
16+
-->
17+
<xacro:macro name="gazebo_rgb" params="
18+
name:=camera
19+
fps:=15
20+
triggered:=false
21+
gz_topic_name:=camera
22+
image_width:=1280
23+
image_height:=720
24+
h_fov
25+
v_fov">
26+
27+
<!--
28+
Assumptions
29+
Standard Gazebo RGB sensor in the same location as the physical camera.
30+
If you set the Lense parameters like we do in the RGBD camera the lighting renders incorrectly.
31+
-->
32+
33+
<gazebo reference="${name}_color_frame">
34+
<sensor name="${name}" type="camera">
35+
<camera>
36+
<horizontal_fov>${h_fov}</horizontal_fov>
37+
<image>
38+
<width>${image_width}</width>
39+
<height>${image_height}</height>
40+
<format>RGB_INT8</format>
41+
</image>
42+
<clip>
43+
<near>0.05</near>
44+
<far>10</far>
45+
</clip>
46+
<distortion>
47+
<k1>0.0</k1>
48+
<k2>0.0</k2>
49+
<k3>0.0</k3>
50+
<p1>0.0</p1>
51+
<p2>0.0</p2>
52+
<center>0.5 0.5</center>
53+
</distortion>
54+
<noise>
55+
<type>gaussian</type>
56+
<mean>0</mean>
57+
<stddev>0.00</stddev>
58+
</noise>
59+
<!-- TODO this term is deprecated but behaves better than setting
60+
'<gz_frame_id>${name}_color_optical_frame</gz_frame_id>'
61+
in the <sensor> namespace -->
62+
<optical_frame_id>${name}_color_optical_frame</optical_frame_id>
63+
<triggered>${triggered}</triggered>
64+
<trigger_topic>${name}/trigger</trigger_topic>
65+
</camera>
66+
<!-- <gz_frame_id>${name}_color_optical_frame</gz_frame_id> -->
67+
<always_on>1</always_on>
68+
<update_rate>${fps}</update_rate>
69+
<topic>${gz_topic_name}/image</topic>
70+
<enable_metrics>false</enable_metrics>
71+
</sensor>
72+
</gazebo>
73+
74+
</xacro:macro>
75+
</robot>

‎urdf/rgbd_camera.gazebo.xacro‎ renamed to ‎gz_camera_macros/urdf/rgbd_camera.gazebo.xacro‎

Lines changed: 3 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -87,6 +87,9 @@ For example:
8787
<far>${max_depth}</far>
8888
</clip>
8989
</depth_camera>
90+
<!-- WARNING
91+
This term is deprecated and the point clouds published from this sensor have the incorrect frame_id associated with the data.
92+
-->
9093
<optical_frame_id>${name}_color_optical_frame</optical_frame_id>
9194
</camera>
9295
<gz_frame_id>${name}_color_frame</gz_frame_id>

‎orbbec_gz_description/CMakeLists.txt‎

Lines changed: 12 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,12 @@
1+
cmake_minimum_required(VERSION 3.5)
2+
project(orbbec_gz_description)
3+
4+
# find dependencies
5+
find_package(ament_cmake REQUIRED)
6+
7+
install(
8+
DIRECTORY urdf launch rviz world
9+
DESTINATION share/${PROJECT_NAME}
10+
)
11+
12+
ament_package()

0 commit comments

Comments
 (0)