From 09a41ffb5f56c6fdb15a013b4713096d72d2757a Mon Sep 17 00:00:00 2001 From: Ammaar Ahmed Date: Fri, 3 Apr 2026 05:17:33 +0100 Subject: [PATCH 1/7] add performance_tuning to jetty/tutorials Signed-off-by: Ammaar Ahmed --- jetty/index.yaml | 3 ++ jetty/performance_tuning.md | 84 +++++++++++++++++++++++++++++++++++++ jetty/tutorials.md | 1 + 3 files changed, 88 insertions(+) create mode 100644 jetty/performance_tuning.md diff --git a/jetty/index.yaml b/jetty/index.yaml index f7ff342e13..4f7f7f8e9c 100644 --- a/jetty/index.yaml +++ b/jetty/index.yaml @@ -69,6 +69,9 @@ pages: - name: sensors title: Sensors file: sensors.md + - name: performance_tuning + title: Performance tuning + file: performance_tuning.md - name: actors title: Actors file: actors.md diff --git a/jetty/performance_tuning.md b/jetty/performance_tuning.md new file mode 100644 index 0000000000..8e556fa754 --- /dev/null +++ b/jetty/performance_tuning.md @@ -0,0 +1,84 @@ +# Performance tuning + +If your Jetty simulation is running below real time or the GUI feels slow, start +by identifying which part of the workload is expensive. A world with many +contacts is tuned differently from a world dominated by cameras, lidar, or +rendering. + +## Measure first + +Before changing settings, enable the world statistics tools described in +[SDF Worlds](sdf_worlds). In particular, keep an eye on: + +* real time factor (RTF) +* simulation time versus real time +* whether the slowdown appears when physics, sensors, or rendering load changes + +This gives you a baseline before you start trading fidelity for speed. + +## Common performance tweaks + +### Reduce physics work + +* Try less aggressive physics settings in [SDF Worlds](sdf_worlds). Larger + `` values usually reduce computation, but they also reduce + accuracy and can change contact behavior. +* Use simpler collision geometry when possible. [Building your own robot](building_robot) + notes that collision geometry does not need to match the visual mesh exactly, + and simpler collisions often reduce computation time. + +### Reduce sensor work + +* Lower `` for sensors that do not need high-frequency data. See + [Sensors](sensors). +* Turn off visualization when you do not need it. +* For lidar, reduce the number of samples or resolution before increasing scene + complexity. +* If a GPU-backed lidar fits your use case, consider `gpu_lidar` in + [Sensors](sensors). It requires Ogre 2. + +### Reduce rendering work + +* Jetty uses Ogre 2 by default. If you are forcing Ogre 1, compare it with the + default first. If Ogre 2 is unavailable on your machine, [Troubleshooting](troubleshooting) + explains the OpenGL requirements and how to fall back to `--render-engine ogre`. +* Reduce expensive visual effects when they are not needed. For example, disable + shadow casting on lights with `false` and prefer + simpler materials if rendering is the bottleneck. +* If your scene uses PBR materials and rendering is the bottleneck, test simpler + materials or Ogre 1 as a comparison point. PBR is supported by render engines + such as Ogre 2, but it is not free. + +### Use simpler models + +* Reduce triangle counts in imported meshes. +* Keep visual meshes and collision meshes separate so collisions can stay simple + even when the visual model is detailed. +* Remove sensors, lights, or plugins from models that are not needed in a given + experiment. + +### Make sure Gazebo is using the right GPU + +* On hybrid Intel / Nvidia systems, Gazebo may start on the integrated GPU. + [Troubleshooting](troubleshooting) shows how to use PRIME render offload or + Nvidia performance mode. +* If Ogre 2 fails to start, check OpenGL support and driver setup before + assuming the simulation itself is slow. + +## Advanced and external options + +These are worth exploring for specialized workloads, but they are not part of a +small Jetty-only tuning guide: + +* Alternative physics backends such as [Bullet Featherstone](https://github.com/gazebosim/gz-physics/issues/44){.external} + may help some articulated systems, but they need workload-specific validation + and are not covered by a Jetty how-to yet. +* Third-party accelerators such as [RGLGazeboPlugin](https://github.com/RobotecAI/RGLGazeboPlugin){.external} + or [gz_wgpu_rt_lidar](https://github.com/arjo129/gz_wgpu_rt_lidar/){.external} + may be useful when GPU-accelerated sensing is the main bottleneck. Follow the + setup and support guidance in those projects. + +Start with the documented knobs in Jetty first: physics step size, simpler +collisions, lower sensor rates, rendering settings, and correct GPU usage. +Those changes are usually easier to validate and easier to maintain across +releases. \ No newline at end of file diff --git a/jetty/tutorials.md b/jetty/tutorials.md index 6b5d9913bd..9a07eb0a94 100644 --- a/jetty/tutorials.md +++ b/jetty/tutorials.md @@ -8,6 +8,7 @@ These tutorials cover general concepts to help get you started with Gazebo. * [Moving the Robot](moving_robot) * [SDF Worlds](sdf_worlds) * [Sensors](sensors) +* [Performance tuning](performance_tuning) * [Actors](actors) ## GUI tutorials From 4cc73f74bba81563be6b0de43f2bbd34105bf4c8 Mon Sep 17 00:00:00 2001 From: Ammaar Ahmed Date: Fri, 3 Apr 2026 05:36:07 +0100 Subject: [PATCH 2/7] Update jetty/performance_tuning.md Co-authored-by: Copilot <175728472+Copilot@users.noreply.github.com> Signed-off-by: Ammaar Ahmed --- jetty/performance_tuning.md | 3 ++- 1 file changed, 2 insertions(+), 1 deletion(-) diff --git a/jetty/performance_tuning.md b/jetty/performance_tuning.md index 8e556fa754..58778cb5f4 100644 --- a/jetty/performance_tuning.md +++ b/jetty/performance_tuning.md @@ -35,7 +35,8 @@ This gives you a baseline before you start trading fidelity for speed. * For lidar, reduce the number of samples or resolution before increasing scene complexity. * If a GPU-backed lidar fits your use case, consider `gpu_lidar` in - [Sensors](sensors). It requires Ogre 2. + [Sensors](sensors). Its availability and performance depend on rendering + engine support and your GPU / driver setup. ### Reduce rendering work From 6666b2064ca8b96d21d951b0ce1178bf45efb5fe Mon Sep 17 00:00:00 2001 From: Ammaar Ahmed Date: Fri, 3 Apr 2026 05:37:30 +0100 Subject: [PATCH 3/7] Update jetty/tutorials.md Co-authored-by: Copilot <175728472+Copilot@users.noreply.github.com> Signed-off-by: Ammaar Ahmed --- jetty/tutorials.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/jetty/tutorials.md b/jetty/tutorials.md index 9a07eb0a94..2a42123a6b 100644 --- a/jetty/tutorials.md +++ b/jetty/tutorials.md @@ -8,7 +8,7 @@ These tutorials cover general concepts to help get you started with Gazebo. * [Moving the Robot](moving_robot) * [SDF Worlds](sdf_worlds) * [Sensors](sensors) -* [Performance tuning](performance_tuning) +* [Performance Tuning](performance_tuning) * [Actors](actors) ## GUI tutorials From a267372267bc1016fe91e7c90236b6e076e5da2c Mon Sep 17 00:00:00 2001 From: Ammaar Ahmed Date: Fri, 3 Apr 2026 05:39:50 +0100 Subject: [PATCH 4/7] Update jetty/performance_tuning.md Co-authored-by: Copilot <175728472+Copilot@users.noreply.github.com> Signed-off-by: Ammaar Ahmed --- jetty/performance_tuning.md | 6 +++--- 1 file changed, 3 insertions(+), 3 deletions(-) diff --git a/jetty/performance_tuning.md b/jetty/performance_tuning.md index 58778cb5f4..95336bb29f 100644 --- a/jetty/performance_tuning.md +++ b/jetty/performance_tuning.md @@ -71,11 +71,11 @@ This gives you a baseline before you start trading fidelity for speed. These are worth exploring for specialized workloads, but they are not part of a small Jetty-only tuning guide: -* Alternative physics backends such as [Bullet Featherstone](https://github.com/gazebosim/gz-physics/issues/44){.external} +* Alternative physics backends such as [Bullet Featherstone](https://github.com/gazebosim/gz-physics/issues/44) may help some articulated systems, but they need workload-specific validation and are not covered by a Jetty how-to yet. -* Third-party accelerators such as [RGLGazeboPlugin](https://github.com/RobotecAI/RGLGazeboPlugin){.external} - or [gz_wgpu_rt_lidar](https://github.com/arjo129/gz_wgpu_rt_lidar/){.external} +* Third-party accelerators such as [RGLGazeboPlugin](https://github.com/RobotecAI/RGLGazeboPlugin) + or [gz_wgpu_rt_lidar](https://github.com/arjo129/gz_wgpu_rt_lidar/) may be useful when GPU-accelerated sensing is the main bottleneck. Follow the setup and support guidance in those projects. From 55a7fef8353ea378022355949c00e11d7e3e8848 Mon Sep 17 00:00:00 2001 From: Ammaar Ahmed Date: Fri, 8 May 2026 08:09:34 +0100 Subject: [PATCH 5/7] Update jetty/performance_tuning.md Co-authored-by: Martin Pecka Signed-off-by: Ammaar Ahmed --- jetty/performance_tuning.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/jetty/performance_tuning.md b/jetty/performance_tuning.md index 95336bb29f..e9dc8eb459 100644 --- a/jetty/performance_tuning.md +++ b/jetty/performance_tuning.md @@ -60,7 +60,7 @@ This gives you a baseline before you start trading fidelity for speed. ### Make sure Gazebo is using the right GPU -* On hybrid Intel / Nvidia systems, Gazebo may start on the integrated GPU. +* On hybrid systems with both integrated and discrete GPUs, Gazebo may start on the integrated GPU. [Troubleshooting](troubleshooting) shows how to use PRIME render offload or Nvidia performance mode. * If Ogre 2 fails to start, check OpenGL support and driver setup before From 4d1b4506cf29b64d5572a4a9e25ff2b532d5e1bc Mon Sep 17 00:00:00 2001 From: Ammaar Ahmed Date: Fri, 8 May 2026 08:09:46 +0100 Subject: [PATCH 6/7] Update jetty/performance_tuning.md Co-authored-by: Martin Pecka Signed-off-by: Ammaar Ahmed --- jetty/performance_tuning.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/jetty/performance_tuning.md b/jetty/performance_tuning.md index e9dc8eb459..8bb5cb869d 100644 --- a/jetty/performance_tuning.md +++ b/jetty/performance_tuning.md @@ -40,7 +40,7 @@ This gives you a baseline before you start trading fidelity for speed. ### Reduce rendering work -* Jetty uses Ogre 2 by default. If you are forcing Ogre 1, compare it with the +* Gazebo uses Ogre 2 by default. If you are forcing Ogre 1, compare it with the default first. If Ogre 2 is unavailable on your machine, [Troubleshooting](troubleshooting) explains the OpenGL requirements and how to fall back to `--render-engine ogre`. * Reduce expensive visual effects when they are not needed. For example, disable From a9ebaeb304d2d3e4748840467f7f1837d7f7ed18 Mon Sep 17 00:00:00 2001 From: Ammaar Ahmed Date: Fri, 8 May 2026 09:02:43 +0100 Subject: [PATCH 7/7] Remove conflict markers from performance tuning guide Signed-off-by: Ammaar Ahmed --- jetty/performance_tuning.md | 6 ------ 1 file changed, 6 deletions(-) diff --git a/jetty/performance_tuning.md b/jetty/performance_tuning.md index 8ea7de6218..19a716c54b 100644 --- a/jetty/performance_tuning.md +++ b/jetty/performance_tuning.md @@ -69,16 +69,10 @@ This gives you a baseline before you start trading fidelity for speed. ### Make sure Gazebo is using the right GPU -<<<<<<< HEAD * On hybrid systems with both integrated and discrete GPUs, Gazebo may start on the integrated GPU. Check the active OpenGL renderer with `glxinfo | grep "OpenGL"`. [Troubleshooting](troubleshooting) shows how to use PRIME render offload or Nvidia performance mode. -======= -* On hybrid systems with both integrated and discrete GPUs, Gazebo may start on the integrated GPU. - [Troubleshooting](troubleshooting) shows how to use PRIME render offload or - Nvidia performance mode. ->>>>>>> origin/jetty/tutorials/performancetuning * If Ogre 2 fails to start, check OpenGL support and driver setup before assuming the simulation itself is slow.