hexpex 0.2.3

A type-hinted, object-oriented Python implementation for working with hex grids

About the Project

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.

Prerequisites

Because this package uses type hints, keyword-only and positional-only arguments you must have Python 3.9 or greater installed.

Installation

Using PIP

pip install hexpex

Using Poetry

poetry add hexpex

Manually (for testing or development)

git clone https://github.com/solbero/hexpex.git
cd hexpex
poetry install

Usage

Classes

Hexpex 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)

Object Methods

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

Operations

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)

Direction Vectors

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)

Conversion

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}

Roadmap

Coordinate systems

• Cube coordinates
• Axial coordinates
• Double offset coordinates

Methods

• 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).

Contributing

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".

1. Fork the project
2. Create your feature branch

git checkout -b feature/AmazingFeature

3. Commit your changes

git commit -m 'Add some AmazingFeature'

4. Push to the branch

git push origin feature/AmazingFeature

5. Open a pull request

License

Distributed under the GPLv3 License. See LICENSE.txt for more information.

Contact

• Email: njord.solberg@gmail.com

Project Links

• Github: https://github.com/solbero/hexpex
• PyPI: https://pypi.org/project/hexpex/