diff --git a/documentation/datasets.rst b/documentation/datasets.rst index f06f810..8af0278 100644 --- a/documentation/datasets.rst +++ b/documentation/datasets.rst @@ -2,5 +2,15 @@ Datasets ##################### -In this section, we provide detailed guidance about how to setup various datasets in a step by step way. -We will keep updating these content and maintain some a troubleshooting section for each dataset. +Generally, the detailed setup procedure for each dataset can be found at its official document. +In this section, we still provide a simple guidance about how to setup each dataset in a step by step way, +saving the time for redirecting to new sites and read the comprehensive guidance. +The content of each subsection is a simplified version based on the official setup procedures of each dataset. +Thus if you encountered some problems with our simplified setup instructions, +please read related official documentation. +Also, we kindly ask you to report the encountered problem when following our procedures. +We will fix it as best as we can and record it in the troubleshooting section for each dataset. + + + + diff --git a/documentation/example.rst b/documentation/example.rst index 0a0594b..5c1e387 100644 --- a/documentation/example.rst +++ b/documentation/example.rst @@ -1,13 +1,13 @@ ####################### -Example +Waymo Example ####################### In this example, we will show you how to convert a small batch of `Waymo `_ scenarios into the internal Scenario Description. After that, the scenarios will be loaded to simulator for closed-loop simulation. First of all, please install `MetaDrive `_ and `ScenarioNet `_ following these steps :ref:`installation`. -**1. Setup Waymo toolkit** - +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. @@ -15,14 +15,17 @@ For Waymo data, please install the toolkit via:: pip install waymo-open-dataset-tf-2-11-0==1.5.0 + # Or install with scenarionet + pip install -e .[scenarionet] + .. note:: This package is only supported on Linux platform. For other datasets like nuPlan and nuScenes, you need to setup `nuplan-devkit `_ and `nuscenes-devkit `_ respectively. Guidance on how to setup these datasets and connect them with ScenarioNet can be found at :ref:`datasets`. -**2. Prepare Data** - +2. Prepare Data +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ Access the Waymo motion data at `Google Cloud `_. Download one tfrecord scenario file from ``waymo_open_dataset_motion_v_1_2_0/uncompressed/scenario/training_20s``. @@ -39,7 +42,8 @@ And place the downloaded tfrecord file to a folder. Let's call it ``exp_waymo`` Likewise, place all downloaded tfrecord files to the same folder. -**3. Convert to Scenario Description** +3. Build Database +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ Run the following command to extract scenarios in ``exp_waymo`` to ``exp_converted``:: @@ -82,7 +86,8 @@ To aggregate the scenarios produced by all workers, the ``exp_converted/dataset_ from `scenario_id` to the path of the target scenario file relative to ``exp_converted``. As a result, we can get all scenarios produced by 8 workers by loading the database `exp_converted`. -**4. Database Operations** +4. Database Operations +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ Several basic operations are available and allow us to split, merge, move, and check the databases. First of all, let's check how many scenarios are included in this database built from ``training_20s.tfrecord-00000-of-01000``:: @@ -119,7 +124,8 @@ It will show there are 61 overlapped scenarios. Congratulations! Now you are already familiar with some common operations. More operations and details is available at :ref:`operations`. -**5. Simulation** +5. Simulation +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ The database can be loaded to MetaDrive simulator for scenario replay or closed-loop simulation. First of all, let's replay scenarios in the ``exp_converted`` database:: diff --git a/documentation/index.rst b/documentation/index.rst index ce3bb79..1f38f1f 100644 --- a/documentation/index.rst +++ b/documentation/index.rst @@ -36,6 +36,7 @@ Please feel free to contact us if you have any suggestions or ideas! nuscenes.rst waymo.rst PG.rst + lyft.rst new_data.rst .. toctree:: diff --git a/documentation/install.rst b/documentation/install.rst index f5d79b3..a92e571 100644 --- a/documentation/install.rst +++ b/documentation/install.rst @@ -4,48 +4,92 @@ Installation ######################## + +1. Conda Environment +~~~~~~~~~~~~~~~~~~~~~~~~ + The ScenarioNet repo contains tools for converting scenarios and building database from various data sources. We recommend to create a new conda environment and install Python>=3.8,<=3.9:: conda create -n scenarionet python==3.9 conda activate scenarionet +2. Make a New Folder (Optional) +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ + +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. +For example, supposing you prefer working at ``/home/lee``, +it would be greate 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:: + + /home/lee/ + ├──mdsn + ├──metadrive + ├──scenarionet + ├──... + +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``. + +.. note:: + This step is optional. One can still ``git clone`` and ``pip install`` the following two packages at any places. + If any ``python -m scenarionet.[command]`` fails to run, please check if there is a folder called `metadrive` + or `scenarionet` contained in the current directory. If so, please switch to a new directory to avoid this issue. + +3. Install MetaDrive +~~~~~~~~~~~~~~~~~~~~~~~~~~~~ + The simulation part is maintained in `MetaDrive `_ repo, and let's install MetaDrive first. - -**1. Install MetaDrive** - The installation of MetaDrive on different platforms is straightforward and easy! -We recommend to install from Github in the following two ways:: +We recommend to install in the following ways:: - # Method 1 (Recommend, if you don't want to access the source code) - pip install git+https://github.com/metadriverse/metadrive.git - - # Method 2 + # Method 1 (Recommend, latest version, source code exposed) git clone git@github.com:metadriverse/metadrive.git cd metadrive pip install -e. - -A more stable version of MetaDrive can be installed from PyPI by:: - - # More stable version than installing from Github + # Method 2 (Stable version, source code hidden) pip install "metadrive-simulator>=0.4.1.1" To check whether MetaDrive is successfully installed, please run:: python -m metadrive.examples.profile_metadrive -.. note:: Please do not run the above command in the folder that has a sub-folder called :code:`./metadrive`. +.. note:: Please do not run the above command at a directory that has a sub-folder called :code:`./metadrive`. -**2. Install ScenarioNet** +4. Install ScenarioNet +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ -For ScenarioNet, we only provide Github installation. Likewise, there are two ways to install from Github:: +For ScenarioNet, we only provide Github installation:: - # Method 1 (Recommend, if you don't want to access the source code) - pip install git+https://github.com/metadriverse/scenarionet.git - - # Method 2 git clone git@github.com:metadriverse/scenarionet.git cd scenarionet + +Anyone of the following commands will automatically install basic requirements with additional requirements +for specific datasets:: + + # Install basic requirement only pip install -e . + # Install Waymo official toolkit + pip install -e .[waymo] + + # Install nuScenes development tookit + pip install -e .[nuscenes] + + # Install nuPlan development tookit + pip install -e .[nuplan] + + # Install all toolkit for all datasets + pip install -e .[all] + + +.. note:: + If you don't wanna 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. diff --git a/documentation/lyft.rst b/documentation/lyft.rst new file mode 100644 index 0000000..dadb69e --- /dev/null +++ b/documentation/lyft.rst @@ -0,0 +1,28 @@ +#################### +Lyft (In Upgrading) +#################### + +| Website: https://woven.toyota/en/prediction-dataset +| Download: https://woven-planet.github.io/l5kit/dataset.html +| Paper: https://proceedings.mlr.press/v155/houston21a/houston21a.pdf + +This dataset includes the logs of movement of cars, cyclists, pedestrians, +and other traffic agents encountered by our automated fleet. +These logs come from processing raw lidar, camera, and radar data through our team’s perception systems and are ideal +for training motion prediction models. +The dataset includes: + +- 1000+ hours of traffic agent movement +- 16k miles of data from 23 vehicles +- 15k semantic map annotations + +.. note:: + Currently, the old Lyft dataset can be read by ``nuscenes-toolkit`` and thus can share the nuScenes convertor. + The new Lyft data is now maintained by Woven Planet and we are working on support the ``L5Kit`` for allowing + using new Lyft data. + + + +Known Issues +############# + diff --git a/setup.py b/setup.py index 498994c..32a89c2 100644 --- a/setup.py +++ b/setup.py @@ -55,6 +55,10 @@ train_requirement = [ "tensorflow", "tensorflow_probability"] +waymo = ["waymo-open-dataset-tf-2-11-0", "tensorflow==2.11.0"] +nuplan = ["nuplan-devkit>=1.2.0"] +nuscenes = ["nuscenes-devkit>=1.1.10"] + setup( name="scenarionet", python_requires='>=3.8', # do version check with assert @@ -67,11 +71,13 @@ setup( install_requires=install_requires, extras_require={ "train": train_requirement, - "doc": doc + "doc": doc, + "waymo": waymo, + "nuplan": nuplan, + "nuscenes": nuscenes, }, include_package_data=True, license="Apache 2.0", long_description=long_description, long_description_content_type='text/markdown', ) -