pyhexlib.graphic module

class pyhexlib.graphic.Size(width, height)

Bases: tuple

height

Alias for field number 1

width

Alias for field number 0

pyhexlib.graphic.angle_to_direction(angle)[source]

Map an absolute angle (degrees) to the nearest hex Direction.

Parameters:

angle (int) – Angle in degrees.

Returns:

Nearest pyhexlib.basic.Direction value.

Return type:

pyhexlib.basic.Direction | None

pyhexlib.graphic.compute_angle(start, target)[source]

Compute the angle in degrees from start to target.

Parameters:

  • start (pygame.Vector2) – Start point as pygame.Vector2.

  • target (pygame.Vector2) – Target point as pygame.Vector2.

Returns:

Angle in degrees (0..359), adjusted for the current hex orientation so that 0 points ‘up’ for flat-top grids.

Return type:

int

pyhexlib.graphic.compute_area(top, left, rows, cols, x_dist, y_dist)[source]

Return a pygame.Rect covering the pixel area for a grid region.

Parameters:

  • top (int) – Top row index of the region.

  • left (int) – Left column index of the region.

  • rows (int) – Number of rows in the region.

  • cols (int) – Number of columns in the region.

  • x_dist (int) – Horizontal spacing between centers in pixels.

  • y_dist (int) – Vertical spacing between centers in pixels.

Returns:

Rectangle in pixel coordinates covering the region.

Return type:

pygame.Rect

pyhexlib.graphic.compute_direction(p1, p2)[source]

Compute the hex pyhexlib.basic.Direction from p1 to p2.

Parameters:

  • p1 (tuple[int, int] | object) – Starting hex as a (row, col) tuple or an object with row and col attributes.

  • p2 (tuple[int, int] | object) – Target hex as a (row, col) tuple or an object with row and col attributes.

Returns:

A direction enum value or None if the cells are not direct neighbors.

Return type:

pyhexlib.basic.Direction | None

pyhexlib.graphic.compute_offset(r, c, x_dist, y_dist, offset, inner_radius, radius)[source]

Compute the pixel offset to position the viewport so that the specified origin hexagon appears near the top-left of the visible area.

Parameters:

  • r (int) – Origin row index.

  • c (int) – Origin column index.

  • x_dist (int) – Horizontal spacing between hex centers.

  • y_dist (int) – Vertical spacing between hex centers.

  • offset (pygame.Vector2) – Current offset or anchor point (unused semantic, passed through to helpers).

  • inner_radius (float) – Distance from center to side.

  • radius (int) – Outer radius in pixels.

Returns:

Pixel offset as pygame.Vector2 to apply to world coordinates.

Return type:

pygame.Vector2

pyhexlib.graphic.compute_screen_size(rows, cols, radius)[source]

Compute the pixel size required to render a hex grid.

Parameters:

  • rows (int) – Number of rows in the grid.

  • cols (int) – Number of columns in the grid.

  • radius (int) – Hexagon outer radius in pixels.

Returns:

Size object with attributes width and height.

Return type:

Size

The computation differs between flat- and pointy-top hexagons and is delegated to internal helpers.

pyhexlib.graphic.compute_viewport_bounds(topleft)[source]

Compute an approximate pyhexlib.basic.Bounds for a viewport starting at the supplied top-left hexagon.

Parameters:

topleft (tuple[int, int] | Hexagon) – The top-left visible hexagon as a (row, col) tuple or pyhexlib.hexagons.Hexagon.

Returns:

A small bounds box starting at topleft. This helper is intentionally approximate and currently returns a 20x20 box.

Return type:

pyhexlib.basic.Bounds

pyhexlib.graphic.direction_to_angle(direction)[source]

Return the rotation angle (degrees) for a hex Direction.

Parameters:

direction (pyhexlib.basic.Direction) – Direction enum value.

Returns:

Angle in degrees, or None if the direction is unknown.

Return type:

int | None

pyhexlib.graphic.draw_centered(surface, image, position)[source]

Blit image onto surface so its center matches position.

Parameters:

  • surface (pygame.Surface) – Destination surface.

  • image (pygame.Surface) – Source image surface to blit.

  • position (tuple[int, int]) – Pixel coordinates (x, y) where the image center should be placed.

Returns:

The destination surface (same object passed in).

Return type:

pygame.Surface

pyhexlib.graphic.hex_center(r, c, x_dist, y_dist, offset, inner_radius, radius)[source]
Parameters:

radius (int)

Return type:

pygame.Vector2

pyhexlib.graphic.hex_center_flat(r, c, x_dist, y_dist, offset, inner_radius, radius)[source]

Compute the pixel center for a flat-top hexagon at grid coordinates (r, c).

Parameters:

  • r (int) – Row index.

  • c (int) – Column index.

  • x_dist (int) – Horizontal spacing between hex centers.

  • y_dist (int) – Vertical spacing between hex centers.

  • offset (pygame.Vector2) – Pixel offset applied to the resulting center.

  • inner_radius (float) – Distance from center to side.

  • radius (int) – Outer radius in pixels.

Returns:

Pixel coordinates of the hex center.

Return type:

pygame.Vector2

pyhexlib.graphic.hex_center_pointy(r, c, x_dist, y_dist, offset, inner_radius, radius)[source]

Compute the pixel center for a pointy-top hexagon at grid coordinates (r, c).

Parameters:

  • r (int) – Row index.

  • c (int) – Column index.

  • x_dist (int) – Horizontal spacing between hex centers.

  • y_dist (int) – Vertical spacing between hex centers.

  • offset (pygame.Vector2) – Pixel offset applied to the resulting center.

  • inner_radius (float) – Distance from center to side.

  • radius (int) – Outer radius in pixels.

Returns:

Pixel coordinates of the hex center.

Return type:

pygame.Vector2

pyhexlib.graphic.hex_corner_with_offset(center, size, i, angle_offset)[source]

Return a single corner point for a hexagon.

Parameters:

  • center (pygame.Vector2) – Center position as pygame.Vector2.

  • size (int) – Hexagon outer radius in pixels.

  • i (int) – Corner index in range 0..5.

  • angle_offset (int) – Angle offset in degrees applied to the base corner angles (0 for flat, 30 for pointy).

Returns:

Corner point as pygame.Vector2.

Return type:

pygame.Vector2

pyhexlib.graphic.hex_corners(center, radius)[source]

Return the six corner points for a hexagon centered at center.

Parameters:

  • center (pygame.Vector2) – Pixel coordinates of the hexagon center as a pygame.Vector2.

  • radius (int) – Outer radius of the hexagon in pixels.

Returns:

List of six corner points as pygame.Vector2 objects.

Return type:

list[pygame.Vector2]

Chooses the flat- or pointy-top variant depending on the global orientation flag pyhexlib.is_flat.

pyhexlib.graphic.hex_corners_flat(center, size)[source]

Return the six corner points for a flat-top hexagon.

Parameters:

  • center (pygame.Vector2) – Center position in pixels as pygame.Vector2.

  • size (int) – Hexagon outer radius in pixels.

Returns:

List of six corner points.

Return type:

list[pygame.Vector2]

pyhexlib.graphic.hex_corners_pointy(center, size)[source]

Return the six corner points for a pointy-top hexagon.

Parameters:

  • center (pygame.Vector2) – Center position in pixels as pygame.Vector2.

  • size (int) – Hexagon outer radius in pixels.

Returns:

List of six corner points.

Return type:

list[pygame.Vector2]

pyhexlib.graphic.hex_dimensions(radius)[source]

Return geometric hexagon metrics for the given radius.

Parameters:

radius (int) – Outer radius of the hexagon in pixels.

Returns:

Tuple (inner_radius, x_dist, y_dist) where inner_radius is the distance from center to a side, and x_dist/y_dist are the horizontal and vertical spacing between hexagon centers for the configured orientation.

Return type:

tuple[float, int, int]

pyhexlib.graphic.rotate_image(image, angle=0)[source]

Rotate an image surface by an absolute angle in degrees.

Parameters:

  • image (pygame.Surface) – Image surface to rotate.

  • angle (int) – Rotation angle in degrees (clockwise).

Returns:

Rotated surface.

Return type:

pygame.Surface

pyhexlib.graphic.rotate_image_to_direction(image, direction)[source]

Rotate an image surface to match a hex grid direction.

Parameters:

  • image (pygame.Surface) – Image surface to rotate.

  • direction (pyhexlib.basic.Direction) – Hex direction to rotate to.

Returns:

Rotated surface.

Return type:

pygame.Surface

pyhexlib.graphic.xy_to_rc(x, y, radius)[source]

Convert pixel coordinates to grid coordinates (row, col).

Parameters:

  • x (float | int) – X coordinate in pixels.

  • y (float | int) – Y coordinate in pixels.

  • radius (int) – Hexagon outer radius in pixels.

Returns:

The corresponding pyhexlib.hexagons.Hexagon.

Return type:

Hexagon

The conversion is delegated to orientation-specific helpers.

pyhexlib.graphic.xy_to_rc_flat(x, y, radius)[source]

Convert pixel coordinates to hex grid coordinates for flat-top hexagons.

Parameters:

  • x (float | int) – X coordinate in pixels.

  • y (float | int) – Y coordinate in pixels.

  • radius (int) – Hexagon outer radius in pixels.

Returns:

The corresponding pyhexlib.hexagons.Hexagon.

Return type:

Hexagon

The algorithm first estimates the column and row and then corrects the result by inspecting the triangular regions near hex edges.

pyhexlib.graphic.xy_to_rc_pointy(x, y, radius)[source]

Convert pixel coordinates to hex grid coordinates for pointy-top hexagons.

Parameters:

  • x (float | int) – X coordinate in pixels.

  • y (float | int) – Y coordinate in pixels.

  • radius (int) – Hexagon outer radius in pixels.

Returns:

The corresponding pyhexlib.hexagons.Hexagon.

Return type:

Hexagon