| 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 |