Gzweb is a WebGL client for Gazebo. Like gzclient, it's a front-end graphical interface to gzserver and provides visualization of the simulation. However, Gzweb is a thin client in comparison, and lets you interact with the simulation from the comfort of a web browser. This means cross-platform support, minimal client-side installation, and support for mobile devices.
GzWeb is usually installed on an Ubuntu server. Once the server is set up and running, clients can interact with the simulation simply by accessing the server's URL on a web browser.
The main dependencies for GzWeb are the Gazebo development libraries, version 9 or greater, and NodeJS version 6 or greater.
Take a look at these tutorials to choose the Gazebo installation that best fits your case. The simplest approach would be to install Gazebo 9 as follows:
sudo apt install gazebo9 libgazebo9-dev
Run the following to install dependencies:
sudo apt install libjansson-dev libboost-dev imagemagick libtinyxml-dev mercurial cmake build-essential
npm using node's version manager
# install nvm curl -o- https://raw.githubusercontent.com/nvm-sh/nvm/v0.35.3/install.sh | bash # source .bashrc so we can use the nvm cmd source ~/.bashrc # install node. Supported versions are 8 to 11. nvm install 8
You may run into conflict with the libssl version needed by Gazebo and nodejs when trying to install using
apton Ubuntu. So the recommended way of installation is to use
Clone the repository into a directory in your home folder for example:
cd ~; git clone https://github.com/osrf/gzweb
Enter the GzWeb repository and switch to the latest release branch:
cd ~/gzweb git checkout gzweb_1.4.1
The first time you build, you'll need to gather all the Gazebo models which you want to simulate in the right directory ('http/client/assets') and prepare them for the web.
Before running the deploy script, it's important to source the Gazebo
If you installed gazebo via deb packages:
If you did a source install then:
Run the deploy script, this downloads models from the web and may take a couple of minutes, see more options below.
npm run deploy --- -m
-mflag tells the deploy script to grab all the models from the model database and any other models in your
GAZEBO_MODEL_PATH. For all subsequent builds, the
-mflag will not be needed.
To skip downloading models from the model database and grab only local models in your Gazebo model path, do:
npm run deploy --- -m local
To generate thumbnails for all the models , run the script with the
-t flag, i.e.:
npm run deploy --- -t
Note: This spins up a
gzserverwith a camera for capturing screenshots of models. So make sure there is rendering support and no background gzerver process running (or set a different
GAZEBO_MASTER_URIin the terminal).
If you'll use GzWeb on mobile devices, you can create coarse versions of all
models, which are lighter to load (50% of original quality). If generated,
these meshes will automatically be used on mobile devices. If you've already
npm run deploy --- -m, run just:
npm run deploy --- -c
Or you can run both flags at the same time to generate coarse versions as you create the database:
npm run deploy --- -m -c
You also have the option to pick specific models and how much percent to coarsen, running:
./coarse_meshes.sh [percent] [path]
[percent] is the edges ratio with respect to the original mesh
(0 to 100), and
[path] is the path of a model. For example:
./coarse_meshes.sh 20 http/client/assets/bowl/
Running GzWeb involves the following pieces:
gzserver running the headless Gazebo simulation (runs by default on
GzWeb's NodeJS server which communicates with
A Websocket server which forwards simulation updates coming from
to the browser
A browser client which connects to the HTTP and websocket servers
Start them as follows:
On the server machine, start
gzserver first, it's recommended
to run in verbose mode so you see debug messages:
Tip: see the port where the Gazebo master is communicating, such as
[Msg] Connected to gazebo master @ http://127.0.0.1:11345
On another terminal, from your GzWeb directory, run the following command to start both the HTTP and Websocket servers:
Tip: You can use the
-poption to choose an arbitrary port, for example:
npm start -p 1234. By default, it serves on port 8080.
Open a browser that has WebGL and websocket support (i.e. most modern browsers) and point it to the IP address and port where the HTTP server is started, for example:
gzserver or the GzWeb servers, just press
Ctrl+C in their terminals.
Q: When installing node package modules, I see errors along the lines of:
npm ERR! Error: failed to fetch from registry: node-gyp
A: Try setting the npm registry first then install the modules again.
npm config set registry http://registry.npmjs.org/
Q: When installing websocket, I see errors along the lines of:
sh: 1: node: not found npm ERR! error installing firstname.lastname@example.org npm WARN This failure might be due to the use of legacy binary "node"
Or along the lines of:
/usr/bin/env: node: No such file or directory There are node-gyp build errors, exiting.
A: In Debian systems, the binary file "node" has been renamed to "nodejs" to avoid a name conflict. Try adding a symlink to the correct name:
sudo ln -s /usr/bin/nodejs /usr/bin/node
You may also find that your repository is too old and you should just install recent versions of node and npm directly.
* Q: When running
npm run deploy ---, I see errors along the lines of:
gyp ERR! configure error
A: There might be a conflict between the gyp version installed and the gyp version in node-gyp. Try removing gyp:
sudo apt-get remove gyp
Q: When running
npm run deploy ---, I have problems finding GTS, like this:
~/gzweb/tools/gzcoarse.cc:18:17: fatal error: gts.h : no such file or directory, #include
A: It seems that your Gazebo installation didn't install GTS headers. Try installing them manually:
sudo apt-get install libgts-dev
The source code for GzWeb is located at the osrf/gzweb GitHub repository.
responsible for visualization, and C++ code inside
responsible for communicating with
GzWeb makes use of the JQuery mobile user interface system for GUI and the three.js library for 3D rendering.
Grunt is used for running tasks including code checking and minification:
gz3d.src.js: All files under
gz3d.gui.js: All files under
gz3d/srcand all the necessary dependencies
gz3d.js: The same as
gz3d.gui.jsbut without GUI-specific files and dependencies
Minification: Compresses the 3 files above into
.min.js versions which are more
efficient to use in production.
gzweb/gz3d/src. You may also
edit files at
gzweb/gz3d/client/js/include, but keep in mind that these
files are copied from external projects.
The following command runs Grunt to perform code check and contatenate files:
npm run update
Verify your changes:
localhost:8080, or just refresh page.
Generate updated documentation:
npm run docs
GzWeb communicates with
gzserver by publishing and subscribing to Gazebo topics.
Make changes to C++ source code in
You can compile by running:
npm run deploy
Verify your changes:
localhost:8080, or just refresh page.
On GzWeb's issue tracker, you're able to report bugs and ask for new features. Simply create an issue and categorize it accordingly.
If you've fixed a bug or added a feature and would like your changes to be integrated into GzWeb, you can make a pull request to the repository, and the changes will be reviewed and merged.
We strive to provide responsive and high-quality support for our software. Please refer to the following list of our support resources to find the right avenue for help and information.