KHexagon/io.github.offlinebrain.khexagon.math

Package-level declarations

The package contains utility functions and classes that aid in performing various mathematical operations specific to the program's focus on coordinates and shapes in a hexagonal grid:

Bresenham's Line Algorithm Functions: These functions, named bresenhamsLine, implement the Bresenham's line generation algorithm. They can produce a symmetric line of coordinates between two points on a hexagonal grid. It's slightly modified to be symmetric, so that the line is the same when drawn from either point.
Line Drawing Functions: The package includes functions like T.lineTo that use the Bresenham's line algorithm to draw lines between two given coordinates on a hexagonal grid.
Distance Calculation Functions: Functions such as T.distanceTo and the standalone distance function are used to calculate the distance between two given coordinates on a hexagonal grid.
Hexagonal Shape Functions: The package also contains functions like T.circle and T.ring to generate a circular or ring-like arrangement of coordinates around a given point on a hexagonal grid.

Please refer to individual function documentation for more detailed explanations and examples of usage.

Types

Layout

data class Layout(val orientation: Orientation = Orientation(), val size: Point = Point(), val origin: Point = Point())

Represents the layout of a hexagonal grid. Read more: Redblobgames Layout Examples

Orientation

data class Orientation(val f0: Float = 0.0f, val f1: Float = 0.0f, val f2: Float = 0.0f, val f3: Float = 0.0f, val b0: Float = 0.0f, val b1: Float = 0.0f, val b2: Float = 0.0f, val b3: Float = 0.0f, val startAngle: Float = 0.0f)

Data class representing the orientation of a hexagonal grid. Read more: Redblobgames Layout

Point

data class Point(val x: Float = 0.0f, val y: Float = 0.0f)

Functions

bresenhamsLine

fun bresenhamsLine(startQ: Int, startR: Int, endQ: Int, endR: Int, process: (x: Int, y: Int) -> Unit)

Implements Bresenham's line generation algorithm to plot a line between two points on a hexagonal grid. Calls the provided process function for each point along the line. This function generates a symmetric line, meaning swapping the start and end points won't affect the result.

bresenhamsLine

fun <T : AxisPoint, FromHexCoordinates<T>> T.bresenhamsLine(end: AxisPoint): List<T>

Uses Bresenham's line generation algorithm to create a path from this coordinate to another.

circle

fun circle(originQ: Int = 0, originR: Int = 0, radius: Int, callback: (Int, Int) -> Unit)

Calls the provided callback on each point within a hexagonal area defined by provided origin and radius.

circle

fun <T : AxisPoint, FromHexCoordinates<T>> T.circle(radius: Int): List<T>

Generates a list of coordinates forming a circular region at this coordinate with a given radius.

distance

fun distance(fromQ: Int, fromR: Int, toQ: Int, toR: Int): Int

Calculates the hexagonal distance between two points given by their (q, r) coordinates.

distance

fun <T : AxisPoint> T.distance(other: AxisPoint): Int

Calculates the hexagonal distance from this coordinate to another.

flatHexHeight

fun flatHexHeight(radius: Int): Int

flatHexWidth

fun flatHexWidth(radius: Int): Int

hexCornerOffset

fun hexCornerOffset(layout: Layout, corner: Int): Point

Calculates the offset of a corner of a hexagon. This is done by first calculating the angle of the corner relative to the layout's start angle, then scaling a unit vector at that angle by the layout's size.

hexRound

fun hexRound(q: Float, r: Float): HexCoordinates

Rounds a point in fractional hexagonal coordinates to the nearest integer coordinates.

hexToPixel

fun hexToPixel(layout: Layout, hex: HexCoordinates): Point

Converts a point in hexagonal coordinates to pixel coordinates. This is done by applying the layout's orientation matrix to the hexagonal coordinates, then scaling and translating the result by the layout's size and origin.

line

fun line(startQ: Int, startR: Int, endQ: Int, endR: Int, process: (x: Int, y: Int) -> Unit)

Generates a line of points between two given points in a hexagonal grid. The line is generated by calculating the distance between the start and end points, and then interpolating the coordinates for each step along the line. The provided process function is called for each point along the line.

line

fun <T : Coordinates<T>, FromHexCoordinates<T>> T.line(other: Coordinates<*>): List<T>

Generates a line of coordinates from this coordinate to another.

pixelToHex

fun pixelToHex(layout: Layout, point: Point): FractionalHexCoordinates

Converts a point in pixel coordinates to hexagonal coordinates. This is done by first normalizing the point's coordinates relative to the layout's origin and size, then applying the layout's orientation matrix to the normalized coordinates.

pointyHexHeight

fun pointyHexHeight(radius: Int): Int

pointyHexWidth

fun pointyHexWidth(radius: Int): Int

polygonCorners

fun polygonCorners(layout: Layout, hex: HexCoordinates): List<Point>

Calculates the corners of a hexagon in pixel coordinates.

ring

fun ring(originQ: Int = 0, originR: Int = 0, radius: Int, callback: (Int, Int) -> Unit)

Calls the provided callback on each point forming a ring in a hexagonal grid defined by provided origin and radius.