From edbc4f3ed61231b038d6ed36aa9523bf2ec24b47 Mon Sep 17 00:00:00 2001 From: lola Date: Mon, 10 Feb 2025 13:42:37 -0800 Subject: [PATCH] Update documentation for MetaDrive optional dependency and SUMO map handling --- docs/simulators.rst | 18 ++++++++++++++---- docs/tutorials/dynamics.rst | 17 +++++++++++++---- 2 files changed, 27 insertions(+), 8 deletions(-) diff --git a/docs/simulators.rst b/docs/simulators.rst index 600323084..c3f3aeb05 100644 --- a/docs/simulators.rst +++ b/docs/simulators.rst @@ -16,10 +16,16 @@ See the individual entries for details on each interface's capabilities and how Currently Supported =================== -Built-in MetaDrive Simulator +MetaDrive (Optional) ---------------------------- -Scenic includes the `MetaDrive `_ simulator as a built-in tool, enabling users to describe dynamic simulations of vehicles, pedestrians, and traffic scenarios without the need for separate installation. +Scenic supports integration with the `MetaDrive `_ simulator as an optional dependency, +enabling users to describe dynamic simulations of vehicles, pedestrians, and traffic scenarios. +If your system supports it, you can install it with: + +.. code-block:: console + + pip install scenic[metadrive] Scenic supports both 2D and 3D rendering modes for MetaDrive simulations. 2D rendering is available on all systems, providing a top-down view. @@ -29,12 +35,16 @@ These issues are expected to be addressed in the next version of MetaDrive. Scenic uses OpenDRIVE maps, while MetaDrive relies on SUMO maps. Scenic provides corresponding SUMO maps for OpenDRIVE maps under the :file:`assets/maps/CARLA` directory. Additionally, you can convert your own OpenDRIVE maps to SUMO maps using the `netconvert `_ tool. +To avoid setting the SUMO map manually, name it the same as your OpenDRIVE file. +Otherwise, specify it explicitly with: + +.. code-block:: console + + --param sumo_map your_map.net.xml The simulator is compatible with scenarios written using Scenic's :ref:`driving_domain`. For more information, refer to the documentation of the `scenic.simulators.metadrive` module. -Examples using the MetaDrive interface can be found in the :file:`examples/metadrive directory`. - Built-in Newtonian Simulator ---------------------------- diff --git a/docs/tutorials/dynamics.rst b/docs/tutorials/dynamics.rst index ee5f5b0d4..b0b7e0b62 100644 --- a/docs/tutorials/dynamics.rst +++ b/docs/tutorials/dynamics.rst @@ -396,8 +396,18 @@ You can see all of the above syntax in action by running some of our examples of scenarios. We have examples written for the CARLA and LGSVL driving simulators, and those in :file:`examples/driving` in particular are designed to use Scenic's abstract :ref:`driving domain ` and so work in either of these simulators, as well -as Scenic's built-in MetaDrive and Newtonian physics simulator. While the Newtonian simulator is convenient -for testing and simple experiments, we recommend using MetaDrive for more realistic driving scenarios. You can find details on these simulators and how to install them on +as Scenic's built-in Newtonian physics simulator and MetaDrive simulator. While the Newtonian simulator is convenient +for testing and simple experiments, we recommend using MetaDrive for more realistic driving scenarios. + +MetaDrive support is **optional**. If your system supports MetaDrive, you can install it separately using: + +.. code-block:: console + + pip install scenic[metadrive] + +If MetaDrive is **not available**, we recommend using the Newtonian simulator instead. + +You can find details on these simulators and how to install them on our :ref:`simulators` page. Let's try running @@ -414,7 +424,7 @@ To run dynamic simulations, add the :option:`--simulate` option (:option:`-S` fo Since this scenario is not written for a particular simulator, you'll need to specify which one you want by using the :option:`--model` option (:option:`-m` for short) to select the corresponding Scenic :term:`world model`: for example, to use the Metadrive simulator we could add -``--model scenic.simulators.metadrive.model`` and include the ``--param sumo_map`` option with the corresponding SUMO map for the OpenDRIVE map you are using. +``--model scenic.simulators.metadrive.model``. It's also a good idea to put a time bound on the simulations, which we can do using the :option:`--time` option. .. code-block:: console @@ -423,7 +433,6 @@ It's also a good idea to put a time bound on the simulations, which we can do us --2d \ --simulate \ --model scenic.simulators.metadrive.model \ - --param sumo_map assets/maps/CARLA/Town05.net.xml \ --time 200 Running the scenario in CARLA is exactly the same, except we use the