Grid¶

def to_geodataframe(self) -> GeoDataFrame[GridSchema]:
    """Convert the GridCell to a GeoDataFrame."""
    gdf = gpd.GeoDataFrame(
        {
            "grid_cell": [self.id],
            "grid_dist": [self.d],
            "cell_geometry": gpd.GeoSeries([self.cell_geometry], crs="EPSG:4326"),
            "cell_utm_crs": [self.utm_crs],
            "cell_utm_footprint": gpd.GeoSeries(
                [self.utm_footprint], crs=self.utm_crs
            ),
        },
        geometry="cell_geometry",
        crs="EPSG:4326",
    )
    return cast(GeoDataFrame, GridSchema.validate(gdf))

def area_name(self, resolution: float) -> str:
    """Get the area name based on grid cell and *resolution* in metres."""
    if isinstance(resolution, float) and resolution.is_integer():
        res_str = str(int(resolution))
    else:
        res_str = str(resolution)
    return f"{self.id}_dist-{self.d}m_res-{res_str}m"

def to_geobox(
    self,
    resolution: float,
    margin: float = 0.0,
    alignment_resolution: float | None = None,
) -> GeoBox:
    """Return an odc-geo GeoBox for this cell's UTM footprint.

    The GeoBox is centred on the reprojected WGS84 centroid and its
    dimensions are an integer number of pixels, so it covers at least
    ``d * (1 + margin/100)`` metres in each direction. The centre and
    half-width are snapped to ``alignment_resolution`` (defaulting to
    ``resolution``) and the bounding box is built with ``anchor='edge'``,
    which preserves the snapped extent.

    To guarantee that nested resolutions share the same origin (e.g. VIIRS
    at 400 m and GOES at 2000 m), pass the coarser resolution as
    ``alignment_resolution`` when building the finer-resolution GeoBox. The
    half-width is then rounded up to a multiple of both resolutions, so the
    finer grid is an exact refinement of the coarser one.

    Args:
        resolution: Target pixel resolution in metres.
        margin: Percentage margin added to the patch's nominal size
            (e.g. 5.0 for 5%).
        alignment_resolution: Grid to which the centre and half-width are
            snapped. Defaults to ``resolution``. Use a coarser resolution
            when you need pixel-level alignment across nested extractions.

    Returns:
        A GeoBox aligned to the cell's UTM grid point.
    """
    utm_centroid = cast(
        Point,
        reproject_geom(
            self.cell_geometry.centroid, src_epsg=_WGS84_CRS, dst_epsg=self.utm_crs
        ),
    )

    align_res = (
        alignment_resolution if alignment_resolution is not None else resolution
    )

    # Snap the centre to the alignment grid. Using the same alignment grid
    # for different resolutions keeps origins stable.
    cx = round(utm_centroid.x / align_res) * align_res
    cy = round(utm_centroid.y / align_res) * align_res
    crs = self.utm_crs

    nominal_half = (self.d * (1 + margin / 100)) / 2
    # Round the half-width up to a multiple of both the target resolution
    # and the alignment resolution so the output shape is an integer number
    # of pixels at both resolutions.
    step = math.lcm(int(round(resolution)), int(round(align_res)))
    exact_half = math.ceil(nominal_half / step) * step

    bbox = (cx - exact_half, cy - exact_half, cx + exact_half, cy + exact_half)
    # anchor='edge' preserves the snapped bounding box instead of expanding
    # it to centre a pixel, giving deterministic origins across resolutions.
    return GeoBox.from_bbox(bbox, crs, resolution=resolution, anchor="edge")

def raw_cell_from_id(self, cell_id: str) -> tuple[Polygon, str, bool]:
    """Return a raw cell (geom, id, is_primary) for the given cell ID."""
    if "_" not in cell_id:
        base_cell = super().cell_from_id(cell_id)
        return base_cell.geom, cell_id, base_cell.is_primary

    parts = cell_id.split("_")
    y_str, x_str = parts[0], parts[1]
    is_primary = _OVERLAP_SUFFIX not in parts

    row_idx = self._row_id_to_index(y_str)
    row_lat = self.get_row_lat(row_idx)
    col_idx = self._col_id_to_index(x_str, row_lat)

    lon_spacing = self.get_lon_spacing(row_lat)
    return self._cell_from_indices(
        row_idx, col_idx, lon_spacing, is_primary, cell_id
    )

def get_cell_name(
    self,
    row_idx: int,
    col_idx: int,
    lon_spacing: float,
    is_primary: bool = True,
) -> str:
    """Build a cell identifier from row/column indices.

    Args:
        row_idx: Row index in the global grid.
        col_idx: Column index in the global grid.
        lon_spacing: Longitude spacing at the row's latitude.
        is_primary: If False, append the overlap suffix.

    Returns:
        Cell identifier such as ``"0U_0R"`` or ``"0U_0R_OV"``.
    """
    name = f"{self._row_index_to_id(row_idx)}_{self._col_index_to_id(col_idx, lon_spacing)}"
    if not is_primary:
        name += f"_{_OVERLAP_SUFFIX}"
    return name

def generate_raw_cells(
    self, polygon: BaseGeometry
) -> Sequence[tuple[Polygon, str, bool]]:
    """Generate raw grid cells that intersect with the given polygon."""
    shapely.prepare(polygon)
    min_lon, min_lat, max_lon, max_lat = polygon.bounds
    if min_lon > max_lon:
        max_lon += 360

    start_row = int(np.floor((min_lat + 90 - self._lat_offset) / self.lat_spacing))
    end_row = int(np.ceil((max_lat + 90 - self._lat_offset) / self.lat_spacing))

    start_row, end_row = _expand_bounds(
        start_row, end_row, min_lat, max_lat, self.get_row_lat
    )

    cells: list[tuple[Polygon, str, bool]] = []

    for row_idx in range(start_row, end_row + 1):
        lat = self.get_row_lat(row_idx)
        lon_spacing = self.get_lon_spacing(lat)
        lon_offset = self.get_lon_offset(lon_spacing)

        start_col = int(np.floor((min_lon + 180 - lon_offset) / lon_spacing))
        end_col = int(np.ceil((max_lon + 180 - lon_offset) / lon_spacing))

        start_col, end_col = _expand_bounds(
            start_col,
            end_col,
            min_lon,
            max_lon,
            lambda col: self.get_col_lon(col, lon_spacing, lon_offset),
        )

        cols = np.arange(start_col, end_col + 1)
        lons = self.get_col_lon(cols, lon_spacing, lon_offset)

        xmin = lons
        ymin = lat
        xmax = lons + lon_spacing
        ymax = lat + self.lat_spacing

        primary_polys = shapely.box(xmin, ymin, xmax, ymax)  # pyright: ignore[reportCallIssue, reportArgumentType]
        primary_mask = shapely.intersects(primary_polys, polygon)

        matched_cols = cols[primary_mask]

        for poly, c_idx in zip(primary_polys[primary_mask], matched_cols):
            c_id = self.get_cell_name(row_idx, c_idx, lon_spacing, is_primary=True)
            cells.append((poly, c_id, True))

        if self.overlap:
            self._add_overlap_cells(
                lons, lat, lon_spacing, cols, row_idx, polygon, cells
            )

    return cells