Hexagony
This is a coordinate system based on Red Blob's hex guide.
It uses the cube coordinate system allowing for flat and pointy coordinates at arbitrary scales.
It uses Vector2 and Vector3 from three.js as coordinate records.
CubeCoords and Hexes are designed to be immutable. changing the value of one or the other can be unpredictable.
Also, CubeCoords are not linked in any way to their Hexes; it is the users' responsibility to use the proper cubeCoords with the proper Hexes matrix.
The reason I wrote this library is that I wanted a focused, unbounded and efficient Hexagon library for visualization purposes.
By Focused I mean by taking a single coordinate system the interface is smaller and more specific.
By unbounded I mean that there is no "edges" or center to the visual space. Coordinates can be expressed in any range of values, as the entire population is never retained by any of the libraries' methods. As the task I have in mind is a "universe" grid, this gives me the ability to operate on an arbitrary chunk of 2d space.
By efficient, I mean that very little data is retained in the structures returned. Corner points are returned dynamically, meaning only the cube coordinates are retained within the Hex ecosystem.
The richest aspect of this system is you can return all the coordinates within a rectangle and/or meeting a filter test -- so that you can return any sort of geometric shape you can conceive of if you can return a function that expresses whether an individual point is contained by it or not.
Elements
Hexagony uses a Hexes record as a frame of reference and CubeCoords as x,y,z cube coordinate records.
There is no fixed origin/extent or persistent coordinate list. Sets of coordinates are generated by querying the hexes matrix to return coordinates. These coordinates can be polled for their euclidean (2d) location, or converted into a series of corner (2d) points.
Hexes
Hexes is a matrix -- a frame of reference that determines the type of hexagons and the orientation ('flat' or 'pointy').
constructor({scale: , pointy: })
- the scale is any positive number
- pointy is a boolean value; if false, the matrix is considered "flat"
corners (cubeCoord) : [Vector2]{6}
returns six x,y points useful for graphing a hexagon. Each point should be distance from the hexes' center.
inverse() : Hexes
returns a copy of Hexes with a different pointiness.
nearestHex(x, y) CubeCoord
nearestHex(point): CubeCoord
returns a CubeCoord whose center is the closest possible point to the input.
closestToPoint(<2d point>, , )
closestToPoint(<2d point>, [])
returns the point whose center is closest to the first coordinate from the candidates. Accepts two CubeCoord instances or an array of CubeCoord instances. Written to enable nearestHex.
floodRect(minX, minY, maxX, maxY, extend: )
returns an array of CubeCoords within the described region. if you pass extend, it includes a safety loop around the hexes. If not, you only get hexes whose center is inside the rect.
floodQuery(fn:bool, extend:<boolean|number>, minX, minY, maxX, maxY,)
finds all points within the region that matches the function.
the function is passed(, , ) and needs to return a boolean.
If extend is true, and the function is an open-ended test (say, pt.x > 0) then this method will loop indefinately - there is a failsafe after 3 seconds but it can potentially return a huge set of values.
If you want to ensure a smaller return set either:
- make the target region the only concern by setting extent to false
- pass a number to extend that is the maximum number of cubes returned.
CubeCoord
CubeCoords are vectors in the Hexagonal cube space (see Red Blob link above). this is not a truly Euclidean space; these axes are only meaningful in the context of the Hexes matrix that created them.
CubeCoords have x, y, and z properties. These are integers, and x + y + z === 0. In fact you don't have to pass in z to the constructor - it is computed.
The location of the CubeCoord is half the sum of the product of the vectors. there are a set of flat vectors for x, y, and z and a set of pointy vectors for x, y, and z contained in the CubeCoords.vectors map.
CubeCoords represent Hexagons. they contain the center of the hexagon in cube space, and can be translated to 2d space with the following methods:
toXY() :
returns a point in 2d space based on the passed in Hexes matrix.
add() :
returns a clone of the sum of this instance and the argument.
neighbors : []
returns six CubeCoords that are the center of the adjacent hexes in cube space. Note, this is irrespective of the matrix/ pointiness -- and is a property not a method.
isEqualTo():
tests whether the x,y,z values of the passed in object are the same as that of the instance. (duck-type logic).
.util.isCoordLike():
.util.goodCoords():
returns an array of all the members that duck-type as Coords.
.util.uniq([]):
returns a unique array of all the unique good coordinates.
.util.toMap([]):
like uniq, but returns results in a map form.
.util.diff([], [])
subtracts the second collection from the first.
CubeCoord also extends Vector3 from three.js but the results
of using methods not documented here is unpredictable.