pyvista.MultiBlock.flatten

pyvista.MultiBlock.flatten#

MultiBlock.flatten(
*,
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[source]#

Flatten this MultiBlock.

Recursively iterate through all blocks and store them in a single MultiBlock instance. All nested 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.

Added in version 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 user_dict keys when nested 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.

separatorstr, 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_keysbool, 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.

copybool, 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 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])
(<class 'pyvista.core.composite.MultiBlock'>, <class 'NoneType'>)

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])
(<class 'pyvista.core.pointset.PolyData'>, <class 'pyvista.core.grid.ImageData'>, <class 'NoneType'>)

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])
(<class 'NoneType'>, <class 'pyvista.core.grid.ImageData'>, <class 'pyvista.core.pointset.PolyData'>)
Contents