pyhexlib.basic module

class pyhexlib.basic.AxialCoordinate(r, q)

Bases: tuple

q

Alias for field number 1

r

Alias for field number 0

class pyhexlib.basic.Bounds(top: int, left: int, bottom: int, right: int)

Bases: object

Parameters:

• top (int)

• left (int)

• bottom (int)

• right (int)

__iter__()

Iterate over bounds as (top, left, bottom, right).

__len__()

Return number of elements when treated like a sequence (4).

Return type:

int

bottom: int

property bottomright: Hexagon

Return the bottom-right corner as a (row, col) tuple.

contains(rc)

Return True if the given (row, col) is inside the bounds.

Parameters:

rc (Hexagon)

Return type:

bool

left: int

right: int

Axis-aligned bounding box for a rectangular region of hexagons.

The Bounds object stores the top/left and bottom/right coordinates and provides convenience properties and sequence-like access.

top

Top row index.

Type:

int

left

Left column index.

Type:

int

bottom

Bottom row index.

Type:

int

right

Right column index.

Type:

int

property size: Tuple[int, int]

Return the size of the bounds as (height, width).

top: int

property topleft: Hexagon

Return the top-left corner as a (row, col) tuple.

class pyhexlib.basic.Direction(value)

Bases: Enum

An enumeration.

EAST = 'East'

NORTH = 'North'

NORTHEAST = 'Northeast'

NORTHWEST = 'Northwest'

SOUTH = 'South'

SOUTHEAST = 'Southeast'

SOUTHWEST = 'Southwest'

WEST = 'West'

class pyhexlib.basic.Hexagon(row, col)

Bases: tuple

col

Alias for field number 1

row

Alias for field number 0

class pyhexlib.basic.Neighborhood(center, reachable)

Bases: object

Parameters:

• center (Hexagon)

• reachable (Dict[Hexagon, Tuple[int, int, Hexagon]])

cost(neighbor)

Return the movement cost to the given neighbor.

If the neighbor is not reachable, float(‘inf’) is returned.

Parameters:

neighbor (Hexagon)

direction(neighbor)

Return the Direction enum representing direction from center to neighbor.

Parameters:

neighbor (Hexagon) – Neighbor coordinate.

Returns:

Direction enum or None if not a direct mapping.

Return type:

Direction | None

neighbors()

Return a list of neighbor coordinates.

Returns:

Neighbor coordinates reachable from the center.

Return type:

List[Hexagon]

path(target)

Reconstruct the path from center to the given target using predecessor links.

The reachable mapping is expected to store tuples where the third element is the predecessor node. Returns the path as a list of hexagon coordinates starting with the center and ending with the target.

Parameters:

target (Hexagon) – Destination coordinate.

Returns:

Ordered list of coordinates from center to target.

Return type:

List[Hexagon]

class pyhexlib.basic.OffsetCoordinate(row, col)

Bases: tuple

col

Alias for field number 1

row

Alias for field number 0

class pyhexlib.basic.Orientation(value)

Bases: Enum

An enumeration.

FLAT = 'Flat Top'

POINTY = 'Pointy Top'

pyhexlib.basic.astar(hexagons, start, goal, cost_fn=None)

A* pathfinding on the same interface as dijkstra.

hexagons can be a dict or any container. cost_fn behaves like in dijkstra (if omitted, a default cost lookup is used).

This implementation supports an optional preference-based penalty that biases the search to keep one of the offset coordinates (‘row’ or ‘col’) close to the start coordinate. This can be used to force a more ‘zigzag’ style horizontal movement instead of the usual straight/triangular shortest path. The parameters are:

• prefer_coord: ‘none’ (default), ‘row’ or ‘col’. If not ‘none’, the heuristic adds a penalty proportional to the absolute difference between the current node’s chosen coordinate and the start node’s chosen coordinate.

• penalty: a non-negative float multiplier controlling how strongly deviations are penalized. Default 0.0 (no penalty) preserves original behavior.

Note: adding a penalty can make the heuristic inadmissible (i.e. no longer guaranteed to be optimistic) and therefore may sacrifice optimality for the desired path shape.

Return type:

List[tuple[int, int]] | None

pyhexlib.basic.axial_coordinates(hexagons)

Map a collection of offset coordinates to axial coordinates.

Parameters:

hexagons (List[tuple[int, int]]) – Iterable of (row, col) coordinates.

Returns:

Mapping from (row,col) -> (r,q).

Return type:

Dict[tuple[int,int], tuple[int,int]]

pyhexlib.basic.axial_to_cube(ax)

Convert axial coordinates (r, q) to cube coordinates (x, y, z).

Cube coordinates are useful for computing hex distances and rotations.

Parameters:

ax (Tuple[int, int]) – Axial coordinates (r, q).

Returns:

Cube coordinates (x, y, z).

Return type:

Tuple[int, int, int]

pyhexlib.basic.axial_to_offset(ra, qa)

Convert axial coordinates (r, q) to offset coordinates (row, col).

The exact formula depends on the global orientation flag in pyhexlib.

Parameters:

• ra (int) – Axial r coordinate.

• qa (int) – Axial q coordinate.

Returns:

Offset coordinates (row, col).

Return type:

Tuple[int, int]

pyhexlib.basic.compute_direction(rc1, rc2)

Compute a Direction between two coordinates, approximating if necessary.

If the two coordinates are direct neighbors the precise direction is returned. Otherwise, the function falls back to computing an approximate direction based on axial/vector geometry.

Parameters:

• rc1 (tuple[int,int]) – Source (row, col).

• rc2 (tuple[int,int]) – Target (row, col).

Returns:

Best matching Direction or None if same cell.

Return type:

Direction | None

pyhexlib.basic.dijkstra(hexagons, start, goal, cost_fn=None)

Dijkstra shortest-path algorithm over hexagon graph.

The hexagons parameter may be a mapping providing cost information for each cell or an iterable container of coordinates. When it is a mapping, the default cost lookup tries to read either .cost or .move_cost from the stored value; otherwise costs default to 1.

Parameters:

• hexagons (Mapping|Iterable) – Graph representation or container of nodes.

• start (tuple[int,int]) – Start coordinate.

• goal (tuple[int,int]) – Goal coordinate.

• cost_fn (callable, optional) – Optional function cost_fn(rc) -> numeric cost.

Returns:

The shortest path from start to goal as a list of coordinates, or None if no path exists.

Return type:

List[tuple[int,int]] | None

pyhexlib.basic.distance(rc1, rc2)

Compute hex distance between two offset coordinates.

Parameters:

• rc1 (tuple[int,int]) – First coordinate (row, col).

• rc2 (tuple[int,int]) – Second coordinate (row, col).

Returns:

Hex distance (number of steps between cells).

Return type:

int

pyhexlib.basic.distance_axial(ax1, ax2)

Compute hex distance between two axial coordinates.

Uses the common axial distance formula.

pyhexlib.basic.distance_axial_with_cube(ax1, ax2)

Compute axial distance using cube coordinates conversion.

This variant converts axial coords to cube coordinates and returns the maximum absolute difference among cube axes.

pyhexlib.basic.get_direction(rc1, rc2)

Return the Direction from rc1 to rc2 if they are direct neighbors.

The function checks the parity appropriate for the configured orientation and looks up the simple neighbor mapping. If the pair is not a direct neighbor, None is returned.

Parameters:

• rc1 (tuple[int,int]) – Source coordinate (row, col).

• rc2 (tuple[int,int]) – Target coordinate (row, col).

Returns:

Direction enum if rc2 is an immediate neighbor of rc1.

Return type:

Direction | None

pyhexlib.basic.nb_dir_mapping(parity)

Return the neighbor-direction mapping for the current orientation and parity.

Parameters:

parity (int) – Parity (0 or 1) of the relevant coordinate (col for flat, row for pointy).

Returns:

A dict mapping neighbor offsets to Direction enums.

Return type:

DirectionMapping

pyhexlib.basic.neighborhood_basic(row, col)

Return the 6 immediate neighboring coordinates for a hex at (row, col).

The neighbor offsets depend on whether the layout is flat- or pointy-top and on the parity of the relevant coordinate (column or row).

Parameters:

• row (int) – Row index of the center hex.

• col (int) – Column index of the center hex.

Returns:

List of six (row, col) neighbor coordinates.

Return type:

List[tuple[int,int]]

pyhexlib.basic.offset_to_axial(row, col)

Convert offset coordinates (row, col) to axial coordinates (r, q).

The conversion depends on the global orientation flag in pyhexlib.

Parameters:

• row (int) – Offset row coordinate.

• col (int) – Offset column coordinate.

Returns:

Axial coordinates (r, q).

Return type:

Tuple[int, int]