matrx.agents.agent_utils.navigator

Module Contents

class Navigator(agent_id, action_set, algorithm=A_STAR_ALGORITHM, custom_algorithm_class=None, traversability_map_func=get_traversability_map, algorithm_settings={'metric': 'euclidean'}, is_circular=False)

A navigator object that can be used for path planning and navigation.

Parameters

agent_id: string

ID of the agent that wants to navigate through a grid world.

action_set: list

List of actions the agent can perform.

algorithm: string. Optional, default “a_star”

The path planning algorithm to use. As of now only A* is supported.

is_circular: bool (Default: False)

When True, it will continuously navigate given waypoints, until infinity.

Warning

This class still depends on the deprecated StateTracker instead of the new State. Note that the StateTracker is created from a state dictionary that can be obtained from a State instance. This is the current workaround to still make the Navigator work with the current State.

Another approach is to not use State at all, and only rely on a StateTracker. See the matrx.agents.agent_types.patrolling_agent.PatrollingAgentBrain which uses this approach.

add_waypoint(self, waypoint)

Adds a waypoint to the path.

Parameters

waypoint: tuple, list

The (x,y) coordinates of the cell.

Raises

AssertError

When the waypoint is not a tuple or list.

add_waypoints(self, waypoints, is_circular=False)

Adds multiple waypoints to the path in order.

Parameters

waypointslist

The list of waypoints of the form (x,y).

is_circularbool

Whether the navigator should continuously visit all waypoints (including the ones already given before).

Raises

AssertError

When the waypoint is not a tuple or list.

get_all_waypoints(self, state_tracker: StateTracker = None)

Returns all current waypoints stored.

Returns

dict

A dictionary with as keys the order and as value the waypoint as (x,y) coordinate.

get_upcoming_waypoints(self, state_tracker: StateTracker = None)

Returns all waypoints not yet visited.

Returns

dict

A dictionary with as keys the order and as value the waypoint as (x,y) coordinate.

get_current_waypoint(self, state_tracker: StateTracker = None)

Returns the current waypoint the navigator will try to visit.

Returns

list

The (x,y) coordinate of the next waypoint.

get_move_action(self, state_tracker: StateTracker)

Returns the next move action.

It applies the path planning algorithm to identify the next best move action to move closer to the next waypoint.

Parameters

state_trackerStateTracker

The state tracker used by the algorithm to determine what (according to what the agent observes) would be the best possible next move action.

Returns

str

The name of the move action the agent is capable of making.

Raises

Warning

Raises a warning (not exception) to signal that no path can be found to the next waypoint.

ValueError

Raised when the agent’s location is not found on the route found by the path planning.

reset(self)

Resets all waypoints to not being visited.

reset_full(self)

Clears all waypoints to an empty Navigator.

class PathPlanner(action_set, settings)

A private MATRX class.

The empty path planner. Future path planning algorithms should implement this class.

plan(self, start, goal, occupation_map)

Plan a route from the start to the goal.

Parameters

starttuple

The starting (x,y) coordinate.

goaltuple

The goal (x,y) coordinate.

occupation_mapnparray

The list of lists representing which grid coordinates are blocked and which are not.

Returns

list

A list of coordinates the agent should visit in order to reach the goal coordinate.

class AStarPlanner(action_set, settings)

Bases: matrx.agents.agent_utils.navigator.PathPlanner

A* algorithm for path planning.

plan(self, start, goal, occupation_map)

Plan a route from the start to the goal.

A* algorithm, returns the shortest path to get from goal to start. Uses an 2D numpy array, with 0 being traversable, anything else (e.g. 1) not traversable Implementation from: https://www.analytics-link.com/single-post/2018/09/14/Applying-the-A-Path-Finding-Algorithm-in-Python-Part-1-2D-square-grid

Parameters

starttuple

The starting (x,y) coordinate.

goaltuple

The goal (x,y) coordinate.

occupation_maplist

The list of lists representing which grid coordinates are blocked and which are not.

Returns

The list of coordinates to move to from start to finish.

class WeightedAStarPlanner(action_set, settings)

Bases: matrx.agents.agent_utils.navigator.PathPlanner

Weighted A* algorithm for path planning.

plan(self, start, goal, occupation_map)

Plan a route from the start to the goal.

A* algorithm, returns the shortest path to get from goal to start. Uses an 2D numpy array, with 0 being traversable, anything else (e.g. 1) not traversable Implementation from: https://www.analytics-link.com/single-post/2018/09/14/Applying-the-A-Path-Finding-Algorithm-in-Python-Part-1-2D-square-grid

Parameters

starttuple

The starting (x,y) coordinate.

goaltuple

The goal (x,y) coordinate.

occupation_maplist

The list of lists representing which grid coordinates are blocked and which are not.

Returns

The list of coordinates to move to from start to finish.

class Waypoint(loc, priority)

A private MATRX class.

Used to represent a navigation waypoint for the Navigator class.

is_visited(self, current_loc=None)

Whether this waypoint is visited.

Parameters

current_loclist (Default: None)

The (x,y) coordinate of an agent. When given, checks if this waypoint is visited by the agent on this location. Otherwise, performs no check.

Returns

bool

Returns True when this waypoint is visited (or just now visited when current_loc is given). False otherwise.

reset(self)

Sets this waypoint as not visited.

get_move_actions(action_set)

Returns the names of all move actions in the given agent’s action set.

Parameters

action_setlist

The names of all actions an agent can perform.

Returns

dict

The dictionary of all move actions that are part of the agent’s actions it can perform. The keys are the action names and values are the delta x and y effects on an agent’s location.