tinycarlo

2D car simulation


License
MIT
Install
pip install tinycarlo==1.1

Documentation

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).