hexgrid

README

Hexgrid

This is a Go library used to handle regular hexagons.

It's based on the algorithms described by Amit Patel in his wonderful guide to hexagons -- I highly recommend reading through that page.

Usage

Importing

import "github.com/falanger/hexgrid"

Examples

Creating hexagons

hexagonA := hexgrid.NewHex(1, 2) //at axial coordinates Q=1 R=2
hexagonB := hexgrid.NewHex(2, 3) //at axial coordinates Q=2 R=3

Measuring the distance (in hexagons) between one hexagon and another

distance := hexagonA.DistanceTo(hexagonB)

Getting the array of hexagons on the path between one hexagon and another

origin := hexgrid.NewHex(10,20)
destination := hexgrid.NewHex(30,40)
path := origin.LineDraw(destination) 

Creating a layout

origin := hexgrid.Point{X: 0, Y: 0}     // The coordinate that corresponds to the center of hexagon 0,0
size := hexgrid.Point{X: 100, Y: 100}   // The length of an hexagon side => 100
layout: = hexgrid.Layout{Origin: origin, Size: size, Orientation: hexagon.OrientationFlat}

Obtaining the pixel that corresponds to a given hexagon

hex := hexgrid.NewHex(1,0)             
pixel := hexgrid.HexToPixel(layout,hex)  // Pixel that corresponds to the center of hex 1,0 (in the given layout)

Obtaining the hexagon that contains the given pixel (and rounding it)

point := hexgrid.Point{X: 10, Y: 20}
hex := PixelToHex(layout, point).Round()

History

• 1.0.0: Combining multiple forks
• 0.1.0: First version

Credits

• Pedro Sousa, for the intial repo.
• Igor Shmulyan, Brendan Le Glaunec, Sergey Kolunov, Puzzlemaker1, and Patrick Fay for their forks.
• And of course Amit Patel of Red Blob Games, without which we wouldn't have any of this.

License

MIT

Documentation

Overview

Package hexgrid provides various utilities to handle regular hexagons math This is a Go implementation of the algorithms described at http://www.redblobgames.com/grids/hexagons/implementation.html

Index

• Constants
• Variables
• type Direction
  • func (d Direction) ToString() string
• type FractionalHex
  • func NewFractionalHex(q, r float64) FractionalHex
  • func PixelToHex(l Layout, p Point) FractionalHex
  • func (h FractionalHex) Round() Hex
• type Hex
  • func HexagonalGrid(radius int) []Hex
  • func NewHex(q, r int) Hex
  • func Range(center Hex, radius int) []Hex
  • func RectangleGrid(width, height int) []Hex
  • func RectangularGrid(width, height int) []Hex
  • func (h Hex) Add(b Hex) Hex
  • func (h Hex) DistanceTo(b Hex) int
  • func (h Hex) FieldOfView(candidates []Hex, blocking []Hex) []Hex
  • func (h Hex) HasLineOfSight(target Hex, blocking []Hex) bool
  • func (h Hex) Length() int
  • func (h Hex) LineDraw(b Hex) []Hex
  • func (h Hex) Neighbor(dir Direction) Hex
  • func (h Hex) Range(radius int) []Hex
  • func (h Hex) Scale(k int) Hex
  • func (h Hex) String() string
  • func (h Hex) Subtract(b Hex) Hex
• type Layout
• type Orientation
• type Point
  • func EdgeOffset(l Layout, c int) Point
  • func Edges(l Layout, h Hex) []Point
  • func HexToPixel(l Layout, h Hex) Point

Constants

const (
	// DirectionSE is the Southeast side of a hex
	DirectionSE = iota
	// DirectionNE is the Northeast side of a hex
	DirectionNE
	// DirectionN is the North side of a hex
	DirectionN
	// DirectionNW is the Northwest side of a hex
	DirectionNW
	// DirectionSW is the Southwest side of a hex
	DirectionSW
	// DirectionS is the South side of a hex
	DirectionS
)

Variables

var (
	// OrientationPointy ...
	OrientationPointy = Orientation{
		math.Sqrt(3.), math.Sqrt(3.) / 2., 0., 3. / 2., math.Sqrt(3.) / 3., -1. / 3., 0., 2. / 3., 0.5}

	// OrientationFlat ...
	OrientationFlat = Orientation{
		3. / 2., 0., math.Sqrt(3.) / 2., math.Sqrt(3.), 2. / 3., 0., -1. / 3., math.Sqrt(3.) / 3., 0.}
)

Types

type Direction

type Direction int

Direction defines the sides of a hex

func (Direction) ToString

func (d Direction) ToString() string

type FractionalHex

type FractionalHex struct {
	Q float64
	R float64
	S float64
}

FractionHex provides a more precise representation for hexagons when precision is required. It's also represented in Cube Coordinates

func NewFractionalHex

func NewFractionalHex(q, r float64) FractionalHex

func PixelToHex

func PixelToHex(l Layout, p Point) FractionalHex

PixelToHex returns the corresponding hexagon axial coordinates for a given pixel on a certain layout

func (FractionalHex) Round

func (h FractionalHex) Round() Hex

Round returns a 'rounded' FractionalHex, returning a Regular Hex

type Hex

type Hex struct {
	Q int // x axis
	R int // y axis
	S int // z axis
}

Hex describes a regular hexagon with Cube Coordinates (although the S coordinate is computed on the constructor)

It's also easy to reference them as axial (trapezoidal coordinates): - R represents the vertical axis - Q the diagonal one - S can be ignored

For additional reference on these coordinate systems, see http://www.redblobgames.com/grids/hexagons/#coordinates

         _ _
       /     \
  _ _ /(0,-1) \ _ _
/     \  -R   /     \

/(-1,0) \ _ _ /(1,-1) \ \ -Q / \ /

\ _ _ / (0,0) \ _ _ /
/     \       /     \

/(-1,1) \ _ _ / (1,0) \ \ / \ +Q /

\ _ _ / (0,1) \ _ _ /
      \  +R   /
       \ _ _ /

func HexagonalGrid

func HexagonalGrid(radius int) []Hex

HexagonalGrid returns a slice of hexagons that form a hexagon with the specified radius.

func NewHex

func NewHex(q, r int) Hex

NewHex constructs new Hex value with specified q and r.

func Range

func Range(center Hex, radius int) []Hex

Range returns the set of hexagons around the center Hex for a given radius

func RectangleGrid

func RectangleGrid(width, height int) []Hex

RectangleGrid returns the set of hexagons that form a rectangle with the specified width and height

func RectangularGrid

func RectangularGrid(width, height int) []Hex

RectangularGrid returns the set of hexagons that form a rectangle with the specified width and height

func (Hex) Add

func (h Hex) Add(b Hex) Hex

Add performs an addition operation by adding the Hex 'b' to this Hex

func (Hex) DistanceTo

func (h Hex) DistanceTo(b Hex) int

DistanceTo returns the distance from the Hex 'h' to the Hex 'b'

func (Hex) FieldOfView

func (h Hex) FieldOfView(candidates []Hex, blocking []Hex) []Hex

FieldOfView feturns the list of hexagons that are visible from this Hex

func (Hex) HasLineOfSight

func (h Hex) HasLineOfSight(target Hex, blocking []Hex) bool

HasLineOfSight determines if a given hexagon is visible from another hexagon, taking into consideration a set of blocking hexagons

func (Hex) Length

func (h Hex) Length() int

Length calculates the length of a hex

func (Hex) LineDraw

func (h Hex) LineDraw(b Hex) []Hex

LineDraw returns the slice of hexagons that exist on a line that goes from hexagon a to hexagon b

func (Hex) Neighbor

func (h Hex) Neighbor(dir Direction) Hex

Neighbor returns the neighbor at a given direction

func (Hex) Range

func (h Hex) Range(radius int) []Hex

Range returns the set of hexagons around this hex for a given radius

func (Hex) Scale

func (h Hex) Scale(k int) Hex

Scale applies a scaling factor 'k' to the hex, returning a new Hex. If factor k is 1 there's no change

func (Hex) String

func (h Hex) String() string

func (Hex) Subtract

func (h Hex) Subtract(b Hex) Hex

Subtract performas a subtraction operation by subtracting the Hex 'b' from this Hex

type Layout

type Layout struct {
	Orientation Orientation
	// Size defines the multiplication factor relative to the canonical
	// hexagon, where the points are on a unit circle
	Size Point
	// Origin defines the center point for hexagon at 0,0
	Origin Point
}

Layout defines a data struct that holds the parameters of a layout of hex tiles

type Orientation

type Orientation struct {
	// contains filtered or unexported fields
}

Orientation defines the orientation of a layout of hex; pointy or flat

type Point

type Point struct {
	X float64
	Y float64
}

Point defines a geometric point with coordinates (x,y)

func EdgeOffset

func EdgeOffset(l Layout, c int) Point

EdgeOffset returns the edge offset of the hexago for the given layout and edge number, starting at the E vertex and proceeding in a counter-clockwise order

func Edges

func Edges(l Layout, h Hex) []Point

Edges returns the corners of the hexagon for the given layout, starting at the E vertex and proceeding in a CCW order

func HexToPixel

func HexToPixel(l Layout, h Hex) Point

HexToPixel returns the center pixel for a given hexagon an a certain layout