diff --git a/Docs/CONTRIBUTING.md b/Docs/CONTRIBUTING.md index cd966e32f..a77d3b8be 100644 --- a/Docs/CONTRIBUTING.md +++ b/Docs/CONTRIBUTING.md @@ -76,11 +76,11 @@ usually offers that make it very affordable. #### What should I know before I get started? -Check out the ["CARLA Design"](carla_design.md) document to get an idea on the -different modules that compose CARLA, and chose the most appropriate one to hold -the new feature. We are aware the developers documentation is still scarce, -please ask us in case of doubt, and of course don't hesitate to improve the -current documentation if you feel confident enough. +Check out the ["CARLA Design"](index.md) document to get an idea +on the different modules that compose CARLA, and chose the most appropriate one +to hold the new feature. We are aware the developers documentation is still +scarce, please ask us in case of doubt, and of course don't hesitate to improve +the current documentation if you feel confident enough. #### Are there any examples in CARLA to see how Unreal programming works? diff --git a/Docs/benchmark_creating.md b/Docs/benchmark_creating.md index 61b846f69..e49981181 100644 --- a/Docs/benchmark_creating.md +++ b/Docs/benchmark_creating.md @@ -13,7 +13,7 @@ In this tutorial we show: ![Benchmark_structure](img/benchmark_diagram_small.png) The driving benchmark is associated with other two modules. -The *agent* module, that is a controller which performs in +The *agent* module, that is a controller which performs in another module: the *experiment suite*. Both modules are abstract classes that must be redefined by the user. @@ -54,11 +54,11 @@ Let's start by deriving a simple forward agent: from carla.agent.agent import Agent from carla.client import VehicleControl - + class ForwardAgent(Agent): -To have its performance evaluated, the ForwardAgent derived class _must_ +To have its performance evaluated, the ForwardAgent derived class _must_ redefine the *run_step* function as it is done in the following excerpt: def run_step(self, measurements, sensor_data, directions, target): @@ -71,18 +71,18 @@ redefine the *run_step* function as it is done in the following excerpt: This function receives the following parameters: - - * [Measurements](measurements.md): the entire state of the world received + + * [Measurements](index.md): the entire state of the world received by the client from the CARLA Simulator. These measurements contains agent position, orientation, dynamic objects information, etc. - * [Sensor Data](cameras_and_sensors.md): The measured data from defined sensors, + * [Sensor Data](cameras_and_sensors.md): The measured data from defined sensors, such as Lidars or RGB cameras. * Directions: Information from the high level planner. Currently the planner sends a high level command from the follwoing set: STRAIGHT, RIGHT, LEFT, NOTHING. * Target Position: The position and orientation of the target. - - With all this information, the *run_step* function is expected - to return a [vehicle control message](measurements.md), containing: + + With all this information, the *run_step* function is expected + to return a [vehicle control message](index.md), containing: steering value, throttle value, brake value, etc. @@ -108,12 +108,12 @@ as in the following code excerpt: from carla.agent_benchmark.experiment import Experiment from carla.sensor import Camera from carla.settings import CarlaSettings - + from .experiment_suite import ExperimentSuite - - + + class BasicExperimentSuite(ExperimentSuite): - + ##### Define test and train weather conditions The user must select the weathers to be used. One should select the set @@ -126,7 +126,7 @@ class property as in the following example: @property def test_weathers(self): return [1] - + ##### Building Experiments @@ -134,15 +134,15 @@ The [experiments are composed by a *task* that is defined by a set of *poses*](b Let's start by selecting poses for one of the cities, let's take Town01, for instance. First of all, we need to see all the possible positions, for that, with a CARLA simulator running in a terminal, run: - + python view_start_positions.py - + ![town01_positions](img/town01_positions.png) - - + + Now let's choose, for instance, 140 as start position and 134 as the end position. This two positions can be visualized by running: - + python view_start_positions.py --pos 140,134 --no-labels ![town01_positions](img/town01_140_134.png) @@ -165,7 +165,7 @@ the number of dynamic objects for each of these tasks and repeat the arbitrary position task to have it also defined with dynamic objects. In the following code excerpt we show the final defined positions and the number of dynamic objects for each task: - + # Define the start/end position below as tasks poses_task0 = [[7, 3]] poses_task1 = [[138, 17]] @@ -212,7 +212,7 @@ vector as we show in the following code excerpt: - + The full code could be found at [basic_experiment_suite.py](https://github.com/carla-simulator/carla/blob/master/PythonClient/carla/driving_benchmark/experiment_suites/basic_experiment_suite.py) @@ -228,7 +228,7 @@ For that you should run the CARLA simulator as: The example presented in this tutorial can be executed for Town01 as: ./driving_benchmark_example.py -c Town01 - + You should expect these results: [town01_basic_forward_results](benchmark_basic_results_town01) For Town02: diff --git a/Docs/cameras_and_sensors.md b/Docs/cameras_and_sensors.md index c2afd113f..d3e0d029e 100644 --- a/Docs/cameras_and_sensors.md +++ b/Docs/cameras_and_sensors.md @@ -1,5 +1,11 @@

Cameras and sensors

+!!! important + This document still refers to the 0.8.X API (stable version). The + proceedings stated here may not apply to latest versions, 0.9.0 or later. + Latest versions introduced significant changes in the API, we are still + working on documenting everything, sorry for the inconvenience. + !!! important Since version 0.8.0 the positions of the sensors are specified in meters instead of centimeters. Always relative to the vehicle. diff --git a/Docs/carla_settings.md b/Docs/carla_settings.md index 25c270f5c..091260510 100644 --- a/Docs/carla_settings.md +++ b/Docs/carla_settings.md @@ -2,6 +2,12 @@ > _This document is a work in progress and might be incomplete._ +!!! important + This document still refers to the 0.8.X API (stable version). The + proceedings stated here may not apply to latest versions, 0.9.0 or later. + Latest versions introduced significant changes in the API, we are still + working on documenting everything, sorry for the inconvenience. + CarlaSettings.ini ----------------- @@ -14,7 +20,7 @@ hierarchy overriding earlier values. 1. `{CarlaFolder}/Unreal/CarlaUE4/Config/CarlaSettings.ini`. 2. File provided by command-line argument `-carla-settings="Path/To/CarlaSettings.ini"`. - 3. Other command-line arguments as `-carla-server` or `-world-port`. + 3. Other command-line arguments like `-carla-port`. 4. Settings file sent by the client on every new episode. Take a look at the [CARLA Settings example][settingslink]. @@ -54,8 +60,6 @@ WeatherId=6 Simulator command-line options ------------------------------ - * `-carla-server` Launches CARLA as server, the execution hangs until a client connects. * `-carla-settings="Path/To/CarlaSettings.ini"` Load settings from the given INI file. See Example.CarlaSettings.ini. - * `-carla-world-port=N` Listen for client connections at port N, agent ports are set to N+1 and N+2 respectively. Activates server. + * `-carla-port=N` Listen for client connections at port N, streaming port is set to N+1. * `-carla-no-hud` Do not display the HUD by default. - * `-carla-no-networking` Disable networking. Overrides `-carla-server` if present. diff --git a/Docs/coding_standard.md b/Docs/coding_standard.md index 157b81570..27ff6f98e 100644 --- a/Docs/coding_standard.md +++ b/Docs/coding_standard.md @@ -26,11 +26,11 @@ C++ --- * Compilation should not give any error or warning - (`clang++ -Wall -Wextra -std=C++14`). + (`clang++ -Wall -Wextra -std=C++14 -Wno-missing-braces`). * Unreal C++ code (CarlaUE4 and Carla plugin) follow the [Unreal Engine's Coding Standard][ue4link] with the exception of using spaces instead of tabs. - * CarlaServer uses [Google's style guide][googlelink]. + * LibCarla uses a variation of [Google's style guide][googlelink]. [ue4link]: https://docs.unrealengine.com/latest/INT/Programming/Development/CodingStandard/ [googlelink]: https://google.github.io/styleguide/cppguide.html diff --git a/Docs/configuring_the_simulation.md b/Docs/configuring_the_simulation.md index d7d6ec5d4..52c8cedfc 100644 --- a/Docs/configuring_the_simulation.md +++ b/Docs/configuring_the_simulation.md @@ -40,6 +40,8 @@ run the simulation at a fixed time-step of 0.2 seconds we execute It is important to note that this mode can only be enabled when launching the simulator since this is actually a feature of Unreal Engine. + diff --git a/Docs/getting_started.md b/Docs/getting_started.md index d090ade58..a772a13b6 100644 --- a/Docs/getting_started.md +++ b/Docs/getting_started.md @@ -2,6 +2,11 @@ ![Welcome to CARLA](img/welcome.png) +!!! important + This tutorial refers to the latest development versions of CARLA, 0.9.0 or + later. For the documentation of the stable version please switch to the + [stable branch](https://carla.readthedocs.io/en/stable/getting_started/). + Welcome to CARLA! This tutorial provides the basic steps for getting started using CARLA. @@ -14,17 +19,50 @@ the package in a folder of your choice. The release package contains the following * The CARLA simulator. - * The "carla" Python module. - * Some Python client examples. + * The "carla" Python API module. + * An "example.py" script. -For now we will focus on the simulator only. The simulator can be run in two -different modes +The simulator can be started by running `CarlaUE4.sh` on Linux, or +`CarlaUE4.exe` on Windows. Unlike previous versions, now the simulator +automatically starts in "server mode". That is, you can already start connecting +your Python scripts to control the actors in the simulation. - * **Server mode:** The simulator is controlled by a client application that - collects data and sends driving instructions. In this mode the simulator - hangs until a client starts a connection. - * **Standalone mode:** The simulator starts in sort of _video-game mode_ in - which you can control the vehicle with the keyboard. +CARLA requires two available TCP ports on your computer, by default 2000 and +2001. Make sure you don't have a firewall or another application blocking those +ports. Alternatively, you can manually change the port CARLA uses by launching +the simulator with the command-line argument `-carla-port=N`, the second port +will be automatically set to `N+1`. -In the next item in this tutorial we will run the **standalone mode** to take a -first look into CARLA. +!!! tip + You can launch the simulator in windowed mode by using the argument + `-windowed`, and control the window size with `-ResX=N` and `-ResY=N`. + +#### Running the example script + +Run the example script with + +```sh +python example.py +``` + +If everything went well you should start seeing cars appearing in the scene. + +_We strongly recommend taking a look at the example code to understand how it +works, and modify it at will. We'll have soon tutorials for writing your own +scripts, but for now the examples is all we have._ + +#### Changing the map + +By default, the simulator starts up in our _"Town01"_ map. The second map can be +started by passing the path to the map as first argument when launching the +simulator + +```sh +# On Linux +$ ./CarlaUE4.sh /Game/Carla/Maps/Town02 +``` + +```cmd +rem On Windows +> CarlaUE4.exe /Game/Carla/Maps/Town02 +``` diff --git a/Docs/index.md b/Docs/index.md index a7e682caf..d11e779fe 100644 --- a/Docs/index.md +++ b/Docs/index.md @@ -1,12 +1,17 @@

CARLA Documentation

+!!! important + This documentation refers to the latest development versions of CARLA, 0.9.0 + or later. For the documentation of the stable version please switch to the + [stable branch](https://carla.readthedocs.io/en/stable/). +

Quick start

* [Getting started](getting_started.md) - * [Running the simulator](running_simulator_standalone.md) - * [Connecting a Python client](connecting_the_client.md) + + * [Configuring the simulation](configuring_the_simulation.md) - * [Measurements](measurements.md) + * [Cameras and sensors](cameras_and_sensors.md) * [F.A.Q.](faq.md) @@ -25,7 +30,8 @@

Advanced topics

* [CARLA settings](carla_settings.md) - * [Simulator keyboard input](simulator_keyboard_input.md) + * [Python API](python_api.md) + * [Running without display and selecting GPUs](carla_headless.md) * [How to link Epic's Automotive Materials](epic_automotive_materials.md) @@ -39,6 +45,6 @@ * [Map customization](map_customization.md) * [How to add assets](how_to_add_assets.md) - * [CARLA design](carla_design.md) - * [CarlaServer documentation](carla_server.md) + + * [Build system](build_system.md) diff --git a/Docs/python_api.md b/Docs/python_api.md new file mode 100644 index 000000000..0c7504c08 --- /dev/null +++ b/Docs/python_api.md @@ -0,0 +1,117 @@ +

Python API

+ +!!! important + Versions prior to 0.9.0 have a very different API. For the documentation of + the stable version please switch to the + [stable branch](https://carla.readthedocs.io/en/stable/). + +## `carla.Client` + +- `Client(host, port, worker_threads=0)` +- `set_timeout(milliseconds)` +- `get_client_version()` +- `get_server_version()` +- `ping()` +- `get_world()` + +## `carla.World` + +- `get_blueprint_library()` +- `spawn_actor(blueprint, transform, attach_to=None)` +- `try_spawn_actor(blueprint, transform, attach_to=None)` + +## `carla.BlueprintLibrary` + +- `find(id)` +- `filter(wildcard_pattern)` +- `__getitem__(pos)` +- `__len__()` +- `__iter__()` + +## `carla.ActorBlueprint` + +- `id` +- `tags` +- `contains_tag(tag)` +- `match_tags(wildcard_pattern)` +- `contains_attribute(key)` +- `get_attribute(key)` +- `set_attribute(key, value)` + +## `carla.ActorAttribute` + +- `is_modifiable` +- `type` +- `recommended_values` +- `as_bool()` +- `as_int()` +- `as_float()` +- `as_str()` +- `as_color()` +- `__eq__()` +- `__ne__()` +- `__nonzero__()` +- `__bool__()` +- `__int__()` +- `__float__()` +- `__str__()` + +## `carla.Actor` + +- `id` +- `type_id` +- `get_world()` +- `get_location()` +- `get_transform()` +- `set_location(location)` +- `set_transform(transform)` +- `destroy()` + +## `carla.Vehicle(carla.Actor)` + +- `apply_control(vehicle_control)` +- `set_autopilot(enabled=True)` + +## `carla.Sensor(carla.Actor)` + +- `listen(callback_function)` + +## `carla.Image` + +- `frame_number` +- `width` +- `height` +- `type` +- `fov` +- `raw_data` + +## `carla.VehicleControl` + +- `throttle` +- `steer` +- `brake` +- `hand_brake` +- `reverse` + +## `carla.Location` + +- `x` +- `y` +- `z` + +## `carla.Rotation` + +- `pitch` +- `yaw` +- `roll` + +## `carla.Transform` + +- `location` +- `rotation` + +## `carla.Color` + +- `r` +- `g` +- `b` diff --git a/PythonAPI/source/libcarla/Blueprint.cpp b/PythonAPI/source/libcarla/Blueprint.cpp index 9502921eb..897f55794 100644 --- a/PythonAPI/source/libcarla/Blueprint.cpp +++ b/PythonAPI/source/libcarla/Blueprint.cpp @@ -113,23 +113,22 @@ void export_blueprint() { .add_property("id", +[](const cc::ActorBlueprint &self) -> std::string { return self.GetId(); }) + .add_property("tags", &cc::ActorBlueprint::GetTags) .def("contains_tag", &cc::ActorBlueprint::ContainsTag) .def("match_tags", &cc::ActorBlueprint::MatchTags) - .def("get_tags", &cc::ActorBlueprint::GetTags) .def("contains_attribute", &cc::ActorBlueprint::ContainsAttribute) .def("get_attribute", +[](const cc::ActorBlueprint &self, const std::string &id) -> cc::ActorAttribute { return self.GetAttribute(id); }) .def("set_attribute", &cc::ActorBlueprint::SetAttribute) - .def("match_tags", &cc::ActorBlueprint::MatchTags) .def(self_ns::str(self_ns::self)) ; class_>("BlueprintLibrary", no_init) - .def("filter", &cc::BlueprintLibrary::Filter) .def("find", +[](const cc::BlueprintLibrary &self, const std::string &key) -> cc::ActorBlueprint { return self.at(key); }) + .def("filter", &cc::BlueprintLibrary::Filter) .def("__getitem__", +[](const cc::BlueprintLibrary &self, size_t pos) -> cc::ActorBlueprint { return self.at(pos); }) diff --git a/Unreal/CarlaUE4/Plugins/Carla/Source/Carla/Settings/CarlaSettings.cpp b/Unreal/CarlaUE4/Plugins/Carla/Source/Carla/Settings/CarlaSettings.cpp index 805ef1254..87b049be3 100755 --- a/Unreal/CarlaUE4/Plugins/Carla/Source/Carla/Settings/CarlaSettings.cpp +++ b/Unreal/CarlaUE4/Plugins/Carla/Source/Carla/Settings/CarlaSettings.cpp @@ -198,6 +198,7 @@ void UCarlaSettings::LoadSettings() } uint32 Value; if (FParse::Value(FCommandLine::Get(), TEXT("-world-port="), Value) || + FParse::Value(FCommandLine::Get(), TEXT("-carla-port="), Value) || FParse::Value(FCommandLine::Get(), TEXT("-carla-world-port="), Value)) { WorldPort = Value; bUseNetworking = true; diff --git a/mkdocs.yml b/mkdocs.yml index 3a366e59b..f6bfa3e71 100644 --- a/mkdocs.yml +++ b/mkdocs.yml @@ -7,10 +7,10 @@ pages: - Home: 'index.md' - Quick start: - 'Getting started': 'getting_started.md' - - 'Running the simulator': 'running_simulator_standalone.md' - - 'Connecting a Python client': 'connecting_the_client.md' + # - 'Running the simulator': 'running_simulator_standalone.md' + # - 'Connecting a Python client': 'connecting_the_client.md' - 'Configuring the simulation': 'configuring_the_simulation.md' - - 'Measurements': 'measurements.md' + # - 'Measurements': 'measurements.md' - 'Cameras and sensors': 'cameras_and_sensors.md' - 'F.A.Q.': 'faq.md' - Driving Benchmark: @@ -23,7 +23,8 @@ pages: - 'How to build on Windows': 'how_to_build_on_windows.md' - Advanced topics: - 'CARLA Settings': 'carla_settings.md' - - 'Simulator keyboard input': 'simulator_keyboard_input.md' + - 'Python API': 'python_api.md' + # - 'Simulator keyboard input': 'simulator_keyboard_input.md' - 'Running without display and selecting GPUs': 'carla_headless.md' - "How to link Epic's Automotive Materials": 'epic_automotive_materials.md' - Contributing: @@ -33,8 +34,8 @@ pages: - Development: - 'Map customization': 'map_customization.md' - 'How to add assets': 'how_to_add_assets.md' - - 'CARLA design': 'carla_design.md' - - 'CarlaServer documentation': 'carla_server.md' + # - 'CARLA design': 'carla_design.md' + # - 'CarlaServer documentation': 'carla_server.md' - 'Build system': 'build_system.md' - Appendix: - 'Driving Benchmark Sample Results Town01': 'benchmark_basic_results_town01.md'