"""Attributes common to PolyData and Grid Objects."""
from __future__ import annotations
from abc import abstractmethod
from collections import UserDict
from collections import defaultdict
import importlib.util
from pathlib import Path
from typing import TYPE_CHECKING
import numpy as np
import pyvista as pv
from pyvista import _vtk
from pyvista._deprecate_positional_args import _deprecate_positional_args
from pyvista.core._vtk_utilities import DisableVtkSnakeCase
from pyvista.core._vtk_utilities import is_vtk_attribute
from pyvista.core._vtk_utilities import vtkPyVistaOverride
from pyvista.typing.mypy_plugin import promote_type
from .datasetattributes import DataSetAttributes
from .pyvista_ndarray import pyvista_ndarray
from .utilities.arrays import FieldAssociation
from .utilities.arrays import _JSONValueType
from .utilities.arrays import _SerializedDictArray
from .utilities.fileio import PICKLE_EXT
from .utilities.fileio import _CompressionOptions
from .utilities.fileio import get_ext
from .utilities.fileio import read
from .utilities.fileio import save_pickle
from .utilities.helpers import wrap
from .utilities.misc import _DataObjectMeta
from .utilities.misc import _NoNewAttrMixin
from .utilities.misc import abstract_class
from .utilities.writer_registry import _get_ext_handler as _get_writer_ext_handler
from .utilities.writer_registry import _list_custom_exts as _list_custom_writer_exts
if TYPE_CHECKING:
from types import FunctionType
from typing import Any
from typing import ClassVar
from typing_extensions import Self
from pyvista import MultiBlock
from ._typing_core import NumpyArray
from .utilities.writer import BaseWriter
# vector array names
DEFAULT_VECTOR_KEY = '_vectors'
USER_DICT_KEY = '_PYVISTA_USER_DICT'
def _raise_unexpected_writer_kwargs(
writer_kwargs: dict[str, Any],
file_ext: str,
*,
target: str,
) -> None:
"""Raise :class:`TypeError` for extras that would be silently dropped."""
names = sorted(writer_kwargs)
msg = (
f'save() got unexpected keyword arguments {names} for '
f'{target} for extension {file_ext!r}. Extra keyword arguments '
f'are only forwarded to custom writers registered via '
f'pyvista.register_writer.'
)
raise TypeError(msg)
@promote_type(_vtk.vtkDataObject)
@abstract_class
class DataObject(
_NoNewAttrMixin,
DisableVtkSnakeCase,
vtkPyVistaOverride,
metaclass=_DataObjectMeta,
):
"""Methods common to all wrapped data objects.
Parameters
----------
*args :
Any extra args are passed as option to all wrapped data objects.
**kwargs :
Any extra keyword args are passed as option to all wrapped data objects.
"""
_WRITERS: ClassVar[dict[str, type[BaseWriter]]] = {}
def __init__(self: Self, *args, **kwargs) -> None:
"""Initialize the data object."""
try:
super().__init__(*args, **kwargs)
except TypeError:
# super() maps to object
super().__init__()
# Remember which arrays come from numpy.bool arrays, because there is no direct
# conversion from bool to vtkBitArray, such arrays are stored as vtkCharArray.
self._association_bitarray_names: defaultdict[Any, Any] = defaultdict(set)
# view these arrays as complex128 as VTK doesn't support complex types
self._association_complex_names: defaultdict[Any, Any] = defaultdict(set)
def __getattr__(self: Self, item: str) -> Any:
"""Get attribute from base class if not found.
Before falling through to the VTK base class, check whether
``item`` matches a pending ``pyvista.accessors`` entry point.
A match triggers a one-shot plugin import, after which normal
attribute resolution finds the newly-attached accessor
descriptor.
"""
# Lazy import to avoid a circular dependency at module load time.
from pyvista.core.utilities.accessor_registry import _resolve_pending_accessor
if _resolve_pending_accessor(item):
return object.__getattribute__(self, item)
return super().__getattribute__(item)
def __dir__(self: Self) -> list[str]:
"""Include pending accessor names so tab completion surfaces them.
Plugin-contributed accessors registered via the ``pyvista.accessors``
entry-point group are imported lazily on first attribute access.
Listing their names alongside the normal attribute set lets IPython
/ Jupyter / REPL tab completion surface them without paying the
plugin import cost ahead of time.
"""
# Lazy import to avoid a circular dependency at module load time.
from pyvista.core.utilities.accessor_registry import _pending_accessor_names
return sorted({*super().__dir__(), *_pending_accessor_names()})
def shallow_copy(self: Self, to_copy: Self | _vtk.vtkDataObject) -> None:
"""Shallow copy the given mesh to this mesh.
Parameters
----------
to_copy : DataObject | :vtk:`vtkDataObject`
Data object to perform a shallow copy from.
"""
self.ShallowCopy(to_copy)
def deep_copy(self: Self, to_copy: Self | _vtk.vtkDataObject) -> None:
"""Overwrite this data object with another data object as a deep copy.
Parameters
----------
to_copy : DataObject | :vtk:`vtkDataObject`
Data object to perform a deep copy from.
"""
self.DeepCopy(to_copy)
def _from_file(self: Self, filename: str | Path, **kwargs) -> None:
"""Read data objects from file."""
data = read(filename, **kwargs)
if not isinstance(self, type(data)):
msg = (
f'Reading file returned data of `{type(data).__name__}`, '
f'but `{type(self).__name__}` was expected.'
)
raise TypeError(msg)
self.shallow_copy(data)
self._post_file_load_processing()
def _post_file_load_processing(self: Self) -> None:
"""Execute after loading a dataset from file, to be optionally overridden by subclasses."""
@_deprecate_positional_args(allowed=['filename'])
def save( # noqa: PLR0917
self: Self,
filename: Path | str,
binary: bool = True, # noqa: FBT001, FBT002
texture: NumpyArray[np.uint8] | str | None = None,
compression: _CompressionOptions = 'zlib',
**writer_kwargs: Any,
) -> None:
"""Save this vtk object to file.
.. include:: /api/utilities/mesh_io.rst
.. versionadded:: 0.45
Support saving pickled meshes
See Also
--------
pyvista.read
Parameters
----------
filename : str, pathlib.Path
Filename of output file. Writer type is inferred from
the extension of the filename.
binary : bool, default: True
If ``True``, write as binary. Otherwise, write as ASCII.
texture : str, np.ndarray, optional
Write a single texture array to file when using a PLY
file. Texture array must be a 3 or 4 component array with
the datatype ``np.uint8``. Array may be a cell array or a
point array, and may also be a string if the array already
exists in the PolyData.
If a string is provided, the texture array will be saved
to disk as that name. If an array is provided, the
texture array will be saved as ``'RGBA'``
.. note::
This feature is only available when saving PLY files.
compression : str or None, default: 'zlib'
The compression type to use when ``binary`` is ``True``
and VTK writer is of type :vtk:`vtkXMLWriter`. This
argument has no effect otherwise. Acceptable values are
``'zlib'``, ``'lz4'``, ``'lzma'``, and ``None``. ``None``
indicates no compression.
.. versionadded:: 0.47
**writer_kwargs : dict, optional
Additional keyword arguments forwarded verbatim to a custom
writer registered via :func:`pyvista.register_writer`. Use
these to expose format-specific options such as compression
level or thread count. When the target extension dispatches
to a built-in VTK writer or to the pickle path, passing any
extra keyword arguments raises :class:`TypeError` — PyVista
never silently drops writer options.
.. versionadded:: 0.48
Raises
------
TypeError
If ``**writer_kwargs`` are provided but the target extension
does not dispatch to a registered custom writer.
ValueError
If ``file_ext`` is not a supported extension.
Notes
-----
Binary files write much faster than ASCII and have a smaller
file size.
"""
if self._WRITERS is None:
msg = ( # type: ignore[unreachable]
f'{self.__class__.__name__} writers are not specified,'
' this should be a dict of (file extension: vtkWriter type)'
)
raise NotImplementedError(msg)
file_path = Path(filename)
file_path = file_path.expanduser()
file_path = file_path.resolve()
file_ext = get_ext(file_path)
# Store complex and bitarray types as field data
self._store_metadata()
# Dispatch order mirrors :func:`pyvista.read`: custom writers
# registered via :func:`pyvista.register_writer` win over
# built-in writers, so ``override=True`` actually replaces a
# built-in writer at save time.
writer_exts = self._WRITERS.keys()
if (custom_writer := _get_writer_ext_handler(file_ext)) is not None:
if not file_path.parent.exists():
msg = f'Parent directory does not exist: {file_path.parent}'
raise FileNotFoundError(msg)
custom_writer(self, str(file_path), **writer_kwargs)
if not file_path.exists():
msg = f'Custom writer failed to write file: {file_path}'
raise OSError(msg)
elif file_ext in writer_exts:
if writer_kwargs:
_raise_unexpected_writer_kwargs(
writer_kwargs,
file_ext,
target='built-in VTK writer',
)
if file_ext == '.vtkhdf' and binary is False:
msg = '.vtkhdf files can only be written in binary format.'
raise ValueError(msg)
# Save using the writer
writer = self._WRITERS[file_ext](file_path, self)
data_format = 'binary' if binary else 'ascii'
writer._apply_kwargs_safely(
texture=texture, data_format=data_format, compression=compression
)
if not file_path.parent.exists():
msg = f'Parent directory does not exist: {file_path.parent}'
raise FileNotFoundError(msg)
writer.write()
if not file_path.exists():
msg = f'VTK writer failed to write file: {file_path}'
raise OSError(msg)
elif file_ext in PICKLE_EXT:
if writer_kwargs:
_raise_unexpected_writer_kwargs(
writer_kwargs,
file_ext,
target='pickle format',
)
save_pickle(filename, self)
else:
msg = (
f'Invalid file extension {file_ext!r} for data type {type(self)}.\n'
f'Must be one of: '
f'{list(writer_exts) + list(PICKLE_EXT) + _list_custom_writer_exts()}'
)
if file_ext == '.pv' and not importlib.util.find_spec(
'pyvista-zstd'
): # pragma: no cover
msg += (
".\nThe '.pv' extension is supported by the `pyvista-zstd` package. "
'It can be installed with `pyvista[io]`.'
)
raise ValueError(msg)
def _store_metadata(self: Self) -> None:
"""Store metadata as field data."""
fdata = self.field_data
for assoc_name in ('bitarray', 'complex'):
for assoc_type in ('POINT', 'CELL'):
assoc_data = getattr(self, f'_association_{assoc_name}_names')
array_names = assoc_data.get(assoc_type)
if array_names:
key = f'_PYVISTA_{assoc_name}_{assoc_type}_'.upper()
fdata[key] = list(array_names)
def _restore_metadata(self: Self) -> None:
"""Restore PyVista metadata from field data.
Metadata is stored using ``_store_metadata`` and contains entries in
the format of f'_PYVISTA_{assoc_name}_{assoc_type}_'. These entries are
removed when calling this method.
"""
fdata = self.field_data
for assoc_name in ('bitarray', 'complex'):
for assoc_type in ('POINT', 'CELL'):
key = f'_PYVISTA_{assoc_name}_{assoc_type}_'.upper()
if key in fdata:
assoc_data = getattr(self, f'_association_{assoc_name}_names')
assoc_data[assoc_type] = set(fdata[key])
del fdata[key]
@abstractmethod
def get_data_range(
self: Self, name: str | None, preference: FieldAssociation | str
) -> tuple[float, float]: # pragma: no cover
"""Get the non-NaN min and max of a named array."""
msg = f'{type(self)} mesh type does not have a `get_data_range` method.'
raise NotImplementedError(msg)
def _get_attrs(self: Self) -> list[tuple[str, Any, str]]: # pragma: no cover
"""Return the representation methods (internal helper)."""
msg = 'Called only by the inherited class'
raise NotImplementedError(msg)
@_deprecate_positional_args
def head(self: Self, display: bool = True, html: bool | None = None) -> str: # noqa: FBT001, FBT002
"""Return the header stats of this dataset.
If in IPython, this will be formatted to HTML. Otherwise
returns a console friendly string.
Parameters
----------
display : bool, default: True
Display this header in iPython.
html : bool, optional
Generate the output as HTML.
Returns
-------
str
Header statistics.
"""
# Generate the output
if html:
fmt = ''
# HTML version
fmt += '\n'
fmt += "\n"
fmt += f'| {type(self).__name__} | Information |
|---|
\n'
row = '| {} | {} |
\n'
# now make a call on the object to get its attributes as a list of len 2 tuples
for attr in self._get_attrs():
try:
fmt += row.format(attr[0], attr[2].format(*attr[1]))
except TypeError:
fmt += row.format(attr[0], attr[2].format(attr[1]))
if hasattr(self, 'n_arrays'):
fmt += row.format('N Arrays', self.n_arrays)
fmt += '
\n'
fmt += '\n'
if display:
from IPython.display import HTML
from IPython.display import display as _display
_display(HTML(fmt))
return ''
return fmt
# Otherwise return a string that is Python console friendly
fmt = f'{type(self).__name__} ({hex(id(self))})\n'
# now make a call on the object to get its attributes as a list of len 2 tuples
# get longest row header
max_len = max(len(attr[0]) for attr in self._get_attrs()) + 4
# now make a call on the object to get its attributes as a list of len
# 2 tuples
row = f' {{:{max_len}s}}' + '{}\n'
for attr in self._get_attrs():
try:
fmt += row.format(attr[0] + ':', attr[2].format(*attr[1]))
except TypeError:
fmt += row.format(attr[0] + ':', attr[2].format(attr[1]))
if hasattr(self, 'n_arrays'):
fmt += row.format('N Arrays:', self.n_arrays)
return fmt.strip()
def _repr_html_(self: Self) -> str: # pragma: no cover
"""Return a pretty representation for Jupyter notebooks.
This includes header details and information about all arrays.
"""
msg = 'Called only by the inherited class'
raise NotImplementedError(msg)
def copy_meta_from(self: Self, *args, **kwargs) -> None: # pragma: no cover
"""Copy pyvista meta data onto this object from another object.
Intended to be overridden by subclasses.
Parameters
----------
*args : tuple
Positional arguments.
**kwargs : dict, optional
Keyword arguments.
"""
# called only by the inherited class
@_deprecate_positional_args
def copy(self: Self, deep: bool = True) -> Self: # noqa: FBT001, FBT002
"""Return a copy of the object.
Parameters
----------
deep : bool, default: True
When ``True`` makes a full copy of the object. When
``False``, performs a shallow copy where the points, cell,
and data arrays are references to the original object.
Returns
-------
pyvista.DataSet
Deep or shallow copy of the input. Type is identical to
the input.
Examples
--------
Create and make a deep copy of a PolyData object.
>>> import pyvista as pv
>>> mesh_a = pv.Sphere()
>>> mesh_b = mesh_a.copy()
>>> mesh_a == mesh_b
True
"""
thistype = type(self)
newobject = thistype()
if deep:
newobject.deep_copy(self)
else:
newobject.shallow_copy(self)
newobject.copy_meta_from(self, deep=deep)
return newobject
def __eq__(self: Self, other: object) -> bool:
"""Test equivalency between data objects."""
if not isinstance(self, type(other)):
return False
if self is other:
return True
# these attrs use numpy.array_equal
if isinstance(self, pv.ImageData):
equal_attrs = ['extent', 'index_to_physical_matrix']
else:
equal_attrs = ['points', 'cells']
if isinstance(self, pv.PolyData):
equal_attrs.extend(['verts', 'lines', 'faces', 'strips'])
elif isinstance(self, pv.UnstructuredGrid):
equal_attrs.append('celltypes')
equal_attrs.append('polyhedron_faces')
equal_attrs.append('polyhedron_face_locations')
for attr in equal_attrs:
# Only check equality for attributes defined by PyVista
# (i.e. ignore any default vtk snake_case attributes)
if hasattr(self, attr) and not is_vtk_attribute(self, attr):
if not np.array_equal(getattr(self, attr), getattr(other, attr), equal_nan=True):
return False
# these attrs can be directly compared
attrs = ['field_data', 'point_data', 'cell_data']
for attr in attrs:
if hasattr(self, attr):
if getattr(self, attr) != getattr(other, attr):
return False
return True
__hash__ = None # type: ignore[assignment] # https://github.com/pyvista/pyvista/pull/7671
@_deprecate_positional_args(allowed=['array', 'name'])
def add_field_data(self: Self, array: NumpyArray[float], name: str, deep: bool = True) -> None: # noqa: FBT001, FBT002
"""Add field data.
Use field data when size of the data you wish to associate
with the dataset does not match the number of points or cells
of the dataset.
Parameters
----------
array : sequence
Array of data to add to the dataset as a field array.
name : str
Name to assign the field array.
deep : bool, default: True
Perform a deep copy of the data when adding it to the
dataset.
Examples
--------
Add field data to a PolyData dataset.
>>> import pyvista as pv
>>> import numpy as np
>>> mesh = pv.Sphere()
>>> mesh.add_field_data(np.arange(10), 'my-field-data')
>>> mesh['my-field-data']
pyvista_ndarray([0, 1, 2, 3, 4, 5, 6, 7, 8, 9])
Add field data to a ImageData dataset.
>>> mesh = pv.ImageData(dimensions=(2, 2, 1))
>>> mesh.add_field_data(['I could', 'write', 'notes', 'here'], 'my-field-data')
>>> mesh['my-field-data']
pyvista_ndarray(['I could', 'write', 'notes', 'here'], dtype='>> blocks = pv.MultiBlock()
>>> blocks.append(pv.Sphere())
>>> blocks['cube'] = pv.Cube(center=(0, 0, -1))
>>> blocks.add_field_data([1, 2, 3], 'my-field-data')
>>> blocks.field_data['my-field-data']
pyvista_ndarray([1, 2, 3])
"""
if not hasattr(self, 'field_data'):
msg = f'`{type(self)}` does not support field data'
raise NotImplementedError(msg)
self.field_data.set_array(array, name, deep_copy=deep)
@property
def field_data(self: Self) -> DataSetAttributes:
"""Return FieldData as DataSetAttributes.
Use field data when size of the data you wish to associate
with the dataset does not match the number of points or cells
of the dataset.
Returns
-------
DataSetAttributes
FieldData as DataSetAttributes.
Examples
--------
Add field data to a PolyData dataset and then return it.
>>> import pyvista as pv
>>> import numpy as np
>>> mesh = pv.Sphere()
>>> mesh.field_data['my-field-data'] = np.arange(10)
>>> mesh.field_data['my-field-data']
pyvista_ndarray([0, 1, 2, 3, 4, 5, 6, 7, 8, 9])
"""
return DataSetAttributes(
self.GetFieldData(),
dataset=self, # type: ignore[arg-type]
association=FieldAssociation.NONE,
)
def clear_field_data(self: Self) -> None:
"""Remove all field data.
Examples
--------
Add field data to a PolyData dataset and then remove it.
>>> import pyvista as pv
>>> mesh = pv.Sphere()
>>> mesh.field_data['my-field-data'] = range(10)
>>> len(mesh.field_data)
1
>>> mesh.clear_field_data()
>>> len(mesh.field_data)
0
"""
if not hasattr(self, 'field_data'):
msg = f'`{type(self)}` does not support field data'
raise NotImplementedError(msg)
self.field_data.clear()
@property
def user_dict(self: Self) -> _SerializedDictArray:
"""Set or return a user-specified data dictionary.
The dictionary is stored as a JSON-serialized string as part of the mesh's
field data. Unlike regular field data, which requires values to be stored
as an array, the user dict provides a mapping for scalar values.
Since the user dict is stored as field data, it is automatically saved
with the mesh when it is saved in a compatible file format (e.g. ``'.vtk'``).
Any saved metadata is automatically de-serialized by PyVista whenever
the user dict is accessed again. Since the data is stored as JSON, it
may also be easily retrieved or read by other programs.
Any JSON-serializable values are permitted by the user dict, i.e. values
can have type ``dict``, ``list``, ``tuple``, ``str``, ``int``, ``float``,
``bool``, or ``None``. Storing NumPy arrays is not directly supported, but
these may be cast beforehand to a supported type, e.g. by calling ``tolist()``
on the array.
To completely remove the user dict string from the dataset's field data,
set its value to ``None``.
.. note::
The user dict is a convenience property intended for metadata storage.
Values are JSON-serialized on every mutation, so it is not a substitute
for a regular field data array when storing bulk array data with many
entries (use a regular field data array for that instead).
.. warning::
Field data is typically passed-through by dataset filters, and therefore
the user dict's items can generally be expected to persist and remain
unchanged in the output of filtering methods. However, this behavior is
not guaranteed, as it's possible that some filters may modify or clear
field data. Use with caution.
.. versionadded:: 0.44
Returns
-------
UserDict
JSON-serialized dict-like object which is subclassed from
:py:class:`collections.UserDict`.
Examples
--------
Load a mesh.
>>> import pyvista as pv
>>> from pyvista import examples
>>> mesh = examples.load_ant()
Add data to the user dict. The contents are serialized as JSON.
>>> mesh.user_dict['name'] = 'ant'
>>> mesh.user_dict
{"name": "ant"}
Alternatively, set the user dict from an existing dict.
>>> mesh.user_dict = dict(name='ant')
The user dict can be updated like a regular dict.
>>> mesh.user_dict.update(
... {
... 'num_legs': 6,
... 'body_parts': ['head', 'thorax', 'abdomen'],
... }
... )
>>> mesh.user_dict
{"name": "ant", "num_legs": 6, "body_parts": ["head", "thorax", "abdomen"]}
Data in the user dict is stored as field data.
>>> mesh.field_data
pyvista DataSetAttributes
Association : NONE
Contains arrays :
_PYVISTA_USER_DICT str "{"name": "ant",..."
Since it's field data, the user dict can be saved to file along with the
mesh and retrieved later.
>>> mesh.save('ant.vtk')
>>> mesh_from_file = pv.read('ant.vtk')
>>> mesh_from_file.user_dict
{"name": "ant", "num_legs": 6, "body_parts": ["head", "thorax", "abdomen"]}
"""
self._config_user_dict()
return self._user_dict
@user_dict.setter
def user_dict(
self: Self,
dict_: dict[str, _JSONValueType] | UserDict[str, _JSONValueType] | None,
) -> None:
# Setting None removes the field data array
if dict_ is None:
if hasattr(self, '_user_dict'):
del self._user_dict
if USER_DICT_KEY in self.field_data.keys():
del self.field_data[USER_DICT_KEY]
return
self._config_user_dict()
if isinstance(dict_, dict):
self._user_dict.data = dict_
elif isinstance(dict_, UserDict):
self._user_dict.data = dict_.data
else:
msg = ( # type: ignore[unreachable]
f'User dict can only be set with type {dict} or {UserDict}.\n'
f'Got {type(dict_)} instead.'
)
raise TypeError(msg)
def _config_user_dict(self: Self) -> None:
"""Init serialized dict array and ensure it is added to field_data."""
field_data = self.field_data
if not hasattr(self, '_user_dict'):
# Init
object.__setattr__(self, '_user_dict', _SerializedDictArray())
if USER_DICT_KEY in field_data.keys():
if isinstance(array := field_data[USER_DICT_KEY], pyvista_ndarray):
# When loaded from file, field will be cast as pyvista ndarray
# Convert to string and initialize new user dict object from it
self._user_dict = _SerializedDictArray(''.join(array))
elif isinstance(array, str) and str(self._user_dict) != array: # type: ignore[unreachable]
# Filters may update the field data block separately, e.g.
# when copying field data, so we need to capture the new
# string and re-init
self._user_dict = _SerializedDictArray(array)
else:
# User dict is correctly configured, do nothing
return
# Set field data array directly instead of calling 'set_array'
# This skips the call to '_prepare_array' which will otherwise
# do all kinds of casting/conversions and mangle this array
self._user_dict.SetName(USER_DICT_KEY)
field_data.VTKObject.AddArray(self._user_dict)
field_data.VTKObject.Modified()
@property
def memory_address(self: Self) -> str:
"""Get address of the underlying VTK C++ object.
Returns
-------
str
Memory address formatted as ``'Addr=%p'``.
Examples
--------
>>> import pyvista as pv
>>> mesh = pv.Sphere()
>>> mesh.memory_address
'Addr=...'
"""
return self.GetInformation().GetAddressAsString('')
@property
def actual_memory_size(self: Self) -> int:
"""Return the actual size of the dataset object.
Returns
-------
int
The actual size of the dataset object in kibibytes (1024
bytes).
Examples
--------
>>> from pyvista import examples
>>> mesh = examples.load_airplane()
>>> mesh.actual_memory_size # doctest:+SKIP
93
"""
return self.GetActualMemorySize()
def copy_structure(self: Self, dataset: Self) -> None:
"""Copy the structure (geometry and topology) of the input dataset object.
Parameters
----------
dataset : :vtk:`vtkDataSet`
Dataset to copy the geometry and topology from.
Examples
--------
>>> import pyvista as pv
>>> source = pv.ImageData(dimensions=(10, 10, 5))
>>> target = pv.ImageData()
>>> target.copy_structure(source)
>>> target.plot(show_edges=True)
"""
self.CopyStructure(dataset) if dataset is not self else None
def copy_attributes(self: Self, dataset: Self) -> None:
"""Copy the data attributes of the input dataset object.
Parameters
----------
dataset : pyvista.DataSet
Dataset to copy the data attributes from.
Examples
--------
>>> import pyvista as pv
>>> source = pv.ImageData(dimensions=(10, 10, 5))
>>> source = source.compute_cell_sizes()
>>> target = pv.ImageData(dimensions=(10, 10, 5))
>>> target.copy_attributes(source)
>>> target.plot(scalars='Volume', show_edges=True)
"""
self.CopyAttributes(dataset)
def __getstate__( # type: ignore[return] # noqa: RET503
self: Self,
) -> tuple[FunctionType, tuple[dict[str, Any]]] | dict[str, Any]:
"""Support pickle."""
pickle_format = pv.PICKLE_FORMAT
if pickle_format == 'vtk':
return self._serialize_vtk_pickle_format()
elif pickle_format in ['xml', 'legacy']:
return self._serialize_pyvista_pickle_format()
# Invalid format, use the setter to raise an error
pv.set_pickle_format(pickle_format)
def _serialize_vtk_pickle_format(
self: Self,
) -> tuple[FunctionType, tuple[dict[str, Any]]]:
# Note: The serialized state has format: ( function, (dict,) )
serialized = _vtk.serialize_VTK_data_object(self)
# Add this object's data to the state dictionary
state_dict = serialized[1][0]
state_dict['_PYVISTA_STATE_DICT'] = self.__dict__.copy()
# Unlike the PyVista formats, we do not return a dict. Instead, return
# the same format returned by the vtk serializer.
return serialized
def _serialize_pyvista_pickle_format(self: Self) -> dict[str, Any]:
"""Support pickle by serializing the VTK object data.
The format of the serialized VTK object data depends on `pyvista.PICKLE_FORMAT`
(case-insensitive).
- If ``'xml'``, the data is serialized as an XML-formatted string.
- If ``'legacy'``, the data is serialized to bytes in VTK's binary format.
.. note::
These formats are custom PyVista legacy formats. The native 'vtk' format is
preferred since it supports more objects (e.g. MultiBlock).
"""
if isinstance(self, pv.MultiBlock):
msg = (
"MultiBlock is not supported with 'xml' or 'legacy' pickle formats."
"\nUse `pyvista.PICKLE_FORMAT='vtk'`."
)
raise TypeError(msg)
state = self.__dict__.copy()
if pv.PICKLE_FORMAT.lower() == 'xml':
# the generic VTK XML writer `vtkXMLDataSetWriter` currently has a bug where it does
# not pass all settings down to the sub-writers. Until this is fixed, use the
# dataset-specific writers
# https://gitlab.kitware.com/vtk/vtk/-/issues/18661
writers = {
_vtk.vtkImageData: _vtk.vtkXMLImageDataWriter,
_vtk.vtkStructuredGrid: _vtk.vtkXMLStructuredGridWriter,
_vtk.vtkRectilinearGrid: _vtk.vtkXMLRectilinearGridWriter,
_vtk.vtkUnstructuredGrid: _vtk.vtkXMLUnstructuredGridWriter,
_vtk.vtkPolyData: _vtk.vtkXMLPolyDataWriter,
_vtk.vtkTable: _vtk.vtkXMLTableWriter,
}
for parent_type, writer_type in writers.items():
if isinstance(self, parent_type):
writer = writer_type() # type: ignore[unreachable]
break
else:
msg = f'Cannot pickle dataset of type {self.GetDataObjectType()}'
raise TypeError(msg)
writer.SetInputDataObject(self) # type: ignore[unreachable]
writer.SetWriteToOutputString(True)
writer.SetDataModeToBinary()
writer.SetCompressorTypeToNone()
writer.Write()
to_serialize = writer.GetOutputString()
elif pv.PICKLE_FORMAT.lower() == 'legacy':
writer = _vtk.vtkDataSetWriter()
writer.SetInputDataObject(self)
writer.SetWriteToOutputString(True)
writer.SetFileTypeToBinary()
writer.Write()
to_serialize = writer.GetOutputStdString()
state['vtk_serialized'] = to_serialize
# this needs to be here because in multiprocessing situations, `pyvista.PICKLE_FORMAT`
# is not shared between processes
state['PICKLE_FORMAT'] = pv.PICKLE_FORMAT
return state
def __setstate__(self: Self, state: Any) -> None:
"""Support unpickle."""
def _is_vtk_format(state_: Any) -> bool:
# Note: The vtk state has format ( function, (dict,) )
return (
isinstance(state_, tuple)
and len(state_) == 2
and isinstance(state_[1], tuple)
and len(state_[1]) == 1
and isinstance(state_[1][0], dict)
)
def _is_pyvista_format(state_: Any) -> bool:
return isinstance(state_, dict) and 'vtk_serialized' in state_
if _is_vtk_format(state):
self._unserialize_vtk_pickle_format(state)
elif _is_pyvista_format(state):
self._unserialize_pyvista_pickle_format(state)
else:
msg = f"Cannot unpickle '{self.__class__.__name__}'. Invalid pickle format."
raise RuntimeError(msg)
def _unserialize_vtk_pickle_format(
self: Self, state: tuple[FunctionType, tuple[dict[str, Any]]]
) -> None:
"""Support unpickle of VTK's format."""
# The vtk state has format: ( function, (dict,) )
unserialize_func = state[0]
state_dict = state[1][0]
self.__dict__.update(state_dict['_PYVISTA_STATE_DICT'])
obj = unserialize_func(state_dict)
self.deep_copy(obj)
def _unserialize_pyvista_pickle_format(self: Self, state: dict[str, Any]) -> None:
"""Support unpickle of PyVista 'xml' and 'legacy' formats.
.. note::
These formats are custom PyVista legacy formats. The native 'vtk' format is
preferred since it supports more objects (e.g. MultiBlock).
"""
vtk_serialized = state.pop('vtk_serialized')
pickle_format = state.pop(
'PICKLE_FORMAT',
'legacy', # backwards compatibility - assume 'legacy'
)
self.__dict__.update(state)
if pickle_format.lower() == 'xml':
# the generic VTK XML reader `vtkXMLGenericDataObjectReader` currently has a
# bug where it does not pass all settings down to the sub-readers.
# Until this is fixed, use the dataset-specific readers
# https://gitlab.kitware.com/vtk/vtk/-/issues/18661
readers = {
_vtk.vtkImageData: _vtk.vtkXMLImageDataReader,
_vtk.vtkStructuredGrid: _vtk.vtkXMLStructuredGridReader,
_vtk.vtkRectilinearGrid: _vtk.vtkXMLRectilinearGridReader,
_vtk.vtkUnstructuredGrid: _vtk.vtkXMLUnstructuredGridReader,
_vtk.vtkPolyData: _vtk.vtkXMLPolyDataReader,
_vtk.vtkTable: _vtk.vtkXMLTableReader,
}
for parent_type, reader_type in readers.items():
if isinstance(self, parent_type):
reader = reader_type() # type: ignore[unreachable]
break
else:
msg = f'Cannot unpickle dataset of type {self.GetDataObjectType()}'
raise TypeError(msg)
reader.ReadFromInputStringOn() # type: ignore[unreachable]
reader.SetInputString(vtk_serialized)
reader.Update()
elif pickle_format.lower() == 'legacy':
reader = _vtk.vtkDataSetReader()
reader.ReadFromInputStringOn()
if isinstance(vtk_serialized, bytes):
reader.SetBinaryInputString(vtk_serialized, len(vtk_serialized)) # type: ignore[arg-type]
elif isinstance(vtk_serialized, str):
reader.SetInputString(vtk_serialized)
reader.Update()
mesh = wrap(reader.GetOutput())
# copy data
self.copy_structure(mesh) # type: ignore[arg-type]
self.copy_attributes(mesh) # type: ignore[arg-type]
@property
@abstractmethod
def is_empty(self) -> bool:
"""Return ``True`` if the object is empty."""
def cast_to_multiblock(self) -> MultiBlock:
"""Convert this :class:`DataObject` to a :class:`~pyvista.MultiBlock`.
Uses :vtk:`vtkConvertToMultiBlockDataSet` internally.
.. versionadded:: 0.47
Returns
-------
MultiBlock
Converted dataset.
"""
alg = _vtk.vtkConvertToMultiBlockDataSet()
alg.SetInputDataObject(self)
alg.Update()
return wrap(alg.GetOutput()) # type:ignore[return-value]