Debian Codegraph @

examples/99-advanced/extending_pyvista.py

raw
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