What is tinycarlo?
tinycarlo is a 2D simulation written in python as an OpenAI Gym. It can be used to test algorithms for autonomous driving with a given perception system. Reinforcement Learning Algorithms can also be trained with this simulation since the simulation already has an integrated reward system. Currently, only kinematics are used and dynamics are not taken into account, therefore the car has no slip. As input, cameras are simulated. These cameras are in birds-eye-view.
To give you an idea for what it can be used, here are 3 ideas:
Segmented road markings
We assume the road marking detection is already given and it segments these markings. The color describes different classes like dashed or solid lines.
An example track can be found here.
Formula Student
In formula student competitions, color coded cones are used to define the track. Using colored circles on the track image, these tracks can be simulated as well. Further processing is needed if your driverless system is not using images.
An example track can be found here.
Carolo-Cup
At the Carolo-Cup you have white road markings on a black surface. So the perception can also be tested with this simulation. To use this sim for your system, you can create a custom track.
Installation
To get started, you'll need to have Python 3.9+ installed. You can use pip to install.
pip install tinycarlo
Please note that gym is already a dependency, so no need to install that too if not already done.
Usage
This simulation can be used like every other OpenAI Gym. Here is a very basic example
import gym
import tinycarlo
env = gym.make("tinycarlo-v1", environment="./example_tracks/formula_student")
observation = env.reset()
while True:
env.render()
action = env.action_space.sample()
observation, reward, done, info = env.step(action)
if done:
observation = env.reset()
break
env.close()To configure the simulation, take a look on Custom Tracks.
Action Space
The action space is a single floating point number with a range of [-1.0, 1.0]. This the normalized steering angle for the car.
Observation Space
The observation space is a dictionary, depending on how many cameras are configured. The value of every key-value pair is the camera image in a uint8 BGR format.
Custom Tracks
To create a custom track, create a new folder with a track.yaml file. The path of the folder is then provided in the gym.make("tinycarlo-v0", environment="./path/to/your/folder") call.
For the structure of the track.yaml file, please use on of the example tracks: example 1 or example 2. Below you can find a detailed descriptions of the parameters:
sim
| Key | Type | Default | Description |
|---|---|---|---|
| fps | int | 30 | Defines the step size of the simulation |
| render_realtime | bool | True | Does only affect the visualization. When using reinforcment learning it can be useful to no render everything in realtime to reduce training time. Step size of simulation is unaffected. |
| step_limit | int | None | If the simulation has reached this limit, the done flag is automatically set. Useful in reinforcement learning |
| overview_downscale | float | 1 | This factor is used to divide the track image in the visualization screen. A value greater than 1 resizes the visualization to make the rendering faster since the full resolution is normally overkill for an overview. |
reward_design
| Key | Type | Default | Description |
|---|---|---|---|
| color_obstacles | list | None | List of obstacles. If the car hits one of these obstacles, a given reward is returned. An obstacle is defined by pixel colors. See more |
| cross_track_error | dict | None | Information if a crosst track error should be used and where it is defined. See more |
color_obstacle
| Key | Type | Description |
|---|---|---|
| color | [int,int,int] | Defines color of an obstacle in BGR format. Please use only 0 or 255, since everything will be binarized. |
| reward | int or done
|
If an int is provided, this will be returned as an reward upon collision. If done as a String is set, the done flag on the step() function will be set, resetting the simulation run. |
cross_track_error
| Key | Type | Default | Description |
|---|---|---|---|
| use_cte | bool | False | Whether to use cross track error or no. If it is True, the next parameter needs to be set! |
| trajectory_color | [int, int, int] | [255,255,255] | Defines the color of the ground truth trajectory used for the cte calculation. This does not need to be a fully connected line in the track image. Multiple colored pixels are fine! Please use only 0 or 255 in BGR format. |
car
| Key | Type | Default | Description |
|---|---|---|---|
| wheelbase | int | 160 | in pixels |
| track_width | int | 100 | in pixels |
| velocity | float or int | 500 | pixels per second |
| max_steering_change | int | None | limits how fast the car can change it's steering angle. This depends on human performance or servo. if none, the steering angle can change completely between to sim steps. |
camera
| Key | Type | Description |
|---|---|---|
| id | String | ID of a camera. Only used as a key for the observation space. |
| resolution | [int, int] | [y,x] resolution of camera. This does not affect the viewing space on track. If this is the same as the roi, np resize will be used. This should be equal or less than the roi to avoid weird upsampling. |
| roi | [int, int] | [y,x] region of interest of camera. This defines the viewing space of the camera on the track image. |
| position | [int, int] | [y,x] position of the camera relative to the middle of the front axle. |
track
| Key | Type | Description |
|---|---|---|
| image | String | relative path to the track image based on the track.yaml file. |
| spawns | list of [float, float, float] | list of spawn points. A spawn point is defined by x,y,alpha. x and y position is relative to the track image, therefore in pixels, and alpha is the direction the car is heading. Alpha is in radians and the 0 point is north (top of the track image). |
