Controller

class State

The state of an action.

idle = <State.idle: 0>

the action has not started

running = <State.running: 1>

the action is running

failure = <State.failure: 2>

the action failed

success = <State.success: 3>

the action succeeded

__init__(value: int) → None

property name

Type:

str

class Action

Holds the state of a long running task and notifies observers when it terminates.

__init__(*args, **kwargs)

abort() → None

Abort the action, calling the done_cb if set.

property done

Type:

bool

Return whenever the action is done or not.

Returns:

True if the action failed or succeeded

property done_cb

Type:

Optional[Callable[[navground.core.Action.State], None]]

A callback called when the action terminates

The callback argument is the final state of the action.

property running

Type:

bool

Return whenever the action is running.

Returns:

True if the action is running

property running_cb

Type:

Optional[Callable[[float], None]]

A callback called when the action is running

The callback argument is the minimal expected time to terminate the action.

property state

Type:

navground.core.Action.State

The current state

class Controller

This class exposes a higher level, stateful interface to a behavior, to which it delegates 2D collision avoidance.

The controller provides actions (event-based interfaces) to

• go to a point/pose, stopping once the target has been reached,

• follow a point/pose, which does not terminates once the target has been reached

• follow a velocity/twist

Typical usage of a controller

1. Pick and configure a Behavior

2. Initialize and configure the controller

3. At regular intervals, update the state, using the Behavior API, and call update().

4. When needed, trigger one of the actions.

5. Either manually check the action’s state or set callbacks to be notified when the action terminates or updates.

6. Actuate the target command by using the return value of update() or by setting a callback set_cmd_cb()

__init__(behavior: navground.core.Behavior = None) → None

Constructs a new instance.

Parameters:

behavior – The navigation behavior

follow_direction(direction: Vector2) → navground.core.Action

Starts an action to follow a target direction.

If an action is already running, the controller aborts it, unless it was following a velocity/twist, in which case it just updates the target.

Parameters:

direction – The target direction. Must have positive norm.

Returns:

The new action.

follow_manual_cmd(cmd: navground.core.Twist2) → navground.core.Action

follow_path(path: navground.core.Path, tolerance: float) → navground.core.Action

Start following a path.

Internally calls go_to_position() to move towards the last point of the path .

Parameters:

• path – The path

• tolerance – The spatial tolerance

Returns:

The new action.

follow_point(point: Vector2) → navground.core.Action

Starts an action to follow a point.

The action keeps running even after the agent arrive at the target.

If an action is already running, the controller aborts it, unless it was following a point/pose, in which case it just updates the target.

Parameters:

point – The target point

Returns:

The new action.

follow_pose(pose: navground.core.Pose2) → navground.core.Action

Starts an action to follow a pose

The action keeps running even after the agent arrive at the target.

If an action is already running, the controller aborts it, unless it was following a point/pose, in which case it just updates the target.

Parameters:

pose – The target pose

Returns:

The new action.

follow_twist(twist: navground.core.Twist2) → navground.core.Action

Starts an action to follow a target twist.

If an action is already running, the controller aborts it, unless it was following a velocity/twist, in which case it just updates the target.

Parameters:

twist – The target twist

Returns:

The new action.

follow_velocity(velocity: Vector2) → navground.core.Action

Starts an action to follow a target velocity.

If an action is already running, the controller aborts it, unless it was following a velocity/twist, in which case it just updates the target.

Parameters:

velocity – The target velocity

Returns:

The new action.

go_to_pose(pose: navground.core.Pose2, position_tolerance: float, orientation_tolerance: float, along_path: navground.core.Path | None = None) → navground.core.Action

Starts an action to go to a pose.

The action succeed once the agent arrives within a tolerance from the target pose and comes to a stop.

If an action is already running, the controller aborts it.

Parameters:

• pose – The target pose

• position_tolerance – The spatial tolerance

• orientation_tolerance – The spatial tolerance

• along_path – An optional path to follow

Returns:

The new action.

go_to_position(position: Vector2, tolerance: float, along_path: navground.core.Path | None = None) → navground.core.Action

Starts an action to go to a point.

The action succeed once the agent arrives within a tolerance from the target point and comes to a stop.

If an action is already running, the controller aborts it.

Parameters:

• point – The target point

• tolerance – The spatial tolerance

• along_path – An optional path to follow

Returns:

The new action.

set_cmd_cb(callback: Callable[[navground.core.Twist2], None]) → None

Sets the callback called each time a command is computed for an active action.

Parameters:

value – A callback that takes the command twist as argument.

stop() → None

Abort the running action.

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

Updates the control for time step.

Internally calls Behavior.compute_cmd() for collision avoidance.

Parameters:

time_step – The time step

Returns:

The command twist to execute the current action

property angular_speed_tolerance

Type:

float

The maximal angular speed to consider the agent as stopped.

the default is 0.01 rad/s.

property behavior

Type:

navground.core.Behavior

The navigation behavior used by the controller

property cmd_frame

Type:

Optional[navground.core.Frame]

The frame of reference for the command.

property idle

Type:

bool

Returns whether the control action is idle.

Returns:

True only if the control action is not running.

property is_still

Type:

bool

@private

property speed_tolerance

Type:

float

The minimal speed to consider the agent as stopped.

the default is 1 cm/s.

property state

Type:

navground.core.Action.State

The state of the control action.