| 1 |
""" |
| 2 |
.. _extending_pyvista_example: |
| 3 |
|
| 4 |
Extending PyVista |
| 5 |
~~~~~~~~~~~~~~~~~ |
| 6 |
|
| 7 |
A :class:`pyvista.DataSet`, such as :class:`pyvista.PolyData`, can be extended |
| 8 |
by users. For example, if the user wants to keep track of the location of the |
| 9 |
maximum point in the (1, 0, 1) direction on the mesh. |
| 10 |
|
| 11 |
There are two methods by which users can handle subclassing. One is directly managing |
| 12 |
the types objects. This may require checking types during filter |
| 13 |
operations. |
| 14 |
|
| 15 |
The second is automatic managing of types. Users can control whether user defined |
| 16 |
classes are nearly always used for particular types of DataSets. |
| 17 |
|
| 18 |
.. note:: |
| 19 |
This is for advanced usage only. Automatic managing of types |
| 20 |
will not work in all situations, in particular when a builtin dataset is directly |
| 21 |
instantiated. See examples below. |
| 22 |
|
| 23 |
""" |
| 24 |
|
| 25 |
import numpy as np |
| 26 |
import pyvista as pv |
| 27 |
import vtk |
| 28 |
|
| 29 |
pv.set_plot_theme('document') |
| 30 |
|
| 31 |
# %% |
| 32 |
# A user defined subclass of :class:`pyvista.PolyData`, ``FooData`` is defined. |
| 33 |
# It includes a property to keep track of the point on the mesh that is |
| 34 |
# furthest along in the (1, 0, 1) direction. |
| 35 |
|
| 36 |
|
| 37 |
class FooData(pv.PolyData): # noqa: D101 |
| 38 |
@property |
| 39 |
def max_point(self): |
| 40 |
"""Returns index of point that is furthest along (1, 0, 1) direction.""" |
| 41 |
return np.argmax(np.dot(self.points, (1.0, 0.0, 1.0))) |
| 42 |
|
| 43 |
|
| 44 |
# %% |
| 45 |
# Directly Managing Types |
| 46 |
# +++++++++++++++++++++++ |
| 47 |
# |
| 48 |
# Now a ``foo_sphere`` object is created of type ``FooData``. |
| 49 |
# The index of the point and location of the point of interest can be obtained |
| 50 |
# directly. The sphere has a radius of 0.5, so the maximum extent in the |
| 51 |
# direction (1, 0, 1) is :math:`0.5\sqrt{0.5}\approx0.354` |
| 52 |
# |
| 53 |
|
| 54 |
foo_sphere = FooData(pv.Sphere(theta_resolution=100, phi_resolution=100)) |
| 55 |
print('Original foo sphere:') |
| 56 |
print(f'Type: {type(foo_sphere)}') |
| 57 |
print(f'Maximum point index: {foo_sphere.max_point}') |
| 58 |
print(f'Location of maximum point: {foo_sphere.points[foo_sphere.max_point, :]}') |
| 59 |
|
| 60 |
# %% |
| 61 |
# Using an inplace operation like :func:`~pyvista.DataObjectFilters.rotate_y` does not |
| 62 |
# affect the type of the object. |
| 63 |
|
| 64 |
foo_sphere.rotate_y(90, inplace=True) |
| 65 |
print('\nRotated foo sphere:') |
| 66 |
print(f'Type: {type(foo_sphere)}') |
| 67 |
print(f'Maximum point index: {foo_sphere.max_point}') |
| 68 |
print(f'Location of maximum point: {foo_sphere.points[foo_sphere.max_point, :]}') |
| 69 |
|
| 70 |
# %% |
| 71 |
# However, filter operations can return different ``DataSet`` types including |
| 72 |
# ones that differ from the original type. In this case, the |
| 73 |
# :func:`decimate <pyvista.PolyDataFilters.decimate>` method returns a |
| 74 |
# :class:`pyvista.PolyData` object. |
| 75 |
|
| 76 |
print('\nDecimated foo sphere:') |
| 77 |
decimated_foo_sphere = foo_sphere.decimate(0.5) |
| 78 |
print(f'Type: {type(decimated_foo_sphere)}') |
| 79 |
|
| 80 |
# %% |
| 81 |
# It is now required to explicitly wrap the object into ``FooData``. |
| 82 |
|
| 83 |
decimated_foo_sphere = FooData(foo_sphere.decimate(0.5)) |
| 84 |
print(f'Type: {type(decimated_foo_sphere)}') |
| 85 |
print(f'Maximum point index: {decimated_foo_sphere.max_point}') |
| 86 |
print(f'Location of maximum point: {foo_sphere.points[foo_sphere.max_point, :]}') |
| 87 |
|
| 88 |
# %% |
| 89 |
# Automatically Managing Types |
| 90 |
# ++++++++++++++++++++++++++++ |
| 91 |
# |
| 92 |
# The default :class:`pyvista.DataSet` type can be set using ``pyvista._wrappers``. |
| 93 |
# In general, it is best to use this method when it is expected to primarily |
| 94 |
# use the user defined class. |
| 95 |
# |
| 96 |
# In this example, all objects that would have been created as |
| 97 |
# :class:`pyvista.PolyData` would now be created as a ``FooData`` object. Note, |
| 98 |
# that the key is the underlying vtk object. |
| 99 |
|
| 100 |
pv._wrappers['vtkPolyData'] = FooData |
| 101 |
|
| 102 |
# %% |
| 103 |
# It is no longer necessary to specifically wrap :class:`pyvista.PolyData` |
| 104 |
# objects to obtain a ``FooData`` object. |
| 105 |
|
| 106 |
foo_sphere = pv.Sphere(theta_resolution=100, phi_resolution=100) |
| 107 |
print('Original foo sphere:') |
| 108 |
print(f'Type: {type(foo_sphere)}') |
| 109 |
print(f'Maximum point index: {foo_sphere.max_point}') |
| 110 |
print(f'Location of maximum point: {foo_sphere.points[foo_sphere.max_point, :]}') |
| 111 |
|
| 112 |
# %% |
| 113 |
# Using an inplace operation like :func:`~pyvista.DataObjectFilters.rotate_y` does not |
| 114 |
# affect the type of the object. |
| 115 |
|
| 116 |
foo_sphere.rotate_y(90, inplace=True) |
| 117 |
print('\nRotated foo sphere:') |
| 118 |
print(f'Type: {type(foo_sphere)}') |
| 119 |
print(f'Maximum point index: {foo_sphere.max_point}') |
| 120 |
print(f'Location of maximum point: {foo_sphere.points[foo_sphere.max_point, :]}') |
| 121 |
|
| 122 |
# %% |
| 123 |
# Filter operations that return :class:`pyvista.PolyData` now return |
| 124 |
# ``FooData`` |
| 125 |
|
| 126 |
print('\nDecimated foo sphere:') |
| 127 |
decimated_foo_sphere = foo_sphere.decimate(0.5) |
| 128 |
print(f'Type: {type(decimated_foo_sphere)}') |
| 129 |
print(f'Maximum point index: {decimated_foo_sphere.max_point}') |
| 130 |
print(f'Location of maximum point: {foo_sphere.points[foo_sphere.max_point, :]}') |
| 131 |
|
| 132 |
# %% |
| 133 |
# Users can still create a native :class:`pyvista.PolyData` object, but |
| 134 |
# using this method may incur unintended consequences. In this case, |
| 135 |
# it is recommended to use the directly managing types method. |
| 136 |
|
| 137 |
poly_object = pv.PolyData(vtk.vtkPolyData()) |
| 138 |
print(f'Type: {type(poly_object)}') |
| 139 |
# catch error |
| 140 |
try: |
| 141 |
poly_object.rotate_y(90, inplace=True) |
| 142 |
except TypeError: |
| 143 |
print('This operation fails') |
| 144 |
|
| 145 |
# %% |
| 146 |
# Usage of ``pyvista._wrappers`` may require resetting the default value |
| 147 |
# to avoid leaking the setting into cases where it is unused. |
| 148 |
|
| 149 |
pv._wrappers['vtkPolyData'] = pv.PolyData |
| 150 |
|
| 151 |
# %% |
| 152 |
# For instances where a localized usage is preferred, a tear-down method is |
| 153 |
# recommended. One example is a ``try...finally`` block. |
| 154 |
|
| 155 |
try: |
| 156 |
pv._wrappers['vtkPolyData'] = FooData |
| 157 |
# some operation that sometimes raises an error |
| 158 |
finally: |
| 159 |
pv._wrappers['vtkPolyData'] = pv.PolyData |