apbase.grid

Regular target-grid generation, shared by IDW and kriging interpolation.

This package exports the Grid class and a functional convenience wrapper for generating regular point grids used as interpolation targets.

class apbase.grid.Grid(*, boundary=None, resolution=20.0, chunk_size=1000000, hull_ratio=0.12, coordinate_transform=None, geographic_mode=None)

Bases: object

Generate regular target points inside a boundary.

The boundary either comes from the caller (boundary=, or the from_wkt()/from_wkb() constructors) or is inferred as a concave hull of x/y source points (from_data_xy(), or plain fit(x, y)) when none is given.

Parameters:

  • boundary (Boundary | None) – Optional Shapely geometry used as the interpolation domain. When omitted, a concave hull is inferred from the finite input points.

  • resolution (float) – Grid spacing in the same units as the input coordinates.

  • chunk_size (int) – Maximum number of candidate points tested per chunk.

  • hull_ratio (float) – Ratio passed to shapely.concave_hull when the boundary is inferred. Has no effect when boundary is supplied explicitly.

  • coordinate_transform (CoordinateTransform | None) – Optional CoordinateTransform applied to boundary before building the grid, so it lands in the same frame as x/y already converted with prepare_metric_xy. Takes priority over geographic_mode.

  • geographic_mode (str | None) – None (default), "local", or "utm". When boundary looks geographic and x/y does not, reprojects boundary to metric before building the grid.

boundary
resolution
chunk_size
hull_ratio
coordinate_transform
geographic_mode
classmethod from_data_xy(x, y, **kwargs)

Create a grid and infer its boundary from x/y source points (concave hull).

Equivalent to Grid(**kwargs).fit(x, y) with no explicit boundary. Use from_wkt(), from_wkb(), or pass boundary= directly instead when the domain is already known – source points are not needed in that case.

Parameters:

  • x (array_like) – Source coordinates used to infer the concave-hull boundary.

  • y (array_like) – Source coordinates used to infer the concave-hull boundary.

  • **kwargs – Keyword arguments forwarded to Grid.

Returns:

Fitted grid.

Return type:

Grid

classmethod from_wkt(wkt, **kwargs)

Create a grid whose boundary is parsed from a WKT string.

No source points are needed: the grid is generated directly from the parsed geometry.

Parameters:

  • wkt (str) – Boundary geometry encoded as WKT.

  • **kwargs – Keyword arguments forwarded to Grid.

Returns:

Fitted grid.

Return type:

Grid

classmethod from_wkb(wkb, **kwargs)

Create a grid whose boundary is parsed from WKB bytes.

No source points are needed: the grid is generated directly from the parsed geometry.

Parameters:

  • wkb (bytes) – Boundary geometry encoded as WKB.

  • **kwargs – Keyword arguments forwarded to Grid.

Returns:

Fitted grid.

Return type:

Grid

property is_fitted: bool

Whether the grid points have already been generated.

Returns:

True after fit() succeeds.

Return type:

bool

property points: ndarray

Generated target coordinates.

Returns:

(n_points, 2) target coordinates inside the fitted boundary.

Return type:

numpy.ndarray

property fitted_boundary: Boundary

Prepared boundary used to keep target points inside the domain.

Returns:

Buffered and prepared boundary used by point-in-boundary tests.

Return type:

shapely.Geometry

property n_threads: int

Thread count used to parallelize boundary containment tests.

Resolved live from apbase.config["n_threads"] (see the class docstring) on every access – not cached at construction time, so it always reflects the current process-wide setting.

Returns:

Current thread count.

Return type:

int

fit(x=None, y=None)

Generate grid points.

When boundary was supplied to the constructor, the grid is built directly from it; x/y are optional in that case, used only to reconcile boundary against coordinate_transform/ geographic_mode (see the class docstring) – x/y are never used to build the grid points themselves when boundary is given. Otherwise x/y are required: non-finite pairs are removed and a concave hull inferred from the rest becomes the boundary. Input coordinates are assumed to already be in the target projected coordinate system, unless converted via coordinate_transform/ geographic_mode.

Parameters:

  • x (array_like or None, default None) – Source coordinates used only when inferring a boundary or reconciling a provided boundary against a coordinate transform.

  • y (array_like or None, default None) – Source coordinates used only when inferring a boundary or reconciling a provided boundary against a coordinate transform.

Returns:

This grid with generated points and prepared fitted_boundary.

Return type:

Grid

Raises:

ValueError – If no boundary can be inferred, the generated candidate grid is empty, or the candidate grid exceeds apbase.config["grid_max_points_ceiling"].

generate(x=None, y=None)

Fit the grid and return generated target coordinates.

Parameters:

  • x (array_like or None, default None) – Source coordinates forwarded to fit().

  • y (array_like or None, default None) – Source coordinates forwarded to fit().

Returns:

(n_points, 2) target coordinates inside the boundary.

Return type:

numpy.ndarray

apbase.grid.create_point_grid(*, x=None, y=None, resolution, boundary=None, chunk_size=1000000, hull_ratio=0.12)

Create regular target coordinates, from a boundary or from x/y.

Parameters:

  • x (array_like or None, default None) – One-dimensional source coordinates. Required only when boundary is omitted, to infer one as a concave hull of the finite pairs.

  • y (array_like or None, default None) – One-dimensional source coordinates. Required only when boundary is omitted, to infer one as a concave hull of the finite pairs.

  • resolution (float) – Grid spacing in the same coordinate unit as x and y.

  • boundary (object or None, default None) – Optional Shapely geometry used as interpolation boundary. When given, x/y are not needed.

  • chunk_size (int, default DEFAULT_CHUNK_SIZE) – Maximum number of candidate points tested per chunk.

  • hull_ratio (float, default DEFAULT_HULL_RATIO) – Ratio used by Shapely concave hull when boundary is omitted.

Returns:

(n_points, 2) generated target coordinates inside the boundary.

Return type:

numpy.ndarray

Raises:

ValueError – If boundary is omitted and x/y cannot infer a valid boundary, or if the candidate grid is empty or too large.