pathfinding3d.core.grid module

pathfinding3d.core.grid.build_nodes(width, height, depth, matrix=None, inverse=False, grid_id=None)

Create nodes according to grid size. If a matrix is given it will be used to determine what nodes are walkable.

Parameters:

• width (int) – The width of the grid.

• height (int) – The height of the grid.

• depth (int) – The depth of the grid.

• matrix (MatrixType) – A 3D array of values (numbers or objects specifying weight) that determine how nodes are connected and if they are walkable. If no matrix is given, all nodes will be walkable.

• inverse (bool, optional) – If true, all values in the matrix that are not 0 will be considered walkable. Otherwise all values that are 0 will be considered walkable.

• grid_id (int, optional) – The id of the grid.

Returns:

A list of list of lists containing the nodes in the grid.

Return type:

List[List[List[GridNode]]]

class pathfinding3d.core.grid.Grid(width=0, height=0, depth=0, matrix=None, grid_id=None, inverse=False)

Bases: object

A grid represents the map (as 3d-list of nodes).

Parameters:

• width (int) –

• height (int) –

• depth (int) –

• matrix (List[List[List[int]]] | ndarray | None) –

• grid_id (int | None) –

• inverse (bool) –

__init__(width=0, height=0, depth=0, matrix=None, grid_id=None, inverse=False)

Create a new grid.

Parameters:

• width (int, optional) – The width of the grid.

• height (int, optional) – The height of the grid.

• depth (int, optional) – The depth of the grid.

• matrix (MatrixType) – A 3D array of values (numbers or objects specifying weight) that determine how nodes are connected and if they are walkable. If no matrix is given, all nodes will be walkable.

• inverse (bool, optional) – If true, all values in the matrix that are not 0 will be considered walkable. Otherwise all values that are 0 will be considered walkable.

• grid_id (int | None) –

_validate_dimensions(width, height, depth, matrix)

Return type:

tuple

Parameters:

• width (int) –

• height (int) –

• depth (int) –

• matrix (List[List[List[int]]] | ndarray | None) –

is_valid_grid()

Check if grid is valid

Returns:

True, if grid is valid

Return type:

bool

node(x, y, z)

Get node at position

Parameters:

• x (int) – x position

• y (int) – y position

• z (int) – z position

Returns:

node at position

Return type:

GridNode

inside(x, y, z)

Check, if field position is inside map

Parameters:

• x (int) – x position

• y (int) – y position

• z (int) – z position

Returns:

True, if position is inside map

Return type:

bool

walkable(x, y, z)

Check, if the tile is inside grid and if it is set as walkable

Parameters:

• x (int) – x position

• y (int) – y position

• z (int) – z position

Returns:

True, if position is inside map and walkable

Return type:

bool

_calc_cost(dx, dy, dz)

Get the distance between current node and the neighbor (cost)

Parameters:

• dx (int) – x distance

• dy (int) – y distance

• dz (int) – z distance

Returns:

distance between current node and the neighbor (cost)

Return type:

float

calc_cost(node_a, node_b, weighted=False)

Get the distance between current node and the neighbor (cost)

Parameters:

• node_a (GridNode) – current node

• node_b (GridNode) – neighbor node

• weighted (bool, optional) – True, if weighted algorithm is used, by default False

Returns:

distance between current node and the neighbor (cost)

Return type:

float

neighbors(node, diagonal_movement=DiagonalMovement.never)

Get all neighbors of one node

Parameters:

• node (GridNode) – node to get neighbors from

• diagonal_movement (int, optional) – if diagonal movement is allowed (see enum in diagonal_movement), by default DiagonalMovement.never

Returns:

list of all neighbors

Return type:

List[GridNode]

cleanup()

Cleanup grid

visualize(path=None, start=None, end=None, visualize_weight=True, save_html=False, save_to='./pathfinding3d_visualization.html', always_show=False)

Creates a 3D visualization of the grid, including optional path, start/end points, and node weights using plotly. This method is designed to help visualize the spatial layout, obstacles, and pathfinding results in three dimensions.

Parameters:

• path (Optional[List[Union[GridNode, Tuple]]], optional) – The path to visualize, specified as a list of GridNode instances or coordinate tuples (x, y, z). If omitted, the grid is visualized without a path. Defaults to None.

• start (Optional[Union[GridNode, Tuple]], optional) – The start node for the path, as either a GridNode or a tuple of coordinates. If not provided and a path is given, the first node of the path is used. Defaults to None.

• end (Optional[Union[GridNode, Tuple]], optional) – The end node for the path, as either a GridNode or a tuple of coordinates. If not provided and a path is given, the last node of the path is used. Defaults to None.

• visualize_weight (bool, optional) – Whether to visualize the weights of the nodes, enhancing the representation of node costs. Defaults to True.

• save_html (bool, optional) – If True, the visualization is saved to an HTML file specified by save_to instead of being displayed. Defaults to False.

• save_to (str, optional) – File path where the HTML visualization is saved if save_html is True. Defaults to “./pathfinding3d_visualization.html”.

• always_show (bool, optional) – If True, displays the visualization in the browser even when save_html is True. Useful for immediate feedback while also saving the result. Defaults to False.

Raises:

Warning – If plotly is not installed, a warning is logged and the visualization is skipped.

Notes

• Requires plotly for visualization. Install with pip install plotly if not already installed.