Gzweb
Web client for Gazebo

Overview

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.

Installation

Gzweb is installed on the server-side. 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.

Gzweb is a graphical interface which communicates with gzserver. To use gzserver, install either Gazebo or DRCSim.

  1. Make sure your system has the right NodeJS version (0.10.x). While this is not the latest version, it is the version that ships with Ubuntu Trusty.

    Note: For Ubuntu Precise or older distributions, the NodeJS version that comes with it may not work with gzweb. In that case, set up your system to grab and install the latest NodeJS debs:

    dpkg -l nodejs
    

    If the above command returns a version < 0.10 or couldn't find the nodejs package use:

    curl -sL https://deb.nodesource.com/setup | sudo bash -
    

    We will install the nodejs package in the following step.

  2. Next, install the dependencies from a terminal:

    sudo apt-get install libjansson-dev nodejs npm libboost-dev imagemagick libtinyxml-dev mercurial cmake build-essential
    
  1. Clone the repository into a directory in your home folder:

    cd ~; hg clone https://bitbucket.org/osrf/gzweb
    
    1. Enter the Gzweb repository and switch to a release branch:
    cd ~/gzweb
    # Note for Gazebo versions < 7, please use the gzweb_1.2.0 branch
    hg up gzweb_1.3.0
    
    1. The first time you build, you'll need to gather all the Gazebo models in the right directory and prepare them for the web. Before running the deploy script, you'll need to source the Gazebo setup.sh file:

    If you installed gazebo via deb packages:

    source /usr/share/gazebo/setup.sh
    

    If you did a source install then:

    source <YOUR_GAZEBO_PATH>/share/gazebo/setup.sh
    
    1. If you have drcsim then source:
    source /usr/share/drcsim/setup.sh
    
    1. Run the deploy script, this downloads models from the web and may take a couple of minutes.
    ./deploy.sh -m
    

    Note: the -m flag tells the deploy script to grab models from the model database and any other models in your Gazebo paths. For all subsequent builds, the -m flag will not be needed. The process will also try to generate thumbnails, see note on thumbnails below.

Options

  • To skip downloading models from the model database and grab only local models in your Gazebo model path, do:

    ./deploy.sh -m local
    
  • To generate thumbnails manually, run the script with the -t flag, i.e.:

    ./deploy.sh -t
    

    Note: This spins up a gzserver with 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_URI in 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 ran ./deploy.sh -m, run just:

    ./deploy.sh -c
    

    Or you can run both flags at the same time to generate coarse versions as you create the database:

    ./deploy.sh -m -c
    
  • You also have the option to pick specific models and how much percent to coarsen, running:

    ./coarse_meshes.sh [percent] [path]
    

    Here, [percent] is the edges ratio with respect to the original mesh (0 to 100), and [path] is the path of the models. For example:

    ./coarse_meshes.sh 20 http/client/assets/bowl/
    
  1. Start gazebo or gzserver first:

    gzserver
    
  2. On another terminal, from your gzweb directory, start the http and websocket servers:

    ./start_gzweb.sh
    
  3. Open a browser (Chrome works well) that has WebGL and websocket support and point it to the ip address and port where the http server is started, by default it's on port 8080, e.g.

    http://localhost:8080
    
  4. To stop Gzweb server, from your gzweb directory, run:

    ./stop_gzweb.sh
    
  • 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 websocket@1.0.8 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 ./deploy.sh, it is missing a file in gz3d/build:

    A: You will need to install Grunt and run it appropriately, as described in the development section. * Q: When running ./deploy.sh, 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 ./deploy.sh, 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
    

Development

The source code for Gzweb is located at the osrf/gzweb Bitbucket repository. The source code is composed of two main parts: Javascript code inside gzweb/gz3d, responsible for visualization, and C++ code inside gzweb/gzbridge, responsible for communicating with gzserver.

Gzweb makes use of the JQuery mobile user interface system for GUI and the three.js library for 3D rendering.

Grunt setup

Grunt is used for running tasks including code checking and minification:

  • Minification: Compresses all *.js code located at gzweb/gz3d/src into gz3d.js and gz3d.min.js files that can be included into other projects.
  • Code check: uses JSHint for detecting potential errors in Javascript code.

To install required Grunt packages:

npm install -g grunt-cli
cd gz3d/utils && npm install

Work Flow:

  1. Make changes to Javascript source code at gzweb/gz3d/src. You may also edit files at gzweb/gz3d/client/js/include, but keep in mind most of these were taken from somewhere else.

  2. Code check and minify Javascript files and copy them to the right directory, running:

    ./updateGZ3D.sh
    
  3. Verify your changes: start gzweb with ./start_gzweb.sh and open browser to localhost:8080, or just refresh page. If you don't see anything changed after modifying the Javascript code, you might need to clear your browser cache to see the changes.

Gzweb communicates with gzserver by publishing and subscribing to Gazebo topics.

Work Flow:

  1. Make changes to C++ source code in gzweb/gzbridge

  2. You can compile by running:

    ./deploy.sh
    
  3. Verify your changes: start gzweb with ./start_gzweb.sh and open browser to localhost:8080, or just refresh page.

Bug reports and feature requests

On Gzweb's issue tracker, you're able to report bugs and ask for new features. Simply create an issue and categorize it accordingly.

Pull requests

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.

User guide
Learn how to use the interface. Click on an item to see its explanation.

Real Time: 00 00:00:00

Sim Time: 00 00:00:00

Click on an item on the menu to see its explanation.

Desktop context menu:
Right-click an entity to see its context menu.

Mobile context menu:
Long-press an entity to see its radial menu.

Click on an item on the menu to see its explanation.

Help

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.

  1. Questions and answers: A community-supported forum for posting questions and answers.
  2. Issue tracker: A resource to submit and follow feature requests, bugs, and enhancements.
  3. Mailing list: A mailing list used for general discussion and questions about Gazebo and simulation.