pyvista.MultiBlock.recursive_iterator

pyvista.MultiBlock.recursive_iterator#

Iterate over all nested blocks recursively.

Added in version 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. 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 MultiBlock nodes. If 'child', the contents are generated from DataSet and None nodes.

skip_nonebool, default: False

If True, do not include None blocks in the iterator. This option only applies when node_type is 'child'.

skip_emptybool, default: False

If True, do not include empty meshes in the iterator. If node_type is 'parent', any MultiBlock block with length 0 is skipped. If node_type is 'child', any DataSet block with 0 points is skipped.

nested_idsbool, 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_namesbool, default: False

Prepend any parent block names to the child block names. This option only applies when contents is 'names', 'items', or 'all'.

separatorstr, 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 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 MultiBlock with nested datasets.

>>> import pyvista as pv
>>> from pyvista import examples
>>> multi = examples.download_biplane()

The dataset has eight 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
<generator object MultiBlock._recursive_iterator at ...>

>>> len(list(iterator))
59

Check if all blocks are 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 get_block() and get the next block indicated by the nested ids.

>>> multi.get_block(next(iterator))
UnstructuredGrid ...

Use the iterator to 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 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 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,)]

pyvista.MultiBlock.recursive_iterator

Contents

pyvista.MultiBlock.recursive_iterator#