pocketpy/docs/modules/array2d.md

---

icon: package

label: array2d

array2d

A rectangular grid for tile maps, images, cellular simulations, and other 2D data. Coordinates are column first, row second: grid[x, y].

Create and address a grid

array2d(width, height, default=None) requires positive dimensions. A callable default receives a vmath.vec2i position for each cell.

from array2d import array2d
from vmath import vec2i

grid = array2d(3, 2, default=0)
grid[1, 0] = 7
assert grid.shape == vec2i(3, 2)
assert grid.numel == 6
assert grid.tolist() == [[0, 7, 0], [0, 0, 0]]
assert grid.get(99, 0, -1) == -1

cells = array2d(2, 2, default=lambda pos: [])
cells[0, 0].append('player')
assert cells[1, 0] == []

A non-callable default is copied by reference into every cell. Use a factory, as above, for independent mutable objects.

array2d.fromlist(rows) accepts a nonempty rectangular list of rows. width/n_cols, height/n_rows, shape, and numel describe the dimensions. Integer cell coordinates must be nonnegative and in bounds. Use is_valid(x, y) or get(x, y, default) for boundary-aware access.

Views, copies, and masks

Slicing creates a view sharing the original grid. Call copy() for a separate grid; contained Python objects are still shallow-copied.

from array2d import array2d

grid = array2d(3, 2, default=0)
view = grid[1:3, :]
view[:, :] = 5
assert grid.tolist() == [[0, 5, 5], [0, 5, 5]]

mask = grid == 5
assert mask.any()
assert not mask.all()
assert grid[mask] == [5, 5, 5, 5]
grid[mask] = 9
assert grid.count(9) == 4

Comparisons produce boolean grids, not a single boolean. Use (a == b).all() for whole-grid equality. Arithmetic and bitwise operations accept scalars or compatible grids.

Transform and analyze

Method	Use
map(function)	Return a new grid of transformed values.
apply(function)	Transform cells in place.
zip_with(other, function)	Combine two grids cell by cell.
index(value), count(value)	Find the first position or count matching cells.
get_bounding_rect(value)	(x, y, width, height); raise ValueError if absent.
count_neighbors(value, neighborhood)	Count matching neighbors of each cell.
get_connected_components(value, neighborhood)	Return a label grid and component count; label 0 is unvisited.
convolve(kernel, padding)	Integer-grid convolution with a padding value.
render(), render_with_color(fg, bg)	Produce text for display.

Neighborhood names are 'Moore' (eight neighbors) and 'von Neumann' (four neighbors). Iteration yields (position, value) pairs.

Chunked grids

chunked_array2d(chunk_size, default=None, auto_add_chunk=True) stores chunks addressed with vec2i world coordinates. It provides chunk creation, removal, movement, context data, and rectangular/chunk views. Use world_to_chunk(position) to obtain the chunk coordinate and local cell coordinate.

The API declarations list the full grid, view, and chunk interfaces. array2d is not supported by pickle; tolist() can provide a serializable representation when the cell values support it.