producer.hexgrid module

Various functions for generating hexagons and hexagonal grids.

producer.hexgrid.hexarea(d=1.0, incircle=False)[source]

Calculate the hexagon area.

If \(d\) is the circumcircle diameter, the area is:

\[A = \frac{3\sqrt{3}}{8} d^2\]
Parameters

  • d (float, numpy.ndarray, optional) – The diameter of circumscribed circle.

  • incircle (bool, optional) – The provided diameter is for the incircle of the hexagon, instead of its circumscribed circle.

Returns

The area of the hexagon(s).

Return type

float, numpy.ndarray

producer.hexgrid.hexgrid(n, d, incircle=False, orientation='horizontal', d_unit='cell', vertices=False, close=False, full=False)[source]

Generate the grid centers for a 2D hexagonal grid.

The grid is generated to match the provided number of points along the long axis and diameter of each grid cell. By default the diameter of each grid cell is defined as its circumscribed circle. This can be changed to its incircle — \(d_i = d_c \cos(\pi/6)\), where \(d_i\) is the incircle diameter and \(d_c\) is the circumscribed circle diameter — using incircle.

Each grid cell is separated by its incircle diameter; i.e., the orientation of each grid cell hexagon (see hexvert()) is vertical for a full grid orientation that is horizontal. This ensures a 100% fill factor for the grid.

Parameters

  • n (int) – The number of hexagonal grid cells along the grids long axis.

  • d (float) – The diameter of each grid cell. By default this is the circumscribed circle (see incircle).

  • incircle (bool, optional) – Use the provided diameter to set the incircle of each hexagonal cell instead of its circumscribed circle.

  • orientation (str, float, optional) – Sets the orientation of the grid, must be either ‘horizontal’, ‘vertical’, or a rotation angle in degrees relative to the horizontal orientation. The horizontal and vertical orientations set the long axis of the grid along the Cartesian x and y axis, respectively. The horizontal orientation is equivalent to a rotation angle of 0 and a vertical orientation is equivalent to a rotation angle of 30 degrees. While the polar-coordinate ordering of the vertices in the output array will change, note the shape degeneracy periodicity of 60 degrees.

  • d_unit (str, optional) – The input unit of the diameter. There are two options: (1) 'cell' means the input diameter is for each grid cell; (2) 'grid' means the input diameter is for the entire grid.

  • vertices (bool, optional) – Return the vertices of each grid cell. If False, only the grid centers are returned.

  • close (bool, optional) – If vertices are to be returned for each grid cell, this sets whether or not to “close” each cell hexagon by repeating the first set of coordinates at the end of the array of vertices.

  • full (bool, optional) – When defining the size of the grid directly (i.e., d_unit='grid'), expand the size of the individual grid cells so that they fill the parent hexagon of the grid.

Returns

An array with shape \((N_{\rm grid},2)\) providing the x and y Cartesian coordinates for the center of each grid cell.

Return type

numpy.ndarray

producer.hexgrid.hexgrid_circle_convert(d, incircle=False)[source]

Convert between the circumscribe circle and the incircle of a hexagon.

Parameters

  • d (float) – The reference hexagonal diameter. By default this is the circumscribed circle (see incircle).

  • incircle (bool, optional) – The provided diameter is the incircle instead of the circumscribed circle.

Returns

Return the conversion of the input. If the input is the circumscribed circle, this returns the incircle, and vice versa.

Return type

float

producer.hexgrid.hexgrid_grid_convert(n, d, incircle=False, d_unit='cell', full=False)[source]

Convert between the diameter of a full hexagonal grid and each hexagonal grid cell.

This function returns the diameter of the full grid if the diameter of the grid cell is provided, and vice versa. The reference circle returned coincides with the one provied; e.g., if the circumcircle of the full grid is provided, the circumcircle of an individual grid cell is returned.

Parameters

  • n (int) – The number of hexagonal grid cells along the grids long axis.

  • d (float) – The reference hexagonal diameter. By default this is the circumscribed circle (see incircle).

  • incircle (bool, optional) – The provided diameter is the incircle of the reference hexagon.

  • d_unit (str, optional) – The input unit of the diameter. There are two options: (1) 'cell' means the input diameter is for each grid cell; (2) 'grid' means the input diameter is for the entire grid.

  • full (bool, optional) – When defining the size of the grid directly (i.e., d_unit='grid'), expand the size of the individual grid cells so that they fill the parent hexagon of the grid.

producer.hexgrid.hexvert(d=1.0, incircle=False, close=False, orientation='horizontal')[source]

Construct the vertices of a hexagon.

Parameters

  • d (float, optional) – The diameter of circumscribed circle.

  • incircle (bool, optional) – Use the provided diameter to set the incircle of the hexagon instead of its circumscribed circle.

  • close (bool, optional) – “Close” the hexagon by repeating the first set of coordinates at the end of the array of vertices.

  • orientation (str, float, optional) – Sets the orientation of the grid, must be either ‘horizontal’, ‘vertical’, or a rotation angle in degrees relative to the horizontal orientation. The horizontal and vertical orientations set the long axis of the grid along the Cartesian x and y axis, respectively. The horizontal orientation is equivalent to a rotation angle of 0 and a vertical orientation is equivalent to a rotation angle of 30 degrees. While the polar-coordinate ordering of the vertices in the output array will change, note the shape degeneracy periodicity of 60 degrees.

Returns

An array with shape \((6,2)\), or \((y,2)\) if close is True, providing the x and y Cartesian vertices of the hexagon.

Return type

numpy.ndarray

producer.hexgrid.nearest_hexgrid(n, upper=False)[source]

Provided an expected number of grid locations, perform a brute-force iteration to find the hexgrid parameters that yield at least n grid locations.

Algorithm starts with a grid long axis with 3 points and just increases the number along the axis until the number of grid points is larger than the provided number. If upper is True, the function treats the provided number as an upper limit on the allowed number of grid points.

Parameters

  • n (int) – Number of grid points to match.

  • upper (bool, optional) – Treat the provided number as an upper limit. If False, the method returns the nearest hexagonal grid parameters that have at least the provided number of grid points. If True, the hexagonal grid instead must have no more than the provided number of grid points.

Returns

Two integers providing (1) the length of the long axis of the hexagonal grid and (2) the number of grid points.

Return type

tuple

producer.hexgrid.nhex(n)[source]

Return the number of grid points in a hexagonal grid given the number of points along its long axis.

Parameters

n (int) – Number of points along the long axis of the grid. Must be odd.

Returns

Number of grid points.

Return type

int

Raises

ValueError – Raised if the provided integer is even.

producer.hexgrid.rotate(coo, rot, deg=True)[source]

Rotate a set of coordinates.

Parameters

  • coo (numpy.ndarray) – Array of Cartesian coordinates to rotate.

  • rot (float) – Counter-clockwise rotation angle.

  • deg (bool, optional) – If True, provided rotation angle is in degrees. If False, the angle is in radians.

Returns

An array with the same shape as coo with the rotated coordinates.

Return type

numpy.ndarray

producer.hexgrid.set_orientation(coo, orientation='horizontal')[source]

Set the orientation of the input set of coordinates.

The input orientation is assumed to be horizontal or, equivalently, a 0 degree rotation. I.e., if orientation is set to 'horizontal' or 0., the input coordinates are simply returned. For non-zero rotation angles, repeated calls to this function result in additional rotations; i.e., there is no absolute reference frame that function can use.

Parameters

  • coo (numpy.ndarray) – Array of Cartesian coordinates to rotate.

  • orientation (str, float, optional) – The orientation to set assuming that the input coordinates are provided at 0 rotation (horizontal). The value of the orientation must be either 'horizontal', 'vertical', or a rotation angle in degrees.

Returns

Rotated coordinates.

Return type

numpy.ndarray

producer.hexgrid.triangle_number(n)[source]

Return the nth triangle number; i.e., the value of 1+2+3+...+(n-1)+n.