neighbourhood

Cell neighbourhood definitions. The neighbourhood of a cell in a pattern defines which other cells are considered its neighbours. This is an important definition for many functions in forma. For example, when finding all cells that border a pattern in pattern.exterior_hull a definition of border in terms of a neighbourhood is required. Cellular automata rules are also defined in terms of neighbourhoods.

This module provides a class to represent a neighbourhood, along with examples of typical neighbourhoods such as the Moore or von Neumann neighbourhoods.

-- Load some neighbourhoods to use with other functions
local moore = neighbourhood.moore()
local vn    = neighbourhood.von_neumann()

-- Define a new neighbourhood from a table of forma.cells
local cell_list = {cell.new(-1,1), cell.new(1,-1)}
local new_neighbourhood = neighbourhood.new(cell_list)

Fields

Name	Type	Description
_category_label	string[]|nil	category labels for rendering
categories	table[]|nil	generated neighbourhood configurations (lazy)

neighbourhood.moore

The Moore neighbourhood. Wikipedia entry.

Contains all cells with Chebyshev distance 1 from origin. Used in Conway's Game of Life. Ordered clockwise assuming a downwards y-axis and rightwards x-axis.

Returns:

• forma.neighbourhood — the Moore neighbourhood

neighbourhood.von_neumann

The von Neumann neighbourhood. Wikipedia entry.

Contains all cells with Manhattan distance 1 from origin. Ordered clockwise assuming an upwards y-axis and rightwards x-axis.

Returns:

• forma.neighbourhood — the von Neumann neighbourhood

neighbourhood.diagonal

The diagonal neighbourhood.

Contains all cells diagonally bordering the origin. i.e the Moore neighbourhood with the von Neumann subtracted. Ordered clockwise assuming an upwards y-axis and rightwards x-axis.

Returns:

• forma.neighbourhood — the diagonal neighbourhood

neighbourhood.diagonal_2

The twice diagonal neighbourhood.

Contains all cells two cells away from the origin along the diagonal axes. Ordered clockwise assuming an upwards y-axis and rightwards x-axis.

Returns:

• forma.neighbourhood — the twice diagonal neighbourhood

neighbourhood.knight

The knight neighbourhood.

Contains all cells that are a knight piece chess move away from the origin.

Returns:

• forma.neighbourhood — the knight neighbourhood

neighbourhood.new

Generate a new neighbourhood from a set of cells.

local cell_list = {cell.new(-1, 1), cell.new(1, -1)}
local nbh = neighbourhood.new(cell_list)

Parameters:

Name	Type	Description
neighbour_cells	forma.cell[]	a list of neighbouring cell vectors

Returns:

• forma.neighbourhood — a neighbourhood comprised of neighbour_cells

neighbourhood.categorise

Identify which category a cell in a pattern fits into. Categorises cells in a pattern according to their neighbourhood configuration. For each cell in a forma.pattern, there are a finite number of possible configurations of neighbouring cells. Specifically, each cell has 2^n possible neighbourhood configurations where n is the number of cells in the neighbourhood. This method categorises cells according to which type of neighbourhood they are in.

Parameters:

Name	Type	Description
nbh	forma.neighbourhood	the neighbourhood to categorise the cell in
ip	forma.pattern	the input pattern
icell	forma.cell	the cell in ip of interest

Returns:

• integer — the category index of nbh that the cell belongs to

neighbourhood.category_label

Returns the category labelling (if it exists) for a neighbourhood.

Parameters:

Name	Type	Description
nbh	forma.neighbourhood	the neighbourhood to fetch the category labelling for

Returns:

• string[]|nil — a table of labels, one for each neighbourhood category

neighbourhood.get_ncategories

Returns the number of categories for a neighbourhood.

Parameters:

Name	Type	Description
nbh	forma.neighbourhood	the neighbourhood in question

Returns:

• integer — the number of categories for neighbourhood nbh