An grid of arbitrary dimensions.

e.g. a Grid [2, 3] Int might look like:

generate id :: Grid [2, 3] Int
fromNestedLists [[0,1,2],
                 [3,4,5]]

Build a grid by selecting an element for each element

fmap f . tabulate ≡ tabulate . fmap f

If no definition is provided, this will default to gtabulate.

Turn a nested list structure into a Grid if the list is well formed. Required list nesting increases for each dimension

fromNestedLists [[0,1,2],[3,4,5]] :: Maybe (Grid [2, 3] Int)
Just (Grid [[0,1,2],[3,4,5]])
fromNestedLists [[0],[1,2]] :: Maybe (Grid [2, 3] Int)
Nothing

Partial variant of fromNestedLists which errors on malformed input

Convert a list into a Grid or fail if not provided the correct number of elements

G.fromList [0, 1, 2, 3, 4, 5] :: Maybe (Grid [2, 3] Int)
Just (Grid [[0,1,2],[3,4,5]])
G.fromList [0, 1, 2, 3] :: Maybe (Grid [2, 3] Int)
Nothing

Partial variant of fromList which errors on malformed input

Turn a grid into a nested list structure. List nesting increases for each dimension

toNestedLists (G.generate id :: Grid [2, 3] Int)
[[0,1,2],[3,4,5]]

The index type for Grids.

Safely construct a Coord for a given grid size, checking that all indexes are in range

λ> coord @[3, 3] [1, 2]
Just [1, 2]

λ> coord @[3, 3] [3, 3]
Nothing

λ> coord @[3, 3] [1, 2, 3]
Nothing

Get the first index from a Coord

Append two Coords

If no definition is provided, this will default to gindex.

Update elements of a grid

Focus an element of a Grid given its Coord

Perform a computation based on the context surrounding a cell Good for doing things like Linear Image Filters (e.g. gaussian blur) or simulating Cellular Automata (e.g. Conway's game of life)

This function accepts a function which indicates what to do with 'out-of-bounds' indexes, clampWindow, wrapWindow and safeWindow are examples.

It also acccepts a transformation function which operates over the functor created by the first parameter and collapses it down to a new value for the cell at that position.

This function is best used with Type Applications to denote the desired window size; the Grid passed to the given function contains the current cell (in the middle) and all the surrounding cells.

Here's an example of computing the average of all neighboring cells, repeating values at the edge of the grid when indexes are out of bounds (using clampWindow)

gaussian :: (IsGrid dims) => Grid dims Double -> Grid dims Double
gaussian = autoConvolute clampBounds avg
 where
  avg :: Grid '[3, 3] Double -> Double
  avg g = sum g / fromIntegral (length g)

This is a fully generic version of autoConvolute which allows the user to provide a function which builds a context from the current coord, then provides a collapsing function over the same functor.

Given a coordinate generate a grid of size window filled with coordinates surrounding the given coord. Mostly used internally

Use with autoConvolute; Clamp out-of-bounds coordinates to the nearest in-bounds coord.

Use with autoConvolute; Wrap out-of-bounds coordinates pac-man style to the other side of the grid

Use with autoConvolute; Out of bounds coords become Nothing

Transpose a 2 dimensional matrix. Equivalent to:

permute @[1, 0]

Permute dimensions of a Grid. This is similar to MatLab's permute function

permute requires a type application containing a permutation pattern; The pattern is a re-ordering of the list [0..n] which represents the new dimension order. For example the permutation pattern [1, 2, 0] when applied to the dimensions [4, 5, 6] results in the dimensions [5, 6, 4].

For 2 dimensional matrixes, a permutation using [1, 0] is simply a matrix transpose

λ> small
fromNestedLists
  [[0,1,2]
  ,[3,4,5]
  ,[6,7,8]]

λ> permute @[1, 0] small
fromNestedLists
  [[0,3,6]
  ,[1,4,7]
  ,[2,5,8]]

Permute the dimensions of a coordinate according to a permutation pattern. see permute regarding permutation patterns

The inverse of splitGrid, joinGrid will nest a grid from: > Grid outer (Grid inner a) -> Grid (outer ++ inner) a

For example, you can nest a simple 3x3 from smaller [3] grids as follows:

joinGrid (myGrid :: Grid [3] (Grid [3] a)) :: Grid '[3, 3] a

The inverse of joinGrid, splitGrid outerDims innerDims will un-nest a grid from: > Grid (outer ++ inner) a -> Grid outer (Grid inner a)

For example, you can unnest a simple 3x3 as follows:

splitGrid @'[3] @'[3] myGrid :: Grid '[3] (Grid [3] a)

Represents valid dimensionalities. All non empty lists of Nats have an instance

Computes the level of nesting requried to represent a given grid dimensionality as a nested list

NestedLists [2, 3] Int == [[Int]]
NestedLists [2, 3, 4] Int == [[[Int]]]