Debian Codegraph @

examples/01-filter/image_representations.py

raw
1 """
2 .. _image_representations_example:
3
4 Image Data Representations
5 ~~~~~~~~~~~~~~~~~~~~~~~~~~
6 This example demonstrates how to use :meth:`~pyvista.ImageDataFilters.points_to_cells`
7 and :meth:`~pyvista.ImageDataFilters.cells_to_points` to re-mesh
8 :class:`~pyvista.ImageData`.
9
10 These filters can be used to ensure that image data has an appropriate representation
11 when generating plots and/or when using either point- or cell-based filters such as
12 :meth:`ImageDataFilters.image_threshold <pyvista.ImageDataFilters.image_threshold>`
13 (point-based) and
14 :meth:`DataSetFilters.threshold <pyvista.DataSetFilters.threshold>` (cell-based).
15
16 """
17
18 # %%#
19 # Representations of 3D Volumes
20 # -----------------------------
21 # Create image data of a 3D volume with eight points and a discrete scalar data
22 # array.
23 import numpy as np
24 import pyvista as pv
25
26 # sphinx_gallery_thumbnail_number = 3
27
28
29 data_array = [8, 7, 6, 5, 4, 3, 2, 1]
30 points_volume = pv.ImageData(dimensions=(2, 2, 2))
31 points_volume.point_data['Data'] = data_array
32
33 # %%#
34 # If we plot the volume, it is represented as a single cell with eight points,
35 # and the point data is interpolated to color the cell.
36
37 points_volume.plot(show_edges=True)
38
39 # %%#
40 # However, in many applications (e.g. 3D medical imaging), the scalar data arrays
41 # represent discretized samples at the centers of voxels. As such, it may
42 # be more appropriate to represent the data as eight voxel cells instead of
43 # eight points. We can use :meth:`~pyvista.ImageDataFilters.points_to_cells` to
44 # generate a cell-based representation.
45
46 cells_volume = points_volume.points_to_cells()
47
48 # %%#
49 # Now, when we plot the volume, we have a more appropriate representation with
50 # eight voxel cells and the scalar data is no longer interpolated.
51
52 cells_volume.plot(show_edges=True)
53
54 # %%#
55 # Let's plot the two representations together for comparison.
56 #
57 # For visualization, we color the points volume (inner mesh) and only show the edges
58 # of the cells volume (outer mesh). We also plot the cell centers in red. Note
59 # how the centers of the image of the cells correspond to the points of the points image.
60
61 cell_centers = cells_volume.cell_centers()
62 cell_edges = cells_volume.extract_all_edges()
63
64 pl = pv.Plotter()
65 pl.add_mesh(points_volume, color=True, show_edges=True, opacity=0.7)
66 pl.add_mesh(cell_edges, color='black', line_width=2)
67 pl.add_points(
68 cell_centers,
69 render_points_as_spheres=True,
70 color='red',
71 point_size=20,
72 )
73 pl.camera.azimuth = -25
74 pl.camera.elevation = 25
75 pl.show()
76
77 # %%#
78 # As long as only one kind of scalar data is used (i.e. either point or cell
79 # data, but not both), it is possible to move between representations without
80 # loss of data.
81
82 array_before = points_volume.active_scalars
83 array_after = points_volume.points_to_cells().cells_to_points().active_scalars
84 np.array_equal(array_before, array_after)
85
86 # %%#
87 # Point Filters with Image Data
88 # -----------------------------
89 # Use a point representation of the image when working with point-based
90 # filters such as :meth:`~pyvista.ImageDataFilters.image_threshold`. If the
91 # image only has cell data, use :meth:`~pyvista.ImageDataFilters.cells_to_points`
92 # re-mesh the input first. Here, we reuse the point-based image defined earlier.
93 #
94 # For context, we first show the input data array.
95
96 points_volume.point_data['Data']
97
98 # %%#
99 # Now apply the filter and print the result.
100
101 points_ithresh = points_volume.image_threshold(2)
102 points_ithresh.point_data['Data']
103
104 # %%#
105 # The filter returns binary point data as expected. Values equal to or greater
106 # or than the threshold of ``2`` are ones and less than the threshold are zeros.
107 #
108 # However, in plotting it, the point values are linearly interpolated. For
109 # visualizing binary data, this interpolation is not desirable.
110
111 points_ithresh.plot(show_edges=True)
112
113 # %%#
114 # To better visualize the result, convert the image of the point returned by the
115 # filter to a cell representation with :meth:`~pyvista.ImageDataFilters.points_to_cells`
116 # before plotting.
117
118 points_ithresh_as_cells = points_ithresh.points_to_cells()
119 points_ithresh_as_cells.plot(show_edges=True)
120
121 # %%#
122 # The binary data is now correctly visualized as binary data.
123
124 # %%#
125 # Cell Filters with Image Data
126 # ----------------------------
127 # Use a cell representation of the image when working with cell-based filters
128 # such as :meth:`~pyvista.DataSetFilters.threshold`. If the image only has point
129 # data, use :meth:`~pyvista.ImageDataFilters.points_to_cells` to re-mesh the
130 # input first. Here, we reuse the cell-based image created earlier.
131 #
132 # For context, we first show the input data array.
133
134 cells_volume.cell_data['Data']
135
136 # %%#
137 # Now apply the filter and print the result.
138
139 cells_thresh = cells_volume.threshold(2)
140 cells_thresh.cell_data['Data']
141
142 # %%#
143 # When the input is cell data, this filter returns seven discrete values greater
144 # than or equal to the threshold value of ``2`` as expected.
145 #
146 # If we plot the result, the cells also produce the correct visualization.
147
148 cells_thresh.plot(show_edges=True)
149
150 # %%#
151 # However, if we apply the same filter to a point-based representation of the
152 # image, the filter does not produce the desired result.
153
154 points_thresh = points_volume.threshold(2)
155 points_thresh.point_data['Data']
156
157 # %%#
158 # In this case, since the image of the point only has a single cell, the filter has no
159 # effect on the data array's values. The thresholded values are the same as the
160 # input values.
161 #
162 # Plotting the result confirms this. The plot is identical to the initial plot
163 # of the point-based image shown at the beginning of this example.
164
165 points_thresh.plot(show_edges=True)
166
167 # %%#
168 # Representations of 2D Images
169 # ----------------------------
170 # The filters :meth:`~pyvista.ImageDataFilters.points_to_cells` and
171 # :meth:`~pyvista.ImageDataFilters.cells_to_points` can similarly be used
172 # with 2D images.
173 #
174 # For this example, we create a 4x4 2D grayscale image with 16 points to represent
175 # 16 pixels.
176
177 data_array = np.linspace(0, 255, 16, dtype=np.uint8)[::-1]
178 points_image = pv.ImageData(dimensions=(4, 4, 1))
179 points_image.point_data['Data'] = data_array
180
181 # %%#
182 # Plot the image. As before, the plot does not appear correct since the point
183 # data is interpolated, and nine cells are shown rather than the desired 16
184 # (one for each pixel).
185
186 plot_kwargs = dict(
187 cpos='xy',
188 zoom='tight',
189 show_axes=False,
190 cmap='gray',
191 clim=[0, 255],
192 show_edges=True,
193 )
194 points_image.plot(**plot_kwargs)
195
196 # %%#
197 # To visualize the image correctly, we first use
198 # :meth:`~pyvista.ImageDataFilters.points_to_cells` to get a cell-based representation of
199 # the image and plot the result. The plot now correctly shows 16-pixel cells with discrete
200 # values.
201
202 cells_image = points_image.points_to_cells()
203 cells_image.plot(**plot_kwargs)
204
205 # %%#
206 # Let's plot the two representations together for comparison.
207 #
208 # For visualization, we color the points image (inner mesh) and show the cells
209 # image (outer mesh) as a wireframe. We also plot the cell centers in red. Note
210 # how the centers of the image of the cells correspond to the points of the points image.
211
212 cell_centers = cells_image.cell_centers()
213
214 pl = pv.Plotter()
215 pl.add_mesh(points_image, color=True, opacity=0.7)
216 pl.add_mesh(cells_image, style='wireframe', color='black', line_width=2)
217 pl.add_points(
218 cell_centers,
219 render_points_as_spheres=True,
220 color='red',
221 point_size=20,
222 )
223 pl.view_xy()
224 pl.show()
225 # %%
226 # .. tags:: filter