World

class BoundingBox

A rectangular region

__init__(*args, **kwargs)

Overloaded function.

1. __init__(min_x: float, max_x: float, min_y: float, max_y: float) -> None

Creates a rectangular region

Parameters:

• min_x – Minimal x coordinates

• max_x – Maximal x coordinate

• min_y – Minimal y coordinate

• max_y – Maximal y coordinate

2. __init__(p1: Vector2, p2: Vector2) -> None

Creates a rectangular region

Parameters:

• p1 – Bottom-left corner

• p2 – Top-right corner

static schema() → object

class Entity

Super-class that adds a unique ID to world entities.

This unique ID should not be fed to navigation behaviors, but only used internally by the simulation, for instance, to identify entities in a UI.

has_been_in_collision_since(time: float) → bool

Determines if the entity has been in collision at least once since the given time.

Parameters:

time – The time

Returns:

True if been in collision since, False otherwise.

property last_collision_time

Type:

float

Returns the last collision time

class Obstacle

A static obstacle with circular shape

__init__(*args, **kwargs)

Overloaded function.

1. __init__(position: Vector2, radius: float) -> None

Constructs a new instance.

Parameters:

• position – The position of the circle

• radius – The radius of the circle

2. __init__(disc: navground.core.Disc) -> None

Constructs a new instance.

Parameters:

disc – A disc

dump() → str

Dumps the object to a YAML-string.

Returns:

The YAML representation

Return type:

str

static load(value: str) → object

Load a obstacle modulation from a YAML string.

Returns:

The loaded obstacle or None if loading fails.

Return type:

Obstacle| None

static schema() → object

Returns the json-schema

Returns:

json-schema

Return type:

dict[str, typing.Any]

property disc

Type:

navground.core.Disc

The disc.

class Wall

A static wall.

Currently, only line segment are valid shapes of walls.

__init__(*args, **kwargs)

Overloaded function.

1. __init__(p1: Vector2, p2: Vector2) -> None

Constructs a new instance.

Parameters:

• p1 – The line segment start vertex

• p2 – The line segment end vertex

2. __init__(line: navground.core.LineSegment) -> None

Constructs a new instance.

Parameters:

ls – A line segment

dump() → str

Dumps the object to a YAML-string.

Returns:

The YAML representation

Return type:

str

static load(value: str) → object

Load a wall modulation from a YAML string.

Returns:

The loaded wall or None if loading fails.

Return type:

Wall| None

static schema() → object

Returns the json-schema

Returns:

json-schema

Return type:

dict[str, typing.Any]

property line

Type:

navground.core.LineSegment

The line segment

class World

__init__() → None

Constructs a new instance.

actuate(time_step: float) → None

Actuate then controllers and perform collisions resolutions.

Parameters:

time_step – The duration of each time step

add_agent(agent: object) → None

Adds an agent to the world.

Parameters:

agent – The agent

add_callback(callback: Callable[[], None]) → None

Adds a callback to be executed after each simulation step.

Parameters:

value – The callback

add_obstacle(*args, **kwargs)

Overloaded function.

1. add_obstacle(disc: navground.core.Disc) -> None

Adds a disc the world as a static obstacle

Parameters:

disc – The disc

2. add_obstacle(obstacle: navground.sim.Obstacle) -> None

Adds a static obstacle the world

Parameters:

obstacle – The obstacle

add_random_obstacles(number: int, min_radius: float, max_radius: float, margin: float = 0.0, max_tries: int = 1000) → None

Adds a random obstacles in the world bounding box

It iteratively try to sample a disc that is far enough of any other item. If the sampling fails, it counts as a try and the process stop after either enough obstacles have been added or enough tries performed.

Parameters:

• number – The number of obstacles

• min_radius – The minimum radius of obstacles

• max_radius – The maximum radius of obstacles

• margin – The minimal distance to other obstacles or agents. For agents, it’s additional to their safety margin.

• max_tries – The maximum tries before terminating.

add_wall(*args, **kwargs)

Overloaded function.

1. add_wall(line: navground.core.LineSegment) -> None

Adds a line to the world as a wall

Parameters:

line – The line

2. add_wall(wall: navground.sim.Wall) -> None

Adds a wall to the world

Parameters:

wall – The wall

agents_are_idle() → bool

Check if all agents are idle (i.e., their tasks are done and their controller are idle).

Returns:

True if all agents are idle

agents_are_idle_or_stuck() → bool

Check if all agents are idle or stuck (i.e., they are no moving because they task is done or they are deadlocked)

Returns:

True if all agents are idle or stuck

clear_collisions() → None

Clear collisions

compute_safety_violation(agent: navground.sim.NativeAgent, safety_margin: float | None = None) → float

Calculates the safety violation, i.e. the maximal penetration of a neighbor or obstacle in the safety margin of the agent.

Parameters:

• agent – The agent

• safety_margin – The safety margin. If not set, it will default to the agent’s behavior safety margin.

Returns:

The safety violation or 0 if no violation.

copy_random_generator(world: navground.sim.World) → None

Copy the random generator from another world

Parameters:

world – The world

dump() → str

Dumps the object to a YAML-string.

Returns:

The YAML representation

Return type:

str

get_agents_in_collision(duration: float = 0.0) → list[navground.sim.NativeAgent]

Gets the agents that had a collision after now - duration.

Parameters:

duration – The duration

Returns:

The agents in collision.

get_agents_in_deadlock(duration: float = 0.0) → list[navground.sim.NativeAgent]

Gets the agents that are in stuck since now - duration.

Parameters:

duration – The duration

Returns:

The agents in deadlock.

get_agents_in_region(bounding_box: navground.sim.BoundingBox) → list[navground.sim.NativeAgent]

Gets all agents in a bounding box.

Parameters:

bb – The bounding box specified in world-fixed coordinates

Returns:

All agents that lie in a bounding box.

get_discs_in_region(bounding_box: navground.sim.BoundingBox, ignore_lattice: bool = False) → list[navground.core.Disc]

Gets all agents in a bounding box.

Parameters:

• bb – The bounding box specified in world-fixed

• ignore_lattice – Whether to ignore the lattice when computing neighbors

Returns:

All obstacles that lie in a bounding box

get_entity(uid: int) → navground.sim.Entity

Find an entity by identifier

Parameters:

uid – The entity uid

Returns:

The entity or nullptr if not found.

get_lattice(axis: int) → tuple[float, float] | None

Gets the periodic lattice.

Parameters:

axis – The axis (0 for x, 1 for y)

Returns:

An optional tuple of points that define a periodic lattice that wraps the selected axis.

get_lattice_grid(include_zero: bool = True, c8: bool = True) → list[Vector2]

The N=0, 1, or 2 vectors that define the lattice, e.g., {delta_x, -delta_x} if only the axis=0 lattice is set.

Parameters:

• include_zero – Whether to include the zero vector

• c8 – Whether to use 8-connectivity instead of 4-connectivity

Returns:

A vector of 2D vectors

get_line_obstacles_in_region(bounding_box: navground.sim.BoundingBox) → list[navground.core.LineSegment]

Gets all walls in a bounding box.

Parameters:

bb – The bounding box specified in world-fixed

Returns:

All walls that lie in a bounding box

get_neighbors(agent: navground.sim.NativeAgent, distance: float, ignore_lattice: bool = False) → list[navground.core.Neighbor]

Gets all neighbor of an agent

Parameters:

• agent – The agent

• distance – The radius of the neighborhood

• ignore_lattice – Whether to ignore the lattice when computing neighbors

Returns:

All neighbor within a circle of radius radius centered around the agent.

get_obstacles_in_region(bounding_box: navground.sim.BoundingBox) → list[navground.sim.Obstacle]

Gets all obstacles in a bounding box.

Parameters:

bb – The bounding box specified in world-fixed coordinates

Returns:

All obstacles that lie in a bounding box.

in_collision(e1: navground.sim.Entity, e2: navground.sim.Entity) → bool

Check if two entities are currently in collision

Parameters:

• e1 – The first entity

• e2 – The second entity

Returns:

True if they are in collision.

index_of_agent(agent: navground.sim.NativeAgent) → int | None

Searches for the index of an agent.

Parameters:

agent – The agent

Returns:

The index of this agent in the world agents list or null if not found.

static load(value: str) → object

Load a world modulation from a YAML string.

Returns:

The loaded world or None if loading fails.

Return type:

World| None

record_collision(e1: navground.sim.Entity, e2: navground.sim.Entity) → None

Record the collision between two entities

Parameters:

• e1 – The first entity

• e2 – The second entity

reset_callbacks() → None

Clear all the callbacks

run(steps: int, time_step: float) → None

Updates the world for one or more time steps

Parameters:

• steps – The number of steps

• time_step – The duration of each time step

run_until(condition: Callable[[], bool], time_step: float) → None

Updates the world until a condition is satisfied

Parameters:

• condition – The condition

• time_step – The duration of each time step

static schema() → object

Returns the json-schema

Returns:

json-schema

Return type:

dict[str, typing.Any]

set_lattice(axis: int, value: tuple[float, float] | None) → None

Sets the periodic lattice.

Parameters:

• axis – The axis (0 for x, 1 for y)

• value – An optional tuple of points that define a periodic lattice that wraps the selected axis. Pass none to unset the lattice and remove wrapping.

set_termination_condition(condition: Callable[[navground.sim.NativeWorld], bool] | None) → None

Sets a condition to terminate simulations

Parameters:

value – The desired condition.

should_terminate() → bool

Checks whether the simulation should terminate

Returns:

True if a termination condition is set and evaluates to true.

snap_twists_to_zero(epsilon: float = 1e-06) → None

Snap agents’ twists smaller than epsilon to zero.

Parameters:

epsilon – The tolerance

space_agents_apart(minimal_distance: float = 0, with_safety_margin: bool = False, max_iterations: int = 10) → None

Move agents so that they do not overlap anymore with themselves or with any obstacle

Parameters:

• minimal_distance – The minimal distance

• with_safety_margin – Whether the safety margin should be added to the minimal distance

• max_iterations – The maximal number of iterations to perform.

subdivide_bounding_box(bounding_box: navground.sim.BoundingBox, ignore_lattice: bool = False) → list[tuple[Vector2, navground.sim.BoundingBox]]

update(time_step: float) → None

Updates world for a single time step.

Parameters:

time_step – The time step

update_dry(time_step: float, advance_time: bool = True) → None

Updates world for a single time step without actuation and collisions resolution.

Parameters:

• time_step – The time step

• advance_time – Whenever to advance time too.

property agents

Type:

list[navground.sim.NativeAgent]

All agents in this world.

property bounding_box

Type:

navground.sim.BoundingBox

The bounding box.

property collisions

Type:

set[tuple[navground.sim.Entity, navground.sim.Entity]]

The colliding pairs computed during the last simulation step.

property discs

Type:

list[navground.core.Disc]

All disc shaped static obstacles in this world.

Parameters:

ignore_lattice – whether to ignore the lattice

property has_termination_condition

Type:

bool

Returns whether there is a termination condition set.

Returns:

True if a termination condition has been set.

property line_obstacles

Type:

list[navground.core.LineSegment]

All line obstacles in this world.

property minimal_bounding_box

Type:

navground.sim.BoundingBox

The bounding box that contains all agents, obstacles and walls.

property obstacles

Type:

list[navground.sim.Obstacle]

All obstacles in this world.

property random_generator

Type:

object

The random generator.

Return type:

numpy.random.Generator

property seed

Type:

int

The random seed.

property step

Type:

int

The simulation step.

property time

Type:

float

The simulation time.

property walls

Type:

list[navground.sim.Wall]

All walls in this world.