Revert "documentation/readmes (#131)" (#140)

This reverts commit fcae30c.
argoverse · Mar 28, 2023 · 6149f8a · 6149f8a
1 parent fcae30c
commit 6149f8a
Show file tree

Hide file tree

Showing 31 changed files with 379 additions and 1,092 deletions.
diff --git a/.github/workflows/mdbook.yml b/.github/workflows/mdbook.yml
diff --git a/.gitignore b/.gitignore
@@ -156,4 +156,4 @@ experiments
 *.pt
 *.mp4
 
-guide/book
+guide/book
diff --git a/DOWNLOAD.md b/DOWNLOAD.md
@@ -0,0 +1,38 @@
+# Downloading the Argoverse 2 Datasets
+Our datasets are available for download from [AWS S3](https://aws.amazon.com/s3/). For the best experience, we highly recommend using the open-source [s5cmd](https://github.com/peak/s5cmd) tool to transfer the data to your local filesystem (additional info available [here](https://aws.amazon.com/blogs/opensource/parallelizing-s3-workloads-s5cmd/)). Please note that an AWS account is not required to download the datasets.
+
+### Installing `s5cmd`
+
+`s5cmd` can be easily installed with the following script:
+
+```bash
+#!/usr/bin/env bash
+
+export INSTALL_DIR=$HOME/.local/bin
+export PATH=$PATH:$INSTALL_DIR
+export S5CMD_URI=https://github.com/peak/s5cmd/releases/download/v1.4.0/s5cmd_1.4.0_$(uname | sed 's/Darwin/macOS/g')-64bit.tar.gz
+
+mkdir -p $INSTALL_DIR
+curl -sL $S5CMD_URI | tar -C $INSTALL_DIR -xvzf - s5cmd
+```
+
+Note that it will install `s5cmd` in your local bin directory. You can always change the path if you prefer installing it in another directory.
+
+### Downloading Datasets
+Once `s5cmd` is installed installed, downloading a dataset is as easy as running the following (using the sensor dataset as an example):
+
+```bash
+s5cmd --no-sign-request cp "s3://argoai-argoverse/av2/sensor/*" target-directory
+```
+
+The command will download all S3 objects to the target directory (for example, `target-directory` can be `/home/av2/sensors/`). Given the size of the dataset, it might take a couple of hours depending on the network connectivity.
+
+When the download is finished, the dataset is ready to use!
+
+### Dataset S3 Locations
+```bash
+s3://argoai-argoverse/av2/sensor/
+s3://argoai-argoverse/av2/lidar/
+s3://argoai-argoverse/av2/motion-forecasting/
+s3://argoai-argoverse/av2/tbv/
+```
diff --git a/README.md b/README.md
@@ -2,34 +2,123 @@
 ![CI Status](https://github.com/argoai/av2-api/actions/workflows/ci.yml/badge.svg)
 [![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](./LICENSE)
 
-# Argoverse 2
+# Argoverse 2 API
 
 > _Official_ GitHub repository for the [Argoverse 2](https://www.argoverse.org) family of datasets.
 
-<p align="center">
-  <img src="https://user-images.githubusercontent.com/29715011/157802162-e40098c1-8677-4c16-ac60-e9bbded6badf.png" height="300">
-</p>
+If you have any questions or run into any problems with either the data or API, please feel free to open a [GitHub issue](https://github.com/argoai/av2-api/issues)!
+
+## Announcements
+
+### Argoverse competitions are live!
+  - Argoverse 2
+    - 3D Object Detection
+      - Challenge Link: https://eval.ai/challenge/1710/overview
+      - Baseline: https://github.com/benjaminrwilson/torchbox3d
+    - Motion Forecasting
+      - Challenge Link: https://eval.ai/challenge/1719/overview
+  - Argoverse 1
+    - Stereo
+      - Challenge Link: https://eval.ai/challenge/1704/overview
+
+## TL;DR
+
+- Install the API: `bash conda/install.sh`
+- Read the [instructions](DOWNLOAD.md) to download the data.
+
+## Overview
+
+- [Setup](#setup)
+- [Datasets](#datasets)
+- [Testing](#testing)
+- [Contributing](#contributing)
+- [Citing](#citing)
+- [License](#license)
 
 ## Getting Started
 
-Please see the [Argoverse User Guide](https://argoverse.github.io/av2-api/).
+### Setup
+
+The easiest way to install the API is via [conda](https://docs.conda.io/en/latest/) by running the following command:
+
+```bash
+bash conda/install.sh
+```
+
+Additional information can be found in the: [INSTALL README](conda/INSTALL.md).
+
+### Datasets
+
+The _Argoverse 2_ family consists of **four** distinct datasets:
+
+| Dataset Name   | Scenarios | Camera Imagery | Lidar| Maps | Additional Information|
+| ---------------| --------: | :------------: | :--: | :--: | :--------------------:|
+| Sensor | 1,000 | :white_check_mark: | :white_check_mark: | :white_check_mark: | [Sensor Dataset README](src/av2/datasets/sensor/README.md) |
+| Lidar  | 20,000 | | :white_check_mark: | :white_check_mark: | [Lidar Dataset README](src/av2/datasets/lidar/README.md) |
+| Motion Forecasting | 250,000 | | | :white_check_mark: | [Motion Forecasting Dataset README](src/av2/datasets/motion_forecasting/README.md) |
+| Map Change (Trust, but Verify) | 1,045 | :white_check_mark:  | :white_check_mark: | :white_check_mark: | [Map Change Dataset README](src/av2/datasets/tbv/README.md) |
 
-## Supported Datasets
+Please see [DOWNLOAD.md](DOWNLOAD.md) for detailed instructions on how to download each dataset.
 
-- Argoverse 2 (AV2)
-  - [Sensor](https://argoverse.github.io/av2-api/datasets/sensor.html)
-  - [Lidar](https://argoverse.github.io/av2-api/datasets/lidar.html)
-  - [Motion Forecasting](https://argoverse.github.io/av2-api/datasets/motion_forecasting.html)
-- Trust, but Verify (TbV)
-  - [Map Change Detection](https://argoverse.github.io/av2-api/datasets/map_change_detection.html)
+<div align="center">
+  <h4> <a href="src/av2/datasets/sensor/README.md"> Sensor Dataset </a> </h4>
+  <img src="https://user-images.githubusercontent.com/29715011/158742778-557f31a4-569d-44aa-a032-99836094dc97.gif" height="150">
+  <img src="https://user-images.githubusercontent.com/29715011/158742776-069501c4-8dd4-4f9d-ac8c-f0421f855607.gif" height="150">
+  <img src="https://user-images.githubusercontent.com/29715011/158739736-fe876299-23da-46ed-98ce-173f938d1702.gif" height="150">
+  <img src="https://user-images.githubusercontent.com/29715011/158739767-886e1c2f-4613-495d-9204-a7b4813af16d.gif" height="150">
+</div>
 
-## Supported Tasks
+<div align="center">
+  <h4> <a href="src/av2/datasets/lidar/README.md"> Lidar Dataset </a> </h4>
+  <img src="https://user-images.githubusercontent.com/29715011/158715494-472339d1-a5d5-4d33-8fcf-3455c0d78d27.gif" height="150">
+  <img src="https://user-images.githubusercontent.com/29715011/158715496-f439ccad-71af-4880-8b43-ade7b6c8f333.gif" height="150">
+  <img src="https://user-images.githubusercontent.com/29715011/158715498-23d7a11f-12a1-4aeb-b9af-dbced217b340.gif" height="150">
+  <img src="https://user-images.githubusercontent.com/29715011/158715497-d1603423-c32f-4cf0-ab1e-6bbc9c458535.gif" height="150">
+</div>
 
-- Argoverse 2 (AV2)
-  - [3D Object Detection](https://argoverse.github.io/av2-api/tasks/3d_object_detection.html)
-  - [3D Scene Flow](https://argoverse.github.io/av2-api/tasks/3d_scene_flow.html)
-  - [Motion Forecasting](https://argoverse.github.io/av2-api/tasks/motion_forecasting.html)
 
+<div align="center">
+  <h4> <a href="src/av2/datasets/motion_forecasting/README.md"> Motion Forecasting Dataset </a> </h4>
+  <img src="https://user-images.githubusercontent.com/29715011/158486284-1a0df794-ee0a-4ae6-a320-0dd0d1daad06.gif" height="150">
+  <img src="https://user-images.githubusercontent.com/29715011/158486286-e734e654-b879-4994-a129-9957cc591af4.gif" height="150">
+  <img src="https://user-images.githubusercontent.com/29715011/158486288-5e7c0971-de0c-4ff5-bea7-76f7922dd1e0.gif" height="150">
+</div>
+
+<div align="center">
+  <h4> <a href="src/av2/datasets/tbv/README.md"> Map Change Dataset (Trust, but Verify) </a> </h4>
+  <img src="https://user-images.githubusercontent.com/29715011/159289930-a58147c3-c6ed-4b4e-a2a8-e23c23feb43e.gif" height="150">
+  <img src="https://user-images.githubusercontent.com/29715011/159289891-8aae12e7-136a-4f44-bbc1-8ef93f01e23e.gif" height="150">
+  <img src="https://user-images.githubusercontent.com/29715011/159152108-3c3001fe-ec7c-48fd-8c08-4a473affb2a3.gif" height="150">
+  <img src="https://user-images.githubusercontent.com/29715011/159152102-27c04180-9ca4-4725-be81-95ee6858d367.gif" height="150">
+</div>
+
+### Map API
+
+Please refer to the [map README](src/av2/map/README.md) for additional details about the common format for vector and
+raster maps that we employ across all AV2 datasets.
+
+## Compatibility Matrix
+
+| `Python Version` |       `linux`      |       `macOS`      |      `windows`     |
+| -------------    | :----------------: | :----------------: | :----------------: |
+| `3.8`            | :white_check_mark: | :white_check_mark: | :white_check_mark: |
+| `3.9`            | :white_check_mark: | :white_check_mark: | :white_check_mark: |
+| `3.10`           | :white_check_mark: | :white_check_mark: | :white_check_mark: |
+
+## Testing
+
+All incoming pull requests are tested using [nox](https://nox.thea.codes/en/stable/) as
+part of the CI process. This ensures that the latest version of the API is always stable on all supported platforms. You
+can run the full suite of automated checks and tests locally using the following command:
+
+```bash
+nox -r
+```
+
+## Contributing
+
+Have a cool feature you'd like to add? Found an unhandled corner case? The Argoverse team welcomes contributions from
+the open source community - please open a PR using the following [template](.github/pull_request_template.md)!
 
 ## Citing
 
@@ -44,7 +133,7 @@ Please use the following citation when referencing the [Argoverse 2](https://dat
 }
 ```
 
-Use the following citation when referencing the [Trust, but Verify](https://datasets-benchmarks-proceedings.neurips.cc/paper/2021/file/6f4922f45568161a8cdf4ad2299f6d23-Paper-round2.pdf) _Map Change Detection_ Dataset:
+Use the following citation when referencing the [Argoverse 2](https://datasets-benchmarks-proceedings.neurips.cc/paper/2021/file/6f4922f45568161a8cdf4ad2299f6d23-Paper-round2.pdf) _Map Change_ Dataset:
 ```BibTeX
 @INPROCEEDINGS { TrustButVerify,
   author = {John Lambert and James Hays},
@@ -53,3 +142,8 @@ Use the following citation when referencing the [Trust, but Verify](https://data
   year = {2021}
 }
 ```
+
+## License
+
+All code provided within this repository is released under the **MIT license** and bound by the _Argoverse_ **terms of use**,
+please see [LICENSE](LICENSE) and [NOTICE](NOTICE) for additional details.
diff --git a/conda/INSTALL.md b/conda/INSTALL.md
@@ -0,0 +1,33 @@
+# Installation
+
+We _highly_ recommend using `conda` with the `conda-forge` channel for package management.
+
+## Install `conda`
+
+You will need to install `conda` on your machine. We recommend to install the `conda-forge` version of `conda` found at https://github.com/conda-forge/miniforge#install.
+
+## Install `av2`
+
+Simply run:
+
+```bash
+bash install.sh
+```
+
+which will install _all_ of the necessary dependencies in a conda environment named `av2`.
+
+To activate your environment (i.e., update your system paths), run:
+
+```bash
+conda activate av2
+```
+
+## FAQ
+
+> Why manage dependencies in `conda` instead of `pip`?
+
+`conda` enables package management outside of the `python` ecosystem. This enables us to specify all necessary dependencies in `environment.yml`. Further, gpu-based packages (e.g., `torch`) are handled better through `conda`.
+
+> Why `conda-forge`?
+
+`conda-forge` is a community-driven channel of conda recipes. It includes a large number of packages which can all be properly tracked in the `conda` resolver allowing for consistent environments without conflicts.
diff --git a/guide/book.toml b/guide/book.toml
-Original file line number
+Diff line change
@@ Expand Up / @@ -156,4 +156,4 @@ experiments @@
     *.pt
     *.mp4
-    guide/book
+    guide/book