hexagon_utilities module¶

class hexagon_utilities.Hex(x=0, y=0, size=1, id=None, flat=True, w=None, cube=None)¶

Bases: object

Represents one Hexagon. Typically on a hexagonal grid

The hexagon can be flat topped (flat = True) or pointy-topped (flat=False) Each Hexagon has: a center (x,y) size (of its edge) flat = True (or False if Pointy-topped) verts = xy of its 6 vertices h = height of the hexaxon from top to bottom w = width = distance between 2 adjacent centers to the right/left of each other

connect_pt_to_vertices(pt, ax=None, **kwargs)¶

Draws ‘spokes’ from a given point to all 6 vertices

pt is a xy tuple It usually is, but doesn’t have to be inside the hexagon

decorate(poly=None, line=None, include_center=True, ax=None, **kwargs)¶: Draw a Polygon to connect specific vertices and optionally center

draw_axis(orient='x', **kwargs)¶

Draw a line from one vertex to its opposite vertex, of speicified orientation

Parameters: orient (str, optional) – Valid values are “x”, “y”, or “z.” Default is “x”

draw_symmetrical_shapes(lattice_tup, axis, shape=['line'], ax=None, color_scheme={}, close=False, connect_original_points=True, draw_axis=False, **kwargs)¶

Draw pairs of lines connecting the given points across the specified axis.

By default, it will draw the line connecting the original set of points as well.

Parameters

lattice_tup (tuple) – This tuple is made up of a pt_name and an index specifying the lattice point uniquely. pt_name: string. A special name to denote specific lattice points. Allowable values are: [‘sa’, ‘sb’, ‘ea’, ‘eb’, ‘ab’]

index: integer index specifies which spoke or apothem to use for theta offset. Valid values are integers from 0..5
axis (string, optional) – The Axis of reflective symmetry. Should be one of ‘x’, ‘y’, ‘z’, or ‘6’.

color_scheme: Dict, optional: Specifies which colors to use for the original and reflected lines. Keys can only ‘x’, ‘y’, ‘z’ or ‘6’ The value of the dictionary should be a List of color names. It should be 1, 2, or 6 colors for 6-fold symmetry. If only one color is specified, then all lines will be drawn with that color.
close: Boolean, optional: A flag to specify if the last point should be connected to the first one via a line. Default is False.

Returns: One or more spokes are drawn as Line2D lines.
Return type: None

draw_xaxis(**kwargs)¶: Draw x-axis for a given hexagon

draw_yaxis(**kwargs)¶: Draw y-axis for a given hexagon

draw_zaxis(**kwargs)¶: Draw z-axis for a given hexagon

get_edge_midpoints()¶: Returns 6 points that are in the middle of each of the 6 Edges

get_lattice_points(density=2)¶

This method serves two purposes. It will store the interior ‘lattice’ points of a hexagon in a dictionary called lattice which can then be used. It also returns the dictionary, for plotting purposes.

Parameters: density, optional – Currently only 2 has been implemented.
Returns: A dictionary of lattice points, with keys = [‘ab’, ‘ea’, ‘eb’,’sa’, ‘sb’,]
Return type: Dictionary

get_points_center_rtheta(dist, theta_offset, index=None)¶

Return 6 points that are dist-and angle theta away from the hex center

Parameters

dist (float) – distance from the hexagon center, in hexagon-size units. Note: This is not absolute distance. Typically dist goes from 0 to 1, and gets multiplied by the size of the hexagon.
theta-offset (float or int) – Angle (in degrees). Note that the angle is w.r.t to the center. It is not absolute.
index (None or integer) – index specifies which spoke or apothem to use for theta offset. If index is None, then all 6 are returned

Returns

List of 6 new points, in [(x1,y1), (x2,y2) …] format

Return type

list

get_points_dist_from_vertex(dist, theta)¶

Return 6 points that are dist and angle theta away from each of the 6 vertices

Note that these points may or may not be on an edge. To be on the edge, theta gets fixed

Parameters

dist (float) – distance from the hexagon vertex, in hexagon-size units. Note: This is not absolute distance. Typically dist goes from 0 to 1, and gets multiplied by the size of the hexagon.
theta (float or int) – Angle (in degrees). Note that the angle is w.r.t to the center. It is not absolute. theta can take on 120 degrees, ranging from -30 to + 90, for the point to stay Inside the hexagon

get_points_on_edge(edge=None, dist_frac=None)¶

Given a Edgenum [0-5] return a point(x,y) distance from vert away on the edge

Parameters

edge (int or None) – edge is the edge-number from 0..5. If it is None, all 6 edges are included.
dist_frac (float) – distance from the hexagon vertex, in hexagon-size units. Note: This is not absolute distance. Typically dist goes from 0 to 1, and gets multiplied by the size of the hexagon. 0 is closest to the starting vertex, 1 is the next vertex.

Returns

List of new points, in [(x1,y1), (x2,y2) …] format

Return type

list

get_points_to_points_rtheta(pt, dist_frac, theta_offset, index=None)¶

Return 6 points that are dist-theta away from the 6 other pts

Parameters

pt (list-like or tuple) – pt should have a length of 6 or 1. It should be a list with format [(x0,y0), (x1,y1), (x2,y2), (x3,y3), (x4,y4), (x5,y5)] or a tuple (x,y)
dist_frac (float) – distance from the pt6 points in hexagon height units. Typically a float in (0, 1)
theta-offset (float or int) – Angle (in degrees). Note that the angle is w.r.t to two points. It is not absolute.
index (None or integer) – index specifies which spoke or apothem to use for theta offset. If index is None, then 6 points are returned

Returns

List of 6 new points, in [(x1,y1), (x2,y2) …] format

Return type

list

get_symmetrical_point(lattice_tup, axis='6')¶

Given a lattice point inside a hexagon, returns symmetrical point(s) per axis specified.

Given one point on the lattice, this method will return all 6 of its reflected siblings, or, if an axi is specified, will return that particular mirror reflected point. Note that this is MIRROR reflection, not rotational symmetry. Use axi = ‘6’ for rotational symmetry.

Parameters

lattice_tup (tuple) – This tuple is made up of a pt_name and an index specifying the lattice point uniquely. pt_name: string. A special name to denote specific lattice points. Allowable values are: [‘ab’, ‘ea’, ‘eb’, ‘sa’, ‘sb’, ‘v’]

index: integer index specifies which spoke or apothem to use for theta offset. Valid values are integers from 0..5
axis (string, optional) – The axis of reflective symmetry. Should be one of ‘x’, ‘y’, ‘z’, or ‘6’.

Returns

an (x, y) tuple of the symmetrical point, or 6 points in [(x1,y1), (x2,y2) …] format

Return type

Tuple

Examples

>>> h = Hex(0, 0, size=1)
>>> h.get_lattice_points()
>>> symp = h.get_symmetrical_points(("ab", 4), "z")

get_verts()¶: Calculate all 6 verticles of the hex

line(start_point, end_point, start_pos=None, end_pos=None, index=None, line_len=None, theta=None, ax=None, **kwargs)¶

Draw one or multiple lines in the hexagon based on specifications.

Parameters

start_point (string) – Name of the point type desired: Allowable values are center, vertex, vertices, edge(s), random, ‘e1’ …’e5’ or ‘v1’…’v5
end_point (string) – Name of the point type desired: Allowable values are center, vertex, vertices, edge(s), random, ‘e1’ …’e5’ or ‘v1’…’v5
dist (float) – distance from the hexagon center, in hexagon-size units. Note: This is not absolute distance. Typically dist goes from 0 to 1, and gets multiplied by the in-radius of the hexagon.
theta (float or int) – Angle (in degrees).
index (None or integer) – index specifies which spoke or apothem to use for theta offset. If index is None, then all 6 are returned

Returns

None – The line(s) get plotted, so nothing is returned

Return type

None

plot_points(pts, **kwargs)¶: Draws all the pts (xy) specified

point(pt_name, action=None, index=None, dist=None, theta=None, ax=None, **kwargs)¶

Return one or six points in the hexagon based on specifications.

Parameters

pt-name (string) – Name of the point type desired: Allowable values are center, vertex, vertices, spokes, edge(s), apo|them
dist (float) – distance from the hexagon center, in hexagon-size units. Note: This is not absolute distance. Typically dist goes from 0 to 1, and gets multiplied by the in-radius of the hexagon.
theta (float or int) – Angle (in degrees).
index (None or integer) – index specifies which spoke or apothem to use for theta offset. If index is None, then all 6 are returned

Returns

If index is specified, then only one point is returned

Return type

List of 6 new points, in [(x1,y1), (x2,y2) ..] format

point_distance(pt)¶

Returns the distance from any xy_point to the hexagon

Parameters: pt (Tuple) – pt should be a tuple (x,y) or [x,y]
Returns: Euclidean Distance from the point pt to the nearest side of the hexagon
Return type: float

render(ax=None, **kwargs)¶: Draws the edges of a given Hexagon. fc will color the face.

render_apothems(index=None, ax=None, **kwargs)¶: Draws spokes from center to specific vertices

render_arc(incircle=True, ax=None, **kwargs)¶

Draw the incircle with raduis equal to the apothem of the hexagon

Parameters: incircle (Boolean, optional) – If True, indicates that the incircle should be rendered If False, indicates that the circumcircle should be rendered Default is True.

render_border(ax=None, **kwargs)¶: Draws all 6 borders of a given Hexagon. fc will color the face.

render_circle(incircle=True, ax=None, **kwargs)¶

Draw the incircle with raduis equal to the apothem of the hexagon

Parameters: incircle (Boolean, optional) – If True, indicates that the incircle should be rendered. If False, indicates that the circumcircle should be rendered. Default is True.

render_line(pts, close=False, ax=None, **kwargs)¶

Connects all specified pts (xy) by drawing lines between them, sequentially

Parameters

pts (List of xy tuples) – [(x0,y0), (x1,y1), (x2,y2),…]
close (Boolean, optional) – A flag to specify if the last point should be connected to the first one via a line. Default is False.

render_parallel_line(edge_name, dist_frac, **kwargs)¶: Draws a Line parallel to a named edge at the specified distance

render_polygon(pt_list, include_center=False, ax=None, **kwargs)¶

Draw a Polygon to connect specific vertices and optionally center

Parameters:

include_center: Boolean: Indicates whether the Center of the hexagon should to a vertex of the Polygon being rendered Default: False
pt_list: List: A list of Integers (0..5) or (x,y) coordinates. Note that this must start and end at the same point to ‘complete’ the polygon to be drawn

render_regular_polygon_inside_hexagon(polygon_sides, center_pt=None, polygon_size=None, angle_radians=None, ax=None, **kwargs)¶

Draws a regular polygon that shares its center with hexagon

Useful for drawing polygon _within_ the existing hexagonal space. For example, smaller hexagons inside the main grid.

Parameters

polygon_sides = number of sides in the regular polygon
center_pt (xy_tuple. Default is None) – (x_coord, y_coord) as the center point to draw the inner polygon from. If None, then defaults to the center of the parent Hexagon.
polygon_size (integer) – Size of the polygon’s side to be drawn. (defaults to hexagon’s size)
angle_radians (float) – Will rotate the regular polygon by radians angle

render_spokes(index=None, ax=None, **kwargs)¶

Draws spokes from center to specific vertices

Parameters: index (None or integer) – index specifies which vertex to use when drawing the spoke If index is None, then all 6 spokes are drawn
Returns: One or more spokes are drawn as Line2D lines.
Return type: None

v_connect(v_pairs, ax=None, **kwargs)¶

Draws edges from specific vertices to specified vertices.

Parameters: v_pairs (List of tuples of integers) – [vi, vj] where vi and vj are in [0..5] or [(vi0, vj0), (vi1, vj1) … ]
Returns: One or more Line2D lines connecting pairs of hexagon vertices
Return type: None

class hexagon_utilities.HexGrid(num_rows, num_cols, size=1, flat=True, xstart=0, ystart=0, rect_h=None, rect_w=None)¶

Bases: object

Represents the a hexagonal grid as painted on the screen. The hex grid can be flat topped (flat = True) or pointy-topped (flat=False)

It has a list of hexs in hlist And there is a rectangle (a bounding box) for the grid, since it has to be rendered in the xy plane

render_grid(**kwargs)¶

render_grid_polygons(pt_list=None, **kwargs)¶: For entire HexGrid connect center to vlist

render_grid_spokes(c_to_vlist=None, **kwargs)¶: For entire HexGrid connect center to specified vertices

render_grid_vconnect(v_pairs=None, **kwargs)¶: For entire HexGrid connect vert to vert without necessarily going through the center

render_grid_vertices(**kwargs)¶

hexagon_utilities.get_hexgrid_centers(hg)¶: get the center x and y coords for each hexagon as a list of (x,y)

hexagon_utilities.get_pt_rtheta_away(pt, dist, theta)¶: Given a point (x,y) and a certain dist at an angle theta, returns the point (x,y)

hexagon_utilities.hex_corner(center, size, i, flat=True)¶: Return the ith vertex of a regular hex with center of size i and flat/pointy orientation

hexagon_utilities.point_to_line_dist(pt, line_seg_endpoint1, line_seg_endpoint2)¶

Calculate the distance between a point and a line segment.

To calculate the closest distance to a line segment, we first need to check if the point projects onto the line segment. If it does, then we calculate the orthogonal distance from the point to the line. If the point does not project to the line segment, we calculate the distance to both endpoints and take the shortest distance.

Parameters

point (numpy.core.multiarray.ndarray) – Numpy array of form [x,y], describing the point.
line (list of numpy.core.multiarray.ndarray) – list of endpoint arrays of form [P1, P2]

Returns

The minimum distance to a point.

Return type

float