DataObject.user_dict

DataObject.user_dict#

property DataObject.user_dict: _SerializedDictArray[source]#

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 (for example, '.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, that is, 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, for example, by calling tolist() on the array.

To completely remove the user dict string from the dataset’s field data, set its value to None.

The returned object belongs to this data object for its lifetime. Writing to it updates this data object, and it reflects field data that is loaded, copied in with copy_from(), or cleared. Copies and filter outputs start with their own copy of the dict. The field data array is created on the first write.

Changed in version 0.50: Copies and filter outputs no longer share the dict with their source, and reading user_dict no longer adds an array to the field data.

Deprecated since version 0.50: Keys that are not strings are deprecated. JSON stores keys as strings, so a key of another type is read back as a string from a copy, a filter output, or a file.

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.

Added in version 0.44.

Returns:
UserDict

JSON-serialized dict-like object which is subclassed from collections.UserDict.

Examples#

Download Python source code | Download Jupyter notebook

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      <U75       (1,)

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"]}