Actor.set_point_sprite_shape

Actor.set_point_sprite_shape#

Actor.set_point_sprite_shape(
shape: PointSpriteShape | str,
) → None[source]#

Set a custom point sprite shape via fragment shader.

Added in version 0.48.

Replaces the default square point rendering with a custom shape defined by a GLSL fragment shader. This uses the discard instruction to clip fragments outside the desired shape boundary.

With native point-shape support, the shape is stored on pyvista.Property.point_shape and applies to point primitives in every representation, including vertex cells in surfaces. Sphere rendering takes precedence while enabled. Older backends use a shader replacement active only in 'points' representation. The requested shape can be read from point_sprite_shape.

Parameters:
shapePointSpriteShape | str

The sprite shape to use. Accepts a PointSpriteShape enum value or a string. Must be one of:

  • 'circle' - Circular disc

  • 'triangle' - Upward-pointing triangle

  • 'hexagon' - Regular hexagon

  • 'diamond' - Diamond (rotated square)

  • 'asterisk' - Five-pointed asterisk

  • 'star' - Five-pointed star

Raises:
ValueError

If shape is not one of the supported shapes.

Notes#

Point sprite shapes only produce visible results when render_points_as_spheres=False and style='points'. When render_points_as_spheres=True, VTK uses a different rendering path that bypasses the fragment shader.

Examples#

Download Python source code | Download Jupyter notebook

Render points as circles instead of squares.

>>> import numpy as np
>>> import pyvista as pv
>>> cloud = pv.PolyData(np.random.default_rng(0).random((100, 3)))
>>> pl = pv.Plotter()
>>> actor = pl.add_mesh(
...     cloud,
...     style='points',
...     render_points_as_spheres=False,
...     point_size=20,
... )
>>> actor.set_point_sprite_shape('circle')

See Also#

Point Sprite Shapes