"""Contains a dictionary that maps file extensions to VTK readers.""" from __future__ import annotations from abc import ABC from abc import abstractmethod from collections.abc import Sequence import importlib import itertools import json from pathlib import Path import pickle from typing import TYPE_CHECKING from typing import Any from typing import Literal from typing import TextIO from typing import TypeVar from typing import cast from typing import overload from urllib.parse import urlparse import numpy as np import pyvista as pv from pyvista import _vtk from pyvista._deprecate_positional_args import _deprecate_positional_args from pyvista._warn_external import warn_external from pyvista.core import _validation from pyvista.core.errors import PyVistaDeprecationWarning from pyvista.core.utilities.misc import _classproperty from pyvista.core.utilities.misc import _NoNewAttrMixin from .observers import Observer if TYPE_CHECKING: from collections.abc import Iterable import imageio import meshio import trimesh from pyvista import BaseReader from pyvista import DataObject from pyvista import DataSet from pyvista import ExplicitStructuredGrid from pyvista import MultiBlock from pyvista import NumpyArray from pyvista import PolyData from pyvista import Texture from pyvista import UnstructuredGrid from pyvista import VectorLike _CompressionOptions = Literal['zlib', 'lz4', 'lzma', None] # noqa: PYI061 PathStrSeq = str | Path | Sequence['PathStrSeq'] PICKLE_EXT = ('.pkl', '.pickle') _PointCellField = Literal['point', 'cell', 'field'] _PassDataOptions = bool | _PointCellField | Sequence[_PointCellField] _ReadReturnT = TypeVar('_ReadReturnT', bound='DataObject') def _lazy_vtk_import(module_name: str, class_name: str) -> type: """Lazy import of a class from vtkmodules.""" module = importlib.import_module(f'vtkmodules.{module_name}') return getattr(module, class_name) class _FileIOBase(ABC, _NoNewAttrMixin): _vtk_module_name: str = '' _vtk_class_name: str = '' def __repr__(self) -> str: """Representation of a FileIO object.""" return f'{self.__class__.__name__}({self.path!r})' @property @abstractmethod def path(self) -> str: """Get the path.""" @path.setter @abstractmethod def path(self, path: str | Path) -> None: """Set the path.""" @_classproperty def _vtk_class(cls) -> _vtk.vtkWriter | None: # noqa: N805 if cls._vtk_module_name and cls._vtk_class_name: return _lazy_vtk_import(cls._vtk_module_name, cls._vtk_class_name) # type: ignore[return-value] return None @classmethod @abstractmethod def _get_extension_mappings(cls) -> list[dict[str, type]]: ... @_classproperty def extensions(cls) -> tuple[str, ...]: # noqa: N805 """Return the file extension(s) associated with this class. These extensions are used by :func:`~pyvista.read` and :class:`~pyvista.DataObject.save` to determine which reader and/or writer is used for reading and/or saving files. """ extensions = set() for mapping in cls._get_extension_mappings(): for ext, typ in mapping.items(): if typ is cls: # type: ignore[comparison-overlap] extensions.add(ext) # type: ignore[unreachable] return tuple(sorted(extensions)) def _warn_multiblock_nested_field_data(mesh: pv.DataObject) -> None: if not isinstance(mesh, pv.MultiBlock): return iterator = mesh.recursive_iterator('all', node_type='parent') for index, name, nested_multiblock in iterator: if len(nested_multiblock.field_data.keys()) > 0: # Avoid circular import from pyvista.core.filters.composite import _format_nested_index # noqa: PLC0415 index_fmt = _format_nested_index(index) msg = ( f"Nested MultiBlock at index {index_fmt} with name '{name}' " f'has field data which will not be saved.\n' 'See https://gitlab.kitware.com/vtk/vtk/-/issues/19414 \n' 'Use `move_nested_field_data_to_root` to store the field data ' 'with the root MultiBlock before saving.' ) warn_external(msg) def set_pickle_format(format: Literal['vtk', 'xml', 'legacy']) -> None: # noqa: A002 """Set the format used to serialize :class:`pyvista.DataObject` when pickled. Parameters ---------- format : str The format for serialization. Acceptable values are: - ``'vtk'`` (default) : objects are serialized using VTK's official marshalling methods. - ``'xml'``: objects are serialized as an XML-formatted string. - ``'legacy'`` objects are serialized to bytes in VTK's binary format. .. note:: The ``'vtk'`` format requires VTK 9.3 or greater. .. warning:: ``'xml'`` and ``'legacy'`` are not recommended. These formats are not officially supported by VTK and have limitations. For example, these formats cannot be used to pickle :class:`pyvista.MultiBlock`. Raises ------ ValueError If the provided format is not supported. """ supported = {'vtk', 'xml', 'legacy'} format_ = cast('Literal["vtk", "xml", "legacy"]', format.lower()) if format_ not in supported: msg = ( f'Unsupported pickle format `{format_}`. Valid options are `{"`, `".join(supported)}`.' ) raise ValueError(msg) if format_ == 'vtk' and pv.vtk_version_info < (9, 3): msg = "'vtk' pickle format requires VTK >= 9.3" raise ValueError(msg) pv.PICKLE_FORMAT = format_ def _get_ext_force(filename: str | Path, force_ext: str | None = None) -> str: if force_ext: return str(force_ext).lower() else: return get_ext(filename) def get_ext(filename: str | Path) -> str: """Extract the extension of the filename. For files with the .gz suffix, the previous extension is returned as well. This is needed e.g. for the compressed NIFTI format (.nii.gz). Parameters ---------- filename : str, Path The filename from which to extract the extension. Returns ------- str The extracted extension. For files with the .gz suffix, the previous extension is returned as well. """ path = Path(filename) base = str(path.parent / path.stem) ext = path.suffix ext = ext.lower() if ext == '.gz': path = Path(base) ext_pre = path.suffix.lower() ext = f'{ext_pre}{ext}' return ext @overload def read( filename: PathStrSeq, force_ext: str | None = ..., file_format: str | None = ..., progress_bar: bool = ..., # noqa: FBT001 *, cls: type[_ReadReturnT], validate: bool | None = ..., ) -> _ReadReturnT: ... @overload def read( filename: PathStrSeq, force_ext: str | None = ..., file_format: str | None = ..., progress_bar: bool = ..., # noqa: FBT001 *, cls: None = ..., validate: bool | None = ..., ) -> DataSet | MultiBlock: ... @_deprecate_positional_args(allowed=['filename']) def read( # noqa: PLR0917 filename: PathStrSeq, force_ext: str | None = None, file_format: str | None = None, progress_bar: bool = False, # noqa: FBT001, FBT002 *, cls: type[DataObject] | None = None, validate: bool | None = None, ) -> DataObject: """Read any file type supported by ``vtk`` or ``meshio``. Automatically determines the correct reader to use then wraps the corresponding mesh as a pyvista object. Attempts native ``vtk`` readers first then tries to use ``meshio``. :py:mod:`Pickled` meshes (``'.pkl'`` or ``'.pickle'``) are also supported. Remote URIs (``https://``, ``s3://``, etc.) are downloaded to a temporary file automatically. Install ``fsspec`` for full protocol support (``pip install pyvista[io]``); ``pooch`` is used as a fallback for HTTP(S). Third-party reader plugins registered via :func:`pyvista.register_reader` are also checked. See :func:`pyvista.get_reader` for list of vtk formats supported. .. include:: /api/utilities/mesh_io.rst .. note:: See https://github.com/nschloe/meshio for formats supported by ``meshio``. Be sure to install ``meshio`` with ``pip install meshio`` if you wish to use it. .. versionadded:: 0.45 Support reading pickled meshes. .. warning:: The pickle module is not secure. Only read pickled mesh files (``'.pkl'`` or ``'.pickle'``) you trust. See :py:mod:`pickle` for details. See Also -------- pyvista.DataObject.save Save a mesh to file. Parameters ---------- filename : str, Path, Sequence[str | Path] The string path to the file to read. If a list of files is given, a :class:`pyvista.MultiBlock` dataset is returned with each file being a separate block in the dataset. force_ext : str, optional If specified, the reader will be chosen by an extension which is different to its actual extension. For example, ``'.vts'``, ``'.vtu'``. file_format : str, optional Format of file to read with meshio. progress_bar : bool, default: False Optionally show a progress bar. Ignored when using ``meshio``. cls : type, optional Expected concrete type of the returned mesh. When given, the result is checked with :func:`isinstance` and a :class:`TypeError` is raised on mismatch. Static type checkers (``mypy``, ``pyright``) use this to narrow the return type to ``cls`` directly, so callers do not need ``typing.cast`` or a manual ``assert isinstance`` to access subclass-specific attributes, e.g. ``pv.read('file.vtu', cls=pv.UnstructuredGrid)``. validate : bool, optional Forwarded to :func:`pyvista.wrap` as the ``validate`` keyword when using a ``vtk`` reader. When ``None`` (the default), honors :attr:`pyvista.core.config.Config.validate_on_wrap`. Pass ``False`` to skip the cheap array-length sanity check on very large trusted files. Has no effect for ``meshio`` or pickle code paths. .. versionadded:: 0.48 Returns ------- pyvista.DataSet | pyvista.MultiBlock Wrapped PyVista dataset. When ``cls`` is given, an instance of ``cls`` is returned instead. Examples -------- Load an example mesh. >>> import pyvista as pv >>> from pyvista import examples >>> mesh = pv.read(examples.antfile) >>> mesh.plot(cpos='xz') Narrow the return type to a specific class. This avoids the need for a manual ``cast`` when working with type checkers such as ``mypy`` or ``pyright``. >>> mesh = pv.read('mesh.vtu', cls=pv.UnstructuredGrid) # doctest:+SKIP Load a vtk file. >>> mesh = pv.read('my_mesh.vtk') # doctest:+SKIP Load a meshio file. >>> mesh = pv.read('mesh.obj') # doctest:+SKIP Load a pickled mesh file. >>> mesh = pv.read('mesh.pkl') # doctest:+SKIP """ result = _read_dispatch( filename, force_ext=force_ext, file_format=file_format, progress_bar=progress_bar, validate=validate, ) if cls is not None and not isinstance(result, cls): msg = ( f'Expected an instance of {cls.__name__} when reading {filename!r}, ' f'but got {type(result).__name__}.' ) raise TypeError(msg) return result def _read_dispatch( # noqa: PLR0911 filename: PathStrSeq, *, force_ext: str | None, file_format: str | None, progress_bar: bool, validate: bool | None, ) -> DataObject: """Dispatch a filename to the right reader and return the wrapped mesh.""" if file_format is not None and force_ext is not None: msg = 'Only one of `file_format` and `force_ext` may be specified.' raise ValueError(msg) if isinstance(filename, Sequence) and not isinstance(filename, str): multi = pv.MultiBlock() for each in filename: name = Path(each).name if isinstance(each, (str, Path)) else None multi.append( _read_dispatch( # type: ignore[arg-type] each, force_ext=None, file_format=file_format, progress_bar=progress_bar, validate=validate, ), name, ) return multi # Circular import: reader_registry -> reader -> fileio from pyvista.core.utilities.reader_registry import LocalFileRequiredError # noqa: PLC0415 from pyvista.core.utilities.reader_registry import _download_uri # noqa: PLC0415 from pyvista.core.utilities.reader_registry import _get_ext_handler # noqa: PLC0415 from pyvista.core.utilities.reader_registry import has_scheme # noqa: PLC0415 # Handle remote URIs before Path coercion if isinstance(filename, str) and has_scheme(filename): uri_ext = get_ext(urlparse(filename).path) if uri_ext.lower() in PICKLE_EXT: msg = ( f'Refusing to load pickle from remote URI {filename!r}. ' f'Loading a pickle from an untrusted source allows arbitrary ' f'code execution. Download the file manually after verifying ' f'its origin, then pass the local path to `pyvista.read_pickle`.' ) raise ValueError(msg) # If a custom reader is registered for this extension, try it # with the raw URI first, the reader may handle cloud paths # natively (e.g. zarr stores on S3). If it fails, fall back to # downloading the file and retrying with a local path. ext_handler = _get_ext_handler(uri_ext) if ext_handler is not None: try: return ext_handler(filename) except LocalFileRequiredError: filename = _download_uri(filename, uri_ext) return ext_handler(filename) filename = _download_uri(filename, uri_ext) filename = Path(filename).expanduser().resolve() if not filename.is_file() and not filename.is_dir(): msg = f'File ({filename}) not found' raise FileNotFoundError(msg) # Read file using meshio.read if file_format is present if file_format: return read_meshio(filename, file_format) ext = _get_ext_force(filename, force_ext) if ext in ['.e', '.exo']: return read_exodus(filename) if ext.lower() == '.grdecl': return read_grdecl(filename) if ext in ['.wrl', '.vrml']: msg = ( 'VRML files must be imported directly into a Plotter. ' 'See `pyvista.Plotter.import_vrml` for details.' ) raise ValueError(msg) if ext in PICKLE_EXT: return read_pickle(filename) # Check for registered custom extension readers ext_handler = _get_ext_handler(ext) if ext_handler is not None: return ext_handler(str(filename)) try: reader = pv.get_reader(filename, force_ext) except ValueError: msg = f'This file was not able to be automatically read by pyvista.\n {str(filename)!r}' # if using force_ext, we are explicitly only using vtk readers if force_ext is not None: raise OSError(msg) try: from meshio._exceptions import ReadError # noqa: PLC0415 except ImportError: raise OSError(msg) try: return read_meshio(filename) except ReadError: if ext == '.pv': # pragma: no cover msg += ( "\nThe '.pv' extension is supported by the `pyvista-zstd` package. " 'It can be installed with `pyvista[io]`.' ) raise OSError(msg) else: observer = Observer() observer.observe(reader.reader) if progress_bar: reader.show_progress() mesh = reader.read(validate=validate) if observer.has_event_occurred(): warn_external( f'The VTK reader `{reader.reader.GetClassName()}` in pyvista reader `{reader}` ' 'raised an error while reading the file.\n' f'\t"{observer.get_message()}"', ) return mesh def _apply_attrs_to_reader( reader: BaseReader[Any], attrs: dict[str, object | Sequence[object]] ) -> None: """For a given pyvista reader, call methods according to attrs. Parameters ---------- reader : pyvista.BaseReader Reader to call methods on. attrs : dict Mapping of methods to call on reader. """ warn_external( 'attrs use is deprecated. Use a Reader class for more flexible control', PyVistaDeprecationWarning, ) for name, args in attrs.items(): attr = getattr(reader.reader, name) if args is not None: if not isinstance(args, (list, tuple)): args = [args] # noqa: PLW2901 attr(*args) else: attr() @_deprecate_positional_args(allowed=['filename']) def read_texture(filename: str | Path, progress_bar: bool = False) -> Texture: # noqa: FBT001, FBT002 """Load a texture from an image file. Will attempt to read any file type supported by ``vtk``, however if it fails, it will attempt to use ``imageio`` to read the file. Parameters ---------- filename : str The path of the texture file to read. progress_bar : bool, default: False Optionally show a progress bar. Returns ------- pyvista.Texture PyVista texture object. Examples -------- Read in an example jpg map file as a texture. >>> from pathlib import Path >>> import pyvista as pv >>> from pyvista import examples >>> Path(examples.mapfile).name '2k_earth_daymap.jpg' >>> texture = pv.read_texture(examples.mapfile) >>> type(texture) """ filename = Path(filename).expanduser().resolve() try: # initialize the reader using the extension to find it image = read(filename, progress_bar=progress_bar) if image.n_points < 2: msg = 'Problem reading the image with VTK.' raise ValueError(msg) return pv.Texture(image) # type: ignore[abstract] except (KeyError, ValueError): # Otherwise, use the imageio reader pass return pv.Texture(_try_imageio_imread(filename)) # type: ignore[abstract] # pragma: no cover @_deprecate_positional_args(allowed=['filename']) def read_exodus( # noqa: PLR0917 filename: str | Path, animate_mode_shapes: bool = True, # noqa: FBT001, FBT002 apply_displacements: bool = True, # noqa: FBT001, FBT002 displacement_magnitude: float = 1.0, read_point_data: bool = True, # noqa: FBT001, FBT002 read_cell_data: bool = True, # noqa: FBT001, FBT002 enabled_sidesets: Iterable[str | int] | None = None, ) -> DataSet | MultiBlock: """Read an ExodusII file (``'.e'`` or ``'.exo'``). Parameters ---------- filename : str, Path The path to the exodus file to read. animate_mode_shapes : bool, default: True When ``True`` then this reader will report a continuous time range [0,1] and animate the displacements in a periodic sinusoid. apply_displacements : bool, default: True Geometric locations can include displacements. When ``True``, the nodal positions are 'displaced' by the standard exodus displacement vector. If displacements are turned off, the user can explicitly add them by applying a warp filter. displacement_magnitude : float, default: 1.0 This is a number between 0 and 1 that is used to scale the ``DisplacementMagnitude`` in a sinusoidal pattern. read_point_data : bool, default: True Read in data associated with points. read_cell_data : bool, default: True Read in data associated with cells. enabled_sidesets : Iterable[str | int], optional The name of the array that store the mapping from side set cells back to the global id of the elements they bound. Returns ------- pyvista.DataSet Wrapped PyVista dataset. Examples -------- >>> import pyvista as pv >>> data = pv.read_exodus('mymesh.exo') # doctest:+SKIP """ from .helpers import wrap # noqa: PLC0415 reader = _vtk.vtkExodusIIReader() reader.SetFileName(str(filename)) reader.UpdateInformation() reader.SetAnimateModeShapes(animate_mode_shapes) reader.SetApplyDisplacements(apply_displacements) reader.SetDisplacementMagnitude(displacement_magnitude) if read_point_data: # read in all point data variables reader.SetAllArrayStatus(_vtk.vtkExodusIIReader.NODAL, 1) if read_cell_data: # read in all cell data variables reader.SetAllArrayStatus(_vtk.vtkExodusIIReader.ELEM_BLOCK, 1) if enabled_sidesets is None: enabled_sidesets = list(range(reader.GetNumberOfSideSetArrays())) for sideset in enabled_sidesets: if isinstance(sideset, int): name = reader.GetSideSetArrayName(sideset) elif isinstance(sideset, str): name = sideset else: msg = f'Could not parse sideset ID/name: {sideset} with type {type(sideset)}' # type: ignore[unreachable] raise TypeError(msg) reader.SetSideSetArrayStatus(name, 1) reader.Update() return cast('pv.DataSet', wrap(reader.GetOutput())) @_deprecate_positional_args(allowed=['filename']) def read_grdecl( filename: str | Path, elevation: bool = True, # noqa: FBT001, FBT002 other_keywords: Sequence[str] | None = None, ) -> ExplicitStructuredGrid: """Read a GRDECL file (``'.GRDECL'``). Parameters ---------- filename : str | Path The path to the GRDECL file to read. elevation : bool, default: True If True, convert depths to elevations and flip grid along Z axis. other_keywords : sequence[str], optional Additional keywords to read that are ignored by default. Returns ------- pyvista.ExplicitStructuredGrid Output explicit structured grid. Examples -------- Read a ``'.GRDECL'`` file. >>> import pyvista as pv >>> grid = pv.read('file.GRDECL') # doctest:+SKIP Unused keywords contained in the file are stored in :attr:`pyvista.DataObject.user_dict`: >>> grid.user_dict # doctest:+SKIP {"MAPUNITS": ..., "GRIDUNIT": ..., ...} """ property_keywords = ( 'ACTNUM', 'COORD', 'ZCORN', 'PERMEABILITY', 'PERMX', 'PERMY', 'PERMZ', 'POROSITY', 'PORO', 'LAYERS', 'ZONES', ) @overload def read_keyword( f: TextIO, split: Literal[True] = True, # noqa: FBT002 converter: type = ..., ) -> list[str]: ... @overload def read_keyword(f: TextIO, split: Literal[False] = False, converter: type = ...) -> str: ... # noqa: FBT002 @overload def read_keyword(f: TextIO, split: bool = ..., converter: type = ...) -> list[str]: ... # noqa: FBT001 @_deprecate_positional_args(allowed=['f']) def read_keyword( f: TextIO, split: bool = True, # noqa: FBT001, FBT002 converter: type | None = None, ) -> str | list[str]: """Read a keyword. Parameters ---------- f : TextIO File buffer. split : bool, default: True If True, split strings. converter : callable, optional Function to apply to split strings. Returns ------- output : list | str A list or a string. """ out: list[str] = [] while True: line = f.readline().strip() if line.endswith('/'): line = line[:-1].strip() if line: end = True else: break elif line.startswith('--') or not line: continue else: end = False if split: line_ = line.split() out += [converter(x) for x in line_] if converter is not None else line_ else: out.append(line) if end: break if not split: return ' '.join(out) return out def read_buffer( f: TextIO, other_keywords: Sequence[str] ) -> tuple[dict[str, Any], Sequence[str]]: """Read a file buffer. Parameters ---------- f : TextIO File buffer. other_keywords : sequence[str], optional Additional keywords to read that are ignored by default. Returns ------- dict Dictionary of read keywords. sequence[str] Included file names. """ keys: Sequence[str] = list(property_keywords) + list(other_keywords) keys = tuple(keys) keywords: dict[str, str | list[Any]] = {} includes = [] for line in f: line_ = line.strip() if line_.startswith('MAPUNITS'): keywords['MAPUNITS'] = read_keyword(f, split=False).replace("'", '').strip() elif line_.startswith('MAPAXES'): keywords['MAPAXES'] = read_keyword(f, converter=float) elif line_.startswith('GRIDUNIT'): keywords['GRIDUNIT'] = read_keyword(f, split=False).replace("'", '').strip() elif line_.startswith('SPECGRID'): data = read_keyword(f) keywords['SPECGRID'] = [ int(data[0]), int(data[1]), int(data[2]), int(data[3]), data[4].strip(), ] elif line_.startswith('INCLUDE'): filename = read_keyword(f, split=False) includes.append(filename.replace("'", '')) elif line_.startswith(keys): key = line.split()[0] data = read_keyword(f) if key in property_keywords: keywords[key] = [] for x in data: if '*' in x: size, new_x = x.split('*') keywords[key] += int(size) * [float(new_x)] # type: ignore[operator] else: keywords[key].append(float(x)) # type: ignore[union-attr] else: keywords[key] = data return keywords, includes def read_keywords(filename: str | Path, other_keywords: Sequence[str]) -> dict[str, Any]: """Read a GRDECL file and return its keywords. Parameters ---------- filename : str | Path The path to the GRDECL file to read. other_keywords : sequence[str], optional Additional keywords to read that are ignored by default. Returns ------- dict Dictionary of read keywords. """ with Path.open(Path(filename)) as f: keywords, includes = read_buffer(f, other_keywords) if includes: path = Path(filename).parent for include in includes: with Path.open(path / include) as f: keywords_, _ = read_buffer(f, other_keywords) keywords.update(keywords_) return keywords # Read keywords other_keywords = other_keywords or [] keywords = read_keywords(filename, other_keywords) try: ni, nj, nk = keywords['SPECGRID'][:3] cylindric = keywords['SPECGRID'][4] == 'T' if cylindric: msg = 'Cylindric grids are not supported.' raise TypeError(msg) except KeyError: msg = "Unable to generate grid without keyword 'SPECGRID'." raise ValueError(msg) relative = False if 'GRIDUNIT' in keywords: grid_unit = keywords['GRIDUNIT'].lower() if not grid_unit.endswith('map'): try: cond1 = grid_unit.startswith(keywords['MAPUNITS'].lower()) if not cond1: warn_external( 'Unable to convert relative coordinates with different ' 'grid and map units. Skipping conversion.', ) except KeyError: warn_external( "Unable to convert relative coordinates without keyword 'MAPUNITS'. " 'Skipping conversion.', ) cond1 = False try: origin = keywords['MAPAXES'][2:4] except KeyError: warn_external( "Unable to convert relative coordinates without keyword 'MAPAXES'. " 'Skipping conversion.', ) origin = None relative = cond1 and origin is not None # Pillars and Z corner points pillars = np.reshape(keywords['COORD'], ((ni + 1) * (nj + 1), 6), order='C') zcorners = np.reshape(keywords['ZCORN'], (2 * ni, 2 * nj, 2 * nk), order='F') # Convert depth to elevation if elevation: zcorners = -zcorners[..., ::-1] pillars[:, [2, 5]] *= -1.0 pillars[:] = pillars[:, [3, 4, 5, 0, 1, 2]] # Shift relative to absolute units if relative: pillars[:, [0, 3]] += origin[0] pillars[:, [1, 4]] += origin[1] # Interpolate X and Y corner points xcorners = np.empty_like(zcorners) ycorners = np.empty_like(zcorners) for i, j in itertools.product(range(2 * ni), range(2 * nj)): ip = np.ravel_multi_index(((i + 1) // 2, (j + 1) // 2), (ni + 1, nj + 1), order='F') z = pillars[ip, [2, 5]] xcorners[i, j] = np.interp(zcorners[i, j], z, pillars[ip, [0, 3]]) ycorners[i, j] = np.interp(zcorners[i, j], z, pillars[ip, [1, 4]]) # Generate explicit structured grid dims = ni + 1, nj + 1, nk + 1 corners = np.column_stack( ( xcorners.ravel(order='F'), ycorners.ravel(order='F'), zcorners.ravel(order='F'), ) ) grid = pv.ExplicitStructuredGrid(dims, corners) # Add property data for key in property_keywords: if key in {'ACTNUM', 'COORD', 'ZCORN'}: continue if key in keywords: v = keywords[key] if elevation: v = np.reshape(v, (ni, nj, nk), order='F') v = v[..., ::-1].ravel(order='F') grid[key] = v # Active cells if 'ACTNUM' in keywords: active = np.array(keywords['ACTNUM']) > 0.0 grid.hide_cells(~active, inplace=True) # type: ignore[arg-type] # Store unused keywords in user dict grid.user_dict = {k: v for k, v in keywords.items() if k not in property_keywords} return grid def read_pickle(filename: str | Path) -> DataObject: """Load a pickled mesh from file. Parameters ---------- filename : str The path of the pickled mesh to read. Returns ------- pyvista.DataObject Unpickled mesh. Examples -------- Save a pickled mesh and read it. >>> import pyvista as pv >>> from pyvista import examples >>> mesh = examples.load_ant() >>> pv.save_pickle('ant.pkl', mesh) >>> new_mesh = pv.read_pickle('ant.pkl') >>> new_mesh PolyData (...) N Cells: 912 N Points: 486 N Strips: 0 X Bounds: -1.601e+01, 1.601e+01 Y Bounds: -9.385e+00, 9.385e+00 Z Bounds: -1.678e+01, 1.678e+01 N Arrays: 0 Unlike other file formats, custom attributes are saved with pickled meshes. >>> pv.set_new_attribute(mesh, 'custom_attribute', 42) >>> pv.save_pickle('ant.pkl', mesh) >>> new_mesh = pv.read_pickle('ant.pkl') >>> new_mesh.custom_attribute 42 """ filename_str = str(filename) if filename_str.endswith(PICKLE_EXT): with open(filename_str, 'rb') as f: # noqa: PTH123 mesh = pickle.load(f) if not isinstance(mesh, pv.DataObject): msg = ( f'Pickled object must be an instance of {pv.DataObject}. ' f'Got {mesh.__class__} instead.' ) raise TypeError(msg) return mesh msg = f'Filename must be a file path with extension {PICKLE_EXT}. Got {filename} instead.' raise ValueError(msg) def save_pickle(filename: str | Path, mesh: DataObject) -> None: """Pickle a mesh and save it to file. Parameters ---------- filename : str The path of the pickled mesh to save, including the extension ``'.pkl'`` or ``'.pickle'``. mesh : pyvista.DataObject Any PyVista mesh. Examples -------- Save a pickled mesh and read it. >>> import pyvista as pv >>> from pyvista import examples >>> mesh = examples.load_ant() >>> pv.save_pickle('ant.pkl', mesh) >>> new_mesh = pv.read_pickle('ant.pkl') >>> new_mesh PolyData (...) N Cells: 912 N Points: 486 N Strips: 0 X Bounds: -1.601e+01, 1.601e+01 Y Bounds: -9.385e+00, 9.385e+00 Z Bounds: -1.678e+01, 1.678e+01 N Arrays: 0 Unlike other file formats, custom attributes are saved with pickled meshes. >>> pv.set_new_attribute(mesh, 'custom_attribute', 42) >>> pv.save_pickle('ant.pkl', mesh) >>> new_mesh = pv.read_pickle('ant.pkl') >>> new_mesh.custom_attribute 42 """ filename_str = str(filename) if not filename_str.endswith(PICKLE_EXT): filename_str += '.pkl' if not isinstance(mesh, pv.DataObject): msg = ( # type: ignore[unreachable] f'Only {pv.DataObject} are supported for pickling. Got {mesh.__class__} instead.' ) raise TypeError(msg) _warn_multiblock_nested_field_data(mesh) with open(filename_str, 'wb') as f: # noqa: PTH123 pickle.dump(mesh, f) def is_meshio_mesh(obj: object) -> bool: """Test if passed object is an instance of :class:`meshio.Mesh`. Parameters ---------- obj : object Any object. Returns ------- bool ``True`` if ``obj`` is a :class:`meshio.Mesh`. """ try: import meshio # noqa: PLC0415 return isinstance(obj, meshio.Mesh) except ImportError: return False def is_trimesh_mesh(obj: object) -> bool: """Test if passed object is an instance of :class:`trimesh.Trimesh`. .. versionadded:: 0.47 Parameters ---------- obj : object Any object. Returns ------- bool ``True`` if ``obj`` is a :class:`trimesh.Trimesh`. """ try: import trimesh # noqa: PLC0415 return isinstance(obj, trimesh.Trimesh) except ImportError: return False def from_meshio(mesh: meshio.Mesh) -> UnstructuredGrid: """Convert a ``meshio`` mesh instance to a PyVista mesh. Parameters ---------- mesh : meshio.Mesh A mesh instance from the ``meshio`` library. Returns ------- pyvista.UnstructuredGrid A PyVista unstructured grid representation of the input ``meshio`` mesh. Raises ------ ImportError If the appropriate version of ``meshio`` library is not found. """ try: # meshio<5.0 compatibility from meshio.vtk._vtk import meshio_to_vtk_type # noqa: PLC0415 from meshio.vtk._vtk import vtk_type_to_numnodes # noqa: PLC0415 except ImportError: # pragma: no cover from meshio._vtk_common import meshio_to_vtk_type # noqa: PLC0415 from meshio.vtk._vtk_42 import vtk_type_to_numnodes # noqa: PLC0415 if len(mesh.cells) == 0: # Empty mesh grid = pv.UnstructuredGrid() if mesh.points.size > 0: grid.points = mesh.points return grid # Extract cells from meshio.Mesh object cells = [] cell_type = [] for c in mesh.cells: if c.type.startswith('polyhedron'): vtk_type = meshio_to_vtk_type['polyhedron'] for cell in c.data: connectivity = [len(cell)] for face in cell: connectivity += [len(face), *face] connectivity.insert(0, len(connectivity)) cells.append(connectivity) else: vtk_type = meshio_to_vtk_type[c.type] numnodes = vtk_type_to_numnodes[vtk_type] if numnodes == -1: # Count nodes in each cell fill_values = np.array([[len(data)] for data in c.data], dtype=c.data.dtype) # type: ignore[union-attr] else: fill_values = np.full((len(c.data), 1), numnodes, dtype=c.data.dtype) # type: ignore[union-attr] cells.append(np.hstack((fill_values, c.data)).ravel()) # type: ignore[arg-type] cell_type += [vtk_type] * len(c.data) # Convert cell sets to cell data if mesh.cell_sets: mesh.cell_sets_to_data() # Extract cell data from meshio.Mesh object cell_data = {k: np.concatenate(v) for k, v in mesh.cell_data.items()} # Create pyvista.UnstructuredGrid object points = mesh.points # Convert to 3D if points are 2D if points.shape[1] == 2: zero_points = np.zeros((len(points), 1), dtype=points.dtype) points = np.hstack((points, zero_points)) grid = pv.UnstructuredGrid( np.concatenate(cells).astype(np.int64, copy=False), np.array(cell_type), np.array(points, np.float64), ) # Set point data grid.point_data.update({k: np.array(v, np.float64) for k, v in mesh.point_data.items()}) # Set cell data grid.cell_data.update(cell_data) # Call datatype-specific post-load processing grid._post_file_load_processing() return grid def to_meshio(mesh: DataSet) -> meshio.Mesh: """Convert a PyVista mesh to a ``meshio`` mesh instance. .. versionadded:: 0.45 Parameters ---------- mesh : pyvista.DataSet Any PyVista mesh/spatial data type. Returns ------- meshio.Mesh A mesh instance from the ``meshio`` library. Raises ------ ImportError If the meshio package is not installed. See Also -------- from_meshio, read_meshio, save_meshio, :func:`~pyvista.wrap` Examples -------- Convert a pyvista sphere to a ``meshio`` mesh instance. >>> import pyvista as pv >>> sphere = pv.Sphere() >>> mesh = pv.to_meshio(sphere) """ try: import meshio # noqa: PLC0415 except ImportError: # pragma: no cover msg = 'To use this feature install meshio with:\n\npip install meshio' raise ImportError(msg) try: # for meshio<5.0 compatibility from meshio.vtk._vtk import vtk_to_meshio_type # noqa: PLC0415 except (ImportError, AttributeError): # pragma: no cover from meshio._vtk_common import vtk_to_meshio_type # noqa: PLC0415 # Cast to unstructured grid mesh = mesh if isinstance(mesh, pv.UnstructuredGrid) else mesh.cast_to_unstructured_grid() mesh = ( mesh.extract_cells(mesh.cell_data['vtkGhostType'] == 0) if 'vtkGhostType' in mesh.cell_data else mesh ) if mesh.is_empty: return meshio.Mesh(mesh.points, []) vtk_celltypes = mesh.celltypes connectivity = mesh.cell_connectivity # Generate polyhedral cell faces if any def split(arr: VectorLike[int]) -> list[VectorLike[int]]: i = 0 offsets: list[int] = [0] while i < len(arr): offsets.append(int(arr[i]) + 1) i += offsets[-1] offsets_ = np.cumsum(offsets) return [arr[i1 + 1 : i2] for i1, i2 in itertools.pairwise(offsets_)] polyhedron_faces = split(mesh.polyhedron_faces) if polyhedron_faces: polyhedron_locations = split(mesh.polyhedron_face_locations) polyhedral_cell_faces: list[list[VectorLike[int]]] = [ [polyhedron_faces[face] for face in cell] for cell in polyhedron_locations ] # Single cell type (except POLYGON and POLYHEDRON) if vtk_celltypes.min() == vtk_celltypes.max() and vtk_celltypes[0] not in { pv.CellType.POLYGON, pv.CellType.POLYHEDRON, }: vtk_celltype = vtk_celltypes[0] cells = connectivity.reshape((mesh.n_cells, connectivity.size // mesh.n_cells)) if vtk_celltype == pv.CellType.PIXEL: cells = cells[:, [0, 1, 3, 2]] celltype = 'quad' elif vtk_celltype == pv.CellType.VOXEL: cells = cells[:, [0, 1, 3, 2, 4, 5, 7, 6]] celltype = 'hexahedron' else: celltype = vtk_to_meshio_type[vtk_celltype] cells = [(celltype, cells)] # Mixed cell types else: cells = [] offset = mesh.offset for i, (i1, i2, vtk_celltype) in enumerate( zip(offset[:-1], offset[1:], vtk_celltypes, strict=False) ): cell = connectivity[i1:i2] if vtk_celltype == pv.CellType.POLYHEDRON: celltype = f'polyhedron{len(cell)}' cell = polyhedral_cell_faces[i] # Handle the missing voxel key (11) in vtk_to_meshio_type elif vtk_celltype == pv.CellType.VOXEL: celltype = 'hexahedron' cell = cell[[0, 1, 3, 2, 4, 5, 7, 6]] # Handle the missing "pixel" key in meshio._mesh.topological_dimension elif vtk_celltype == pv.CellType.PIXEL: celltype = 'quad' cell = cell[[0, 1, 3, 2]] else: celltype = ( f'polygon{len(cell)}' if vtk_celltype == pv.CellType.POLYGON else vtk_to_meshio_type[vtk_celltype] ) if len(cells) > 0 and cells[-1][0] == celltype: cells[-1][1].append(cell) else: cells.append((celltype, [cell])) cells = [ (celltype if not celltype.startswith('polygon') else 'polygon', celldata) for celltype, celldata in cells ] # Point data point_data = {k.replace(' ', '_'): v for k, v in mesh.point_data.items()} # Cell data vtk_cell_data = mesh.cell_data indices = np.insert(np.cumsum([len(c[1]) for c in cells]), 0, 0) cell_data = { k.replace(' ', '_'): [v[i1:i2] for i1, i2 in itertools.pairwise(indices)] for k, v in vtk_cell_data.items() } return meshio.Mesh(mesh.points, cells, point_data=point_data, cell_data=cell_data) def read_meshio(filename: str | Path, file_format: str | None = None) -> UnstructuredGrid: """Read any mesh file using meshio. Parameters ---------- filename : str The name of the file to read. It should include the file extension. file_format : str, optional The format of the file to read. If not provided, the file format will be inferred from the file extension. Returns ------- UnstructuredGrid The mesh read from the file. Raises ------ ImportError If the meshio package is not installed. """ try: import meshio # noqa: PLC0415 except ImportError: # pragma: no cover msg = 'To use this feature install meshio with:\n\npip install meshio' raise ImportError(msg) # Make sure relative paths will work filename = Path(filename).expanduser().resolve() # Read mesh file mesh = meshio.read(filename, file_format) return from_meshio(mesh) def save_meshio( filename: str | Path, mesh: DataSet, file_format: str | None = None, **kwargs ) -> None: """Save mesh to file using meshio. Parameters ---------- filename : str Filename to save the mesh to. mesh : pyvista.DataSet Any PyVista mesh/spatial data type. file_format : str, optional File type for meshio to save. For example ``'.bdf'``. This is normally inferred from the extension but this can be overridden. **kwargs : dict, optional Additional keyword arguments. See ``meshio.Mesh.write`` for more details. Examples -------- Save a pyvista sphere to a Abaqus data file. >>> import pyvista as pv >>> sphere = pv.Sphere() >>> pv.save_meshio('mymesh.inp', sphere) # doctest:+SKIP """ # Make sure relative paths will work filename = Path(filename).expanduser().resolve() # Save using meshio to_meshio(mesh).write(filename, file_format=file_format, **kwargs) def _process_filename(filename: str | Path) -> Path: return Path(filename).expanduser().resolve() def _try_imageio_imread(filename: str | Path) -> imageio.core.util.Array: """Attempt to read a file using ``imageio.imread``. Parameters ---------- filename : str, Path Name of the file to read using ``imageio``. Returns ------- imageio.core.util.Array Image read from ``imageio``. Raises ------ ModuleNotFoundError Raised when ``imageio`` is not installed when attempting to read ``filename``. """ try: from imageio.v2 import imread # noqa: PLC0415 except ModuleNotFoundError: # pragma: no cover msg = ( 'Problem reading the image with VTK. Install imageio to try to read the ' 'file using imageio with:\n\n' ' pip install imageio' ) raise ModuleNotFoundError(msg) from None return imread(filename) def _validate_pass_data(pass_data: _PassDataOptions) -> tuple[bool, bool, bool]: pass_point_data = pass_cell_data = pass_field_data = False if pass_data is True: pass_point_data = pass_cell_data = pass_field_data = True elif pass_data: if isinstance(pass_data, str): if pass_data == 'point': pass_point_data = True elif pass_data == 'cell': pass_cell_data = True elif pass_data == 'field': pass_field_data = True elif isinstance(pass_data, Sequence): if 'point' in pass_data: pass_point_data = True if 'cell' in pass_data: pass_cell_data = True if 'field' in pass_data: pass_field_data = True if not (pass_point_data or pass_cell_data or pass_field_data) and pass_data is not False: # Input is not valid allowed = [True, False, 'point', 'cell', 'field'] _validation.check_contains(allowed, must_contain=pass_data, name='pass_data') return pass_point_data, pass_cell_data, pass_field_data def from_trimesh( mesh: trimesh.Trimesh, *, pass_data: _PassDataOptions = True ) -> PolyData: # numpydoc ignore=RT01 """Convert a Trimesh mesh to a PyVista mesh. - ``vertex_attributes`` are stored as point data. - ``face_attributes`` are stored as cell data. - ``metadata`` is stored as field data: NumPy arrays are stored directly as field data arrays, and any other metadata (e.g. strings or lists) is stored in the :attr:`~pyvista.DataObject.user_dict`. .. note:: No copies of point, cell, or data arrays are made. Use :meth:`~pyvista.DataObject.copy` after converting to avoid any side effects. .. versionadded:: 0.47 Parameters ---------- mesh : trimesh.Trimesh Trimesh object to convert. pass_data : bool | str | sequence[str], default: True Pass point, cell, and/or field data from the Trimesh object. All data is passed by default. Set this to ``'point'``, ``'cell'``, ``'field'`` or any combination thereof to only pass specific fields. See Also -------- to_trimesh, from_meshio, :func:`~pyvista.wrap` Examples -------- See :ref:`wrap_trimesh_example` for examples. """ try: import trimesh # noqa: PLC0415 except ImportError: # pragma: no cover msg = 'To use this feature install trimesh with:\n\npip install trimesh' raise ImportError(msg) else: _validation.check_instance(mesh, trimesh.Trimesh, name='mesh') # Handle case with no faces faces: NumpyArray[int] = mesh.faces if faces.size == 0: faces = faces.reshape((0, 3)) # Trimesh doesn't pad faces polydata = pv.PolyData.from_regular_faces(mesh.vertices, faces=faces, deep=False) pass_point_data, pass_cell_data, pass_field_data = _validate_pass_data(pass_data) if pass_point_data: # Set texture coordinates if ( hasattr(visual := mesh.visual, 'uv') and visual is not None and (uv := visual.uv) is not None ): polydata.active_texture_coordinates = uv polydata.point_data.update(mesh.vertex_attributes, copy=False) if pass_cell_data: polydata.cell_data.update(mesh.face_attributes, copy=False) if pass_field_data: for key, val in mesh.metadata.items(): if isinstance(val, np.ndarray): polydata.field_data[key] = val else: try: json.dumps(val) except TypeError: msg = ( f'Unable to store metadata key {key!r} with value type {type(val)}.\n' f'Only NumPy arrays or JSON-serializable values are supported.' ) warn_external(msg) else: polydata.user_dict[key] = val return polydata def to_trimesh( # numpydoc ignore=RT01 mesh: DataSet, *, triangulate: bool = False, pass_data: _PassDataOptions = True, ) -> trimesh.Trimesh: """Convert a PyVista mesh to a Trimesh mesh. - Point data is stored as ``vertex_attributes``. - Cell data is stored as ``face_attributes``. - Field data is stored as ``metadata``. Any :attr:`~pyvista.DataObject.user_dict` keys are stored directly as metadata. .. note:: No copies of point, cell, or data arrays are made. Use :meth:`~pyvista.DataObject.copy` before converting to avoid any side effects. .. versionadded:: 0.47 Parameters ---------- mesh : DataSet Dataset to convert. triangulate : bool, default: False Triangulate the mesh before conversion. If the mesh has 3D cells, the mesh's surface is extracted. All 2D polygonal cells are triangulated as required, and all 0D and 1D cells or any unused points are ignored. pass_data : bool | str | sequence[str], default: True Pass point, cell, and/or field data to the Trimesh object. All data is passed by default. Set this to ``'point'``, ``'cell'``, ``'field'`` or any combination thereof to only pass specific fields. See Also -------- from_trimesh, to_meshio, :func:`~pyvista.wrap` Examples -------- See :ref:`wrap_trimesh_example` for examples. """ try: import trimesh # noqa: PLC0415 from trimesh.visual import TextureVisuals # noqa: PLC0415 except ImportError: # pragma: no cover msg = 'To use this feature install trimesh with:\n\npip install trimesh' raise ImportError(msg) # Avoid circular import from pyvista.core.dataobject import USER_DICT_KEY # noqa: PLC0415 _validation.check_instance(mesh, pv.DataSet, name='mesh') if isinstance(mesh, pv.PolyData): is_all_triangles = mesh.is_all_triangles elif isinstance(mesh, pv.UnstructuredGrid): is_all_triangles = mesh.distinct_cell_types == {pv.CellType.TRIANGLE} elif mesh.is_empty: is_all_triangles = True else: is_all_triangles = False if not is_all_triangles and not triangulate: msg = ( 'Mesh must be all triangles to convert to Trimesh object.\n' 'Use `triangulate=True` to automatically convert to a triangle surface mesh.' ) raise pv.NotAllTrianglesError(msg) surf = ( mesh if isinstance(mesh, pv.PolyData) else mesh.extract_surface(algorithm=None, pass_pointid=False, pass_cellid=False) ) surf = surf if is_all_triangles else surf.triangulate() pass_point_data, pass_cell_data, pass_field_data = _validate_pass_data(pass_data) if pass_point_data: vertex_attributes = dict((point_data := mesh.point_data).items()) vertex_normals = vertex_attributes.pop(point_data.active_normals_name, None) # type: ignore[arg-type] # Store texture coordinates texture_coordinates = vertex_attributes.pop( point_data.active_texture_coordinates_name, # type: ignore[arg-type] None, ) visual = ( TextureVisuals(uv=texture_coordinates) if texture_coordinates is not None else None ) else: vertex_attributes = None vertex_normals = None visual = None if pass_cell_data: face_attributes = dict((cell_data := mesh.cell_data).items()) face_normals = face_attributes.pop(cell_data.active_normals_name, None) # type: ignore[arg-type] else: face_attributes = None face_normals = None if pass_field_data: metadata = dict(mesh.field_data.items()) if USER_DICT_KEY in metadata.keys(): metadata.pop(USER_DICT_KEY) metadata.update(mesh.user_dict) else: metadata = None return trimesh.Trimesh( vertices=surf.points, faces=surf.regular_faces, vertex_normals=vertex_normals, face_normals=face_normals, face_attributes=face_attributes, # type: ignore[arg-type] vertex_attributes=vertex_attributes, # type: ignore[arg-type] metadata=metadata, visual=visual, process=False, )