diff --git a/Docs/connecting_the_client.md b/Docs/connecting_the_client.md new file mode 100644 index 000000000..286727156 --- /dev/null +++ b/Docs/connecting_the_client.md @@ -0,0 +1,99 @@ +

Connecting a Python client

+ +![Running CARLA with client](img/client_window.png) + +The power of CARLA simulator resides in its ability to be controlled +programmatically with an external client. This client can control most of the +aspects of simulation, from environment to duration of each episode, it can +retrieve data from different sensors, and send control instructions to the +player vehicle. + +PythonClient contents +--------------------- + +In the release package, inside the _"PythonClient"_ folder, we provide the +Python API module together with some use examples. + +File or folder | Description +------------------------ | ------------ +carla/ | Contains the "carla" module, the Python API for communicating with the simulator. +client_example.py | Basic usage example of the "carla" module. +manual_control.py | A GUI client in which the vehicle can be controlled manually. +point_cloud_example.py | Usage example for converting depth images into a point cloud in world coordinates. +run_benchmark.py | Run the CoRL'17 benchmark with a trivial agent. + +!!! note + If you are building CARLA from source, the Python code is inside the + _"PythonClient"_ folder in the CARLA repository. Bear in mind that the + `master` branch contains latest fixes and changes that might be incompatible + with the release version. Consider using the `stable` branch. + +Install dependencies +-------------------- + +We recommend using Python 3.5, but all the Python code in the "carla" module and +given examples is also compatible with Python 2.7. + +Install the dependencies with "pip" using the requirements file provided + + $ pip install -r PythonClient/requirements.txt + +Running the client example +-------------------------- + +The "client_example.py" script contains a basic usage example for using the +"carla" module. We recommend taking a look at the source-code of this script if +you plan to familiarize with the CARLA Python API. + +

Launching the client

+ +The script tries to connect to a CARLA simulator instance running in _server +mode_. Now we are going to launch the script with "autopilot" enabled + + $ ./client_example.py --autopilot + +The script now will try repeatedly to connect with the server, since we haven't +started the simulator yet it will keep printing an error until we launch the +server. + +!!! note + By default CARLA uses the ports 2000, 2001, and 2002. Make sure to have + these ports available. + +

Launching the simulator in server mode

+ +To launch CARLA simulator in **server mode** we just need to pass the +`-carla-server` argument + + $ ./CarlaUE4.sh -carla-server + +Once the map is loaded, the vehicle should start driving around controlled by +the Python script. + +!!! important + Before you start running your own experiments, it is important to know the + details for running the simulation at [fixed time-step](fixed_time_step.md) + for achieving maximum speed and repeatability. + +

Saving images to disk

+ +Now you can stop the client script and relaunch it with different options. For +instance now we are going to save to disk the images of the two cameras that the +client attaches to the vehicle + + $ ./client_example.py --autopilot --images-to-disk + +And _"_out"_ folder should have appeared in your working directory containing each +captured frame as PNG. + +![Saved images to disk](img/saved_images_to_disk.png) + +You can see all the available options in the script's help + + $ ./client_example.py --help + +

Running other examples

+ +The other scripts present in the _"PythonClient"_ folder run in a similar +fashion. We recommend now launching _"manual_control.py"_ for a GUI interface +implemented with PyGame. diff --git a/Docs/img/client_window.png b/Docs/img/client_window.png new file mode 100644 index 000000000..4cca1756c Binary files /dev/null and b/Docs/img/client_window.png differ diff --git a/Docs/img/saved_images_to_disk.png b/Docs/img/saved_images_to_disk.png new file mode 100644 index 000000000..ecfe1dc8e Binary files /dev/null and b/Docs/img/saved_images_to_disk.png differ