grid3d

py3dinterpolations.core.grid3d

3D grid definitions for interpolation.

GridAxis(name, min, max, res) dataclass

A single axis of a 3D grid.

Parameters:

Name	Type	Description	Default
name	Axis	Axis identifier.	required
min	float	Minimum value.	required
max	float	Maximum value.	required
res	float	Resolution (step size).	required

grid property

1D array of evenly spaced values along this axis.

Grid3D(x, y, z)

Bases: ABC

Abstract base class for 3D interpolation grids.

Parameters:

Name	Type	Description	Default
x	GridAxis	X axis definition.	required
y	GridAxis	Y axis definition.	required
z	GridAxis	Z axis definition.	required

Source code in py3dinterpolations/core/grid3d.py

def __init__(self, x: GridAxis, y: GridAxis, z: GridAxis):
    self._x = x
    self._y = y
    self._z = z
    self._result: InterpolationResult | None = None

grid property

1D grid arrays per axis.

normalized_grid property

Min-max normalized 1D grid arrays per axis.

gridres property

Grid resolution; scalar if uniform, dict otherwise.

mesh property

3D meshgrid arrays.

normalized_mesh property

Normalized 3D meshgrid arrays.

get_axis(axis)

Get a grid axis by name.

Parameters:

Name	Type	Description	Default
axis	str | Axis	Axis name ("X", "Y", "Z") or Axis enum.	required

Raises:

Type	Description
ValueError	If axis name is invalid.

Source code in py3dinterpolations/core/grid3d.py

def get_axis(self, axis: str | Axis) -> GridAxis:
    """Get a grid axis by name.

    Args:
        axis: Axis name ("X", "Y", "Z") or Axis enum.

    Raises:
        ValueError: If axis name is invalid.
    """
    axis = Axis(axis)
    match axis:
        case Axis.X:
            return self._x
        case Axis.Y:
            return self._y
        case Axis.Z:
            return self._z

prediction_points() abstractmethod

Return (N, 3) array of points at which to predict.

Source code in py3dinterpolations/core/grid3d.py

@abstractmethod
def prediction_points(self) -> np.ndarray:
    """Return (N, 3) array of points at which to predict."""
    ...

RegularGrid3D(x_min, x_max, y_min, y_max, z_min, z_max, gridres)

Bases: Grid3D

Regular 3D grid with equal spacing in all axes.

Parameters:

Name	Type	Description	Default
x_min	float	Minimum X value.	required
x_max	float	Maximum X value.	required
y_min	float	Minimum Y value.	required
y_max	float	Maximum Y value.	required
z_min	float	Minimum Z value.	required
z_max	float	Maximum Z value.	required
gridres	float	Uniform grid resolution.	required

Source code in py3dinterpolations/core/grid3d.py

def __init__(
    self,
    x_min: float,
    x_max: float,
    y_min: float,
    y_max: float,
    z_min: float,
    z_max: float,
    gridres: float,
):
    super().__init__(
        x=GridAxis(Axis.X, x_min, x_max, gridres),
        y=GridAxis(Axis.Y, y_min, y_max, gridres),
        z=GridAxis(Axis.Z, z_min, z_max, gridres),
    )

prediction_points()

Return all grid points as (N, 3) array.

Source code in py3dinterpolations/core/grid3d.py

def prediction_points(self) -> np.ndarray:
    """Return all grid points as (N, 3) array."""
    m = self.mesh
    return np.column_stack([m["X"].ravel(), m["Y"].ravel(), m["Z"].ravel()])

IrregularGrid3D(x_min, x_max, x_res, y_min, y_max, y_res, z_min, z_max, z_res, hull=None)

Bases: Grid3D

3D grid with per-axis resolution and optional convex hull filtering.

Parameters:

Name	Type	Description	Default
x_min	float	Minimum X value.	required
x_max	float	Maximum X value.	required
x_res	float	X axis resolution.	required
y_min	float	Minimum Y value.	required
y_max	float	Maximum Y value.	required
y_res	float	Y axis resolution.	required
z_min	float	Minimum Z value.	required
z_max	float	Maximum Z value.	required
z_res	float	Z axis resolution.	required
hull	BaseGeometry | None	Optional convex hull geometry for XY filtering.	None

Source code in py3dinterpolations/core/grid3d.py

def __init__(
    self,
    x_min: float,
    x_max: float,
    x_res: float,
    y_min: float,
    y_max: float,
    y_res: float,
    z_min: float,
    z_max: float,
    z_res: float,
    hull: BaseGeometry | None = None,
):
    super().__init__(
        x=GridAxis(Axis.X, x_min, x_max, x_res),
        y=GridAxis(Axis.Y, y_min, y_max, y_res),
        z=GridAxis(Axis.Z, z_min, z_max, z_res),
    )
    self._hull = hull

prediction_points()

Return grid points filtered by convex hull if available.

Source code in py3dinterpolations/core/grid3d.py

def prediction_points(self) -> np.ndarray:
    """Return grid points filtered by convex hull if available."""
    m = self.mesh
    points = np.column_stack([m["X"].ravel(), m["Y"].ravel(), m["Z"].ravel()])
    if self._hull is not None:
        from shapely import Point

        mask = np.array([self._hull.contains(Point(p[0], p[1])) for p in points])
        filtered: np.ndarray = points[mask]
        return filtered
    return points

create_grid(griddata, resolution)

Factory to create the appropriate Grid3D from data and resolution.

Parameters:

Name	Type	Description	Default
griddata	GridData	Source data to derive grid extents from.	required
resolution	float | dict[str, float]	Uniform float for RegularGrid3D, or per-axis dict for IrregularGrid3D.	required

Returns:

Type	Description
Grid3D	A Grid3D subclass instance.

Raises:

Type	Description
TypeError	If resolution type is unsupported.

Source code in py3dinterpolations/core/grid3d.py

def create_grid(
    griddata: GridData,
    resolution: float | dict[str, float],
) -> Grid3D:
    """Factory to create the appropriate Grid3D from data and resolution.

    Args:
        griddata: Source data to derive grid extents from.
        resolution: Uniform float for RegularGrid3D,
            or per-axis dict for IrregularGrid3D.

    Returns:
        A Grid3D subclass instance.

    Raises:
        TypeError: If resolution type is unsupported.
    """
    specs = griddata.specs
    res = GridResolution.from_input(resolution)

    if isinstance(resolution, (int, float)):
        return RegularGrid3D(
            x_min=specs.xmin,
            x_max=specs.xmax,
            y_min=specs.ymin,
            y_max=specs.ymax,
            z_min=specs.zmin,
            z_max=specs.zmax,
            gridres=res.x,
        )
    if isinstance(resolution, dict):
        return IrregularGrid3D(
            x_min=specs.xmin,
            x_max=specs.xmax,
            x_res=res.x,
            y_min=specs.ymin,
            y_max=specs.ymax,
            y_res=res.y,
            z_min=specs.zmin,
            z_max=specs.zmax,
            z_res=res.z,
            hull=griddata.hull,
        )
    msg = f"resolution must be float or dict, got {type(resolution)}"
    raise TypeError(msg)