Base class

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

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

select the concrete behavior, the agent’s size (agents are shaped like discs), and Kinematics;
configure the generic parameters: optimal_speed, horizon, safety_margin rotation_tau, and heading_behavior;
configure the specific parameters of the concrete behavior.
call prepare() to finalize the initialization

At regular time intervals

update the agent’s state with pose and twist (or other convenience methods)
update the target with target
update the environment state get_environment_state()
ask for a control commands by calling compute_cmd()
actuate the control commands through user code

At the termination

call close()

__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.

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

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

close() → None#

Clean-up the behavior before termination.

Call it once the behavior is not used anymore.

The base class implementation does nothing. Override it to add any logic to clean-up steps performed in prepare().

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:

computes a desired angular speed to rotate in rotation_tau time towards the desired orientation
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:

calls desired_velocity_towards_point to compute a desired velocity
calls twist_towards_velocity to compute a desired twist
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:

calls desired_velocity_towards_velocity to compute a desired velocity
calls twist_towards_velocity to compute a desired twist
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:

position along a path => calls cmd_twist_along_path
pose => calls cmd_twist_towards_pose
position => calls cmd_twist_towards_point
orientation => calls cmd_twist_towards_orientation
velocity => calls cmd_twist_towards_velocity
angular speed => calls cmd_twist_towards_angular_speed
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() → 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

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_property_type_name(name: str) → str#

Gets the type of a property.

Parameters:: name – The name of the property
Returns:: The property type name or an empty string if the property is not defined.

get_target_angular_direction(ignore_tolerance: bool = False) → int | 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_angular_distance(ignore_tolerance: bool = False) → float#

Returns the distance to the target orientation, if valid, else 0.

Parameters:: ignore_tolerance – Whether to ignore the target tolerance
Returns:: The angular distance.

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_angular_velocity(ignore_tolerance: bool = False) → float#

Gets the current target angular velocity.

Multiplication of get_target_angular_direction() by get_target_angular_speed(). Returns zero if the target angular direction is undefined.

Note that this returns a signed value, while get_target_angular_speed(), returns the absolute value instead. Moreover considers (angular) tolerances, while get_target_angular_speed() not, just like get_target_velocity() vs get_target_speed().

Parameters:: ignore_tolerance – Whether to ignore the target tolerance
Returns:: The angular velocity z-component.

get_target_direction(frame: navground.core.Frame = navground.core.Frame.absolute, ignore_tolerance: bool = False) → 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
ignore_tolerance – Whether to ignore the target tolerance

Returns:

The normalized direction in the desired frame

get_target_distance(ignore_tolerance: bool = False) → float#

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

Parameters:: ignore_tolerance – Whether to ignore the target tolerance
Returns:: The distance.

get_target_orientation(frame: navground.core.Frame, ignore_tolerance: bool = False) → float | None#

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

Parameters:

frame – The desired frame
ignore_tolerance – Whether to ignore the target tolerance

Returns:

The orientation in the desired frame

get_target_pose(frame: navground.core.Frame = navground.core.Frame.absolute, ignore_tolerance: bool = False) → navground.core.Pose2 | None#

Returns the target’s pose composed by position get_target_position() and orientation get_target_orientation(), if both are defined, else null.

Parameters:

frame – The desired frame
ignore_tolerance – Whether to ignore the target tolerance

Returns:

The pose in the desired frame or null.

get_target_position(frame: navground.core.Frame = navground.core.Frame.absolute, ignore_tolerance: bool = False) → Vector2 | None#

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

Parameters:

frame – The desired frame
ignore_tolerance – Whether to ignore the target tolerance

Returns:

The vector 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_twist(frame: navground.core.Frame = navground.core.Frame.absolute, ignore_tolerance: bool = False) → navground.core.Twist2#

Gets the current target velocity.

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

Parameters:

frame – The desired frame
ignore_tolerance – Whether to ignore the target tolerance

Returns:

The velocity in the desired frame.

get_target_velocity(frame: navground.core.Frame = navground.core.Frame.absolute, ignore_tolerance: bool = False) → Vector2#

Gets the current target velocity.

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

Parameters:

frame – The desired frame
ignore_tolerance – Whether to ignore the target tolerance

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.

has(name: str) → bool#

Checks whether a property exists.

Parameters:: name – The name of the property
Returns:: True if the property exists

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.

is_stopped(epsilon_speed: float = 1e-06, epsilon_angular_speed: float = 1e-06) → bool#

Determines if the behavior twist is small enough.

Parameters:

epsilon_speed – The maximal speed to be at stop
epsilon_angular_speed – The maximal angular speed to be at stop

Returns:

True if stopped, False otherwise.

static load(value: str) → object#

Load a behavior from a YAML string.

Parameters:: value – the 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.

prepare() → None#

Finalizes the behavior initialization.

Call it after configuring the behavior parameters, before starting using it.

The base class implementation does nothing. Override it to add any logic that to finalizes the concrete behavior before using it. For instance, it can be used to load resources or configure the coordination with other behaviors.

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 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 has_target#

Type:: bool

Whether the current target is valid

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()

Base class

Contents

Base class#