Skip to content

Commit

Permalink
update readme
Browse files Browse the repository at this point in the history
  • Loading branch information
@AlirezaMorsali
AlirezaMorsali committed Oct 7, 2022
1 parent 1db29ed commit 7baea85
Show file tree
Hide file tree
Showing 4 changed files with 104 additions and 109 deletions.
108 changes: 3 additions & 105 deletions README.md
View file
Original file line number Diff line number Diff line change
@@ -1,117 +1,15 @@
# InvertedAI
[pypi-badge]: https://badge.fury.io/py/invertedai.svg
[pypi-link]: https://pypi.org/project/invertedai/


[![Documentation Status](https://readthedocs.org/projects/inverted-ai/badge/?version=latest)](https://inverted-ai.readthedocs.io/en/latest/?badge=latest)
[![PyPI][pypi-badge]][pypi-link]

# InvertedAI
## Overview
<!-- start elevator-pitch -->
Inverted AI has trained cutting-edge realistic behavioral driving models that are human-like and close the SIM2Real. Our API provides access to these behavioral models and can be useful for several tasks in autonomous vehicle (AV) research and development.

![](docs/images/top_camera.gif)
<!-- end elevator-pitch -->

# Get Started
<!-- start quickstart -->
In this quickstart tutorial, you’ll run a simple sample AV simulation with Inverted AI Python API. Along the way, you’ll learn key concepts and techniques that are fundamental to using the API for other tasks. In particular, you will be familiar with two main Inverted AI models:

- Drive
- Initialize

## Installation

[pypi-badge]: https://badge.fury.io/py/invertedai.svg
[pypi-link]: https://pypi.org/project/invertedai/

To install use [![PyPI][pypi-badge]][pypi-link]:

```bash
pip install invertedai
```

## Setting up

Import the _invertedai_ package and set the API key with **add_apikey** method.

Refer to the [product page](https://www.inverted.ai) to get your API key (or recharge for more tokens).

```python

import invertedai as iai
iai.add_apikey("XXXXXXXXXXXXXX")
## Quick Start
```{include} docs/source/quickstart.md
```

## Browse through available maps (location)
Inverted AI provides an assortment of diverse road configurations and geometries, including real-world locations and maps from simulators (CARLA, Huawei SMARTS, ...).\
To search the catalog use **iai.available_maps** method by providing keywords
```python
iai.available_maps("roundabout", "carla")
```

To get information about a scene use **iai.get_map**.
```python
iai.get_map**("CARLA:Town03:Roundabout")
```
The scene information include the map in [Lanelet2](https://github.com/fzi-forschungszentrum-informatik/Lanelet2) format, map in JPEG format, maximum number of allowed (driveable) vehicles, latitude longitude coordinates (for real-world locations), id and list of traffic light and signs (if any exist in the map), etc.

## Initialize
To run the simulation, the map must be first populated with agents.
Inverted AI provides the **initialize**, a state-of-the-art model trained with real-life driving scenarios which can generate realistic positions for the initial state of the simulation.\
Having realistic, complicated and diverse initial conditions are particularly crucial to observer interesting and informative interaction between the agents, i.e., the ego vehicle and NPCs (non-player characters).

You can use **initialize** in two modes:
- _Initialize all agents_: generates initial conditions (position and speed) for all the agents including the ego vehicle
```python
response = iai.initialize(
location="CARLA:Town03:Roundabout",
agent_count=10,
)
```
- _Initialize NPCs_: generates initial conditions (position and speed) only for the NPCs according to the provided state of the ego vehicle.
```python
response = iai.initialize(
location="CARLA:Town03:Roundabout",
agent_count=10,
<!-- ego_state=[-11.75, 26.58, 1.36, 4.94], -->
<!-- ego_attribute=[4.97, 2.04, 1.96] -->
)
```
> _response_ is a dictionary of _states_, and _agent-attribute_ (_recurrent-states_ is also returned for compatibility with **drive**)\
> _response["states"]_ is a list of agent states, by default the first on the list is always the ego vehicle.
## Drive
**drive** is Inverted AI's cutting-edge realistic driving model trained on millions of miles of traffic data.
This model can drive all the agents with only the current state of the environment, i.e., one step observations (which could be obtained from **initialize**) or with multiple past observations.
```python
response = iai.drive(
location="CARLA:Town03:Roundabout",
agent_attributes=response["attributes"],
states=response["states"],
recurrent_states=response["recurrent_states"],
traffic_states_id=response["traffic_states_id"],
steps=1,
get_birdviews=True,
get_infractions=True,
)
```
>For convenience and to reduce data overhead, ***drive** also returns _recurrent-states_ which can be feedbacked to the model instead of providing all the past observations.\
>Furthermore, **drive** drive all the agents for $steps\times \frac{1}{FPS}$ where by default $FPS=10[frames/sec]$, should you require other time resolutions [contact us](mailto:info@inverted.ai).
## Running demo locally

Download the
<a href="https://minhaskamal.github.io/DownGit/#/home?url=https://github.com/inverted-ai/invertedai/tree/master/examples" target="_blank">examples directory</a>
and run:
```
python -m venv .venv
source .venv/bin/activate
pip install --upgrade pip
pip install -r requirements.txt
.venv/bin/jupyter notebook Drive-Demo.ipynb
```

## Running demo in Colab
[![Open In Colab](https://colab.research.google.com/assets/colab-badge.svg)](https://colab.research.google.com/github/inverted-ai/invertedai-drive/blob/develop/examples/Colab-Demo.ipynb)
<!-- end quickstart -->
3 changes: 2 additions & 1 deletion docs/source/apireference.md
View file
Original file line number Diff line number Diff line change
@@ -1,3 +1,4 @@
# API Reference

## H2
## available-maps

1 change: 1 addition & 0 deletions docs/source/index.md
View file
Original file line number Diff line number Diff line change
Expand Up @@ -86,3 +86,4 @@ REFERENCES
* :ref:`modindex`
* :ref:`search`
```

101 changes: 98 additions & 3 deletions docs/source/quickstart.md
View file
Original file line number Diff line number Diff line change
@@ -1,6 +1,101 @@

# Get Started
```{include} ../../README.md
:start-after: <!-- start quickstart -->
:end-before: <!-- end quickstart -->
<!-- start quickstart -->
In this quickstart tutorial, you’ll run a simple sample AV simulation with Inverted AI Python API. Along the way, you’ll learn key concepts and techniques that are fundamental to using the API for other tasks. In particular, you will be familiar with two main Inverted AI models:

- Drive
- Initialize

## Demo
- **Goolge Colab***: [![Open In Colab](https://colab.research.google.com/assets/colab-badge.svg)](https://colab.research.google.com/github/inverted-ai/invertedai-drive/blob/develop/examples/Colab-Demo.ipynb)

- **Locally**: Download the
<a href="https://minhaskamal.github.io/DownGit/#/home?url=https://github.com/inverted-ai/invertedai/tree/master/examples" target="_blank">examples directory</a>, navigate to the unzipped directory in terminal and run

```
python3 -m venv .venv
source .venv/bin/activate
pip install --upgrade pip
pip install -r requirements.txt
.venv/bin/jupyter notebook Drive-Demo.ipynb
```

## Installation

[pypi-badge]: https://badge.fury.io/py/invertedai.svg
[pypi-link]: https://pypi.org/project/invertedai/

To install use [![PyPI][pypi-badge]][pypi-link]:

```bash
pip install invertedai
```

## Setting up

Import the _invertedai_ package and set the API key with **add_apikey** method.

Refer to the [product page](https://www.inverted.ai) to get your API key (or recharge for more tokens).

```python

import invertedai as iai
iai.add_apikey("XXXXXXXXXXXXXX")
```

## Browse through available maps (location)

[available maps](/docs/source/apireference.md) Inverted AI provides an assortment of diverse road configurations and geometries, including real-world locations and maps from simulators (CARLA, Huawei SMARTS, ...).\
To search the catalog use **iai.available_maps** method by providing keywords
```python
iai.available_maps("roundabout", "carla")
```

To get information about a scene use **iai.get_map**.
```python
iai.get_map**("CARLA:Town03:Roundabout")
```
The scene information include the map in [Lanelet2](https://github.com/fzi-forschungszentrum-informatik/Lanelet2) format, map in JPEG format, maximum number of allowed (driveable) vehicles, latitude longitude coordinates (for real-world locations), id and list of traffic light and signs (if any exist in the map), etc.

## Initialize
To run the simulation, the map must be first populated with agents.
Inverted AI provides the **initialize**, a state-of-the-art model trained with real-life driving scenarios which can generate realistic positions for the initial state of the simulation.\
Having realistic, complicated and diverse initial conditions are particularly crucial to observer interesting and informative interaction between the agents, i.e., the ego vehicle and NPCs (non-player characters).

You can use **initialize** in two modes:
- _Initialize all agents_: generates initial conditions (position and speed) for all the agents including the ego vehicle
```python
response = iai.initialize(
location="CARLA:Town03:Roundabout",
agent_count=10,
)
```
- _Initialize NPCs_: generates initial conditions (position and speed) only for the NPCs according to the provided state of the ego vehicle.
```python
response = iai.initialize(
location="CARLA:Town03:Roundabout",
agent_count=10,
)
```
> _response_ is a dictionary of _states_, and _agent-attribute_ (_recurrent-states_ is also returned for compatibility with **drive**)\
> _response["states"]_ is a list of agent states, by default the first on the list is always the ego vehicle.
## Drive
**drive** is Inverted AI's cutting-edge realistic driving model trained on millions of miles of traffic data.
This model can drive all the agents with only the current state of the environment, i.e., one step observations (which could be obtained from **initialize**) or with multiple past observations.
```python
response = iai.drive(
location="CARLA:Town03:Roundabout",
agent_attributes=response["attributes"],
states=response["states"],
recurrent_states=response["recurrent_states"],
traffic_states_id=response["traffic_states_id"],
steps=1,
get_birdviews=True,
get_infractions=True,
)
```
>For convenience and to reduce data overhead, ***drive** also returns _recurrent-states_ which can be feedbacked to the model instead of providing all the past observations.\
>Furthermore, **drive** drive all the agents for $steps\times \frac{1}{FPS}$ where by default $FPS=10[frames/sec]$, should you require other time resolutions [contact us](mailto:info@inverted.ai).
<!-- end quickstart -->

0 comments on commit 7baea85

Please sign in to comment.