""" .. _image_representations_example: Image Data Representations ~~~~~~~~~~~~~~~~~~~~~~~~~~ This example demonstrates how to use :meth:`~pyvista.ImageDataFilters.points_to_cells` and :meth:`~pyvista.ImageDataFilters.cells_to_points` to re-mesh :class:`~pyvista.ImageData`. These filters can be used to ensure that image data has an appropriate representation when generating plots and/or when using either point- or cell-based filters such as :meth:`ImageDataFilters.image_threshold ` (point-based) and :meth:`DataSetFilters.threshold ` (cell-based). """ # %%# # Representations of 3D Volumes # ----------------------------- # Create image data of a 3D volume with eight points and a discrete scalar data # array. from __future__ import annotations import numpy as np import pyvista as pv # sphinx_gallery_thumbnail_number = 3 data_array = [8, 7, 6, 5, 4, 3, 2, 1] points_volume = pv.ImageData(dimensions=(2, 2, 2)) points_volume.point_data['Data'] = data_array # %%# # If we plot the volume, it is represented as a single cell with eight points, # and the point data is interpolated to color the cell. points_volume.plot(show_edges=True) # %%# # However, in many applications (e.g. 3D medical imaging), the scalar data arrays # represent discretized samples at the centers of voxels. As such, it may # be more appropriate to represent the data as eight voxel cells instead of # eight points. We can use :meth:`~pyvista.ImageDataFilters.points_to_cells` to # generate a cell-based representation. cells_volume = points_volume.points_to_cells() # %%# # Now, when we plot the volume, we have a more appropriate representation with # eight voxel cells and the scalar data is no longer interpolated. cells_volume.plot(show_edges=True) # %%# # Let's plot the two representations together for comparison. # # For visualization, we color the points volume (inner mesh) and only show the edges # of the cells volume (outer mesh). We also plot the cell centers in red. Note # how the centers of the image of the cells correspond to the points of the points image. cell_centers = cells_volume.cell_centers() cell_edges = cells_volume.extract_all_edges() plot = pv.Plotter() plot.add_mesh(points_volume, color=True, show_edges=True, opacity=0.7) plot.add_mesh(cell_edges, color='black', line_width=2) plot.add_points( cell_centers, render_points_as_spheres=True, color='red', point_size=20, ) plot.camera.azimuth = -25 plot.camera.elevation = 25 plot.show() # %%# # As long as only one kind of scalar data is used (i.e. either point or cell # data, but not both), it is possible to move between representations without # loss of data. array_before = points_volume.active_scalars array_after = points_volume.points_to_cells().cells_to_points().active_scalars np.array_equal(array_before, array_after) # %%# # Point Filters with Image Data # ----------------------------- # Use a point representation of the image when working with point-based # filters such as :meth:`~pyvista.ImageDataFilters.image_threshold`. If the # image only has cell data, use :meth:`~pyvista.ImageDataFilters.cells_to_points` # re-mesh the input first. Here, we reuse the point-based image defined earlier. # # For context, we first show the input data array. points_volume.point_data['Data'] # %%# # Now apply the filter and print the result. points_ithresh = points_volume.image_threshold(2) points_ithresh.point_data['Data'] # %%# # The filter returns binary point data as expected. Values equal to or greater # or than the threshold of ``2`` are ones and less than the threshold are zeros. # # However, in plotting it, the point values are linearly interpolated. For # visualizing binary data, this interpolation is not desirable. points_ithresh.plot(show_edges=True) # %%# # To better visualize the result, convert the image of the point returned by the # filter to a cell representation with :meth:`~pyvista.ImageDataFilters.points_to_cells` # before plotting. points_ithresh_as_cells = points_ithresh.points_to_cells() points_ithresh_as_cells.plot(show_edges=True) # %%# # The binary data is now correctly visualized as binary data. # %%# # Cell Filters with Image Data # ---------------------------- # Use a cell representation of the image when working with cell-based filters # such as :meth:`~pyvista.DataSetFilters.threshold`. If the image only has point # data, use :meth:`~pyvista.ImageDataFilters.points_to_cells` to re-mesh the # input first. Here, we reuse the cell-based image created earlier. # # For context, we first show the input data array. cells_volume.cell_data['Data'] # %%# # Now apply the filter and print the result. cells_thresh = cells_volume.threshold(2) cells_thresh.cell_data['Data'] # %%# # When the input is cell data, this filter returns seven discrete values greater # than or equal to the threshold value of ``2`` as expected. # # If we plot the result, the cells also produce the correct visualization. cells_thresh.plot(show_edges=True) # %%# # However, if we apply the same filter to a point-based representation of the # image, the filter does not produce the desired result. points_thresh = points_volume.threshold(2) points_thresh.point_data['Data'] # %%# # In this case, since the image of the point only has a single cell, the filter has no # effect on the data array's values. The thresholded values are the same as the # input values. # # Plotting the result confirms this. The plot is identical to the initial plot # of the point-based image shown at the beginning of this example. points_thresh.plot(show_edges=True) # %%# # Representations of 2D Images # ---------------------------- # The filters :meth:`~pyvista.ImageDataFilters.points_to_cells` and # :meth:`~pyvista.ImageDataFilters.cells_to_points` can similarly be used # with 2D images. # # For this example, we create a 4x4 2D grayscale image with 16 points to represent # 16 pixels. data_array = np.linspace(0, 255, 16, dtype=np.uint8)[::-1] points_image = pv.ImageData(dimensions=(4, 4, 1)) points_image.point_data['Data'] = data_array # %%# # Plot the image. As before, the plot does not appear correct since the point # data is interpolated, and nine cells are shown rather than the desired 16 # (one for each pixel). plot_kwargs = dict( cpos='xy', zoom='tight', show_axes=False, cmap='gray', clim=[0, 255], show_edges=True, ) points_image.plot(**plot_kwargs) # %%# # To visualize the image correctly, we first use :meth:`~pyvista.ImageDataFilters.points_to_cells` # to get a cell-based representation of the image and plot the result. The plot # now correctly shows 16-pixel cells with discrete values. cells_image = points_image.points_to_cells() cells_image.plot(**plot_kwargs) # %%# # Let's plot the two representations together for comparison. # # For visualization, we color the points image (inner mesh) and show the cells # image (outer mesh) as a wireframe. We also plot the cell centers in red. Note # how the centers of the image of the cells correspond to the points of the points image. cell_centers = cells_image.cell_centers() plot = pv.Plotter() plot.add_mesh(points_image, color=True, opacity=0.7) plot.add_mesh(cells_image, style='wireframe', color='black', line_width=2) plot.add_points( cell_centers, render_points_as_spheres=True, color='red', point_size=20, ) plot.view_xy() plot.show() # %% # .. tags:: filter