huangfu/scenarionet
1
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity

Update document, add a colab example for reading data, upgrade numpy dependency (#34)

Browse Source 
* Minor update to docs

* WIP

* adjust numpy requirement

* prepare example for reading data from SN dataset

* prepare example for reading data from SN dataset

* clean
This commit is contained in:
PENG Zhenghao
2023-10-18 14:32:01 -07:00
committed by GitHub
parent 5fa5c1070f
commit af9fe0a2aa
11 changed files with 3847 additions and 47 deletions
Download Patch File Download Diff File Expand all files Collapse all files

10
documentation/README.md
View File

@@ -1,9 +1,11 @@
This folder contains files for the documentation: [https://scenarionet.readthedocs.io/](https://scenarionet.readthedocs.io/).
This folder contains files for the documentation:
[https://scenarionet.readthedocs.io/](https://scenarionet.readthedocs.io/).
To build documents locally, please run the following codes:
To build documents locally, please run the following script:
```
```bash
cd scenarionet
pip install -e .[doc]
cd scenarionet/documentation
cd documentation
make html
```

2
documentation/build.sh Normal file
View File

@@ -0,0 +1,2 @@
rm -rf build
make html

34
documentation/example.rst
View File

@@ -1,25 +1,45 @@
#####################
Example Colab
#####################
.. |colab_sim| image:: https://colab.research.google.com/assets/colab-badge.svg
:alt: Open In Colab
:target: https://colab.research.google.com/github/metadriverse/scenarionet/blob/main/tutorial/simulation.ipynb
**Colab example for running simulation with ScenarioNet:** |colab_sim|
.. |colab_read| image:: https://colab.research.google.com/assets/colab-badge.svg
:alt: Open In Colab
:target: https://colab.research.google.com/github/metadriverse/scenarionet/blob/main/tutorial/read_established_scenarionet_dataset.ipynb
**Colab example for reading established ScenarioNet dataset:** |colab_read|
#######################
Waymo Example
#######################
In this example, we will show you how to convert a small batch of `Waymo <https://waymo.com/intl/en_us/open/>`_ scenarios into the internal Scenario Description.
After that, the scenarios will be loaded to simulator for closed-loop simulation.
In this example, we will show you how to convert a small batch of `Waymo <https://waymo.com/intl/en_us/open/>`_ scenarios into the internal **Scenario Description**.
After that, the scenarios will be loaded to MetaDrive simulator for closed-loop simulation.
First of all, please install `MetaDrive <https://github.com/metadriverse/metadrive>`_ and `ScenarioNet <https://github.com/metadriverse/scenarionet>`_ following these steps :ref:`installation`.
1. Setup Waymo toolkit
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
For any dataset, this step is necessary after installing ScenarioNet,
as we need to use the official toolkits of the data provider to parse the original scenario description and convert to our internal scenario description.
For Waymo data, please install the toolkit via::
For any dataset, the first step after installing ScenarioNet is to install the corresponding official toolkit as we need to use it to parse the original data and convert to our internal scenario description. For Waymo data, please install the toolkit via::
pip install waymo-open-dataset-tf-2-11-0
pip install tensorflow==2.11.0
.. note::
This package is only supported on Linux platform.
`waymo-open-dataset` may degrade numpy, causing conflicts with cv2.
A workaround is ``pip install numpy==1.24.2``
`waymo-open-dataset` may degrade numpy, causing conflicts with `cv2` (`opencv-python`).
A workaround is to ``pip install numpy==1.24.2``
For other datasets like nuPlan and nuScenes, you need to setup `nuplan-devkit <https://github.com/motional/nuplan-devkit>`_ and `nuscenes-devkit <https://github.com/nutonomy/nuscenes-devkit>`_ respectively.
Guidance on how to setup these datasets and connect them with ScenarioNet can be found at :ref:`datasets`.

32
documentation/index.rst
View File

@@ -3,6 +3,24 @@ ScenarioNet Documentation
##########################
.. |colab_sim| image:: https://colab.research.google.com/assets/colab-badge.svg
:alt: Open In Colab
:target: https://colab.research.google.com/github/metadriverse/scenarionet/blob/main/tutorial/simulation.ipynb
**Colab example for running simulation with ScenarioNet:** |colab_sim|
.. |colab_read| image:: https://colab.research.google.com/assets/colab-badge.svg
:alt: Open In Colab
:target: https://colab.research.google.com/github/metadriverse/scenarionet/blob/main/tutorial/read_established_scenarionet_dataset.ipynb
**Colab example for reading established ScenarioNet dataset:** |colab_read|
Welcome to the ScenarioNet documentation!
ScenarioNet is an open-sourced platform for large-scale traffic scenario modeling and simulation with the following features:
@@ -14,7 +32,7 @@ It can thus support several applications including large-scale scenario generati
This documentation brings you the information on installation, usages and more of ScenarioNet!
You can also visit the `GitHub repo <https://github.com/metadriverse/scenarionet>`_ and `Webpage <https://metadriverse.github.io/scenarionet/>`_ for code and videos.
Please feel free to contact us if you have any suggestions or ideas!
Please feel free to contact us if you have any suggestion or idea!
.. toctree::
@@ -23,12 +41,12 @@ Please feel free to contact us if you have any suggestions or ideas!
install.rst
example.rst
operations.rst
.. modify the toctree in datasets.rst together
.. toctree::
:maxdepth: 1
:caption: Supported Dataset
:caption: Setup Datasets
datasets.rst
nuplan.rst
@@ -38,6 +56,14 @@ Please feel free to contact us if you have any suggestions or ideas!
lyft.rst
new_data.rst
.. toctree::
:maxdepth: 2
:caption: Operations
operations.rst
.. toctree::
:maxdepth: 2
:caption: System Design

24
documentation/install.rst
View File

@@ -19,9 +19,9 @@ We recommend to create a new conda environment and install Python>=3.8,<=3.9::
In addition, the operations in ScenarioNet are executed as Python module ``python -m``, and thus we have to make sure
the working directory contains NO folders named ``metadrive`` or ``scenarionet``.
Therefore, we strongly recommend creating a new folder under your routine working directory.
Therefore, we strongly recommend creating a new folder under your daily working directory.
For example, supposing you prefer working at ``/home/lee``,
it would be greate to have a new folder ``mdsn`` created under this path.
it would be great to have a new folder ``mdsn`` created under this path.
And the ``git clone`` and package installation should happen in this new directory.
As a result, the directory tree should look like this::
@@ -32,7 +32,7 @@ As a result, the directory tree should look like this::
├──...
In this way, you can freely run the dataset operations at any places other than ``/home/lee/mdsn``.
Now, let's move to this new directory for further installation with ``cd mdsn``.
Now, let's move current workding directory to this new directory for further installation with ``cd mdsn``.
.. note::
This step is optional. One can still ``git clone`` and ``pip install`` the following two packages at any places.
@@ -42,15 +42,21 @@ Now, let's move to this new directory for further installation with ``cd mdsn``.
3. Install MetaDrive
~~~~~~~~~~~~~~~~~~~~~~~~~~~~
The simulation part is maintained in `MetaDrive <https://github.com/metadriverse/metadrive>`_ repo, and let's install MetaDrive first.
The simulation part is maintained in `MetaDrive <https://github.com/metadriverse/metadrive>`_ repo,
and let's install MetaDrive first.
The installation of MetaDrive on different platforms is straightforward and easy!
We recommend to install in the following ways::
# Method 1 (Recommend, latest version, source code exposed)
# Method 1A (Recommended, latest version, source code exposed)
git clone git@github.com:metadriverse/metadrive.git
cd metadrive
pip install -e.
# Method 1B (Recommended, latest version, source code exposed)
git clone https://github.com/metadriverse/metadrive.git
cd metadrive
pip install -e.
# Method 2 (Stable version, source code hidden)
pip install "metadrive-simulator>=0.4.1.1"
@@ -58,20 +64,18 @@ To check whether MetaDrive is successfully installed, please run::
python -m metadrive.examples.profile_metadrive
.. note:: Please do not run the above command at a directory that has a sub-folder called :code:`./metadrive`.
.. note:: Please do not run the above command at a directory that has a subfolder called :code:`./metadrive`.
4. Install ScenarioNet
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
For ScenarioNet, we only provide Github installation::
For ScenarioNet, we only provide the Github installation::
git clone git@github.com:metadriverse/scenarionet.git
cd scenarionet
pip install -e .
.. note::
If you don't wanna access the source code, you can install these two packages with
If you don't want to access the source code, you can install these two packages with
``pip install git+https://github.com/metadriverse/scenarionet.git``
and ``pip install git+https://github.com/metadriverse/metadrive.git``.
Though it is more straightforward, one has to install additional requirements, like development
toolkits, manually.

4
documentation/operations.rst
View File

@@ -1,6 +1,6 @@
###########
######################
Operations
###########
######################
How to run
~~~~~~~~~~