Raster Layers

class RasterBase(width, height, crs, total_bounds)

Base class for raster layers.

Initialize a raster base layer.

Parameters:

• width – Width of the raster base layer.

• height – Height of the raster base layer.

• crs – Coordinate reference system of the raster base layer.

• total_bounds – Bounds of the raster base layer in [min_x, min_y, max_x, max_y] format.

property width: int

Return the width of the raster base layer.

Returns:

Width of the raster base layer.

Return type:

int

property height: int

Return the height of the raster base layer.

Returns:

Height of the raster base layer.

Return type:

int

property total_bounds: ndarray | None

Return the bounds of the object in [min_x, min_y, max_x, max_y] format.

Returns:

The bounds of the object in [min_x, min_y, max_x, max_y] format.

Return type:

np.ndarray | None

property transform: Affine

Return the affine transformation of the raster base layer.

Returns:

Affine transformation of the raster base layer.

Return type:

Affine

property resolution: tuple[float, float]

Returns the (width, height) of a cell in the units of CRS.

Returns:

Width and height of a cell in the units of CRS.

Return type:

Tuple[float, float]

to_crs(crs, inplace=False) → RasterBase | None

Transform the object to a new coordinate reference system.

Parameters:

• crs – The coordinate reference system to transform to.

• inplace – Whether to transform the object in place or return a new object. Defaults to False.

Returns:

The transformed object if not inplace.

Return type:

GeoBase | None

out_of_bounds(pos: tuple[int, int]) → bool

Determines whether position is off the grid.

Parameters:

pos (Coordinate) – Position to check.

Returns:

True if position is off the grid, False otherwise.

Return type:

bool

property crs: CRS | None

Return the coordinate reference system of the object.

class Cell(model, pos=None, indices=None)

Cells are containers of raster attributes, and are building blocks of RasterLayer.

Initialize a cell.

Parameters:

• pos – Position of the cell in (x, y) format. Origin is at lower left corner of the grid

• indices – Indices of the cell in (row, col) format. Origin is at upper left corner of the grid

pos: tuple[int, int] | None

indices: tuple[int, int] | None

step()

A single step of the agent.

advance() → None

property random: Random

remove() → None

Remove and delete the agent from the model.

class RasterLayer(width, height, crs, total_bounds, model, cell_cls: type[~mesa_geo.raster_layers.Cell] = <class 'mesa_geo.raster_layers.Cell'>)

Some methods in RasterLayer are copied from mesa.space.Grid, including:

__getitem__ __iter__ coord_iter iter_neighborhood get_neighborhood iter_neighbors get_neighbors # copied and renamed to get_neighboring_cells out_of_bounds # copied into RasterBase iter_cell_list_contents get_cell_list_contents

Methods from mesa.space.Grid that are not copied over:

torus_adj neighbor_iter move_agent place_agent _place_agent remove_agent is_cell_empty move_to_empty find_empty exists_empty_cells

Another difference is that mesa.space.Grid has self.grid: List[List[Agent | None]], whereas it is self.cells: List[List[Cell]] here in RasterLayer.

Initialize a raster base layer.

Parameters:

• width – Width of the raster base layer.

• height – Height of the raster base layer.

• crs – Coordinate reference system of the raster base layer.

• total_bounds – Bounds of the raster base layer in [min_x, min_y, max_x, max_y] format.

cells: list[list[Cell]]

property attributes: set[str]

Return the attributes of the cells in the raster layer.

Returns:

Attributes of the cells in the raster layer.

Return type:

Set[str]

coord_iter() → Iterator[tuple[Cell, int, int]]

An iterator that returns coordinates as well as cell contents.

apply_raster(data: ndarray, attr_name: str | None = None) → None

Apply raster data to the cells.

Parameters:

• data (np.ndarray) – 2D numpy array with shape (1, height, width).

• attr_name (str | None) – Name of the attribute to be added to the cells. If None, a random name will be generated. Default is None.

Raises:

ValueError – If the shape of the data is not (1, height, width).

get_raster(attr_name: str | None = None) → ndarray

Return the values of given attribute.

Parameters:

attr_name (str | None) – Name of the attribute to be returned. If None, returns all attributes. Default is None.

Returns:

The values of given attribute as a 2D numpy array with shape (1, height, width).

Return type:

np.ndarray

iter_neighborhood(pos: tuple[int, int], moore: bool, include_center: bool = False, radius: int = 1) → Iterator[tuple[int, int]]

Return an iterator over cell coordinates that are in the neighborhood of a certain point.

Parameters:

• pos (Coordinate) – Coordinate tuple for the neighborhood to get.

• moore (bool) – Whether to use Moore neighborhood or not. If True, return Moore neighborhood (including diagonals). If False, return Von Neumann neighborhood (exclude diagonals).

• include_center (bool) – If True, return the (x, y) cell as well. Otherwise, return surrounding cells only. Default is False.

• radius (int) – Radius, in cells, of the neighborhood. Default is 1.

Returns:

An iterator over cell coordinates that are in the neighborhood. For example with radius 1, it will return list with number of elements equals at most 9 (8) if Moore, 5 (4) if Von Neumann (if not including the center).

Return type:

Iterator[Coordinate]

iter_neighbors(pos: tuple[int, int], moore: bool, include_center: bool = False, radius: int = 1) → Iterator[Cell]

Return an iterator over neighbors to a certain point.

Parameters:

• pos (Coordinate) – Coordinate tuple for the neighborhood to get.

• moore (bool) – Whether to use Moore neighborhood or not. If True, return Moore neighborhood (including diagonals). If False, return Von Neumann neighborhood (exclude diagonals).

• include_center (bool) – If True, return the (x, y) cell as well. Otherwise, return surrounding cells only. Default is False.

• radius (int) – Radius, in cells, of the neighborhood. Default is 1.

Returns:

An iterator of cells that are in the neighborhood; at most 9 (8) if Moore, 5 (4) if Von Neumann (if not including the center).

Return type:

Iterator[Cell]

iter_cell_list_contents(positions) → Any

property crs: CRS | None

Return the coordinate reference system of the object.

get_cell_list_contents(positions) → Any

property height: int

Return the height of the raster base layer.

Returns:

Height of the raster base layer.

Return type:

int

out_of_bounds(pos: tuple[int, int]) → bool

Determines whether position is off the grid.

Parameters:

pos (Coordinate) – Position to check.

Returns:

True if position is off the grid, False otherwise.

Return type:

bool

property resolution: tuple[float, float]

Returns the (width, height) of a cell in the units of CRS.

Returns:

Width and height of a cell in the units of CRS.

Return type:

Tuple[float, float]

property total_bounds: ndarray | None

Return the bounds of the object in [min_x, min_y, max_x, max_y] format.

Returns:

The bounds of the object in [min_x, min_y, max_x, max_y] format.

Return type:

np.ndarray | None

property transform: Affine

Return the affine transformation of the raster base layer.

Returns:

Affine transformation of the raster base layer.

Return type:

Affine

property width: int

Return the width of the raster base layer.

Returns:

Width of the raster base layer.

Return type:

int

get_neighborhood(pos: tuple[int, int], moore: bool, include_center: bool = False, radius: int = 1) → list[tuple[int, int]]

get_neighboring_cells(pos: tuple[int, int], moore: bool, include_center: bool = False, radius: int = 1) → list[Cell]

to_crs(crs, inplace=False) → RasterLayer | None

Transform the object to a new coordinate reference system.

Parameters:

• crs – The coordinate reference system to transform to.

• inplace – Whether to transform the object in place or return a new object. Defaults to False.

Returns:

The transformed object if not inplace.

Return type:

GeoBase | None

to_image(colormap) → ImageLayer

Returns an ImageLayer colored by the provided colormap.

classmethod from_file(raster_file: str, model: ~mesa.model.Model, cell_cls: type[~mesa_geo.raster_layers.Cell] = <class 'mesa_geo.raster_layers.Cell'>, attr_name: str | None = None, rio_opener: ~collections.abc.Callable | None = None) → RasterLayer

Creates a RasterLayer from a raster file.

Parameters:

• raster_file (str) – Path to the raster file.

• cell_cls (Type[Cell]) – The class of the cells in the layer.

• attr_name (str | None) – The name of the attribute to use for the cell values. If None, a random name will be generated. Default is None.

• rio_opener (Callable | None) – A callable passed to Rasterio open() function.

to_file(raster_file: str, attr_name: str | None = None, driver: str = 'GTiff') → None

Writes a raster layer to a file.

Parameters:

• raster_file (str) – The path to the raster file to write to.

• attr_name (str | None) – The name of the attribute to write to the raster. If None, all attributes are written. Default is None.

• driver (str) – The GDAL driver to use for writing the raster file. Default is ‘GTiff’. See GDAL docs at https://gdal.org/drivers/raster/index.html.

class ImageLayer(values, crs, total_bounds)

Initializes an ImageLayer.

Parameters:

• values – The values of the image layer.

• crs – The coordinate reference system of the image layer.

• total_bounds – The bounds of the image layer in [min_x, min_y, max_x, max_y] format.

property crs: CRS | None

Return the coordinate reference system of the object.

property height: int

Return the height of the raster base layer.

Returns:

Height of the raster base layer.

Return type:

int

out_of_bounds(pos: tuple[int, int]) → bool

Determines whether position is off the grid.

Parameters:

pos (Coordinate) – Position to check.

Returns:

True if position is off the grid, False otherwise.

Return type:

bool

property resolution: tuple[float, float]

Returns the (width, height) of a cell in the units of CRS.

Returns:

Width and height of a cell in the units of CRS.

Return type:

Tuple[float, float]

property total_bounds: ndarray | None

Return the bounds of the object in [min_x, min_y, max_x, max_y] format.

Returns:

The bounds of the object in [min_x, min_y, max_x, max_y] format.

Return type:

np.ndarray | None

property transform: Affine

Return the affine transformation of the raster base layer.

Returns:

Affine transformation of the raster base layer.

Return type:

Affine

property width: int

Return the width of the raster base layer.

Returns:

Width of the raster base layer.

Return type:

int

property values: ndarray

Returns the values of the image layer.

Returns:

The values of the image layer.

Return type:

np.ndarray

to_crs(crs, inplace=False) → ImageLayer | None

Transform the object to a new coordinate reference system.

Parameters:

• crs – The coordinate reference system to transform to.

• inplace – Whether to transform the object in place or return a new object. Defaults to False.

Returns:

The transformed object if not inplace.

Return type:

GeoBase | None

classmethod from_file(image_file) → ImageLayer

Creates an ImageLayer from an image file.

Parameters:

image_file – The path to the image file.

Returns:

The ImageLayer.

Return type:

ImageLayer