diff --git a/tutorials.md.in b/tutorials.md.in index a41255775a0..779c6705c76 100644 --- a/tutorials.md.in +++ b/tutorials.md.in @@ -38,6 +38,7 @@ Ignition @IGN_DESIGNATION_CAP@ library and how to use the library effectively. * \subpage test_fixture "Test Fixture": Writing automated CI tests * \subpage spherical_coordinates "Spherical coordinates": Working with latitude and longitude * \subpage python_interfaces Python interfaces +* \subpage headless_rendering "Headless rendering": Access the GPU on a remote machine to produce sensor data without an X server. **Migration from Gazebo classic** diff --git a/tutorials/headless_rendering.md b/tutorials/headless_rendering.md new file mode 100644 index 00000000000..124efa8df06 --- /dev/null +++ b/tutorials/headless_rendering.md @@ -0,0 +1,76 @@ +\page headless_rendering Headless Rendering + +It is often desirable to run simulation on a remote computer, such as +a computer managed by cloud provider, in order to paralellize work or access +specific compute resources. Simulated sensors that require GPU access have +historically been difficult to use on a remote computer due to OpenGL's +X server requirement on linux systems. This issue can be resolved through +installation and proper configuration of X, but the steps can be complex and +error prone. + +An easier solution is through the use of [EGL](https://www.khronos.org/egl), which allows for the the creation of rendering surfaces without an X server. Ignition Gazebo has added support for EGL via the `--headless-rendering` command line option. Use of EGL is only available with OGRE2. + +Example usage: + +``` +ign gazebo -v 4 -s --headless-rendering sensors_demo.sdf +``` + +If you are using Ignition Gazebo as a library, then you can configure the +server to use headless rendering through the +`ServerConfig::SetHeadlessRendering(bool)` function. Make sure your SDF +world uses OGRE2. + +## AWS Example + +This example will guide you through the process of launching and configuring +an AWS GPU instance with Gazebo running headless. A GPU instance is +recommended when sensors that require a render engine are used. It is +possible to use a machine without a GPU, in which case OGRE will revert to +software rendering. You can read more about [OGRE's EGL implementation +here](https://www.ogre3d.org/2021/02/06/ogre-2-2-5-cerberus-released-and-egl-headless-support). + +1. Go to the [AWS EC2 service](https://console.aws.amazon.com/ec2) +2. Click the `Launch Instance` button in the upper right. +3. Select `Ubuntu Server` version 20.04 or greater from the AMI list. +4. Choose a GPU enabled instance type, such as `g3.4xlarge`. +5. Enable `Auto-assign Public IP` on the `Configure Instance Details` step. + This is not the best practice, but it simplifies this tutorial. +6. Add around 200GB storage to your instance on the `Add Storage` step. +7. Enable ssh source `Anywhere` on the `Configure Security Group` step. +8. Review and launch your instance. Make sure to setup a key pair in the + popup that appears after clicking `Launch`. + 1. You can configure other options as needed. Review the [AWS + documentation](https://docs.aws.amazon.com/AWSEC2/latest/UserGuide/EC2_GetStarted.html) for additional help. +9. Select the newly launched instance on the EC2 dashboard, and take note of + the `Public IPv4 address`. +10. SSH into your new machine instance. + ``` + ssh -i SSH_PEM_FILE_USED_DURING_LAUNCH ubuntu@EC_INSTANCE_PUBLIC_IP + ``` +12. Install Ubuntu drivers, which will install nvidia drivers: + ``` + sudo apt-get update + sudo apt install ubuntu-drivers-common + sudo ubuntu-drivers install + ``` +13. Add the `ubuntu` user to the `render` group, which is required to access + to the dri interfaces. + ``` + sudo usermod -a -G render ubuntu + ``` +14. Reboot the machine and log back in. + ``` + sudo reboot + ``` +11. [Install Gazebo](https://ignitionrobotics.org/docs/latest/install). +12. Run a Gazebo world that uses OGRE2 with camera sensors using headless rendering. This will enable EGL. + ``` + ign gazebo -v 4 -s -r --headless-rendering sensors_demo.sdf + ``` +13. Check that simulation is producing sensor data by ssh'ing into the EC2 + instance from a new terminal and echoing a sensor topic. + ``` + ssh -i SSH_PEM_FILE_USED_DURING_LAUNCH ubuntu@EC_INSTANCE_PUBLIC_IP + ign topic -et /thermal_camera + ```