Finds patterns & shapes in Go board arrangements and names moves.

Use npm to install:

$ npm install @sabaki/boardmatcher

To use this module, require it as follows:

const boardmatcher = require('@sabaki/boardmatcher')

To access library pattern data, require:

const library = require('@sabaki/boardmatcher/library')

The board arrangement is represented by an array of arrays. Each of those subarrays represent one row, all containing the same number of integers. -1 denotes a white stone, 1 a black stone, and 0 represents an empty vertex.

[[ 0,  0,  1,  0, -1, -1,  1,  0, 0],
 [ 1,  0,  1, -1, -1,  1,  1,  1, 0],
 [ 0,  0,  1, -1,  0,  1, -1, -1, 0],
 [ 1,  1,  1, -1, -1, -1,  1, -1, 0],
 [ 1, -1,  1,  1, -1,  1,  1,  1, 0],
 [-1, -1, -1, -1, -1,  1,  0,  0, 0],
 [ 0, -1, -1,  0, -1,  1,  1,  1, 1],
 [ 0,  0,  0,  0,  0, -1, -1, -1, 1],
 [ 0,  0,  0,  0,  0,  0,  0, -1, 0]]

Board positions are represented by an array of the form [x, y] where x and y are non-negative integers, zero-based coordinates of the vertex. [0, 0] denotes the top left position of the board.

Signed vertices are arrays of the form [[x, y], sign] where [x, y] is a vertex, and sign is either -1, 0, or 1 for denoting a white stone, an empty vertex, or a black stone respectively.

A pattern object is an object of the following form:

{
    name?: <String> | null,
    url?: <String> | null,
    size?: <Integer> | null,
    type?: 'corner' | null,
    anchors?: <SignedVertex[]> | null,
    vertices: <SignedVertex[]>
}

• name and url are irrelevant for the matchCorner and matchShape.
• If size is set, this pattern only matches on square boards with the given size.
• If type is set to 'corner', this pattern takes the relative position to the corner into account. Otherwise, the pattern will be invariant to translations.

A match object is an object of the following form:

{
    symmetryIndex: <Integer>,
    invert: <Boolean>,
    anchors: <Vertex[]>,
    vertices: <Vertex[]>
}

• symmetryIndex is an integer between 0 and 7 denoting how the pattern vertices has to be transformed so they match the relative positions of the match.
• invert indicates whether the pattern colors have to be inverted so that they match the matched colors or not.
• anchors holds the anchors of the match that corresponds to the pattern anchors.
• vertices holds the vertices of the match that corresponds to the pattern vertices.

• data <BoardData>
• sign - -1, or 1, denoting the white player or the black player respectively
• vertex - The move the player given by sign is about to make
• options (optional)
  • library <Pattern[]> (optional) - The pattern library to use. Defaults to a pre-curated pattern library.

Returns null if boardmatcher cannot name the given move, otherwise a string with the move name.

• See boardmatcher.nameMove().

Returns null if boardmatcher cannot find a pattern for the given move, otherwise an object of the following form:

{
    pattern: <Pattern>,
    match: <Match>
}

• data <BoardData>
• pattern <Pattern>

A generator function that yields all matches of the given pattern on data. pattern will be regarded as corner type regardless of its type.

• data <BoardData>
• anchor <Vertex>
• pattern <Pattern>

A generator function that yields all matches of the given pattern, for which the given anchor vertex corresponds to one of its anchors, on data.