pyvista.ImageDataFilters.pad_image

ImageDataFilters.pad_image(

pad_value: float | VectorLike[float] | Literal['wrap', 'mirror'] = 0.0,

*,

pad_size: int | VectorLike[int] = 1,

dimensionality: VectorLike[bool] | Literal[0, 1, 2, 3, '0D', '1D', '2D', '3D', 'preserve'] = 'preserve',

scalars: str | None = None,

pad_all_scalars: bool = False,

progress_bar: bool = False,

pad_singleton_dims: bool | None = None,

) → pyvista.ImageData

Enlarge an image by padding its boundaries with new points.

Added in version 0.44.0.

Padded points may be mirrored, wrapped, or filled with a constant value. By default, all boundaries of the image are padded with a single constant value.

This filter is designed to work with 1D, 2D, or 3D image data and will only pad non-singleton dimensions unless otherwise specified.

Parameters:

pad_valuefloat | sequence[float] | ‘mirror’ | ‘wrap’, default: 0.0

Padding value(s) given to new points outside the original image extent. Specify:

• a number: New points are filled with the specified constant value.

• a vector: New points are filled with the specified multi-component vector.

• 'wrap': New points are filled by wrapping around the padding axis.

• 'mirror': New points are filled by mirroring the padding axis.

pad_sizeint | sequence[int], default: 1

Number of points to add to the image boundaries. Specify:

• A single value to pad all boundaries equally.

• Two values, one for each (X, Y) axis, to apply symmetric padding to each axis independently.

• Three values, one for each (X, Y, Z) axis, to apply symmetric padding to each axis independently.

• Four values, one for each (-X, +X, -Y, +Y) boundary, to apply padding to each boundary independently.

• Six values, one for each (-X, +X, -Y, +Y, -Z, +Z) boundary, to apply padding to each boundary independently.

dimensionalityVectorLike[bool], Literal[1, 2, 3, “1D”, “2D”, “3D”, “preserve”], default: ‘preserve’

Control which dimensions will be padded by the filter.

• Can be specified as a sequence of 3 boolean to apply padding on a per

  dimension basis.

• 1 or '1D': apply padding such that the output is a 1D ImageData where exactly one dimension is greater than one, e.g. (>1, 1, 1). Only valid for 0D or 1D inputs.

• 2 or '2D': apply padding such that the output is a 2D ImageData where exactly two dimensions are greater than one, e.g. (>1, >1, 1). Only valid for 0D, 1D, or 2D inputs.

• 3 or '3D': apply padding such that the output is a 3D ImageData, where all three dimensions are greater than one, e.g. (>1, >1, >1). Valid for any 0D, 1D, 2D, or 3D inputs.

Note

The pad_size for singleton dimensions is set to 0 by default, even if non-zero pad sizes are specified for these axes with this parameter. Set dimensionality to a value different than 'preserve' to override this behavior and enable padding any or all dimensions.

Added in version 0.45.0.

scalarsstr, optional

Name of scalars to pad. Defaults to currently active scalars. Unless pad_all_scalars is True, only the specified scalars are included in the output.

pad_all_scalarsbool, default: False

Pad all point data scalars and include them in the output. This is useful for padding images with multiple scalars. If False, only the specified scalars are padded.

progress_barbool, default: False

Display a progress bar to indicate progress.

pad_singleton_dimsbool, optional

Control whether to pad singleton dimensions.

Deprecated since version 0.45.0: Deprecated, use dimensionality='preserve' instead of pad_singleton_dims=True and dimensionality='3D' instead of pad_singleton_dims=False.

Estimated removal on v0.48.0.

Returns:

pyvista.ImageData

Padded image.

Examples

Pad a grayscale image with a 100-pixel wide border. The padding is black (i.e. has a value of 0) by default.

>>> import pyvista as pv
>>> from pyvista import examples
>>>
>>> gray_image = examples.download_moonlanding_image()
>>> gray_image.dimensions
(630, 474, 1)
>>> padded = gray_image.pad_image(pad_size=100)
>>> padded.dimensions
(830, 674, 1)

Plot the image. To show grayscale images correctly, we define a custom plotting method.

>>> def grayscale_image_plotter(image):
...     import vtk
...
...     actor = vtk.vtkImageActor()
...     actor.GetMapper().SetInputData(image)
...     actor.GetProperty().SetInterpolationTypeToNearest()
...     plot = pv.Plotter()
...     plot.add_actor(actor)
...     plot.view_xy()
...     plot.camera.tight()
...     return plot
>>>
>>> plot = grayscale_image_plotter(padded)
>>> plot.show()

Static Scene

Interactive Scene

Pad only the x-axis with a white border.

>>> padded = gray_image.pad_image(pad_value=255, pad_size=(200, 0))
>>> plot = grayscale_image_plotter(padded)
>>> plot.show()

Static Scene

Interactive Scene

Pad with wrapping.

>>> padded = gray_image.pad_image('wrap', pad_size=100)
>>> plot = grayscale_image_plotter(padded)
>>> plot.show()

Static Scene

Interactive Scene

Pad with mirroring.

>>> padded = gray_image.pad_image('mirror', pad_size=100)
>>> plot = grayscale_image_plotter(padded)
>>> plot.show()

Static Scene

Interactive Scene

Pad a color image using multi-component color vectors. Here, RGBA values are used.

>>> color_image = examples.download_beach()
>>> red = (255, 0, 0)  # RGB
>>> padded = color_image.pad_image(pad_value=red, pad_size=50)
>>>
>>> plot_kwargs = dict(cpos='xy', zoom='tight', rgb=True, show_axes=False)
>>> padded.plot(**plot_kwargs)

Static Scene

Interactive Scene

Pad each edge of the image separately with a different color.

>>> orange = pv.Color('orange').int_rgb
>>> purple = pv.Color('purple').int_rgb
>>> blue = pv.Color('blue').int_rgb
>>> green = pv.Color('green').int_rgb
>>>
>>> padded = color_image.pad_image(orange, pad_size=(25, 0, 0, 0))
>>> padded = padded.pad_image(purple, pad_size=(0, 25, 0, 0))
>>> padded = padded.pad_image(blue, pad_size=(0, 0, 25, 0))
>>> padded = padded.pad_image(green, pad_size=(0, 0, 0, 25))
>>>
>>> padded.plot(**plot_kwargs)

Static Scene

Interactive Scene