Metadata-Version: 2.4
Name: thirdeye-sim
Version: 0.1.0
Summary: Dream: a driving environment on Gurgaon's real roads, in traffic and events at rates measured from Indian dashcam footage
Author: Third Eye Labs
License-Expression: Apache-2.0
Project-URL: Homepage, https://dream.thirdeyelabs.ai
Project-URL: Repository, https://github.com/thirdeyelabsai/thirdeye-sim
Project-URL: Documentation, https://github.com/thirdeyelabsai/thirdeye-sim/blob/main/docs/environment.md
Project-URL: Company, https://thirdeyelabs.ai
Project-URL: Dataset, https://huggingface.co/datasets/thirdeyelabs/indian-road-dataset
Keywords: autonomous-driving,simulation,reinforcement-learning,gymnasium,india,planning
Classifier: Development Status :: 3 - Alpha
Classifier: Intended Audience :: Science/Research
Classifier: Programming Language :: Python :: 3
Classifier: Topic :: Scientific/Engineering :: Artificial Intelligence
Requires-Python: >=3.10
Description-Content-Type: text/markdown
License-File: LICENSE
License-File: NOTICE
Requires-Dist: gymnasium>=1.0
Requires-Dist: numpy>=1.26
Requires-Dist: shapely>=2.0
Provides-Extra: render
Requires-Dist: pygame>=2.5; extra == "render"
Requires-Dist: moderngl>=5.10; extra == "render"
Requires-Dist: pyproj>=3.6; extra == "render"
Provides-Extra: map
Requires-Dist: sumolib>=1.20; extra == "map"
Requires-Dist: pyproj>=3.6; extra == "map"
Dynamic: license-file

# Dream

A driving simulator of Gurgaon's real roads, in traffic that behaves like India's. Two-wheelers squeeze past, autos cut in,
people cross anywhere and cows stand in the lane. How often each of these happens comes from dashcam footage of
Delhi NCR that the Third Eye Labs team labelled by hand. The name comes from the world-models idea: driving
software can learn inside a dream of the world before it meets the real one.

- **Play it in your browser:** https://dream.thirdeyelabs.ai (nothing to install)
- **Use it in Python:** a [Gymnasium](https://gymnasium.farama.org) environment for training and testing driving
  software, with planner scores in the style of nuPlan and CARLA.

## Install

```
pip install "thirdeyelabs[sim]"          # the environment (installs thirdeye-sim)
pip install "thirdeye-sim[render]"       # plus the 3D view and the desktop game
```

Python 3.10 or later. `thirdeyelabs` is our dataset package; its `sim` extra installs this simulator, which is
also on PyPI on its own as `thirdeye-sim`.

## Quick start

```python
import gymnasium as gym
import thirdeye_sim.env                  # registers ThirdEye/Gurgaon-v0

env = gym.make("ThirdEye/Gurgaon-v0")
obs, info = env.reset(seed=0)
while True:
    obs, reward, terminated, truncated, info = env.step(env.action_space.sample())
    if terminated or truncated:
        break
```

The observation, actions, reward and options are in [docs/environment.md](docs/environment.md).

## Score a planner

```
python -m thirdeye_sim.evaluate --episodes 20
```

Drives each planner in `thirdeye_sim/planners.py` over the same seeded routes in Gurgaon traffic and in
orderly traffic, and reports nuPlan-style and CARLA-style scores beside the raw counts. Add your own planner
to `PLANNERS` to score it.

## Check the traffic against real roads

```
python -m thirdeye_sim.realism
```

Compares how often each kind of event happens in the simulator with how often it happens in our footage, and
how fast traffic moves. The results and what they do not cover yet are at https://dream.thirdeyelabs.ai/realism.

## What is measured and what is assumed

Event rates come from labelled footage, with their uncertainty. Some things are assumed until we can measure
them, and the code marks them as assumed: lane counts on roads OpenStreetMap leaves untagged, most speed
breakers, potholes, and the rates of the cow, dog and U-turn events. [STANDARDS.md](STANDARDS.md) lists every
standard we follow and every addition we make.

## Licences

- Code: Apache-2.0 ([LICENSE](LICENSE))
- Map data: © OpenStreetMap contributors, under the ODbL ([NOTICE](NOTICE))
- Event rates and measurements: CC BY 4.0

## Citation

See [CITATION.cff](CITATION.cff). Built by [Third Eye Labs](https://thirdeyelabs.ai).
