Add Cell.xy for RasterLayer cell coordinates and clarify pos/indices semantics (#299)

* Add Cell.xy for RasterLayer cell coordinates and clarify pos/indices semantics

* [pre-commit.ci] auto fixes from pre-commit.com hooks

for more information, see https://pre-commit.ci

* Update test_RasterLayer.py

* [pre-commit.ci] auto fixes from pre-commit.com hooks

for more information, see https://pre-commit.ci

* Update test_RasterLayer.py

* [pre-commit.ci] auto fixes from pre-commit.com hooks

for more information, see https://pre-commit.ci

* update cell coordinates and deprecation accessors

* update raster layer docstring

* remove cell.grid_pos and recover cell.pos

---------

Co-authored-by: pre-commit-ci[bot] <66853113+pre-commit-ci[bot]@users.noreply.github.com>
Co-authored-by: Wang Boyu <boyu.wby@gmail.com>

Author: 3 people

mesa_geo/raster_layers.py

@@ -8,6 +8,7 @@
 import copy
 import itertools
 import math
+import warnings
 from collections.abc import Callable, Iterable, Iterator, Sequence
 from typing import Any, cast, overload
 
@@ -16,7 +17,7 @@
 from affine import Affine
 from mesa import Model
 from mesa.agent import Agent
-from mesa.space import Coordinate, accept_tuple_argument
+from mesa.space import Coordinate, FloatCoordinate, accept_tuple_argument
 from rasterio.warp import (
     Resampling,
     calculate_default_transform,
@@ -99,6 +100,13 @@ def height(self, height: int) -> None:
 
     @property
     def total_bounds(self) -> np.ndarray | None:
+        """
+        Return the bounds of the raster layer in [min_x, min_y, max_x, max_y] format.
+
+        :return: Bounds of the raster layer in [min_x, min_y, max_x, max_y] format.
+        :rtype: np.ndarray | None
+        """
+
         return self._total_bounds
 
     @total_bounds.setter
@@ -159,24 +167,105 @@ def out_of_bounds(self, pos: Coordinate) -> bool:
 class Cell(Agent):
     """
     Cells are containers of raster attributes, and are building blocks of `RasterLayer`.
+
+    Deprecated:
+        `Cell.indices` is deprecated. Use `Cell.rowcol` instead.
     """
 
-    pos: Coordinate | None
-    indices: Coordinate | None
+    _pos: Coordinate | None
+    _rowcol: Coordinate | None
+    _xy: FloatCoordinate | None
 
-    def __init__(self, model, pos=None, indices=None):
+    def __init__(
+        self,
+        model,
+        pos=None,
+        indices=None,
+        *,
+        rowcol=None,
+        xy=None,
+    ):
         """
         Initialize a cell.
 
-        :param pos: Position of the cell in (x, y) format.
+        :param pos: Grid position of the cell in (grid_x, grid_y) format.
             Origin is at lower left corner of the grid
-        :param indices: Indices of the cell in (row, col) format.
+        :param indices: (Deprecated) Indices of the cell in (row, col) format.
+            Origin is at upper left corner of the grid. Use rowcol instead.
+        :param rowcol: Indices of the cell in (row, col) format.
             Origin is at upper left corner of the grid
+        :param xy: Cell center coordinates in the CRS.
         """
 
         super().__init__(model)
-        self.pos = pos
-        self.indices = indices
+        self._pos = pos
+        self._rowcol = indices if rowcol is None else rowcol
+        self._xy = xy
+
+    @property
+    def pos(self) -> Coordinate | None:
+        """
+        Grid position in (grid_x, grid_y) format with origin at lower left of the grid.
+        """
+        return self._pos
+
+    @pos.setter
+    def pos(self, pos: Coordinate | None) -> None:
+        """
+        Deprecated setter for `pos`.
+        """
+        warnings.warn(
+            "Cell.pos setter is deprecated and will be read-only in a future release.",
+            DeprecationWarning,
+            stacklevel=2,
+        )
+        # set the pos for backward compatibility
+        # in the future, this will be removed and raise an AttributeError,
+        # because pos is read-only
+        self._pos = pos
+
+    @property
+    def indices(self) -> Coordinate | None:
+        """
+        Deprecated alias of `rowcol`.
+        """
+        warnings.warn(
+            "Cell.indices is deprecated and will be removed in a future release. "
+            "Use Cell.rowcol instead.",
+            DeprecationWarning,
+            stacklevel=2,
+        )
+        return self._rowcol
+
+    @indices.setter
+    def indices(self, indices: Coordinate | None) -> None:
+        """
+        Deprecated setter for `rowcol`.
+        """
+        warnings.warn(
+            "Cell.indices is deprecated and will be removed in a future release. "
+            "Use Cell.rowcol instead.",
+            DeprecationWarning,
+            stacklevel=2,
+        )
+        # for backward compatibility, set the rowcol to the indices
+        # in the future, this will be removed
+        # and raise an AttributeError, because indices is read-only
+        self._rowcol = indices
+
+    @property
+    def rowcol(self) -> Coordinate | None:
+        """
+        Raster indices in (row, col) format with origin at upper left of the grid.
+        """
+        return self._rowcol
+
+    @property
+    def xy(self) -> FloatCoordinate | None:
+        """
+        Cell center coordinates in the CRS.
+        """
+        return self._xy
 
     def step(self):
         pass
@@ -228,13 +317,31 @@ def __init__(
         self._attributes = set()
         self._neighborhood_cache = {}
 
+    def _update_transform(self) -> None:
+        super()._update_transform()
+        if getattr(self, "cells", None):
+            self._sync_cell_xy()
+
+    def _sync_cell_xy(self) -> None:
+        for column in self.cells:
+            for cell in column:
+                row, col = cell.rowcol
+                cell._xy = rio.transform.xy(self.transform, row, col, offset="center")
+
     def _initialize_cells(self, model: Model, cell_cls: type[Cell]):
         self.cells = []
-        for x in range(self.width):
+        for grid_x in range(self.width):
             col: list[cell_cls] = []
-            for y in range(self.height):
-                row_idx, col_idx = self.height - y - 1, x
-                col.append(self.cell_cls(model, pos=(x, y), indices=(row_idx, col_idx)))
+            for grid_y in range(self.height):
+                row_idx, col_idx = self.height - grid_y - 1, grid_x
+                xy = rio.transform.xy(self.transform, row_idx, col_idx, offset="center")
+                cell = self.cell_cls(
+                    model,
+                    pos=(grid_x, grid_y),
+                    rowcol=(row_idx, col_idx),
+                    xy=xy,
+                )
+                col.append(cell)
             self.cells.append(col)
 
     @property
@@ -337,9 +444,13 @@ def apply_raster(self, data: np.ndarray, attr_name: str | None = None) -> None:
         if attr_name is None:
             attr_name = f"attribute_{len(self.cell_cls.__dict__)}"
         self._attributes.add(attr_name)
-        for x in range(self.width):
-            for y in range(self.height):
-                setattr(self.cells[x][y], attr_name, data[0, self.height - y - 1, x])
+        for grid_x in range(self.width):
+            for grid_y in range(self.height):
+                setattr(
+                    self.cells[grid_x][grid_y],
+                    attr_name,
+                    data[0, self.height - grid_y - 1, grid_x],
+                )
 
     def get_raster(self, attr_name: str | None = None) -> np.ndarray:
         """
@@ -364,9 +475,11 @@ def get_raster(self, attr_name: str | None = None) -> np.ndarray:
             attr_names = {attr_name}
         data = np.empty((num_bands, self.height, self.width))
         for ind, name in enumerate(attr_names):
-            for x in range(self.width):
-                for y in range(self.height):
-                    data[ind, self.height - y - 1, x] = getattr(self.cells[x][y], name)
+            for grid_x in range(self.width):
+                for grid_y in range(self.height):
+                    data[ind, self.height - grid_y - 1, grid_x] = getattr(
+                        self.cells[grid_x][grid_y], name
+                    )
         return data
 
     def iter_neighborhood(
@@ -380,12 +493,13 @@ def iter_neighborhood(
         Return an iterator over cell coordinates that are in the
         neighborhood of a certain point.
 
-        :param Coordinate pos: Coordinate tuple for the neighborhood to get.
+        :param Coordinate pos: Grid coordinate tuple (grid_x, grid_y) for the
+            neighborhood to get. Origin is at lower left corner of the grid.
         :param bool moore: Whether to use Moore neighborhood or not. If True,
             return Moore neighborhood (including diagonals). If False, return
             Von Neumann neighborhood (exclude diagonals).
-        :param bool include_center: If True, return the (x, y) cell as well.
-            Otherwise, return surrounding cells only. Default is False.
+        :param bool include_center: If True, return the (grid_x, grid_y) cell as
+            well. Otherwise, return surrounding cells only. Default is False.
         :param int radius: Radius, in cells, of the neighborhood. Default is 1.
         :return: An iterator over cell coordinates that are in the neighborhood.
             For example with radius 1, it will return list with number of elements
@@ -406,12 +520,13 @@ def iter_neighbors(
         """
         Return an iterator over neighbors to a certain point.
 
-        :param Coordinate pos: Coordinate tuple for the neighborhood to get.
+        :param Coordinate pos: Grid coordinate tuple (grid_x, grid_y) for the
+            neighborhood to get. Origin is at lower left corner of the grid.
         :param bool moore: Whether to use Moore neighborhood or not. If True,
             return Moore neighborhood (including diagonals). If False, return
             Von Neumann neighborhood (exclude diagonals).
-        :param bool include_center: If True, return the (x, y) cell as well.
-            Otherwise, return surrounding cells only. Default is False.
+        :param bool include_center: If True, return the (grid_x, grid_y) cell
+            as well. Otherwise, return surrounding cells only. Default is False.
         :param int radius: Radius, in cells, of the neighborhood. Default is 1.
         :return: 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).
@@ -429,8 +544,8 @@ def iter_cell_list_contents(
         Returns an iterator of the contents of the cells
         identified in cell_list.
 
-        :param Iterable[Coordinate] cell_list: Array-like of (x, y) tuples,
-            or single tuple.
+        :param Iterable[Coordinate] cell_list: Array-like of grid (grid_x, grid_y) tuples,
+            or single tuple (grid_x, grid_y). Origin is at lower left corner of the grid.
         :return: An iterator of the contents of the cells identified in cell_list.
         :rtype: Iterator[Cell]
         """
@@ -448,8 +563,8 @@ def get_cell_list_contents(self, cell_list: Iterable[Coordinate]) -> list[Cell]:
 
         Note: this method returns a list of cells.
 
-        :param Iterable[Coordinate] cell_list: Array-like of (x, y) tuples,
-            or single tuple.
+        :param Iterable[Coordinate] cell_list: Array-like of grid (grid_x, grid_y) tuples,
+            or single tuple (grid_x, grid_y). Origin is at lower left corner of the grid.
         :return: A list of the contents of the cells identified in cell_list.
         :rtype: List[Cell]
         """
@@ -463,6 +578,24 @@ def get_neighborhood(
         include_center: bool = False,
         radius: int = 1,
     ) -> list[Coordinate]:
+        """
+        Return a list of cell coordinates that are in the
+        neighborhood of a certain point.
+
+        :param Coordinate pos: Grid coordinate tuple (grid_x, grid_y) for the
+            neighborhood to get. Origin is at lower left corner of the grid.
+        :param bool moore: Whether to use Moore neighborhood or not. If True,
+            return Moore neighborhood (including diagonals). If False, return
+            Von Neumann neighborhood (exclude diagonals).
+        :param bool include_center: If True, return the (grid_x, grid_y) cell as
+            well. Otherwise, return surrounding cells only. Default is False.
+        :param int radius: Radius, in cells, of the neighborhood. Default is 1.
+        :return: A list of 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).
+        :rtype: List[Coordinate]
+        """
         cache_key = (pos, moore, include_center, radius)
         neighborhood = self._neighborhood_cache.get(cache_key, None)
 
@@ -500,8 +633,18 @@ def get_neighboring_cells(
         return [self.cells[idx[0]][idx[1]] for idx in neighboring_cell_idx]
 
     def to_crs(self, crs, inplace=False) -> RasterLayer | None:
+        """
+        Transform the raster layer to a new coordinate reference system.
+
+        :param crs: The coordinate reference system to transform to.
+        :param inplace: Whether to transform the raster layer in place or
+            return a new raster layer. Defaults to False.
+        :return: The transformed raster layer if not inplace.
+        :rtype: RasterLayer | None
+        """
+
         super()._to_crs_check(crs)
-        layer = self if inplace else copy.copy(self)
+        layer = self if inplace else copy.deepcopy(self)
 
         src_crs = rio.crs.CRS.from_user_input(layer.crs)
         dst_crs = rio.crs.CRS.from_user_input(crs)
@@ -518,6 +661,8 @@ def to_crs(self, crs, inplace=False) -> RasterLayer | None:
             ]
             layer.crs = crs
             layer._transform = transform
+            if getattr(layer, "cells", None):
+                layer._sync_cell_xy()
 
         if not inplace:
             return layer
@@ -529,7 +674,7 @@ def to_image(self, colormap) -> ImageLayer:
 
         values = np.empty(shape=(4, self.height, self.width))
         for cell in self:
-            row, col = cell.indices
+            row, col = cell.rowcol
             values[:, row, col] = colormap(cell)
         return ImageLayer(values=values, crs=self.crs, total_bounds=self.total_bounds)
 
@@ -563,6 +708,7 @@ def from_file(
             ]
             obj = cls(width, height, dataset.crs, total_bounds, model, cell_cls)
             obj._transform = dataset.transform
+            obj._sync_cell_xy()
             obj.apply_raster(values, attr_name=attr_name)
             return obj
 
@@ -639,6 +785,15 @@ def values(self, values: np.ndarray) -> None:
         self._update_transform()
 
     def to_crs(self, crs, inplace=False) -> ImageLayer | None:
+        """
+        Transform the image layer to a new coordinate reference system.
+
+        :param crs: The coordinate reference system to transform to.
+        :param inplace: Whether to transform the image layer in place or
+            return a new image layer. Defaults to False.
+        :return: The transformed image layer if not inplace.
+        :rtype: ImageLayer | None
+        """
         super()._to_crs_check(crs)
         layer = self if inplace else copy.copy(self)