Base class

class Heading

Different behavior variants for the angular motion when it is no constrained by the kinematics or already specified by the current target.

They ability to apply them depends on the kinematics and on the current target.

idle = <Heading.idle: 0>

never turn

target_point = <Heading.target_point: 1>

turn towards the target position

target_angle = <Heading.target_angle: 2>

turn towards the target orientation

target_angular_speed = <Heading.target_angular_speed: 3>

follow a target angular speed

velocity = <Heading.velocity: 4>

turn towards the velocity orientation. This is the only behavior available to constrained kinematics.

__init__(value: int) → None

property name

Type:

str

property value

Type:

int

class Behavior

This class describes a generic behavior to reach a target position avoiding collision.

Users should not instantiate this class, which will not make the agent move, but one of its concrete sub-classes equipped with the desired navigation algorithms, which are implemented by overriding any of the (virtual) methods listed in compute_cmd_internal.

The following describes the typical usage of a behavior.

At initialization

1. select the concrete behavior, the agent’s size (agents are shaped like discs), and Kinematics;

2. configure the generic parameters: optimal_speed, horizon, safety_margin rotation_tau, and heading_behavior;

3. configure the specific parameters of the concrete behavior.

At regular time intervals

1. update the agent’s state with pose and twist (or other convenience methods)

2. update the target with target

3. update the environment state get_environment_state()

4. ask for a control commands by calling compute_cmd()

5. actuate the control commands through user code

__init__(kinematics: navground.core.Kinematics = None, radius: float = 0) → None

Constructs a new instance.

Parameters:

• kinematics – The kinematics of the agent.

• radius – The radius of the agent.

actuate(*args, **kwargs)

Overloaded function.

1. actuate(twist: navground.core.Twist2, time_step: float, enforce_feasibility: bool = False) -> None

Actuate a twist command, integrating using Pose2.integrate()

Parameters:

• twist_cmd – The twist

• time_step – The time step

• enforce_feasibility – Whether to enforce that the command is kinematically feasible

2. actuate(time_step: float) -> None

Convenience method to actuate the stored actuated twist command,

Parameters:

time_step – The time step

add_modulation(value: object) → None

Adds a modulation.

Parameters:

value – The modulation to add

check_if_target_satisfied() → bool

Check if the current target has been satisfied

Returns:

True if the current target has been satisfied.

clear_modulations() → None

Removes all modulations

cmd_twist_along_path(path: navground.core.Path, speed: float, time_step: float) → navground.core.Twist2

Compute a command to follow a path

Users may override it to specialize a Behavior.

The base implementation uses a carrot planner to computes a target velocity, and then calls cmd_twist_towards_velocity.

Parameters:

• path – The desired path in world-fixed frame

• speed – The desired speed

• time_step – The time step

Returns:

The command twist.

cmd_twist_towards_angular_speed(angular_speed: float, time_step: float) → navground.core.Twist2

Computes a command to turn at a desired angular speed

Users may override it to specialize a Behavior.

The base implementation returns the nearest feasible twist to a twist with null velocity and desired angular speed.

Parameters:

• angular_speed – The desired angular speed

• time_step – The time step

Returns:

The command twist.

cmd_twist_towards_orientation(orientation: float, angular_speed: float, time_step: float) → navground.core.Twist2

Computes a command to turn towards a desired orientation

Users may override it to specialize a Behavior.

The base implementation:

1. computes a desired angular speed to rotate in rotation_tau time towards the desired orientation

2. calls cmd_twist_towards_angular_speed

Parameters:

• orientation – The desired orientation in world-fixed frame

• angular_speed – The desired angular speed

• time_step – The time step

Returns:

The command twist.

cmd_twist_towards_point(point: Vector2, speed: float, time_step: float) → navground.core.Twist2

Computes a command to move towards a desired position

Users may override it to specialize a Behavior.

The base implementation:

1. calls desired_velocity_towards_point to compute a desired velocity

2. calls twist_towards_velocity to compute a desired twist

3. returns the nearest feasible twist.

Parameters:

• point – The desired position in world-fixed frame

• speed – The desired speed

• time_step – The time step

Returns:

The command twist.

cmd_twist_towards_pose(pose: navground.core.Pose2, speed: float, angular_speed: float, time_step: float) → navground.core.Twist2

Computes a command to move towards a desired pose

Users may override it to specialize a Behavior.

The base implementation ignores the orientation, calling call cmd_twist_towards_point, to first reach the desired position and then rotate in place to reach the desired orientation.

Parameters:

• pose – The desired pose in world-fixed frame

• speed – The desired speed

• angular_speed – The desired angular speed

• time_step – The time step

Returns:

The command twist.

cmd_twist_towards_stopping(time_step: float) → navground.core.Twist2

Computes a command to stop

Users may override it to specialize a Behavior.

The base implementation returns the null twist.

Parameters:

time_step – The time step

Returns:

The command twist.

cmd_twist_towards_velocity(velocity: Vector2, time_step: float) → navground.core.Twist2

Computes a command to turn towards a desired orientation

Users may override it to specialize a Behavior.

The base implementation:

1. calls desired_velocity_towards_velocity to compute a desired velocity

2. calls twist_towards_velocity to compute a desired twist

3. returns the nearest feasible twist.

Parameters:

• velocity – The velocity in world-fixed frame

• time_step – The time step

Returns:

The command twist.

compute_cmd(time_step: float, frame: navground.core.Frame | None = None, enforce_feasibility: bool = False) → navground.core.Twist2

Query the behavior to get a control command

Before calling this method, update the state using methods such as pose, and twist and set the target target.

Behaviors may use caching to speed up the next queries if the state does not change.

Modulations are applied as wrappers/context modifiers: right before evaluating the behavior in compute_cmd_internal, it will call BehaviorModulation.pre() for any modulation in modulations, and right after BehaviorModulation.post() but in reverse order.

Parameters:

• time_step – The control time step. Not all behavior use it but some may use it, for example, to limit accelerations.

• frame – An optional desired frame of reference for the command.

• enforce_feasibility – Whether to enforce that the command is kinematically feasible

Returns:

The control command as a twist in the specified frame.

compute_cmd_internal(time_step: float) → navground.core.Twist2

Computes the control command.

This is a virtual protected that sub-classes may override to define a behavior and is not part of the public API. Users should call compute_cmd() instead.

The base implementation checks for a valid target:

1. position along a path => calls cmd_twist_along_path

2. pose => calls cmd_twist_towards_pose

3. position => calls cmd_twist_towards_point

4. orientation => calls cmd_twist_towards_orientation

5. velocity => calls cmd_twist_towards_velocity

6. angular speed => calls cmd_twist_towards_angular_speed

7. else => calls cmd_twist_towards_stopping.

To specialize a Behavior, users may override this or any of the methods listed above. They may also override the following internal methods:

• desired_velocity_towards_point

• desired_velocity_towards_velocity

• twist_towards_velocity

The command should be kinematically feasible. The base implementation does not guaranteed it, delegating the check to the methods listed above.

Parameters:

time_step – The time step

Returns:

The command in the desired frame.

desired_velocity_towards_point(point: Vector2, speed: float, time_step: float) → Vector2

Computes a control velocity towards a desired position

Users may override it to specialize a Behavior.

The base implementation returns a null vector.

Parameters:

• point – The desired point in world-fixed frame

• speed – The desired speed

• time_step – The time step

Returns:

A velocity in world-fixed frame

desired_velocity_towards_velocity(velocity: Vector2, time_step: float) → Vector2

Computes a control velocity towards a desired velocity

Users may override it to specialize a Behavior.

The base implementation returns a null vector.

Parameters:

• velocity – The desired velocity in world-fixed frame

• time_step – The time step

Returns:

A velocity in world-fixed frame

dump(::core::Behavior) → str

Dumps the object to a YAML-string.

Returns:

The YAML representation

Return type:

str

estimate_time_until_target_satisfied() → float

Estimate how much time before the target is satisfied

Returns:

A positive value if the target is not yet satisfied, else 0.

feasible_angular_speed(value: float) → float

Clamp an angular speed in the range of feasible values given by the kinematics.

Parameters:

value – The desired value

Returns:

the nearest feasible value

feasible_speed(value: float) → float

Clamp a speed in the range of feasible values given by the kinematics.

Parameters:

value – The desired value

Returns:

the nearest feasible value

feasible_twist(value: navground.core.Twist2) → navground.core.Twist2

Clamp an twist in the range of feasible values given by the kinematics.

Parameters:

value – The desired value

Returns:

the nearest feasible value

feasible_twist_from_current(value: navground.core.Twist2, time_step: float) → navground.core.Twist2

Computes the nearest feasible twist given the kinematics and the current twist over a time step

Parameters:

• value – The desired value

• time_step – The time step

Returns:

the nearest feasible value

get(name: str) → bool | int | float | str | Vector2 | list[bool] | list[int] | list[float] | list[str] | list[Vector2]

Gets the value of the specified property.

Parameters:

name – The name of the property

Raise:

std::runtime_error A runtime error if no property is found.

Returns:

The value of the property

get_actuated_twist(frame: navground.core.Frame = navground.core.Frame.absolute) → navground.core.Twist2

Gets the last actuated twist.

Parameters:

frame – The desired frame of reference.

Returns:

The actuated twist.

get_environment_state() → navground.core.EnvironmentState

Gets the environment state.

Returns:

The environment state.

get_target_angular_speed() → float

Returns the nearest feasible angular speed to target’s angular speed, if defined, else to the behavior own optimal angular speed.

Returns:

The angular speed.

get_target_direction(frame: navground.core.Frame = navground.core.Frame.absolute) → Vector2 | None

Returns the direction towards the target’s position if not satisfied, or the target’s direction if defined, else null.

Parameters:

frame – The desired frame

Returns:

The normalized direction in the desired frame

get_target_distance(ignore_tolerance: bool = False) → float | None

Returns the distance to the target point, if valid, else null.

Parameters:

ignore_tolerance – Whether to ignore the target tolerance

Returns:

The distance.

get_target_orientation(frame: navground.core.Frame) → float | None

Returns the target’s orientation if not satisfied, else null.

Parameters:

frame – The desired frame

Returns:

The orientation in the desired frame

get_target_position(frame: navground.core.Frame = navground.core.Frame.absolute) → Vector2 | None

Returns the target’s position if not satisfied, else null.

Parameters:

frame – The desired frame

Returns:

The position in the desired frame

get_target_speed() → float

Returns the nearest feasible speed to target’s speed, if defined, else to the behavior own optimal speed.

Returns:

The speed

get_target_velocity(frame: navground.core.Frame = navground.core.Frame.absolute) → Vector2

Gets the current target velocity.

Multiplication of get_target_direction() by get_target_speed(). Returns a zero vector if the target direction is undefined.

Parameters:

frame – The desired frame

Returns:

The velocity in the desired frame.

get_twist(frame: navground.core.Frame = navground.core.Frame.absolute) → navground.core.Twist2

Gets the current twist.

Parameters:

frame – The desired frame of reference.

Returns:

The current twist.

get_velocity(frame: navground.core.Frame = navground.core.Frame.absolute) → Vector2

Convenience method to get the current velocity. See get_twist()

Parameters:

frame – The desired frame of reference.

Returns:

The velocity.

static has_type(name: str) → bool

Check whether a type name has been registered.

Parameters:

type – The associated type name.

Returns:

True if the type name has been registered.

static load(value: str) → object

Load a behavior modulation from a YAML string.

Returns:

The loaded behavior or None if loading fails.

Return type:

Behavior| None

static make_type(name: str) → object

Create an object of a sub-class selected by name.

Parameters:

type – The associated type name.

Returns:

An object of a registered sub-class or None in case the desired name is not found.

static register_schema() → object

Returns the json-schema that includes registered components.

Returns:

“anyOf” json-schema of all registered components.

Return type:

dict[str, typing.Any]

remove_modulation(value: object) → None

Removes a modulation.

Parameters:

value – The modulation to remove

static schema(reference_register_schema: bool = True, type: str | None = None) → object

Returns the json-schema of a component

Returns an empty dictionary if a not registered type is requested.

Parameters:

• reference_register_schema – Whether to reference registered components schema in the base class schema.

• type (str) – An optional registered type. If not specified, it returns the schema of the base class.

Returns:

A json-schema of the registered class

Return type:

dict[str, typing.Any]

set(name: str, value: bool | int | float | str | Vector2 | list[bool] | list[int] | list[float] | list[str] | list[Vector2]) → None

Set the value of a named property. Fails silently if no property can be found or if the value has a non-compatible type.

Parameters:

• name – The name of the property

• value – The desired value for the property

set_state_from(other: navground.core.Behavior) → None

Clone the state of this behavior from another behavior

Parameters:

other – The other behavior

set_velocity(velocity: Vector2, frame: navground.core.Frame = navground.core.Frame.absolute) → None

Convenience method to set the current velocity. See twist

Parameters:

• value – The velocity

• frame – The desired frame of reference.

to_frame(value: navground.core.Twist2, frame: navground.core.Frame) → navground.core.Twist2

Convert a twist to a reference frame.

Parameters:

• value – The original twist.

• frame – The desired frame of reference

Returns:

The twist in the desired frame of reference.

twist_from_wheel_speeds(value: list[float]) → navground.core.Twist2

Convenience method to transform from wheel speeds to twist.

If the agent is not wheeled (Kinematics.is_wheeled()), an zero twist is returned.

Parameters:

value – The wheel speeds

Returns:

The corresponding twist.

twist_towards_velocity(velocity: Vector2) → navground.core.Twist2

Computes a twist to reach a control velocity

This method assumes that the control velocity is safe. Use it to convert a velocity to a twist once you have computed (using, e.g., desired_velocity_towards_point or desired_velocity_towards_velocity) a safe control velocity.

Parameters:

velocity – The control velocity in world-fixed frame

Returns:

A command twist.

wheel_speeds_from_twist(value: navground.core.Twist2) → list[float]

Convenience method to transform from twist to wheel speeds.

If the agent is not wheeled (Kinematics.is_wheeled()), an empty vector is returned.

Parameters:

value – The twist

Returns:

The corresponding wheel speeds.

property actuated_twist

Type:

navground.core.Twist2

The last actuated twist.

Parameters:

frame – the desired frame of reference.

property actuated_wheel_speeds

Type:

list[float]

Convenience method to get the last actuated wheel speeds from actuated_twist.

If the agent is not wheeled (Kinematics.is_wheeled()), an empty vector is returned.

property angular_speed

Type:

float

Convenience method to get the current the angular speed.

property assume_cmd_is_actuated

Type:

bool

Whether to assume that the compute command will be actuated as it is.

if set, behavior will assume that the control command computed by compute_cmd() be actuated, therefore setting actuated_twist to that value. if not set, the user should set behavior.actuated_twist before querying for a new control commands: some behavior use the old actuated control command to compute smoother controls.

property desired_velocity

Type:

Vector2

The last computed desired velocity.

property efficacy

Type:

float

The efficacy: the projection of the current velocity on the ideal velocity (ignoring obstacles) towards the target.

a value of 1.0 denotes ideal efficacy, value of 0.0 that the agent is stuck.

property environment_state

Type:

navground.core.EnvironmentState

The environment state.

property heading_behavior

Type:

navground.core.Behavior.Heading

The heading behavior:

property horizon

Type:

float

The horizon: the size of the portion of environment around the agent considered when computing possible collisions. larger values generally lead to a more computationally expensive compute_cmd() but fewer deadlocks and less jamming.

property is_stuck

Type:

bool

Determines if the agent is stuck: if should move but it is still.

property kinematics

Type:

navground.core.Kinematics

The kinematics.

property max_angular_speed

Type:

float

The maximal angular speed speed.

property max_speed

Type:

float

The maximal speed.

property modulations

Type:

list[navground.core.BehaviorModulation]

The modulations applied to this behavior

property optimal_angular_speed

Type:

float

The desired optimal angular speed.

if not configured through optimal_angular_speed, it will return set to max_angular_speed.

property optimal_speed

Type:

float

The desired optimal speed.

if not configured through optimal_speed, it return max_speed.

property orientation

Type:

float

Convenience method to get the current orientation. See pose.

property path_look_ahead

Type:

float

The path look-ahead distance

property path_tau

Type:

float

The path relaxation time

property pose

Type:

navground.core.Pose2

The current pose in the world-fixed frame.

property position

Type:

Vector2

Convenience method to get the current position in the world-fixed frame. See pose.

property properties

Type:

dict[str, navground.core.Property]

The registered properties

property radius

Type:

float

The radius of the agent.

property rotation_tau

Type:

float

The relaxation time to rotate towards a desired orientation.

the default behaviors applies a p control to rotations, e.g., \(\omega = \frac{\delta \theta}{\tau_\textrm{rot}}\)

property safety_margin

Type:

float

The minimal safety margin to keep away from obstacles

property social_margin

Type:

navground.core.SocialMargin

The behavior social margin modulation

property speed

Type:

float

Convenience method to get the current speed. See get_twist()

property target

Type:

navground.core.Target

The target.

property target_ref

Type:

navground.core.Target

A reference to the target.

property twist

Type:

navground.core.Twist2

The current twist.

Parameters:

frame – the desired frame of reference.

property type

Type:

str

The name associated to the type of an object

property velocity

Type:

Vector2

Convenience method to get the current velocity. See get_twist()

Parameters:

frame – The desired frame of reference.

property wheel_speeds

Type:

list[float]

Convenience method to get the current wheel speeds. See get_twist()