"""Container to mimic :vtk:`vtkMultiBlockDataSet` objects. These classes hold many VTK datasets in one object that can be passed to VTK algorithms and PyVista filtering/plotting routines. """ from __future__ import annotations from collections.abc import Iterator from collections.abc import MutableSequence from collections.abc import Sequence import itertools import pathlib from typing import TYPE_CHECKING from typing import Any from typing import Literal from typing import NoReturn from typing import Union from typing import cast from typing import overload import numpy as np from typing_extensions import TypedDict from typing_extensions import Unpack import pyvista from pyvista._deprecate_positional_args import _deprecate_positional_args from pyvista.core import _validation from . import _vtk_core as _vtk from ._typing_core import BoundsTuple from .dataobject import USER_DICT_KEY from .dataobject import DataObject from .dataset import DataSet from .filters.composite import CompositeFilters from .filters.composite import _format_nested_index from .pyvista_ndarray import pyvista_ndarray from .utilities.arrays import CellLiteral from .utilities.arrays import FieldAssociation from .utilities.arrays import FieldLiteral from .utilities.arrays import PointLiteral from .utilities.arrays import parse_field_choice from .utilities.geometric_objects import Box from .utilities.helpers import is_pyvista_dataset from .utilities.helpers import wrap from .utilities.misc import _BoundsSizeMixin if TYPE_CHECKING: from collections.abc import Iterable from pyvista import PolyData from ._typing_core import NumpyArray _TypeMultiBlockLeaf = Union['MultiBlock', DataSet, None] class MultiBlock( _BoundsSizeMixin, CompositeFilters, DataObject, MutableSequence, # type: ignore[type-arg] _vtk.vtkMultiBlockDataSet, ): """A composite class to hold many data sets which can be iterated over. This wraps/extends the :vtk:`vtkMultiBlockDataSet` class so that we can easily plot these data sets and use the composite in a Pythonic manner. You can think of ``MultiBlock`` like a list as we can iterate over this data structure by index. It has some dictionary features as we can also access blocks by their string name. .. versionchanged:: 0.36.0 ``MultiBlock`` adheres more closely to being list like, and inherits from :class:`collections.abc.MutableSequence`. Multiple nonconforming behaviors were removed or modified. Parameters ---------- *args : dict, optional Data object dictionary. **kwargs : dict, optional See :func:`pyvista.read` for additional options. Examples -------- >>> import pyvista as pv Create an empty composite dataset. >>> blocks = pv.MultiBlock() Add a dataset to the collection. >>> sphere = pv.Sphere() >>> blocks.append(sphere) Add a named block. >>> blocks['cube'] = pv.Cube() Instantiate from a list of objects. >>> data = [ ... pv.Sphere(center=(2, 0, 0)), ... pv.Cube(center=(0, 2, 0)), ... pv.Cone(), ... ] >>> blocks = pv.MultiBlock(data) >>> blocks.plot() Instantiate from a dictionary. >>> data = { ... 'cube': pv.Cube(), ... 'sphere': pv.Sphere(center=(2, 2, 0)), ... } >>> blocks = pv.MultiBlock(data) >>> blocks.plot() Iterate over the collection. >>> for name in blocks.keys(): ... block = blocks[name] >>> for block in blocks: ... # Do something with each dataset ... surf = block.extract_surface() """ plot = pyvista._plot.plot _WRITERS = dict.fromkeys(['.vtm', '.vtmb'], _vtk.vtkXMLMultiBlockDataWriter) if _vtk.vtk_version_info >= (9, 4): _WRITERS['.vtkhdf'] = _vtk.vtkHDFWriter def __init__(self: MultiBlock, *args, **kwargs) -> None: """Initialize multi block.""" super().__init__() deep = kwargs.pop('deep', False) # keep a python reference to the dataset to avoid # unintentional garbage collections since python does not # add a reference to the dataset when it's added here in # MultiBlock. See https://github.com/pyvista/pyvista/pull/1805 self._refs: Any = {} if len(args) == 1: if isinstance(args[0], _vtk.vtkMultiBlockDataSet): if deep: self.deep_copy(args[0]) else: self.shallow_copy(args[0]) elif isinstance(args[0], (list, tuple)): for block in args[0]: self.append(block) elif isinstance(args[0], (str, pathlib.Path)): self._from_file(args[0], **kwargs) elif isinstance(args[0], dict): for key, block in args[0].items(): self.append(block, key) else: msg = f'Type {type(args[0])} is not supported by pyvista.MultiBlock' raise TypeError(msg) elif len(args) > 1: msg = 'Invalid number of arguments:\n``pyvista.MultiBlock``supports 0 or 1 arguments.' raise ValueError(msg) # Upon creation make sure all nested structures are wrapped self.wrap_nested() def wrap_nested(self: MultiBlock) -> None: """Ensure that all nested data structures are wrapped as PyVista datasets. This is performed in place. """ for i in range(self.n_blocks): block = self.GetBlock(i) if not is_pyvista_dataset(block): self.SetBlock(i, wrap(block)) def _items(self) -> Iterable[tuple[str | None, _TypeMultiBlockLeaf]]: yield from zip(self.keys(), self) _OrderLiteral = Literal['nested_first', 'nested_last'] class _RecursiveIteratorBasicKwargs(TypedDict, total=False): """Define kwargs which have no impact on return type.""" skip_empty: bool prepend_names: bool separator: str @overload # 'ids', nested_ids=True def recursive_iterator( self: MultiBlock, contents: Literal['ids'], order: _OrderLiteral | None = ..., *, node_type: Literal['parent', 'child'] = ..., skip_none: bool = ..., nested_ids: Literal[True] | None = ..., **kwargs: Unpack[_RecursiveIteratorBasicKwargs], ) -> Iterator[tuple[int, ...]]: ... @overload # 'ids', nested_ids=False def recursive_iterator( self: MultiBlock, contents: Literal['ids'], order: _OrderLiteral | None = ..., *, node_type: Literal['parent', 'child'] = ..., skip_none: bool = ..., nested_ids: Literal[False], **kwargs: Unpack[_RecursiveIteratorBasicKwargs], ) -> Iterator[int]: ... @overload # 'names' def recursive_iterator( self: MultiBlock, contents: Literal['names'], order: _OrderLiteral | None = ..., *, node_type: Literal['parent', 'child'] = ..., skip_none: bool = ..., nested_ids: bool | None = ..., **kwargs: Unpack[_RecursiveIteratorBasicKwargs], ) -> Iterator[str]: ... @overload # 'items', node_type='child', skip_none=False def recursive_iterator( self: MultiBlock, contents: Literal['items'], order: _OrderLiteral | None = ..., *, node_type: Literal['child'] = ..., skip_none: Literal[False] = ..., nested_ids: bool | None = ..., **kwargs: Unpack[_RecursiveIteratorBasicKwargs], ) -> Iterator[tuple[str, DataSet | None]]: ... @overload # 'items', node_type='child', skip_none=True def recursive_iterator( self: MultiBlock, contents: Literal['items'], order: _OrderLiteral | None = ..., *, node_type: Literal['child'] = ..., skip_none: Literal[True], nested_ids: bool | None = ..., **kwargs: Unpack[_RecursiveIteratorBasicKwargs], ) -> Iterator[tuple[str, DataSet]]: ... @overload # 'blocks', node_type='child', skip_None=True def recursive_iterator( self: MultiBlock, contents: Literal['blocks'] = ..., order: _OrderLiteral | None = ..., *, node_type: Literal['child'] = ..., skip_none: Literal[True], nested_ids: bool | None = ..., **kwargs: Unpack[_RecursiveIteratorBasicKwargs], ) -> Iterator[DataSet]: ... @overload # 'blocks', node_type='child', skip_None=False def recursive_iterator( self: MultiBlock, contents: Literal['blocks'] = ..., order: _OrderLiteral | None = ..., *, node_type: Literal['child'] = ..., skip_none: Literal[False] = ..., nested_ids: bool | None = ..., **kwargs: Unpack[_RecursiveIteratorBasicKwargs], ) -> Iterator[DataSet | None]: ... @overload # 'all', node_type='child', skip_none=True, nested_ids=True def recursive_iterator( self: MultiBlock, contents: Literal['all'], order: _OrderLiteral | None = ..., *, node_type: Literal['child'] = ..., skip_none: Literal[True], nested_ids: Literal[True] | None = ..., **kwargs: Unpack[_RecursiveIteratorBasicKwargs], ) -> Iterator[tuple[tuple[int, ...], str, DataSet]]: ... @overload # 'all', node_type='child', skip_none=False, nested_ids=True def recursive_iterator( self: MultiBlock, contents: Literal['all'], order: _OrderLiteral | None = ..., *, node_type: Literal['child'] = ..., skip_none: Literal[False] = ..., nested_ids: Literal[True] | None = ..., **kwargs: Unpack[_RecursiveIteratorBasicKwargs], ) -> Iterator[tuple[tuple[int, ...], str, DataSet | None]]: ... @overload # 'all', node_type='child', skip_none=True, nested_ids=False def recursive_iterator( self: MultiBlock, contents: Literal['all'], order: _OrderLiteral | None = ..., *, node_type: Literal['child'] = ..., skip_none: Literal[True], nested_ids: Literal[False], **kwargs: Unpack[_RecursiveIteratorBasicKwargs], ) -> Iterator[tuple[int, str, DataSet]]: ... @overload # 'all', node_type='child', skip_none=False, nested_ids=False def recursive_iterator( self: MultiBlock, contents: Literal['all'], order: _OrderLiteral | None = ..., *, node_type: Literal['child'] = ..., skip_none: Literal[False] = ..., nested_ids: Literal[False], **kwargs: Unpack[_RecursiveIteratorBasicKwargs], ) -> Iterator[tuple[int, str, DataSet | None]]: ... @overload # 'items', node_type='parent' def recursive_iterator( self: MultiBlock, contents: Literal['items'], order: _OrderLiteral | None = ..., *, node_type: Literal['parent'], skip_none: bool = ..., nested_ids: bool | None = ..., **kwargs: Unpack[_RecursiveIteratorBasicKwargs], ) -> Iterator[tuple[str, MultiBlock]]: ... @overload # 'blocks', node_type='parent' def recursive_iterator( self: MultiBlock, contents: Literal['blocks'] = ..., order: _OrderLiteral | None = ..., *, node_type: Literal['parent'], skip_none: Literal[False] = ..., nested_ids: bool | None = ..., **kwargs: Unpack[_RecursiveIteratorBasicKwargs], ) -> Iterator[MultiBlock]: ... @overload # 'all', node_type='parent', nested_ids=True def recursive_iterator( self: MultiBlock, contents: Literal['all'], order: _OrderLiteral | None = ..., *, node_type: Literal['parent'], skip_none: Literal[False] = ..., nested_ids: Literal[True] | None = ..., **kwargs: Unpack[_RecursiveIteratorBasicKwargs], ) -> Iterator[tuple[tuple[int, ...], str, MultiBlock]]: ... @overload # 'all', node_type='parent', nested_ids=False def recursive_iterator( self: MultiBlock, contents: Literal['all'], order: _OrderLiteral | None = ..., *, node_type: Literal['parent'], skip_none: Literal[False] = ..., nested_ids: Literal[False], **kwargs: Unpack[_RecursiveIteratorBasicKwargs], ) -> Iterator[tuple[int, str, MultiBlock]]: ... @overload # general case def recursive_iterator( self: MultiBlock, contents: Literal['ids', 'names', 'blocks', 'items', 'all'] = ..., order: _OrderLiteral | None = ..., *, node_type: Literal['parent', 'child'] = ..., skip_none: bool = ..., skip_empty: bool = ..., nested_ids: bool | None = ..., prepend_names: bool = ..., separator: str = ..., ) -> ( Iterator[int | tuple[int, ...] | str | _TypeMultiBlockLeaf] | Iterator[tuple[str, _TypeMultiBlockLeaf]] | Iterator[tuple[int | tuple[int, ...], str, _TypeMultiBlockLeaf]] ): ... def recursive_iterator( self: MultiBlock, contents: Literal['ids', 'names', 'blocks', 'items', 'all'] = 'blocks', order: Literal['nested_first', 'nested_last'] | None = None, *, node_type: Literal['parent', 'child'] = 'child', skip_none: bool = False, skip_empty: bool = False, nested_ids: bool | None = None, prepend_names: bool = False, separator: str = '::', ) -> ( Iterator[int | tuple[int, ...] | str | _TypeMultiBlockLeaf] | Iterator[tuple[str, _TypeMultiBlockLeaf]] | Iterator[tuple[int | tuple[int, ...], str, _TypeMultiBlockLeaf]] ): """Iterate over all nested blocks recursively. .. versionadded:: 0.45 Parameters ---------- contents : 'ids' | 'names' | 'blocks' | 'items', default: 'blocks' Values to include in the iterator. - ``'ids'``: Return an iterator with nested block indices. - ``'names'``: Return an iterator with nested block names (i.e. :meth:`keys`). - ``'blocks'``: Return an iterator with nested blocks. - ``'items'``: Return an iterator with nested ``(name, block)`` pairs. - ``'all'``: Return an iterator with nested ``(index, name, block)`` triplets. .. note:: Use the ``nested_ids`` and ``prepend_names`` options to modify how the block ids and names are represented, respectively. order : 'nested_first', 'nested_last', optional Order in which to iterate through nested blocks. - ``'nested_first'``: Iterate through nested ``MultiBlock`` blocks first. - ``'nested_last'``: Iterate through nested ``MultiBlock`` blocks last. By default, the ``MultiBlock`` is iterated recursively as-is without changing the order. This option only applies when ``node_type`` is ``'child'``. node_type : 'parent' | 'child', default: 'child' Type of node blocks to generate ``contents`` from. If ``'parent'``, the contents are generated from :class:`MultiBlock` nodes. If ``'child'``, the contents are generated from :class:`~pyvista.DataSet` and ``None`` nodes. skip_none : bool, default: False If ``True``, do not include ``None`` blocks in the iterator. This option only applies when ``node_type`` is ``'child'``. skip_empty : bool, default: False If ``True``, do not include empty meshes in the iterator. If ``node_type`` is ``'parent'``, any :class:`MultiBlock` block with length ``0`` is skipped. If ``node_type`` is ``'child'``, any :class:`~pyvista.DataSet` block with ``0`` points is skipped. nested_ids : bool, default: True Prepend parent block indices to the child block indices. If ``True``, a tuple of indices is returned for each block. If ``False``, a single integer index is returned for each block. This option only applies when ``contents`` is ``'ids'`` or ``'all'``. prepend_names : bool, default: False Prepend any parent block names to the child block names. This option only applies when ``contents`` is ``'names'``, ``'items'``, or ``'all'``. separator : str, default: '::' String separator to use when ``prepend_names`` is enabled. The separator is inserted between parent and child block names. Returns ------- Iterator Iterator of ids, names, blocks, or name-block pairs depending on ``contents``. See Also -------- flatten Uses the iterator internally to flatten a :class:`MultiBlock`. pyvista.CompositeFilters.generic_filter Uses the iterator internally to apply filters to all blocks. clean Remove ``None`` and/or empty mesh blocks. Examples -------- Load a :class:`MultiBlock` with nested datasets. >>> import pyvista as pv >>> from pyvista import examples >>> multi = examples.download_biplane() The dataset has eight :class:`MultiBlock` blocks. >>> multi.n_blocks 8 >>> all(isinstance(block, pv.MultiBlock) for block in multi) True Get the iterator and show the count of all recursively nested blocks. >>> iterator = multi.recursive_iterator() >>> iterator >>> len(list(iterator)) 59 Check if all blocks are :class:`~pyvista.DataSet` objects. Note that ``None`` blocks are included by default, so this may not be ``True`` in all cases. >>> all(isinstance(item, pv.DataSet) for item in multi.recursive_iterator()) True Use the iterator to apply a filter inplace to all recursively nested datasets. >>> _ = [ ... dataset.connectivity(inplace=True) ... for dataset in multi.recursive_iterator() ... ] Iterate through nested block names. >>> iterator = multi.recursive_iterator('names') >>> next(iterator) 'Unnamed block ID: 1' Prepend parent block names. >>> iterator = multi.recursive_iterator('names', prepend_names=True) >>> next(iterator) 'Element Blocks::Unnamed block ID: 1' Iterate through name-block pairs. Prepend parent block names again using a custom separator. >>> iterator = multi.recursive_iterator( ... 'items', prepend_names=True, separator='->' ... ) >>> next(iterator) ('Element Blocks->Unnamed block ID: 1', UnstructuredGrid (...) N Cells: 8 N Points: 27 X Bounds: 4.486e-01, 1.249e+00 Y Bounds: 1.372e+00, 1.872e+00 Z Bounds: -6.351e-01, 3.649e-01 N Arrays: 6) Iterate through ids. The ids are returned as a tuple by default. >>> iterator = multi.recursive_iterator('ids') >>> next(iterator) (0, 0) Use :meth:`get_block` and get the next block indicated by the nested ids. >>> multi.get_block(next(iterator)) UnstructuredGrid ... Use the iterator to :attr:`replace` all blocks with new blocks. Similar to a previous example, we use a filter but this time the operation is not performed in place. >>> iterator = multi.recursive_iterator('all', nested_ids=True) >>> for ids, _, block in iterator: ... multi.replace(ids, block.connectivity()) Use ``node_type='parent'`` to get information about :class:`MultiBlock` nodes. >>> iterator = multi.recursive_iterator(node_type='parent') The iterator has ``8`` items. In this case this matches the number of blocks in the root block. >>> len(list(iterator)) 8 Use ``skip_empty`` to skip :class:`MultiBlock` nodes which have length ``0`` and return their block ids. >>> iterator = multi.recursive_iterator( ... 'ids', node_type='parent', skip_empty=True ... ) >>> ids = list(iterator) There are two non-empty blocks at index ``0`` and ``4``. >>> len(ids) 2 >>> ids [(0,), (4,)] """ _validation.check_contains( ['ids', 'names', 'blocks', 'items', 'all'], must_contain=contents, name='contents', ) _validation.check_contains( ['nested_first', 'nested_last', None], must_contain=order, name='order' ) nested_ids = contents in ['ids', 'all'] if nested_ids is None else nested_ids if nested_ids and contents not in ['ids', 'all']: msg = 'Nested ids option only applies when ids are returned.' raise ValueError(msg) if prepend_names and contents not in ['names', 'items', 'all']: msg = 'Prepend names option only applies when names are returned.' raise ValueError(msg) if node_type == 'parent': if skip_none: msg = "Cannot skip None blocks when the node type is 'parent'." raise ValueError(msg) if order is not None: msg = "Cannot set order when the node type is 'parent'." raise TypeError(msg) _validation.check_instance(separator, str, name='separator') if not separator: msg = 'String separator cannot be empty.' raise ValueError(msg) return self._recursive_iterator( ids=[[i] for i in range(self.n_blocks)], names=self.keys(), contents=contents, order=order, node_type=node_type, skip_none=skip_none, skip_empty=skip_empty, nested_ids=nested_ids, prepend_names=prepend_names, separator=separator, ) def _recursive_iterator( self, *, ids: Iterable[list[int]], names: Iterable[str], contents: Literal['ids', 'names', 'blocks', 'items', 'all'], order: Literal['nested_first', 'nested_last'] | None = None, node_type: Literal['parent', 'child'] = 'child', skip_none: bool, skip_empty: bool, nested_ids: bool, prepend_names: bool, separator: str, ) -> ( Iterator[int | tuple[int, ...] | str | _TypeMultiBlockLeaf] | Iterator[tuple[str, _TypeMultiBlockLeaf]] | Iterator[tuple[int | tuple[int, ...], str, _TypeMultiBlockLeaf]] ): # Determine ordering of blocks and names to iterate through if order is None: blocks: Sequence[_TypeMultiBlockLeaf] = self else: # Need to reorder blocks multi_ids = [] multi_names = [] multi_blocks = [] other_ids = [] other_names = [] other_blocks = [] for id_, name, block in zip(ids, names, self): if isinstance(block, MultiBlock): multi_ids.append(id_) multi_names.append(name) multi_blocks.append(block) else: other_ids.append(id_) other_names.append(name) other_blocks.append(block) if order == 'nested_last': ids = [*other_ids, *multi_ids] names = [*other_names, *multi_names] blocks = [*other_blocks, *multi_blocks] else: ids = [*multi_ids, *other_ids] names = [*multi_names, *other_names] blocks = [*multi_blocks, *other_blocks] # Iterate through ids, names, blocks for id_, name, block in zip(ids, names, blocks): if (skip_none and block is None) or ( skip_empty and (block is not None and block.is_empty) ): continue elif isinstance(block, MultiBlock): if skip_empty and len(block) == 0: continue # Process names names = block.keys() if prepend_names: # Include parent name with the block names names = [f'{name}{separator}{block_name}' for block_name in names] # Process ids if nested_ids: # Include parent id with the block ids ids = [[*id_, i] for i in range(block.n_blocks)] else: ids = [[i] for i in range(block.n_blocks)] # Yield from multiblock but fall-through in some cases for 'parent' nodes if node_type == 'child' or block.is_nested: yield from block._recursive_iterator( ids=ids, names=names, contents=contents, order=order, node_type=node_type, skip_none=skip_none, skip_empty=skip_empty, nested_ids=nested_ids, prepend_names=prepend_names, separator=separator, ) if node_type == 'child': continue elif node_type == 'parent': continue if contents == 'ids': yield tuple(id_) if nested_ids else id_[0] elif contents == 'names': yield name elif contents == 'blocks': yield block elif contents == 'items': yield name, block elif contents == 'all': id_out = tuple(id_) if nested_ids else id_[0] yield id_out, name, block else: # pragma: no cover msg = f"Unexpected contents '{contents}'." # type: ignore[unreachable] raise RuntimeError(msg) def move_nested_field_data_to_root( self, *, copy: bool | None = None, field_data_mode: Literal['preserve', 'prepend'] = 'preserve', user_dict_mode: Literal['preserve', 'prepend', 'flat', 'nested'] = 'preserve', separator: str = '::', check_duplicate_keys: bool = True, ) -> None: """Move or copy field data from all nested :class:`MultiBlock` blocks. Any nested :class:`MultiBlock` blocks will have its :attr:`~pyvista.DataObject.field_data` contents moved to the root block, (i.e. `this` ``MultiBock``). By default, this data will be cleared from the nested block(s) but a copy may be made instead. If any nested :class:`MultiBlock` blocks define a :attr:`~pyvista.DataObject.user_dict`, the root user-dict is also updated to include the nested block's user-dict data. All field data and user-dict keys are directly updated from the nested blocks by default. Optionally, different modes are provided to control the key names and/or how the data is moved. The move is done safely such that no key values will be overwritten and no data is lost. If any nested keys are duplicates of the root keys, an error is raised. .. note:: This operation only applies to nested :class:`MultiBlock` blocks. Field data associated with :class:`~pyvista.DataSet` blocks is `not` affected. .. versionadded:: 0.45 Parameters ---------- copy : bool, optional Set this value to copy the data. If ``True``, deep-copy the data from nested ``MultiBlock`` blocks to the root block. Both the root and nested blocks will share the same keys and refer to separate copies of the data. If ``False``, both the root and nested blocks will share the same keys but refer to the same data. By default, no copy is made; the nested field data is moved to the root block and cleared from the nested ``MultiBlock`` blocks. .. note:: This option does not apply to any nested :attr:`~pyvista.DataObject.user_dict` data. User-dict data is always deep-copied. field_data_mode : 'preserve' | 'prepend', default: 'preserve' Mode for naming the root field data keys when moving nested field data. - ``'preserve'``: The array names of nested field data are preserved. - ``'prepend'``: Preserve the array names and prepend the parent names. user_dict_mode : 'preserve' | 'prepend' | 'flat' | 'nested', default: 'preserve' Mode for naming the root :attr:`~pyvista.DataObject.user_dict` keys when nested :class:`MultiBlock` blocks define a user-dict. - ``'preserve'``: Update the root user dict directly with the items of any nested user-dict. - ``'nested'``: Create nested keys in the root user-dict which match the nested hierarchy of any nested ``MultiBlock`` blocks. - ``'flat'``: Create a new key in the root user dict for each nested ``MultiBlock`` that has a user-dict. - ``'prepend'``: Similar to ``'flat'`` except the key names are prepended with the parent block names. .. note:: If there is only a single level of nesting the ``'flat'``, ``'nested'`` and ``'prepend'`` modes are all equivalent. They only differ when there is at least two levels of nesting. separator : str, default: '::' String separator to use when ``'prepend'`` mode is enabled for either field data or for the user-dict. The separator is inserted between parent and child block names. check_duplicate_keys : bool, default: True Update the root data safely without overwriting existing data. If ``True``, an error is raised if any nested keys match the root block's keys. If ``False``, nested data is moved without checking if a key already exists, and data may be overwritten. Raises ------ ValueError If any field data keys in nested :class:`MultiBlock` blocks are duplicated in the root block and ``check_duplicate_keys`` is ``True``. See Also -------- flatten Examples -------- Create a :class:`MultiBlock` with field data. >>> import pyvista as pv >>> multi = pv.MultiBlock() >>> multi.field_data['data'] = [1, 2, 3] Nest the dataset inside another ``MultiBlock``. >>> root = pv.MultiBlock([multi]) Show that the root block does not have any field data. >>> root.field_data.keys() [] Move the nested field data to the root. >>> root.move_nested_field_data_to_root() The field data is now at the root. >>> root.field_data.keys() ['data'] And no longer exists in the nested ``MultiBlock``. >>> multi.field_data.keys() [] Add more field data to the nested block. >>> multi.field_data['more_data'] = [4, 5, 6] Move it to the root again, but this time prepend the name of the block the data came from. >>> root.move_nested_field_data_to_root(field_data_mode='prepend') >>> root.field_data.keys() ['data', 'Block-00::more_data'] The :attr:`~pyvista.DataObject.user_dict` is also field data which is moved to the root block's user-dict. Add sample data to the nested block and move it to the root. >>> data = dict(foo='bar') >>> multi.user_dict = data >>> root.move_nested_field_data_to_root() Check the root's user-dict. By default, the key names are preserved and the root dict is updated with the nested dict. >>> root.user_dict {"foo": "bar"} Clear the field data and re-add data to the nested user-dict. >>> root.clear_field_data() >>> multi.user_dict = data Move the data again but use the ``'flat'`` mode. This time, a new key is added which matches the nested block's name. >>> root.move_nested_field_data_to_root(user_dict_mode='flat') >>> root.user_dict {"Block-00": {"foo": "bar"}} """ _validation.check_contains( ['prepend', 'preserve'], must_contain=field_data_mode, name='field_data_mode', ) _validation.check_contains( ['prepend', 'preserve', 'flat', 'nested'], must_contain=user_dict_mode, name='user_dict_mode', ) root_field_data = self.field_data prepend_names = field_data_mode == 'prepend' iterator = self.recursive_iterator( 'all', node_type='parent', prepend_names=True, separator=separator ) for index, block_name, nested_multi in iterator: # Get nested field data to be moved nested_field_data = nested_multi.field_data if prepend_names: # Add the field data to a temp mesh so we can rename the arrays temp_mesh = pyvista.ImageData() temp_field_data = temp_mesh.field_data for old_name in nested_field_data: new_name = f'{block_name}{separator}{old_name}' temp_field_data[new_name] = nested_field_data[old_name] field_data_to_copy = temp_field_data else: field_data_to_copy = nested_field_data for array_name in field_data_to_copy: # Check for nested user-dict data if array_name.endswith(USER_DICT_KEY): root_user_dict = self.user_dict def raise_key_error( duplicate_key: str, block_name_: str, index_: tuple[int, ...] ) -> NoReturn: index_fmt = _format_nested_index(index_) msg = ( f'The root user dict cannot be updated with data from nested ' f"MultiBlock at index {index_fmt} with name '{block_name_}'.\n" f"The key '{duplicate_key}' already exists in the root user dict " f'and would be overwritten.' ) raise ValueError(msg) if user_dict_mode == 'preserve': if check_duplicate_keys: # Check if the keys already exist before updating root_user_dict_keys = root_user_dict.keys() for nested_key in nested_multi.user_dict.keys(): if nested_key in root_user_dict_keys: raise_key_error(nested_key, block_name, index) root_user_dict.update(nested_multi.user_dict) else: # Remove prepended names new_key = ( block_name if user_dict_mode == 'prepend' else block_name.split(separator)[-1] ) # Update the parent keys instead of the root keys if 'nested' if user_dict_mode == 'nested': parent, _ = self._navigate_to_parent(index) dict_to_update = parent.user_dict else: dict_to_update = root_user_dict if check_duplicate_keys: # Check if the keys already exist before updating if new_key in dict_to_update: raise_key_error(new_key, block_name, index) dict_to_update[new_key] = dict(nested_multi.user_dict) elif check_duplicate_keys and array_name in root_field_data: # Duplicate keys - raise error index_fmt = _format_nested_index(index) msg = ( f"The field data array '{array_name}' from nested MultiBlock " f"at index {index_fmt} with name '{block_name}'\n" f"also exists in the root MultiBlock's field data and cannot be moved." ) if not prepend_names: msg += "\nUse `field_data_mode='prepend'` to make the array names unique." raise ValueError(msg) else: # Copy the field data array = field_data_to_copy[array_name] # Remove prepended names short_array_name = ( array_name.split(separator)[-1] if field_data_mode != 'prepend' else array_name ) root_field_data._update_array( name=short_array_name, array=array, copy=bool(copy) ) if copy is None: nested_field_data.clear() def flatten( self, *, order: Literal['nested_first', 'nested_last'] | None = None, name_mode: Literal['preserve', 'prepend', 'reset'] = 'preserve', field_data_mode: Literal['preserve', 'prepend'] = 'preserve', user_dict_mode: Literal['preserve', 'prepend', 'flat', 'nested'] = 'preserve', separator: str = '::', check_duplicate_keys: bool = True, copy: bool = True, ) -> MultiBlock: """Flatten this :class:`MultiBlock`. Recursively iterate through all blocks and store them in a single :class:`MultiBlock` instance. All nested :class:`~pyvista.DataSet` and ``None`` blocks are preserved, and any nested ``MultiBlock`` container blocks are removed. Field data from any nested ``MultiBlock`` containers is preserved, however, and is also flattened. The flattening operation is "safe" by default in the sense that duplicate keys for block names and field data are not allowed and no data will be overwritten. .. versionadded:: 0.45 Parameters ---------- order : 'nested_last', 'nested_first', optional Order in which to flatten the contents. - ``'nested_first'``: Flatten nested ``MultiBlock`` blocks first. - ``'nested_last'``: Flatten nested ``MultiBlock`` blocks last. By default, the ``MultiBlock`` is flattened recursively as-is without changing the order. name_mode : 'preserve' | 'prepend' | 'reset', default: 'preserve' Mode for naming blocks in the flattened output. - ``'preserve'``: The names of all blocks are preserved. - ``'prepend'``: Preserve the block names and prepend the parent names. - ``'reset'``: Reset the block names to default values. field_data_mode : 'preserve' | 'prepend', default: 'preserve' Mode for naming the root field data keys when flattening nested field data. - ``'preserve'``: The array names of nested field data are preserved. - ``'prepend'``: Preserve the array names and prepend the parent names. user_dict_mode : 'preserve' | 'prepend' | 'flat' | 'nested', default: 'preserve' Mode for naming the flattened :attr:`~pyvista.DataObject.user_dict` keys when nested :class:`MultiBlock` blocks define a user-dict. - ``'preserve'``: Update the flattened user dict directly with the items of any nested user-dict. - ``'nested'``: Create nested keys in the flattened user-dict which match the nested hierarchy of any nested ``MultiBlock`` blocks. - ``'flat'``: Create a new key in the flattened user dict for each nested ``MultiBlock`` that has a user-dict. - ``'prepend'``: Similar to ``'flat'`` except the key names are prepended with the parent block names. .. note:: If there is only a single level of nesting the ``'flat'``, ``'nested'`` and ``'prepend'`` modes are all equivalent. They only differ when there is at least two levels of nesting. separator : str, default: '::' String separator to use when ``'prepend'`` mode is used. The separator is inserted between parent and child block name or field data array names. check_duplicate_keys : bool, default: True Flatten the MultiBlock data safely without overwriting any data or duplicating block names. If ``True``, an error is raised if any duplicate, non-unique field data keys or block names are identified. If ``False``, nested field data is flattened without checking for duplicate keys and data may be overwritten; the flattened MultiBlock may also have duplicate block names. copy : bool, default: True Return a deep copy of all nested blocks in the flattened ``MultiBlock``. If ``False``, shallow copies are returned. Returns ------- MultiBlock Flattened ``MultiBlock``. See Also -------- recursive_iterator move_nested_field_data_to_root pyvista.CompositeFilters.generic_filter clean Examples -------- Create a nested :class:`MultiBlock` with three levels of nesting and three end nodes. >>> import pyvista as pv >>> nested = pv.MultiBlock( ... { ... 'nested1': pv.MultiBlock( ... { ... 'nested2': pv.MultiBlock({'poly': pv.PolyData()}), ... 'image': pv.ImageData(), ... } ... ), ... 'none': None, ... } ... ) The root ``MultiBlock`` has two blocks. >>> nested.n_blocks 2 >>> type(nested[0]), type(nested[1]) (, ) Flatten the ``MultiBlock``. The nested ``MultiBlock`` containers are removed and only their contents are returned (i.e. the three end nodes). >>> flat = nested.flatten() >>> flat.n_blocks 3 >>> ( ... type(flat[0]), ... type(flat[1]), ... type(flat[2]), ... ) # doctest: +NORMALIZE_WHITESPACE (, , ) By default, the block names are preserved. >>> flat.keys() ['poly', 'image', 'none'] Prepend the names of parent blocks to the names instead. >>> flat = nested.flatten(name_mode='prepend') >>> flat.keys() ['nested1::nested2::poly', 'nested1::image', 'none'] Reset the names to default values instead. >>> flat = nested.flatten(name_mode='reset') >>> flat.keys() ['Block-00', 'Block-01', 'Block-02'] Flatten the ``MultiBlock`` with nested multi-blocks flattened last. Note the difference between this ordering of blocks and the default ordering returned earlier. >>> flat = nested.flatten(order='nested_last') >>> ( ... type(flat[0]), ... type(flat[1]), ... type(flat[2]), ... ) # doctest: +NORMALIZE_WHITESPACE (, , ) """ _validation.check_contains( ['preserve', 'prepend', 'reset'], must_contain=name_mode, name='name_mode' ) prepend_names = name_mode == 'prepend' if copy: input_multi = self.copy() else: # Shallow copy nested multiblocks to avoid mutating input field data input_multi = MultiBlock() input_multi.shallow_copy(self, recursive=True) # Move field data to output output_multi = MultiBlock() input_multi.move_nested_field_data_to_root( field_data_mode=field_data_mode, user_dict_mode=user_dict_mode, check_duplicate_keys=check_duplicate_keys, separator=separator, ) output_multi.field_data.update(input_multi.field_data, copy=copy) # Create iterator iterator = input_multi.recursive_iterator( contents='all', order=order, skip_none=False, skip_empty=False, prepend_names=prepend_names, separator=separator, ) # Append blocks to output reset_name = name_mode == 'reset' for index, name, block in iterator: if not reset_name and check_duplicate_keys: if name in output_multi.keys(): # Duplicate block name - raise error index_fmt = _format_nested_index(index) msg = ( f"Block at index {index_fmt} with name '{name}' " f'cannot be flattened. Another block \n' 'with the same name already exists. ' "Use `name_mode='reset'` or `check_duplicate_keys=False`." ) raise ValueError(msg) output_multi.append(block, None if reset_name else name) return output_multi @property def is_nested(self) -> bool: # numpydoc ignore=RT01 """Return ``True`` if any blocks are a :class:`MultiBlock`. .. versionadded:: 0.45 Examples -------- Create a simple :class:`MultiBlock`: >>> import pyvista as pv >>> multi = pv.MultiBlock([pv.Sphere()]) It only contains a :class:`~pyvista.DataSet`, so it is not nested. >>> multi.is_nested False Nest it inside another MultiBlock. >>> nested = pv.MultiBlock([multi]) >>> nested.is_nested True """ return any(isinstance(block, pyvista.MultiBlock) for block in self) @property def is_empty(self) -> bool: # numpydoc ignore=RT01 """Return ``True`` if there are no blocks. .. versionadded:: 0.45 Examples -------- >>> import pyvista as pv >>> mesh = pv.MultiBlock() >>> mesh.is_empty True >>> mesh.append(pv.Sphere()) >>> mesh.is_empty False """ return self.n_blocks == 0 @property def bounds(self: MultiBlock) -> BoundsTuple: """Find min/max for bounds across blocks. Returns ------- tuple[float, float, float, float, float, float] Length 6 tuple of floats containing min/max along each axis. Examples -------- Return the bounds across blocks. >>> import pyvista as pv >>> data = [ ... pv.Sphere(center=(2, 0, 0)), ... pv.Cube(center=(0, 2, 0)), ... pv.Cone(), ... ] >>> blocks = pv.MultiBlock(data) >>> blocks.bounds BoundsTuple(x_min = -0.5, x_max = 2.5, y_min = -0.5, y_max = 2.5, z_min = -0.5, z_max = 0.5) """ # apply reduction of min and max over each block # (typing.cast necessary to make mypy happy with ufunc.reduce() later) all_bounds = [cast('list[float]', block.bounds) for block in self if block] # edge case where block has no bounds if not all_bounds: # pragma: no cover minima = (0.0, 0.0, 0.0) maxima = (0.0, 0.0, 0.0) else: minima = np.minimum.reduce(all_bounds)[::2].tolist() maxima = np.maximum.reduce(all_bounds)[1::2].tolist() # interleave minima and maxima for bounds return BoundsTuple(minima[0], maxima[0], minima[1], maxima[1], minima[2], maxima[2]) @property def center(self: MultiBlock) -> tuple[float, float, float]: """Return the center of the bounding box. Returns ------- tuple[float, float, float] Center of the bounding box. Examples -------- >>> import pyvista as pv >>> data = [ ... pv.Sphere(center=(2, 0, 0)), ... pv.Cube(center=(0, 2, 0)), ... pv.Cone(), ... ] >>> blocks = pv.MultiBlock(data) >>> blocks.center # doctest:+SKIP array([1., 1., 0.]) """ return tuple(np.reshape(self.bounds, (3, 2)).mean(axis=1).tolist()) @property def length(self: MultiBlock) -> float: """Return the length of the diagonal of the bounding box. Returns ------- float Length of the diagonal of the bounding box. Examples -------- >>> import pyvista as pv >>> data = [ ... pv.Sphere(center=(2, 0, 0)), ... pv.Cube(center=(0, 2, 0)), ... pv.Cone(), ... ] >>> blocks = pv.MultiBlock(data) >>> blocks.length 4.3584 """ return Box(self.bounds).length @property def n_blocks(self: MultiBlock) -> int: """Return the total number of blocks set. Returns ------- int Total number of blocks set. Examples -------- >>> import pyvista as pv >>> data = [ ... pv.Sphere(center=(2, 0, 0)), ... pv.Cube(center=(0, 2, 0)), ... pv.Cone(), ... ] >>> blocks = pv.MultiBlock(data) >>> blocks.n_blocks 3 """ return self.GetNumberOfBlocks() @n_blocks.setter def n_blocks(self: MultiBlock, n: int) -> None: """Change the total number of blocks set. Parameters ---------- n : int The total number of blocks set. """ self.SetNumberOfBlocks(n) self.Modified() @property def volume(self: MultiBlock) -> float: """Return the total volume of all meshes in this dataset. Returns ------- float Total volume of the mesh. Examples -------- >>> import pyvista as pv >>> data = [ ... pv.Sphere(center=(2, 0, 0)), ... pv.Cube(center=(0, 2, 0)), ... pv.Cone(), ... ] >>> blocks = pv.MultiBlock(data) >>> blocks.volume 1.7348 """ return sum(block.volume for block in self if block) @_deprecate_positional_args(allowed=['name']) def get_data_range( # type: ignore[override] self: MultiBlock, name: str | None, allow_missing: bool = False, # noqa: FBT001, FBT002 preference: PointLiteral | CellLiteral | FieldLiteral = 'cell', ) -> tuple[float, float]: """Get the min/max of an array given its name across all blocks. Parameters ---------- name : str, optional The name of the array to get the range. If ``None``, the active scalars are used. allow_missing : bool, default: False Allow a block to be missing the named array. preference : str, default: "cell" When scalars is specified, this is the preferred array type to search for in the dataset. Must be either ``'point'``, ``'cell'``, or ``'field'``. .. versionadded:: 0.45 Returns ------- tuple ``(min, max)`` of the named array. """ mini, maxi = np.inf, -np.inf for i in range(self.n_blocks): data = self[i] if data is None: continue # get the scalars if available - recursive try: tmi, tma = data.get_data_range(name, preference=preference) except KeyError: if allow_missing: continue else: raise if not np.isnan(tmi) and tmi < mini: mini = tmi if not np.isnan(tma) and tma > maxi: maxi = tma return mini, maxi def get_index_by_name(self: MultiBlock, name: str) -> int: """Find the index number by block name. Parameters ---------- name : str Name of the block. Returns ------- int Index of the block. Examples -------- >>> import pyvista as pv >>> data = { ... 'cube': pv.Cube(), ... 'sphere': pv.Sphere(center=(2, 2, 0)), ... } >>> blocks = pv.MultiBlock(data) >>> blocks.get_index_by_name('sphere') 1 """ for i in range(self.n_blocks): if self.get_block_name(i) == name: return i msg = f'Block name ({name}) not found' raise KeyError(msg) @overload def __getitem__( self: MultiBlock, index: int | str, ) -> _TypeMultiBlockLeaf: ... # pragma: no cover @overload def __getitem__(self: MultiBlock, index: slice) -> MultiBlock: ... # pragma: no cover def __getitem__(self: MultiBlock, index): """Get a block by its index or name. If the name is non-unique then returns the first occurrence. """ if isinstance(index, slice): multi = MultiBlock() for i in range(self.n_blocks)[index]: multi.append(self[i], self.get_block_name(i)) return multi elif isinstance(index, str): index = self.get_index_by_name(index) ############################ if index < -self.n_blocks or index >= self.n_blocks: msg = f'index ({index}) out of range for this dataset.' raise IndexError(msg) if index < 0: index = self.n_blocks + index return wrap(self.GetBlock(index)) def append(self: MultiBlock, dataset: _TypeMultiBlockLeaf, name: str | None = None) -> None: """Add a data set to the next block index. Parameters ---------- dataset : pyvista.DataSet or pyvista.MultiBlock Dataset to append to this multi-block. name : str, optional Block name to give to dataset. A default name is given depending on the block index as ``'Block-{i:02}'``. Examples -------- >>> import pyvista as pv >>> from pyvista import examples >>> data = { ... 'cube': pv.Cube(), ... 'sphere': pv.Sphere(center=(2, 2, 0)), ... } >>> blocks = pv.MultiBlock(data) >>> blocks.append(pv.Cone()) >>> len(blocks) 3 >>> blocks.append(examples.load_uniform(), 'uniform') >>> blocks.keys() ['cube', 'sphere', 'Block-02', 'uniform'] """ # do not allow to add self if dataset is self: msg = 'Cannot nest a composite dataset in itself.' raise ValueError(msg) index = self.n_blocks # note off by one so use as index # always wrap since we may need to reference the VTK memory address wrapped = wrap(dataset) if isinstance(wrapped, pyvista_ndarray): msg = 'dataset should not be or contain an array' # type: ignore[unreachable] raise TypeError(msg) dataset = wrapped self.n_blocks += 1 self[index] = dataset # No overwrite if name is None self.set_block_name(index, name) def extend(self: MultiBlock, datasets: Iterable[_TypeMultiBlockLeaf]) -> None: """Extend MultiBlock with an Iterable. If another MultiBlock object is supplied, the key names will be preserved. Parameters ---------- datasets : Iterable[pyvista.DataSet or pyvista.MultiBlock] Datasets to extend. Examples -------- >>> import pyvista as pv >>> from pyvista import examples >>> data = { ... 'cube': pv.Cube(), ... 'sphere': pv.Sphere(center=(2, 2, 0)), ... } >>> blocks = pv.MultiBlock(data) >>> blocks_uniform = pv.MultiBlock({'uniform': examples.load_uniform()}) >>> blocks.extend(blocks_uniform) >>> len(blocks) 3 >>> blocks.keys() ['cube', 'sphere', 'uniform'] """ # Code based on collections.abc if isinstance(datasets, MultiBlock): for key, data in zip(datasets.keys(), datasets): self.append(data, key) else: for v in datasets: self.append(v) def get( self: MultiBlock, index: int | str, default: _TypeMultiBlockLeaf = None, ) -> _TypeMultiBlockLeaf: """Get a block by its index or name. If the name is non-unique then returns the first occurrence. Returns ``default`` if name isn't in the dataset. Parameters ---------- index : int | str Index or name of the dataset within the multiblock. default : pyvista.DataSet or pyvista.MultiBlock, optional Default to return if index is not in the multiblock. Returns ------- pyvista.DataSet or pyvista.MultiBlock or None Dataset from the given index if it exists. See Also -------- get_block Get a block and raise an ``IndexError`` if index is not found. Examples -------- >>> import pyvista as pv >>> from pyvista import examples >>> data = {'poly': pv.PolyData(), 'img': pv.ImageData()} >>> blocks = pv.MultiBlock(data) >>> blocks.get('poly') PolyData ... >>> blocks.get('cone') """ try: return self[index] except KeyError: return default def get_block( self: MultiBlock, index: int | Sequence[int] | str, ) -> _TypeMultiBlockLeaf: """Get a block by its index or name. If the name is non-unique then returns the first occurrence. This method is similar to using ``[]`` for indexing except this method also supports indexing nested blocks. .. versionadded:: 0.45 Parameters ---------- index : int | Sequence[int] | str Index or name of the dataset within the multiblock. Specify a sequence of indices to replace a nested block. Returns ------- pyvista.DataSet or pyvista.MultiBlock or None Dataset from the given index if it exists. See Also -------- get Get a block and return a default value instead of raising an ``IndexError``. Examples -------- >>> import pyvista as pv >>> blocks = pv.MultiBlock([pv.PolyData(), pv.ImageData()]) >>> nested = pv.MultiBlock([blocks]) >>> nested.get_block(0) MultiBlock ... >>> nested.get_block((0, 1)) ImageData ... """ if isinstance(index, Sequence) and not isinstance(index, str): parent, final_index = self._navigate_to_parent(index) return parent[final_index] return self[index] def set_block_name(self: MultiBlock, index: int | str, name: str | None) -> None: """Set a block's string name at the specified index. Parameters ---------- index : int | str Index or the dataset within the multiblock. .. versionadded:: 0.45 Allow indexing by name. name : str, optional Name to assign to the block at ``index``. If ``None``, no name is assigned to the block. Examples -------- >>> import pyvista as pv >>> data = { ... 'cube': pv.Cube(), ... 'sphere': pv.Sphere(center=(2, 2, 0)), ... } >>> blocks = pv.MultiBlock(data) >>> blocks.append(pv.Cone()) >>> blocks.set_block_name(2, 'cone') >>> blocks.keys() ['cube', 'sphere', 'cone'] """ if name is None: return index = ( self.get_index_by_name(index) if isinstance(index, str) else range(self.n_blocks)[index] ) self.GetMetaData(index).Set(_vtk.vtkCompositeDataSet.NAME(), name) self.Modified() def get_block_name(self: MultiBlock, index: int) -> str: """Return the string name of the block at the given index. Parameters ---------- index : int Index of the block to get the name of. Returns ------- str Name of the block at the given index. Examples -------- >>> import pyvista as pv >>> data = { ... 'cube': pv.Cube(), ... 'sphere': pv.Sphere(center=(2, 2, 0)), ... } >>> blocks = pv.MultiBlock(data) >>> blocks.get_block_name(0) 'cube' """ index = range(self.n_blocks)[index] # Safely cast as vtkInformation since `None` case is caught by IndexError above meta = cast('_vtk.vtkInformation', self.GetMetaData(index)) return meta.Get(_vtk.vtkCompositeDataSet.NAME()) # type:ignore[return-value] def keys(self: MultiBlock) -> list[str]: """Get all the block names in the dataset. Returns ------- list List of block names. Examples -------- >>> import pyvista as pv >>> data = { ... 'cube': pv.Cube(), ... 'sphere': pv.Sphere(center=(2, 2, 0)), ... } >>> blocks = pv.MultiBlock(data) >>> blocks.keys() ['cube', 'sphere'] """ return [self.get_block_name(i) for i in range(self.n_blocks)] def _ipython_key_completions_(self: MultiBlock) -> list[str]: return self.keys() def replace( self: MultiBlock, index: int | Sequence[int] | str, dataset: _TypeMultiBlockLeaf ) -> None: """Replace dataset at index while preserving key name. Parameters ---------- index : int | Sequence[int] | str Index or name of the block to replace. Specify a sequence of indices to replace a nested block. .. versionadded:: 0.45 Allow indexing nested blocks. dataset : pyvista.DataSet or pyvista.MultiBlock Dataset for replacing the one at index. Examples -------- >>> import pyvista as pv >>> from pyvista import examples >>> import numpy as np >>> data = { ... 'cube': pv.Cube(), ... 'sphere': pv.Sphere(center=(2, 2, 0)), ... } >>> blocks = pv.MultiBlock(data) >>> blocks.replace(1, pv.Sphere(center=(10, 10, 10))) >>> blocks.keys() ['cube', 'sphere'] >>> np.allclose(blocks[1].center, [10.0, 10.0, 10.0]) True Load a dataset with nested blocks. >>> multi = examples.download_biplane() Get one of the blocks and extract its surface. >>> block = multi[0][42] >>> surface = block.extract_geometry() Replace the block. >>> multi.replace((0, 42), surface) This is similar to replacing the block directly with indexing but the block name is also preserved. >>> multi[0][42] = surface """ if isinstance(index, Sequence) and not isinstance(index, str): parent, final_index = self._navigate_to_parent(index) parent.replace(final_index, dataset) return name = index if isinstance(index, str) else self.get_block_name(index) self[index] = dataset self.set_block_name(index, name) return def _navigate_to_parent(self, indices: Sequence[int]) -> tuple[MultiBlock, int]: """Navigate to the parent MultiBlock and return (parent, final_index).""" _validation.check_length(indices, min_length=1, name='index') # Navigate through the indices except the last one target: _TypeMultiBlockLeaf = self for ind in indices[:-1]: if target is None or isinstance(target, pyvista.DataSet): msg = f'Invalid indices {indices}.' raise IndexError(msg) target = target[ind] if not isinstance(target, MultiBlock): msg = f'Invalid indices {indices}.' raise IndexError(msg) return target, indices[-1] @overload def __setitem__( self: MultiBlock, index: int | str, data: _TypeMultiBlockLeaf, ) -> None: ... # pragma: no cover @overload def __setitem__( self: MultiBlock, index: slice, data: Iterable[_TypeMultiBlockLeaf], ) -> None: ... # pragma: no cover def __setitem__( self: MultiBlock, index: int | str | slice, data, ) -> None: """Set a block with a VTK data object. To set the name simultaneously, pass a string name as the 2nd index. Examples -------- >>> import pyvista as pv >>> multi = pv.MultiBlock() >>> multi.append(pv.PolyData()) >>> multi[0] = pv.UnstructuredGrid() >>> multi.append(pv.PolyData(), 'poly') >>> multi.keys() ['Block-00', 'poly'] >>> multi['bar'] = pv.PolyData() >>> multi.n_blocks 3 """ i: int = 0 name: str | None = None if isinstance(index, str): try: i = self.get_index_by_name(index) except KeyError: self.append(data, index) return name = index elif isinstance(index, slice): index_iter = range(self.n_blocks)[index] for i, (idx, d) in enumerate(itertools.zip_longest(index_iter, data)): if idx is None: self.insert( index_iter[-1] + 1 + (i - len(index_iter)), d, ) # insert after last entry, increasing elif d is None: del self[index_iter[-1] + 1] # delete next entry else: self[idx] = d return else: i = index # data, i, and name are a single value now data = cast('DataSet', wrap(data)) i = range(self.n_blocks)[i] # this is the only spot in the class where we actually add # data to the MultiBlock # check if we are overwriting a block existing_dataset = self.GetBlock(i) if existing_dataset is not None: self._remove_ref(i) self.SetBlock(i, data) if data is not None: self._refs[data.memory_address] = data if name is None: name = f'Block-{i:02}' self.set_block_name(i, name) # Note that this calls self.Modified() def __delitem__(self: MultiBlock, index: int | str | slice) -> None: """Remove a block at the specified index.""" if isinstance(index, slice): if index.indices(self.n_blocks)[2] > 0: for i in reversed(range(*index.indices(self.n_blocks))): self.__delitem__(i) else: for i in range(*index.indices(self.n_blocks)): self.__delitem__(i) return if isinstance(index, str): index = self.get_index_by_name(index) self._remove_ref(index) self.RemoveBlock(index) def _remove_ref(self: MultiBlock, index: int) -> None: """Remove python reference to the dataset.""" dataset = self[index] if hasattr(dataset, 'memory_address'): self._refs.pop(dataset.memory_address, None) # type: ignore[union-attr] def __eq__(self: MultiBlock, other: object) -> bool: """Equality comparison.""" if not isinstance(other, MultiBlock): return False if self is other: return True if len(self) != len(other): return False if not self.keys() == other.keys(): return False return not any(self_mesh != other_mesh for self_mesh, other_mesh in zip(self, other)) __hash__ = None # type: ignore[assignment] # https://github.com/pyvista/pyvista/pull/7671 def insert( self: MultiBlock, index: int, dataset: _TypeMultiBlockLeaf, name: str | None = None, ) -> None: """Insert data before index. Parameters ---------- index : int Index before which to insert data. dataset : pyvista.DataSet or pyvista.MultiBlock Data to insert. name : str, optional Name for key to give dataset. A default name is given depending on the block index as ``'Block-{i:02}'``. Examples -------- Insert a new :class:`pyvista.PolyData` at the start of the multiblock. >>> import pyvista as pv >>> data = { ... 'cube': pv.Cube(), ... 'sphere': pv.Sphere(center=(2, 2, 0)), ... } >>> blocks = pv.MultiBlock(data) >>> blocks.keys() ['cube', 'sphere'] >>> blocks.insert(0, pv.Plane(), 'plane') >>> blocks.keys() ['plane', 'cube', 'sphere'] """ index = range(self.n_blocks)[index] self.n_blocks += 1 for i in reversed(range(index, self.n_blocks - 1)): self[i + 1] = self[i] self.set_block_name(i + 1, self.get_block_name(i)) self[index] = dataset self.set_block_name(index, name) def pop(self: MultiBlock, index: int | str = -1) -> _TypeMultiBlockLeaf: """Pop off a block at the specified index. Parameters ---------- index : int or str, default: -1 Index or name of the dataset within the multiblock. Defaults to last dataset. Returns ------- pyvista.DataSet or pyvista.MultiBlock Dataset from the given index that was removed. Examples -------- Pop the ``"cube"`` multiblock. >>> import pyvista as pv >>> data = { ... 'cube': pv.Cube(), ... 'sphere': pv.Sphere(center=(2, 2, 0)), ... } >>> blocks = pv.MultiBlock(data) >>> blocks.keys() ['cube', 'sphere'] >>> cube = blocks.pop('cube') >>> blocks.keys() ['sphere'] """ if isinstance(index, int): index = range(self.n_blocks)[index] data = self[index] del self[index] return data def reverse(self: MultiBlock) -> None: """Reverse MultiBlock in-place. Examples -------- Reverse a multiblock. >>> import pyvista as pv >>> data = { ... 'cube': pv.Cube(), ... 'sphere': pv.Sphere(center=(2, 2, 0)), ... } >>> blocks = pv.MultiBlock(data) >>> blocks.keys() ['cube', 'sphere'] >>> blocks.reverse() >>> blocks.keys() ['sphere', 'cube'] """ # Taken from implementation in collections.abc.MutableSequence names = self.keys() n = len(self) for i in range(n // 2): self[i], self[n - i - 1] = self[n - i - 1], self[i] for i, name in enumerate(reversed(names)): self.set_block_name(i, name) @_deprecate_positional_args def clean(self: MultiBlock, empty: bool = True) -> None: # noqa: FBT001, FBT002 """Remove any null blocks in place. Parameters ---------- empty : bool, default: True Remove any meshes that are empty as well (have zero points). Examples -------- >>> import pyvista as pv >>> data = {'cube': pv.Cube(), 'empty': pv.PolyData()} >>> blocks = pv.MultiBlock(data) >>> blocks.clean(empty=True) >>> blocks.keys() ['cube'] """ null_blocks = [] for i in range(self.n_blocks): data = self[i] if isinstance(data, MultiBlock): # Recursively move through nested structures data.clean() if data.n_blocks < 1: null_blocks.append(i) elif data is None or (empty and data.n_points < 1): null_blocks.append(i) # Now remove the null/empty meshes null_blocks = np.array(null_blocks, dtype=int) # type: ignore[assignment] for i in range(len(null_blocks)): # Cast as int because windows is super annoying del self[int(null_blocks[i])] null_blocks -= 1 # type: ignore[assignment, operator] def _get_attrs(self: MultiBlock) -> list[tuple[str, Any, str]]: """Return the representation methods (internal helper).""" attrs: list[tuple[str, Any, str]] = [] attrs.append(('N Blocks:', self.n_blocks, '{}')) bds = self.bounds attrs.append(('X Bounds:', (bds.x_min, bds.x_max), '{:.3e}, {:.3e}')) attrs.append(('Y Bounds:', (bds.y_min, bds.y_max), '{:.3e}, {:.3e}')) attrs.append(('Z Bounds:', (bds.z_min, bds.z_max), '{:.3e}, {:.3e}')) return attrs def _repr_html_(self: MultiBlock) -> str: """Define a pretty representation for Jupyter notebooks.""" fmt = '' fmt += "" fmt += '' fmt += '
InformationBlocks
' fmt += '\n' fmt += '\n' fmt += f'\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])) fmt += '
{type(self).__name__}Values
{}{}
\n' fmt += '\n' fmt += '		' fmt += '\n' fmt += '\n' row = '\n' fmt += row.format('Index', 'Name', 'Type') for i in range(self.n_blocks): data = self[i] fmt += row.format(i, self.get_block_name(i), type(data).__name__) fmt += '
{}{}{}
\n' fmt += '\n' fmt += '
' return fmt def __repr__(self: MultiBlock) -> str: """Define an adequate representation.""" # 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 max_len = max(len(attr[0]) for attr in self._get_attrs()) + 3 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])) return fmt.strip() def __str__(self: MultiBlock) -> str: """Return the str representation of the multi block.""" return MultiBlock.__repr__(self) def __len__(self: MultiBlock) -> int: """Return the number of blocks.""" return self.n_blocks @_deprecate_positional_args(allowed=['ido']) def copy_meta_from( self: MultiBlock, ido: MultiBlock, deep: bool, # noqa: FBT001 ) -> None: # numpydoc ignore=PR01 """Copy pyvista meta data onto this object from another object.""" # Note that `pyvista.MultiBlock` datasets currently don't have any meta. # This method is here for consistency with the rest of the API and # in case we add meta data to this pbject down the road. @_deprecate_positional_args def copy(self: MultiBlock, deep: bool = True) -> MultiBlock: # noqa: FBT001, FBT002 """Return a copy of the multiblock. Parameters ---------- deep : bool, default: True When ``True``, make a full copy of the object. Returns ------- pyvista.MultiBlock Deep or shallow copy of the ``MultiBlock``. Examples -------- >>> import pyvista as pv >>> data = [ ... pv.Sphere(center=(2, 0, 0)), ... pv.Cube(center=(0, 2, 0)), ... pv.Cone(), ... ] >>> blocks = pv.MultiBlock(data) >>> new_blocks = blocks.copy() >>> len(new_blocks) 3 """ 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 @_deprecate_positional_args(allowed=['to_copy']) def shallow_copy( # type: ignore[override] self: MultiBlock, to_copy: _vtk.vtkMultiBlockDataSet, recursive: bool = False, # noqa: FBT001, FBT002 ) -> None: """Shallow copy the given multiblock to this multiblock. Parameters ---------- to_copy : MultiBlock | :vtk:`vtkMultiBlockDataSet` Data object to perform a shallow copy from. recursive : bool, default: False Also shallow-copy any nested :class:`~pyvista.MultiBlock` blocks. By default, only the root :class:`~pyvista.MultiBlock` is shallow-copied and any nested multi-blocks are not shallow-copied. """ if pyvista.vtk_version_info >= (9, 3): # pragma: no cover self.CompositeShallowCopy(to_copy) else: self.ShallowCopy(to_copy) self.wrap_nested() # Shallow copy creates new instances of nested multiblocks # Iterate through the blocks to fix this recursively def _replace_nested_multiblocks( this_object_: MultiBlock, new_object: _vtk.vtkMultiBlockDataSet ) -> None: for i, this_block in enumerate(this_object_): if isinstance(this_block, _vtk.vtkMultiBlockDataSet): block_to_copy = cast('MultiBlock', new_object.GetBlock(i)) this_object_.replace(i, block_to_copy) _replace_nested_multiblocks(cast('MultiBlock', this_block), block_to_copy) if not recursive: _replace_nested_multiblocks(self, to_copy) def deep_copy(self: MultiBlock, to_copy: _vtk.vtkMultiBlockDataSet) -> None: # type: ignore[override] """Overwrite this MultiBlock with another MultiBlock as a deep copy. Parameters ---------- to_copy : MultiBlock | :vtk:`vtkMultiBlockDataSet` MultiBlock to perform a deep copy from. """ super().deep_copy(to_copy) self.wrap_nested() # Deep copy will not copy the block name for None blocks (name is set to None instead) # Iterate through the blocks to fix this recursively def _set_name_for_none_blocks( this_object_: MultiBlock, new_object_: _vtk.vtkMultiBlockDataSet ) -> None: new_object_ = pyvista.wrap(new_object_) for i, dataset in enumerate(new_object_): if dataset is None: this_object_.set_block_name(i, new_object_.get_block_name(i)) elif isinstance(dataset, MultiBlock): _set_name_for_none_blocks(cast('MultiBlock', this_object_[i]), dataset) _set_name_for_none_blocks(self, to_copy) @_deprecate_positional_args(allowed=['name']) def set_active_scalars( self: MultiBlock, name: str | None, preference: PointLiteral | CellLiteral = 'cell', allow_missing: bool = False, # noqa: FBT001, FBT002 ) -> tuple[FieldAssociation, NumpyArray[float]]: """Find the scalars by name and appropriately set it as active. To deactivate any active scalars, pass ``None`` as the ``name``. Parameters ---------- name : str or None Name of the scalars array to assign as active. If ``None``, deactivates active scalars for both point and cell data. preference : str, default: "cell" If there are two arrays of the same name associated with points or cells, it will prioritize an array matching this type. Can be either ``'cell'`` or ``'point'``. allow_missing : bool, default: False Allow missing scalars in part of the composite dataset. If all blocks are missing the array, it will raise a ``KeyError``. Returns ------- pyvista.core.utilities.arrays.FieldAssociation Field association of the scalars activated. numpy.ndarray An array from the dataset matching ``name``. Notes ----- The number of components of the data must match. """ data_assoc: list[tuple[FieldAssociation, NumpyArray[float], _TypeMultiBlockLeaf]] = [] for block in self: if block is not None: if isinstance(block, MultiBlock): field, scalars = block.set_active_scalars( name, preference=preference, allow_missing=allow_missing, ) else: try: field, scalars_out = block.set_active_scalars(name, preference=preference) if scalars_out is None: field, scalars = FieldAssociation.NONE, pyvista_ndarray([]) else: scalars = scalars_out except KeyError: if not allow_missing: raise block.set_active_scalars(None, preference=preference) field, scalars = FieldAssociation.NONE, pyvista_ndarray([]) if field != FieldAssociation.NONE: data_assoc.append((field, scalars, block)) if name is None: return FieldAssociation.NONE, pyvista_ndarray([]) if not data_assoc: msg = f'"{name}" is missing from all the blocks of this composite dataset.' raise KeyError(msg) field_asc = data_assoc[0][0] # set the field association to the preference if at least one occurrence # of it exists preference_ = parse_field_choice(preference) if field_asc != preference_: for field, _, _ in data_assoc: if field == preference_: field_asc = preference_ break # Verify array consistency dims: set[int] = set() dtypes: set[np.dtype[Any]] = set() for _ in self: for field, scalars, _ in data_assoc: # only check for the active field association if field != field_asc: continue dims.add(scalars.ndim) dtypes.add(scalars.dtype) if len(dims) > 1: msg = f'Inconsistent dimensions {dims} in active scalars.' raise ValueError(msg) # check complex mismatch is_complex = [np.issubdtype(dtype, np.complexfloating) for dtype in dtypes] if any(is_complex) and not all(is_complex): msg = 'Inconsistent complex and real data types in active scalars.' raise ValueError(msg) return field_asc, scalars @_deprecate_positional_args def as_polydata_blocks(self: MultiBlock, copy: bool = False) -> MultiBlock: # noqa: FBT001, FBT002 """Convert all the datasets within this MultiBlock to :class:`~pyvista.PolyData`. Parameters ---------- copy : bool, default: False Option to create a shallow copy of any datasets that are already a :class:`~pyvista.PolyData`. When ``False``, any datasets that are already PolyData will not be copied. Returns ------- pyvista.MultiBlock MultiBlock containing only :class:`pyvista.PolyData` datasets. See Also -------- as_unstructured_grid_blocks Convert all blocks to :class:`~pyvista.UnstructuredGrid`. is_all_polydata Check if all blocks are :class:`~pyvista.PolyData`. :meth:`~pyvista.CompositeFilters.extract_geometry` Convert this :class:`~pyvista.MultiBlock` to :class:`~pyvista.PolyData`. Notes ----- Null blocks are converted to empty :class:`pyvista.PolyData` objects. Downstream filters that operate on PolyData cannot accept MultiBlocks with null blocks. """ # Define how to process each block def block_filter(block: DataSet | None) -> PolyData: if block is None: return pyvista.PolyData() elif isinstance(block, pyvista.PointSet): return block.cast_to_polydata(deep=True) elif isinstance(block, pyvista.PolyData): return block.copy(deep=False) if copy else block else: return block.extract_surface() return self.generic_filter(block_filter, _skip_none=False) @_deprecate_positional_args def as_unstructured_grid_blocks(self: MultiBlock, copy: bool = False) -> MultiBlock: # noqa: FBT001, FBT002 """Convert all the datasets within this MultiBlock to :class:`~pyvista.UnstructuredGrid`. .. versionadded:: 0.45 Parameters ---------- copy : bool, default: False Option to create a shallow copy of any datasets that are already a :class:`~pyvista.UnstructuredGrid`. When ``False``, any datasets that are already UnstructuredGrid will not be copied. Returns ------- MultiBlock MultiBlock containing only :class:`~pyvista.UnstructuredGrid` datasets. See Also -------- as_polydata_blocks Notes ----- Null blocks are converted to empty :class:`~pyvista.UnstructuredGrid` objects. Downstream filters that operate on UnstructuredGrid may not accept MultiBlocks with null blocks. """ # Define how to process each block def block_filter(block: DataSet | None) -> DataSet: if block is None: return pyvista.UnstructuredGrid() elif isinstance(block, pyvista.UnstructuredGrid): return block.copy(deep=False) if copy else block else: return block.cast_to_unstructured_grid() return self.generic_filter(block_filter, _skip_none=False) @property def is_all_polydata(self: MultiBlock) -> bool: """Return ``True`` when all the blocks are :class:`~pyvista.PolyData`. This method will recursively check if any internal blocks are also :class:`~pyvista.PolyData`. Returns ------- bool Return ``True`` when all blocks are :class:`~pyvista.PolyData`. See Also -------- as_polydata_blocks Convert all blocks to :class:`~pyvista.PolyData`. :meth:`~pyvista.CompositeFilters.extract_geometry` Convert this :class:`~pyvista.MultiBlock` to :class:`~pyvista.PolyData`. """ return all(isinstance(block, pyvista.PolyData) for block in self.recursive_iterator()) @property def block_types(self) -> set[type[_TypeMultiBlockLeaf]]: # numpydoc ignore=RT01 """Return a set of all block type(s). .. versionadded:: 0.45 See Also -------- nested_block_types Examples -------- Load a dataset with nested multi-blocks. Here we load :func:`~pyvista.examples.downloads.download_biplane`. >>> from pyvista import examples >>> multi = examples.download_biplane() The dataset has eight nested multi-block blocks, so the block types only contains :class:`MultiBlock`. >>> multi.block_types {} The nested blocks only contain a single mesh type so the nested block types only contains :class:`~pyvista.UnstructuredGrid`. >>> multi.nested_block_types {} """ return {type(block) for block in self} @property def nested_block_types(self) -> set[type[DataSet | None]]: # numpydoc ignore=RT01 """Return a set of all nested block type(s). .. versionadded:: 0.45 See Also -------- block_types is_homogeneous is_heterogeneous recursive_iterator Examples -------- Load a dataset with nested multi-blocks. Here we load :func:`~pyvista.examples.downloads.download_biplane`. >>> from pyvista import examples >>> multi = examples.download_biplane() The dataset has eight nested multi-block blocks, so the block types only contains :class:`MultiBlock`. >>> multi.block_types {} The nested blocks only contain a single mesh type so the nested block types only contains :class:`~pyvista.UnstructuredGrid`. >>> multi.nested_block_types {} """ return {type(block) for block in self.recursive_iterator()} @property def is_homogeneous(self: MultiBlock) -> bool: # numpydoc ignore=RT01 """Return ``True`` if all nested blocks have the same type. .. versionadded:: 0.45 See Also -------- is_heterogeneous nested_block_types recursive_iterator Examples -------- Load a dataset with nested multi-blocks. Here we load :func:`~pyvista.examples.downloads.download_biplane`. >>> from pyvista import examples >>> multi = examples.download_biplane() Show the :attr:`nested_block_types`. >>> multi.nested_block_types {} Since there is only one type, the dataset is homogeneous. >>> multi.is_homogeneous True """ return len(self.nested_block_types) == 1 @property def is_heterogeneous(self: MultiBlock) -> bool: # numpydoc ignore=RT01 """Return ``True`` any two nested blocks have different type. .. versionadded:: 0.45 See Also -------- is_homogeneous nested_block_types recursive_iterator Examples -------- Load a dataset with nested multi-blocks. Here we load :func:`~pyvista.examples.downloads.download_mug`. >>> from pyvista import examples >>> multi = examples.download_mug() Show the :attr:`nested_block_types`. >>> multi.nested_block_types # doctest:+SKIP {, } Since there is more than one type, the dataset is heterogeneous. >>> multi.is_heterogeneous True """ return len(self.nested_block_types) > 1 def _activate_plotting_scalars( self: MultiBlock, *, scalars_name: str, preference: PointLiteral | CellLiteral, component: int | None, rgb: NumpyArray[float], ) -> tuple[FieldAssociation, str, np.dtype[np.number[Any]]]: """Active a scalars for an instance of :class:`pyvista.Plotter`.""" # set the active scalars field, scalars = self.set_active_scalars( scalars_name, preference=preference, allow_missing=True, ) data_attr = f'{field.name.lower()}_data' dtype = scalars.dtype if rgb: if scalars.ndim != 2 or scalars.shape[1] not in (3, 4): msg = 'RGB array must be n_points/n_cells by 3/4 in shape.' raise ValueError(msg) if dtype != np.uint8: # uint8 is required by the mapper to display correctly _validation.check_subdtype(scalars, (np.floating, np.integer), name='rgb scalars') scalars_name = self._convert_to_uint8_rgb_scalars(data_attr, scalars_name) elif np.issubdtype(scalars.dtype, np.complexfloating): # Use only the real component if an array is complex scalars_name = self._convert_to_real_scalars(data_attr, scalars_name) elif scalars.dtype in (np.bool_, np.uint8): # bool and uint8 do not display properly, must convert to float self._convert_to_real_scalars(data_attr, scalars_name) if scalars.dtype == np.bool_: dtype = np.bool_ # type: ignore[assignment] elif scalars.ndim > 1: # multi-component if not isinstance(component, (int, type(None))): msg = '`component` must be either None or an integer' # type: ignore[unreachable] raise TypeError(msg) if component is not None: if component >= scalars.shape[1] or component < 0: msg = ( 'Component must be nonnegative and less than the ' f'dimensionality of the scalars array: {scalars.shape[1]}' ) raise ValueError(msg) scalars_name = self._convert_to_single_component(data_attr, scalars_name, component) return field, scalars_name, dtype def _convert_to_real_scalars(self: MultiBlock, data_attr: str, scalars_name: str) -> str: """Extract the real component of the active scalars of this dataset.""" for block in self: if isinstance(block, MultiBlock): block._convert_to_real_scalars(data_attr, scalars_name) elif block is not None: scalars = getattr(block, data_attr).get(scalars_name, None) if scalars is not None: scalars = np.array(scalars.astype(float)) dattr = getattr(block, data_attr) dattr[f'{scalars_name}-real'] = scalars dattr.active_scalars_name = f'{scalars_name}-real' return f'{scalars_name}-real' def _convert_to_uint8_rgb_scalars(self: MultiBlock, data_attr: str, scalars_name: str) -> str: """Convert rgb float or int scalars to uint8.""" for block in self: if isinstance(block, MultiBlock): block._convert_to_uint8_rgb_scalars(data_attr, scalars_name) elif block is not None: scalars = getattr(block, data_attr).get(scalars_name, None) if scalars is not None: if np.issubdtype(scalars.dtype, np.floating): _validation.check_range(scalars, [0.0, 1.0], name='rgb float scalars') scalars = np.array(scalars, dtype=np.uint8) * 255 elif np.issubdtype(scalars.dtype, np.integer): _validation.check_range(scalars, [0, 255], name='rgb int scalars') scalars = np.array(scalars, dtype=np.uint8) dattr = getattr(block, data_attr) dattr[f'{scalars_name}-uint8'] = scalars dattr.active_scalars_name = f'{scalars_name}-uint8' return f'{scalars_name}-uint8' def _convert_to_single_component( self: MultiBlock, data_attr: str, scalars_name: str, component: int | None, ) -> str: """Convert multi-component scalars to a single component.""" if component is None: for block in self: if isinstance(block, MultiBlock): block._convert_to_single_component(data_attr, scalars_name, component) elif block is not None: scalars = getattr(block, data_attr).get(scalars_name, None) if scalars is not None: scalars = np.linalg.norm(scalars, axis=1) dattr = getattr(block, data_attr) dattr[f'{scalars_name}-normed'] = scalars dattr.active_scalars_name = f'{scalars_name}-normed' return f'{scalars_name}-normed' for block in self: if isinstance(block, MultiBlock): block._convert_to_single_component(data_attr, scalars_name, component) elif block is not None: scalars = getattr(block, data_attr).get(scalars_name, None) if scalars is not None: dattr = getattr(block, data_attr) dattr[f'{scalars_name}-{component}'] = scalars[:, component] dattr.active_scalars_name = f'{scalars_name}-{component}' return f'{scalars_name}-{component}' def _get_consistent_active_scalars( self: MultiBlock, ) -> tuple[str | None, str | None]: """Get if there are any consistent active scalars.""" point_names = set() cell_names = set() for block in self: if block is not None: if isinstance(block, MultiBlock): point_name, cell_name = block._get_consistent_active_scalars() else: point_name = block.point_data.active_scalars_name cell_name = block.cell_data.active_scalars_name point_names.add(point_name) cell_names.add(cell_name) point_name = point_names.pop() if len(point_names) == 1 else None cell_name = cell_names.pop() if len(cell_names) == 1 else None return point_name, cell_name def clear_all_data(self: MultiBlock) -> None: """Clear all data from all blocks.""" for block in self: if isinstance(block, MultiBlock): block.clear_all_data() elif block is not None: block.clear_data() def clear_all_point_data(self: MultiBlock) -> None: """Clear all point data from all blocks.""" for block in self: if isinstance(block, MultiBlock): block.clear_all_point_data() elif block is not None: block.clear_point_data() def clear_all_cell_data(self: MultiBlock) -> None: """Clear all cell data from all blocks.""" for block in self: if isinstance(block, MultiBlock): block.clear_all_cell_data() elif block is not None: block.clear_cell_data()