A type-hinted, object-oriented Python implementation for working with hex grids
This is a type-hinted, object-oriented implementation in Python of hexagonal grids as described on Red Blob Games. This package allows you to easily work with hexagonal grids in Python. All of its classes, attributes and methods are type-hinted which allows your editor to autocomplete signatures and catch bugs and mistakes early.
Because this package uses type hints, keyword-only and positional-only arguments you must have Python 3.9 or greater installed.
pip install hexpexpoetry add hexpexgit clone https://github.com/solbero/hexpex.git
cd hexpex
poetry installHexpex provides classes for working with hexagonal grids in both the cube and axial coordinate systems. For more information about the difference between these two coordinate systems see the writeup on Red Blob Games.
from hexpex import Axial, Cube
Cube(q=1, r=0, s=-1)
Axial(q=1, r=0)adjacent()- Returns the hex coordinate in adjacent direction from self
diagonal()- Returns the hex coordinate in diagonal direction from self
distance()- Returns the distance between passed hex coordinate and self
range()- Returns a set of hex coordinates within passed distance of self
ring()- Returns a set of hex coordinates on a ring passed distance from self
rotation()- Returns a set of rotated hex coordinates rotated around self
spiral()- Yields hex positions in a spiral from self out to passed distance from self
Objects can be added or subtracted from each other, and multiplied or divided by integers.
from hexpex import Axial, Cube
cube_1 = Cube(q=2, r=0, s=-2)
cube_2 = Cube(q=-1, r=0, s=1)
cube_1 + cube_2
#> Cube(1, 0, -1)
cube_1 - cube_2
#> Cube(3, 0, -3)
cube_1 * 2
#> Cube(4, 0, -4)
cube_1 // 2
#> Cube(1, 0, -1)
axial_1 = Axial(q=2, r=0)
axial_2 = Axial(q=-1, r=0)
axial_1 + axial_2
#> Axial(1, 0)
axial_1 - axial_2
#> Axial(3, 0)
axial_1 * 2
#> Axial(4, 0)
axial_1 // 2
#> Axial(1, 0)Hexpex provides some helper enums for giving direction vectors to the methods adjacent(), diagonal() and spiral().
To use them import the enums for your coordinate system and hex orientation (pointy or flat).
For more information on the difference between the two hex orientations see Red Blob Games.
from hexpex import Cube, CubeFlatAdjacentDirection as AdjacentDirection, CubeFlatDiagonalDirection as DiagonalDirection
cube = Cube(0, 0, 0)
cube.adjacent(AdjacentDirection.SE)
#> Cube(1, 0, -1)
cube.diagonal(DiagonalDirection.E)
#> Cube(2, -1, -1)A cube object can be converted to an axial object using the to_axial() method.
The reverse is true for an axial object using the to_cube() method.
Both representations can also be converted to a tuple using the to_tuple() method and to a dict using the to_dict()method.
from hexpex import Axial, Cube
cube = Cube(1, 0, -1)
axial = Axial(1, 0)
cube.to_axial()
#> Axial(1, 0)
axial.to_cube()
#> Cube(1, 0, -1)
cube.to_tuple()
#> (1, 0, -1)
axial.to_tuple()
#> (1, 0)
cube.to_dict()
#> {"q": 1, "r": 0, "s": -1}
axial.to_dict()
#> {"q": 1, "r": 0}- Cube coordinates
- Axial coordinates
- Double offset coordinates
- Distances
- Neighbors
- Range
- Rings
- Rotation
- Spiral
- Line drawing
- Reflection
- Rounding
- Hex to pixel
- Pixel to hex
See the open issues for a full list of proposed features (and known issues).
If you have a suggestion that would make this project better, please fork the repo and create a pull request. You can also simply open an issue with the label "enhancement".
- Fork the project
- Create your feature branch
git checkout -b feature/AmazingFeature- Commit your changes
git commit -m 'Add some AmazingFeature'- Push to the branch
git push origin feature/AmazingFeature- Open a pull request
Distributed under the GPLv3 License.
See LICENSE.txt for more information.
- Email: njord.solberg@gmail.com