quickpaver.RectilinearGrid.to_pyvista#

RectilinearGrid.to_pyvista(cell_data: dict[str, ndarray[tuple[Any, ...], dtype[float64]] | ndarray[tuple[Any, ...], dtype[int64]]] | None = None, representation: Literal['image', 'rectilinear', 'structured'] = 'image', apply_rotation: bool = True) → object[source]#

Convert the grid to a PyVista dataset.

The preferred representation is "image", which returns a compact pyvista.ImageData object. Since this grid has uniform cell spacing along each local axis, ImageData is the most memory-efficient PyVista representation.

If rotations are enabled and representation="image", the grid orientation is stored using the PyVista direction_matrix argument. This preserves a compact image-data representation while representing the rotated coordinate frame.

Parameters:

  • cell_data (Optional[dict[str, Union[NDArrayFloat, NDArrayInt]]], optional) –

    Optional mapping of cell-data names to arrays. Each array must contain exactly n_grid_cells values, either as a flattened one-dimensional array or as an array with shape (nx, ny, nz). Arrays are flattened using Fortran order so that their order is consistent with the grid numbering convention:

    node_number = ix + iy * nx + iz * ny * nx

    If None, no cell data are attached. By default None.

  • representation (Literal["image", "rectilinear", "structured"], optional) –

    PyVista representation to return:

    • "image" returns a compact pyvista.ImageData.

    • "rectilinear" returns a pyvista.RectilinearGrid.

    This is only valid for non-rotated grids. - "structured" returns a pyvista.StructuredGrid. This representation explicitly stores all grid points and supports rotations through PyVista geometry transforms.

    By default "image".

  • apply_rotation (bool, optional) – Whether to apply the grid Euler rotations. If False, the returned PyVista grid is axis-aligned. By default True.

Returns:

PyVista dataset. Depending on representation, this is usually one of:

  • pyvista.ImageData

  • pyvista.RectilinearGrid

  • pyvista.StructuredGrid

Return type:

object

Raises:

  • ImportError – If PyVista is not installed.

  • ValueError – If representation is invalid.

  • ValueError – If representation="rectilinear" is requested for a rotated grid.

  • ValueError – If a cell-data array does not contain exactly n_grid_cells values.

  • RuntimeError – If rotated ImageData is requested with a PyVista version that does not support direction_matrix.

Notes

PyVista is imported locally so that it remains an optional dependency.

The PyVista grid is built from vertices, not cell centres. Therefore, the PyVista point dimensions are (nx + 1, ny + 1, nz + 1) and the number of cells is nx * ny * nz.

The rotation order is consistent with _rotate_coords():

R_x(psi) @ R_y(phi) @ R_z(theta)

For representation="structured", rotations are applied sequentially using PyVista as z, then y, then x rotations around self.rot_center.