pyvista.DataObject.user_dict

property DataObject.user_dict: _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 and is intended for metadata storage. It has an inefficient dictionary implementation and should only be used to store a small number of infrequently-accessed keys with relatively small values. It should not be used to store frequently accessed array data with many entries (a regular field data array should be used 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.

Returns:

UserDict

JSON-serialized dict-like object which is subclassed from 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"]}