diff --git a/Docs/img/plugins_carlaviz_data.jpg b/Docs/img/plugins_carlaviz_data.jpg new file mode 100644 index 000000000..c6f32c290 Binary files /dev/null and b/Docs/img/plugins_carlaviz_data.jpg differ diff --git a/Docs/img/plugins_carlaviz_data.jpg~ b/Docs/img/plugins_carlaviz_data.jpg~ new file mode 100644 index 000000000..289bd5848 Binary files /dev/null and b/Docs/img/plugins_carlaviz_data.jpg~ differ diff --git a/Docs/img/plugins_carlaviz_demo.jpg b/Docs/img/plugins_carlaviz_demo.jpg new file mode 100644 index 000000000..55d19f56d Binary files /dev/null and b/Docs/img/plugins_carlaviz_demo.jpg differ diff --git a/Docs/img/plugins_carlaviz_empty.jpg b/Docs/img/plugins_carlaviz_empty.jpg new file mode 100644 index 000000000..796b8fc82 Binary files /dev/null and b/Docs/img/plugins_carlaviz_empty.jpg differ diff --git a/Docs/img/plugins_carlaviz_full.jpg b/Docs/img/plugins_carlaviz_full.jpg new file mode 100644 index 000000000..f018b532e Binary files /dev/null and b/Docs/img/plugins_carlaviz_full.jpg differ diff --git a/Docs/img/plugins_carlaviz_run.jpg b/Docs/img/plugins_carlaviz_run.jpg new file mode 100644 index 000000000..a6b3ad1d6 Binary files /dev/null and b/Docs/img/plugins_carlaviz_run.jpg differ diff --git a/Docs/index.md b/Docs/index.md index f8bb8b983..8aa72b624 100644 --- a/Docs/index.md +++ b/Docs/index.md @@ -92,6 +92,11 @@ CARLA forum [__Sensors reference__](ref_sensors.md) — Everything about sensors and the data they retrieve. +## Plugins +

+ [__carlaviz — web visualizer__](plugins_carlaviz.md) + — Plugin that listens the simulation and shows the scene and some simulation data in a web browser. + ## ROS bridge

[__ROS bridge installation__](ros_installation.md) diff --git a/Docs/plugins_carlaviz.md b/Docs/plugins_carlaviz.md new file mode 100644 index 000000000..6f7772c38 --- /dev/null +++ b/Docs/plugins_carlaviz.md @@ -0,0 +1,150 @@ +# carlaviz + +The carlaviz plugin is used to visualize the simulation in a web browser. A windows with some basic representation of the scene is created. Actors are updated on-the-fly, sensor data can be retrieved, and additional text, lines and polylines can be drawn in the scene. + +* [__General information__](#general-information) + * [Support](#support) +* [__Get carlaviz__](#get-carlaviz) + * [Prerequisites](#prerequisites) + * [Download the plugin](#download-the-plugin) +* [__Utilities__](#utilities) + +--- +## General information + +* __Contributor__ — Minjun Xu, also known as [wx9698](https://github.com/wx9698). +* __License__ — [MIT](https://en.wikipedia.org/wiki/MIT_License). + +### Support + +* __Linux__ — CARLA 0.9.6, 0.9.7, 0.9.8, 0.9.9. +* __Windows__ — CARLA 0.9.9. +* __Build from source__ — Latest updates. + +--- +## Get carlaviz + +### Prerequisites + +* __Docker__ — Visit the docs and [install Docker](https://docs.docker.com/get-docker/). +* __Operative system__ — Any OS able to run CARLA should work. +* __Websocket-client__ — ```pip3 install websocket_client```. Install [pip](https://pip.pypa.io/en/stable/installing/) if it is not already in the system. + +### Download the plugin + +Open a terminal and pull the Docker image of carlaviz, based on the CARLA version to be run. + +```bash +# Pull only the image that matches the CARLA package being used +docker pull mjxu96/carlaviz:0.9.6 +docker pull mjxu96/carlaviz:0.9.7 +docker pull mjxu96/carlaviz:0.9.8 +docker pull mjxu96/carlaviz:0.9.9 + +# Pull this image if working on a CARLA build from source +docker pull carlasim/carlaviz:latest +``` + +!!! Important + Currently in Windows there is only support for 0.9.9. + +CARLA up to 0.9.9 (included) is set to be single-stream. For later versions, multi-streaming for sensors is implemented. + +* __In single-stream__, a sensor can only be heard by one client. When a sensor is already being heard by another client, for example when running `manual_control.py`, carlaviz is forced to duplicate the sensor in order to retrieve the data, and performance may suffer. + +* __In multi-stream__, a sensor can be heard by multiple clients. carlaviz has no need to duplicate these and performance does not suffer. + +!!! Note + Alternatively on Linux, users can build carlaviz following the instructions [here](https://github.com/carla-simulator/carlaviz/blob/master/docs/build.md), but using a Docker image will make things much easier. + +--- +## Run carlaviz + +__1. Run CARLA.__ + +* __a) In a CARLA package__ — Go to the CARLA folder and start the simulation with `CarlaUE4.exe` (Windows) or `./CarlaUE4.sh` (Linux). + +* __b) In a build from source__ — Go to the CARLA folder, run the UE editor with `make launch` and press `Play`. + +__2. Run carlaviz.__ In another terminal run the following command according to the Docker image that has been downloaded. + +Change `` for the name of the image previously downloaded, e.g. `carlasim/carlaviz:latest` or `mjxu96/carlaviz:0.9.9`. + +```sh +docker run -it --network="host" -e CARLAVIZ_HOST_IP=localhost -e CARLA_SERVER_IP=localhost -e CARLA_SERVER_PORT=2000 +``` + +If the everything has been properly set, carlaviz will show a successful message similar to the following. + +![carlaviz_run](img/plugins_carlaviz_run.jpg) + +!!! Warning + Remember to edit the previous command to match the Docker image being used. + + +__3. Open the localhost__ Open your web browser and go to `http://127.0.0.1:8080/`. carlaviz runs by default in port `8080`. The output should be similar to the following. + +![carlaviz_empty](img/plugins_carlaviz_empty.jpg) + +--- +## Utilities + +Once the plugin is operative, it can be used to visualize the simulation, the actors that live in it, and the data the sensors retrieve. The plugin shows a visualization window on the right, were the scene is updated in real-tme, and a sidebar on the left with a list of items to be shown. Some of these items will appear in the visualization window, others (mainly sensor and game data) appear just above the items list. +Here is a list of options available for visualization. Additional elements may show, such as + +* __View Mode__ — Change the point of view in the visualization window. + * `Top Down` — Aerial point of view. + * `Perspective` — Free point of view. + * `Driver` — First person point of view. + +* __/vehicle__ — Show properties of the ego vehicle. Includes a speedometer and accelerometer in the visualization window, and the data retrieved by IMU, GNSS and collision detector sensors. + * `/velocity` — Velocity of the ego vehicle. + * `/acceleration` — Acceleration of the ego vehicle. +* __/drawing__ — Show additional elements in the visualization window drawn with [CarlaPainter](https://github.com/wx9698/carlaviz/blob/master/examples/carla_painter.py). + * `/texts` — Text elements. + * `/points` — Point elements. + * `/polylines` — Polyline elements. +* __/objects__ — Show actors in the visualization window. + * `/walkers` — Update walkers. + * `/vehicles` — Update vehicles. +* __/game__ — Show game data. + * `/time` — Current simulation time and frame. +* __/lidar__ — LIDAR sensor data. + * `/points` — Cloud of points detected by a LIDAR sensor. +* __/radar__ — LIDAR sensor data. + * `/points` — Cloud of points detected by a RADAR sensor. +* __/traffic__ — Landmark data. + * `/traffic_light` — Show the map's traffic lights in the visualization window. + * `/stop_sign` — Show the map's stop signs in the visualization window. + + +Try to spawn some actors. These will be automatically updated in the visualization window. +```sh +cd PythonAPI/examples +python3 spawn_npc.py -n 10 -w 5 +``` + +![carlaviz_full](img/plugins_carlaviz_full.jpg) + +Spawn an ego vehicle with manual control and move around, to see how the plugin updates sensor data. +```sh +cd PythonAPI/examples +python3 manual_control.py +``` + +![carlaviz_data](img/plugins_carlaviz_data.jpg) + +The contributor ([wx9698](https://github.com/wx9698)), created an additional class, [CarlaPainter](https://github.com/wx9698/carlaviz/blob/master/examples/carla_painter.py), that allows the user to draw elements to be shown in the visualization window. These include text, points and polylines. Follow [this example](https://github.com/carla-simulator/carlaviz/blob/master/examples/example.py) to spawn an ego vehicle with a LIDAR, and draw the LIDAR data, the trajectory and velocity of the vehicle. + +![carlaviz_demo](img/plugins_carlaviz_demo.jpg) + +--- + +That is all there is to know about the carlaviz plugin. If there are any doubts, feel free to post these in the forum. + +

+

+ +CARLA forum +

+
diff --git a/mkdocs.yml b/mkdocs.yml index 10321875c..2367f7d8a 100644 --- a/mkdocs.yml +++ b/mkdocs.yml @@ -39,6 +39,8 @@ nav: - 'C++ reference' : 'ref_cpp.md' - 'Recorder binary file format': 'ref_recorder_binary_file_format.md' - "Sensors reference": 'ref_sensors.md' +- Plugins: + - 'carlaviz — web visualizer': 'plugins_carlaviz.md' - ROS bridge: - 'ROS bridge installation': 'ros_installation.md' - 'CARLA messages reference': 'ros_msgs.md'