Webviz ![CircleCI](https://camo.githubusercontent.com/9abce416dac854203d571ba164f77b3bf9bc139730ed811a8aa230ad1d9da101/68747470733a2f2f636972636c6563692e636f6d2f67682f6372756973652d6175746f6d6174696f6e2f77656276697a2e7376673f7374796c653d737667)
Drag and drop your own bag files into Webviz to explore your robotics data, or connect to a live robot or simulation using the rosbridge_server.
Webviz is a web-based application for playback and visualization of ROS bag files. This repository also contains some libraries that can be used independently to build web-based visualization tools.
- webviz-core (homepage, tool, github): A tool to inspect ROS bags.
- regl-worldview (homepage, npm, github): React library for rendering 2D and 3D scenes using regl.
- @cruise-automation/hooks (npm, github): A list of resusable React hooks.
- @cruise-automation/button (npm, github): React button component that supports animated progress for destructive actions, "pulse" animation, and Bulma classes.
- @cruise-automation/tooltip (npm, github): React component that uses popper.js to add rich, customizable tooltips to DOM elements.
Please see the individual package READMEs for details on how to install and use them.
Slack
We have a Slack workspace to make it easier to ask questions and chat with other people who use Webviz. Join using the latest link posted here.
Foxglove
Foxglove Studio is a fork of Webviz that was started by former Cruise employees. The tools have the same purpose (visualizing ROS data), but Cruise does not currently offer commercial support for Webviz, and community support can be ad-hoc. Webviz also has a slightly different feature set than Foxglove. Check out Foxglove if Webviz does not currently meet your needs.
How to use Webviz
We have in-app help resources. Go to the application and click the "?" icon in the top right. Each individual panel also has a "?" icon in its top right.
Running the static Webviz application
We recommend using the hosted version of Webviz, which can connect to your rosbridge_server or stream in bag data from your S3/GCS bucket. This way you'll always use the latest version of Webviz.
However, sometimes the hosted version is inconvenient, when streaming data from robots on the field where there is poor internet connectivity. For this it is useful to use a static build of webviz.
Docker
The easiest way to use the static build, is to use our Docker image, which is automatically built on every commit to the master
branch.
docker run -p 8080:8080 cruise/webviz
Building manually
npm run bootstrap # install dependencies
npm run build-static-webviz # generate static build in __static_webviz__
npm run serve-static-webviz # serve static build on localhost:8080
Recording videos
Prerequisites:
npm run bootstrap
to install dependencies- Install FFmpeg:
apt-get install ffmpeg
orbrew install ffmpeg
or so. - Download the ROS bag to your local machine, and also save the layout to a
.json
file. - Make sure that the bag+layout that you want to record actually work when you manually play it in Webviz.
Now run the packages/webviz-core/script/record-local-bag-video.js
script, usually something like this:
packages/webviz-core/script/record-local-bag-video.js --bag ~/my-bag.bag --layout ~/my-layout.json --mp3 ~/loud-dance-music.mp3 --out ~/my-video.mp4 --speed 1.5
By default it will use webviz.io/app for the recording, but if you want to use a local instance of Webviz you can use the --url
parameter. For full options run packages/webviz-core/script/record-local-bag-video.js --help
.
Measuring performance
Similarly to recording videos, we have a script to measure the performance of a given layout+bag combination. This is useful for determining if a new feature makes things slower or faster. Run packages/webviz-core/script/measure-performance.js --help
to learn more.
Developing
To install dependencies, first run npm run bootstrap
. This command will populate the repos root /node_modules
and underyling packages /node_modules
. From there, you have a few options depending on where you'd like to make changes.
Webviz Core
npm run webviz-dev
Docs
npm run docs-dev
Storybook
npm run storybook
Useful for regl-worldview
changes.
Full list of scripts
npm run webviz-dev
to run a webviz-only server that you can develop Webviz on.npm run bootstrap
in the root directory to install dependencies.npm run build
to run a single build ornpm run watch
to watch and build.npm run docs-dev
to run the docs app (e.g. go to http://localhost:8080/app to open Webviz). Requiresbuild
to be run first.npm run docs-deploy
to deploy the docs to https://webviz.io/.npm run storybook
to run storybook. Requiresbuild
to be run first.npm run screenshot-local
ornpm run screenshot-local-debug
to generate screenshots from stories.npm run lint
to run the linters (andnpm run lint:fix
to automatically fix issues).npm run flow
to run Flow.npm run flow-typed-rebuild
to update the flow-typed definitions (any time when changing packages).npm test
to run tests.npm run build-static-webviz
to make a special build of just the Webviz application in the__static_webviz__
directory.npm run serve-static-webviz
to host the contents of the__static_webviz__
directory onlocalhost:8080
.
If you have the right permissions, you can publish:
npm run publish
to publish npm packages.npm run docs-deploy
to deploy that statically hosted website (this is also done automatically in CI on the master branch).
If you run into any issues, file an issue on Github or ask us on Slack (see above).
Contributing
PRs, bug reports, and feature requests are welcome! Please observe CONTRIBUTING.md and CODE_OF_CONDUCT.md when making a contribution.
Note that while it's possible to fork Webviz to make your own custom version, we'd encourage you to use webviz.io/app and propose generic solutions that everyone would benefit from. Cruise also still has its own fork of Webviz, but long term we'd like to move away from that. For examples of generic features, see the Node Playground panel, using generic RViz markers in the 3d panel, streaming in bags from any cloud service, loading layouts hosted on arbitrary URLs, and so on. We'd love your creative ideas for making Webviz widely useful!