diff --git a/Docs/python_api.md b/Docs/python_api.md index 9269d6438..20419d5ed 100644 --- a/Docs/python_api.md +++ b/Docs/python_api.md @@ -214,7 +214,7 @@ A class that contains every actor present on the scene and provides access to th

Methods

- **filter**(**self**, **wildcard_pattern**) -Filters a list of Actors matching `wildcard_pattern` against their variable **type_id** (which identifies the blueprint used to spawn them). Matching follows [fnmatch](https://docs.python.org/2/library/fnmatch.html) standard. +Filters a list of Actors matching `wildcard_pattern` against their variable __type_id__ (which identifies the blueprint used to spawn them). Matching follows [fnmatch](https://docs.python.org/2/library/fnmatch.html) standard. - **Parameters:** - `wildcard_pattern` (_str_) - **Return:** _list_ @@ -2673,21 +2673,23 @@ This method applies settings contained in an object to the simulation running an - `world_settings` (_[carla.WorldSettings](#carla.WorldSettings)_) - **Return:** _int_ - **on_tick**(**self**, **callback**) -The method will start callbacks for a defined function `callback`. It will return the ID for this callback so it can be removed with **remove_on_tick()**. +This method is used in [__asynchronous__ mode](https://[carla.readthedocs.io](#carla.readthedocs.io)/en/latest/adv_synchrony_timestep/). It starts callbacks from the client for the function defined as `callback`, and returns the ID of the callback. The function will be called everytime the server ticks. It requires a [carla.WorldSnapshot](#carla.WorldSnapshot) as argument, which can be retrieved from __wait_for_tick()__. Use __remove_on_tick()__ to stop the callbacks. - **Parameters:** - - `callback` (_[carla.WorldSnapshot](#carla.WorldSnapshot)_) – A defined function with a snapshot as compulsory parameter that will be called every tick. + - `callback` (_[carla.WorldSnapshot](#carla.WorldSnapshot)_) – Function with a snapshot as compulsory parameter that will be called when the client receives a tick. - **Return:** _int_ - **remove_on_tick**(**self**, **callback_id**) -Stops the callback for `callback_id` started with **on_tick()**. +Stops the callback for `callback_id` started with __on_tick()__. - **Parameters:** - - `callback_id` (_callback_) – The callback to be removed. + - `callback_id` (_callback_) – The callback to be removed. The ID is returned when creating the callback. - **tick**(**self**, **seconds**=10.0) -This method only has effect on synchronous mode, when both client and server move together. The client tells the server when to step to the next frame and returns the id of the newly started frame. +This method is used in [__synchronous__ mode](https://[carla.readthedocs.io](#carla.readthedocs.io)/en/latest/adv_synchrony_timestep/), when the server waits for a client tick before computing the next frame. This method will send the tick, and give way to the server. It returns the ID of the new frame computed by the server. - **Parameters:** - `seconds` (_float – seconds_) – Maximum time the server should wait for a tick. It is set to 10.0 by default. - **Return:** _int_ + - **Note:** _If no tick is received in synchronous mode, the simulation will freeze. Also, if many ticks are received from different clients, there may be synchronization issues. Please read the docs about [synchronous mode](https://[carla.readthedocs.io](#carla.readthedocs.io)/en/latest/adv_synchrony_timestep/) to learn more. +_ - **wait_for_tick**(**self**, **seconds**=10.0) -The client tells the server to pause the simulation until a **World.tick()** is received. +This method is used in [__asynchronous__ mode](https://[carla.readthedocs.io](#carla.readthedocs.io)/en/latest/adv_synchrony_timestep/). It makes the client wait for a server tick. When the next frame is computed, the server will tick and return a snapshot describing the new state of the world. - **Parameters:** - `seconds` (_float – seconds_) – Maximum time the server should wait for a tick. It is set to 10.0 by default. - **Return:** _[carla.WorldSnapshot](#carla.WorldSnapshot)_ @@ -2700,7 +2702,7 @@ The method will create, return and spawn an actor into the world. The actor will - `attachment` (_[carla.AttachmentType](#carla.AttachmentType)_) – Determines how fixed and rigorous should be the changes in position according to its parent object. - **Return:** _[carla.Actor](#carla.Actor)_ - **try_spawn_actor**(**self**, **blueprint**, **transform**, **attach_to**=None, **attachment**=Rigid) -Same as **spawn_actor()** but returns None on failure instead of throwing an exception. +Same as __spawn_actor()__ but returns None on failure instead of throwing an exception. - **Parameters:** - `blueprint` (_[carla.ActorBlueprint](#carla.ActorBlueprint)_) – The reference from which the actor will be created. - `transform` (_[carla.Transform](#carla.Transform)_) – Contains the location and orientation the actor will be spawned with. @@ -2755,7 +2757,7 @@ Provided a landmark, returns the traffic sign object it describes. - `landmark` (_[carla.Landmark](#carla.Landmark)_) – The landmark object describing a traffic sign. - **Return:** _[carla.TrafficSign](#carla.TrafficSign)_ - **get_random_location_from_navigation**(**self**) -This can only be used with walkers. It retrieves a random location to be used as a destination using the **go_to_location()** method in [carla.WalkerAIController](#carla.WalkerAIController). This location will be part of a sidewalk. Roads, crosswalks and grass zones are excluded. The method does not take into consideration locations of existing actors so if a collision happens when trying to spawn an actor, it will return an error. Take a look at [`spawn_npc.py`](https://github.com/carla-simulator/carla/blob/e73ad54d182e743b50690ca00f1709b08b16528c/PythonAPI/examples/spawn_npc.py#L179) for an example. +This can only be used with walkers. It retrieves a random location to be used as a destination using the __go_to_location()__ method in [carla.WalkerAIController](#carla.WalkerAIController). This location will be part of a sidewalk. Roads, crosswalks and grass zones are excluded. The method does not take into consideration locations of existing actors so if a collision happens when trying to spawn an actor, it will return an error. Take a look at [`spawn_npc.py`](https://github.com/carla-simulator/carla/blob/e73ad54d182e743b50690ca00f1709b08b16528c/PythonAPI/examples/spawn_npc.py#L179) for an example. - **Return:** _[carla.Location](#carla.Location)_ - **get_settings**(**self**) Returns an object containing some data about the simulation such as synchrony between client and server or rendering mode. @@ -2798,7 +2800,7 @@ Ensures that the time elapsed between two steps of the simulation is fixed. Set

Methods

- **\__init__**(**self**, **synchronous_mode**=False, **no_rendering_mode**=False, **fixed_delta_seconds**=0.0) -Creates an object containing desired settings that could later be applied through [carla.World](#carla.World) and its method **apply_settings()**. +Creates an object containing desired settings that could later be applied through [carla.World](#carla.World) and its method __apply_settings()__. - **Parameters:** - `synchronous_mode` (_bool_) – Set this to true to enable client-server synchrony. - `no_rendering_mode` (_bool_) – Set this to true to completely disable rendering in the simulation. diff --git a/PythonAPI/docs/world.yml b/PythonAPI/docs/world.yml index 3edcc54e7..4d8823479 100644 --- a/PythonAPI/docs/world.yml +++ b/PythonAPI/docs/world.yml @@ -71,7 +71,7 @@ - param_name: wildcard_pattern type: str doc: > - Filters a list of Actors matching `wildcard_pattern` against their variable **type_id** (which identifies the blueprint used to spawn them). Matching follows [fnmatch](https://docs.python.org/2/library/fnmatch.html) standard. + Filters a list of Actors matching `wildcard_pattern` against their variable __type_id__ (which identifies the blueprint used to spawn them). Matching follows [fnmatch](https://docs.python.org/2/library/fnmatch.html) standard. # -------------------------------------- - def_name: find return: carla.Actor @@ -143,7 +143,7 @@ doc: > Set a fixed time-step in between frames. 0.0 means variable time-step and it is the default mode. doc: > - Creates an object containing desired settings that could later be applied through carla.World and its method **apply_settings()**. + Creates an object containing desired settings that could later be applied through carla.World and its method __apply_settings()__. # -------------------------------------- - def_name: __eq__ return: bool @@ -216,18 +216,18 @@ - param_name: callback type: carla.WorldSnapshot doc: > - A defined function with a snapshot as compulsory parameter that will be called every tick. + Function with a snapshot as compulsory parameter that will be called when the client receives a tick. doc: > - The method will start callbacks for a defined function `callback`. It will return the ID for this callback so it can be removed with **remove_on_tick()**. + This method is used in [__asynchronous__ mode](https://carla.readthedocs.io/en/latest/adv_synchrony_timestep/). It starts callbacks from the client for the function defined as `callback`, and returns the ID of the callback. The function will be called everytime the server ticks. It requires a carla.WorldSnapshot as argument, which can be retrieved from __wait_for_tick()__. Use __remove_on_tick()__ to stop the callbacks. # -------------------------------------- - def_name: remove_on_tick params: - param_name: callback_id type: callback doc: > - The callback to be removed. + The callback to be removed. The ID is returned when creating the callback. doc: > - Stops the callback for `callback_id` started with **on_tick()**. + Stops the callback for `callback_id` started with __on_tick()__. # -------------------------------------- - def_name: tick return: int @@ -239,7 +239,9 @@ doc: > Maximum time the server should wait for a tick. It is set to 10.0 by default. doc: > - This method only has effect on synchronous mode, when both client and server move together. The client tells the server when to step to the next frame and returns the id of the newly started frame. + This method is used in [__synchronous__ mode](https://carla.readthedocs.io/en/latest/adv_synchrony_timestep/), when the server waits for a client tick before computing the next frame. This method will send the tick, and give way to the server. It returns the ID of the new frame computed by the server. + note: > + If no tick is received in synchronous mode, the simulation will freeze. Also, if many ticks are received from different clients, there may be synchronization issues. Please read the docs about [synchronous mode](https://carla.readthedocs.io/en/latest/adv_synchrony_timestep/) to learn more. # -------------------------------------- - def_name: wait_for_tick return: carla.WorldSnapshot @@ -251,7 +253,7 @@ doc: > Maximum time the server should wait for a tick. It is set to 10.0 by default. doc: > - The client tells the server to pause the simulation until a **World.tick()** is received. + This method is used in [__asynchronous__ mode](https://carla.readthedocs.io/en/latest/adv_synchrony_timestep/). It makes the client wait for a server tick. When the next frame is computed, the server will tick and return a snapshot describing the new state of the world. # -------------------------------------- - def_name: spawn_actor return: carla.Actor @@ -299,7 +301,7 @@ doc: > Determines how fixed and rigorous should be the changes in position according to its parent object. doc: > - Same as **spawn_actor()** but returns None on failure instead of throwing an exception. + Same as __spawn_actor()__ but returns None on failure instead of throwing an exception. # -------------------------------------- - def_name: get_actor return: carla.Actor @@ -387,7 +389,7 @@ - def_name: get_random_location_from_navigation return: carla.Location doc: > - This can only be used with walkers. It retrieves a random location to be used as a destination using the **go_to_location()** method in carla.WalkerAIController. This location will be part of a sidewalk. Roads, crosswalks and grass zones are excluded. The method does not take into consideration locations of existing actors so if a collision happens when trying to spawn an actor, it will return an error. Take a look at [`spawn_npc.py`](https://github.com/carla-simulator/carla/blob/e73ad54d182e743b50690ca00f1709b08b16528c/PythonAPI/examples/spawn_npc.py#L179) for an example. + This can only be used with walkers. It retrieves a random location to be used as a destination using the __go_to_location()__ method in carla.WalkerAIController. This location will be part of a sidewalk. Roads, crosswalks and grass zones are excluded. The method does not take into consideration locations of existing actors so if a collision happens when trying to spawn an actor, it will return an error. Take a look at [`spawn_npc.py`](https://github.com/carla-simulator/carla/blob/e73ad54d182e743b50690ca00f1709b08b16528c/PythonAPI/examples/spawn_npc.py#L179) for an example. # -------------------------------------- - def_name: get_settings return: carla.WorldSettings