vispy.visuals.filters.mesh module

class vispy.visuals.filters.mesh.FacePickingFilter(fpos=9, *, discard_transparent=False)

Bases: PrimitivePickingFilter

Filter used to color mesh faces by a picking ID.

Note that the ID color uses the alpha channel, so this may not be used with blending enabled.

Examples

Picking Faces from a Mesh

class vispy.visuals.filters.mesh.InstancedShadingFilter(shading='flat', ambient_coefficient=(1, 1, 1, 1), diffuse_coefficient=(1, 1, 1, 1), specular_coefficient=(1, 1, 1, 1), shininess=100, light_dir=(10, 5, -5), ambient_light=(1, 1, 1, 0.25), diffuse_light=(1, 1, 1, 0.7), specular_light=(1, 1, 1, 0.25), enabled=True)

Bases: ShadingFilter

Shading filter modified for use with InstancedMeshVisual.

See ShadingFilter for details and usage.

class vispy.visuals.filters.mesh.ShadingFilter(shading='flat', ambient_coefficient=(1, 1, 1, 1), diffuse_coefficient=(1, 1, 1, 1), specular_coefficient=(1, 1, 1, 1), shininess=100, light_dir=(10, 5, -5), ambient_light=(1, 1, 1, 0.25), diffuse_light=(1, 1, 1, 0.7), specular_light=(1, 1, 1, 0.25), enabled=True)

Bases: Filter

Apply shading to a MeshVisual using the Phong reflection model.

For convenience, a MeshVisual creates and embeds a shading filter when constructed with an explicit shading parameter, e.g. mesh = MeshVisual(…, shading=’smooth’). The filter is then accessible as mesh.shading_filter.

When attached manually to a MeshVisual, the shading filter should come after any other filter that modifies the base color to be shaded. See the examples below.

Parameters:

shadingstr

Shading mode: None, ‘flat’ or ‘smooth’. If None, the shading is disabled.

ambient_coefficientstr or tuple or Color

Color and intensity of the ambient reflection coefficient (Ka).

diffuse_coefficientstr or tuple or Color

Color and intensity of the diffuse reflection coefficient (Kd).

specular_coefficientstr or tuple or Color

Color and intensity of the specular reflection coefficient (Ks).

shininessfloat

The shininess controls the size of specular highlight. The higher, the more localized. Must be greater than or equal to zero.

light_dirarray_like

Direction of the light. Assuming a directional light.

ambient_lightstr or tuple or Color

Color and intensity of the ambient light.

diffuse_lightstr or tuple or Color

Color and intensity of the diffuse light.

specular_lightstr or tuple or Color

Color and intensity of the specular light.

enabledbool, default=True

Whether the filter is enabled at creation time. This can be changed at run time with enabled.

Notes

Under the Phong reflection model, the illumination I is computed as:

I = I_ambient + mesh_color * I_diffuse + I_specular

for each color channel independently. mesh_color is the color of the MeshVisual, possibly modified by the filters applied before this one. The ambient, diffuse and specular terms are defined as:

I_ambient = Ka * Ia
I_diffuse = Kd * Id * dot(L, N)
I_specular = Ks * Is * dot(R, V) ** s

with

L

the light direction, assuming a directional light,

N

the normal to the surface at the reflection point,

R

the direction of the reflection,

V

the direction to the viewer,

s

the shininess factor.

The Ka, Kd and Ks coefficients are defined as an RGBA color. The RGB components define the color that the surface reflects, and the alpha component (A) defines the intensity/attenuation of the reflection. When applied in the per-channel illumation formulas above, the color component is multiplied by the intensity to obtain the final coefficient, e.g. Kd = R * A for the red channel.

Similarly, the light intensities, Ia, Id and Is, are defined by RGBA colors, corresponding to the color of the light and its intensity.

Examples

Define the mesh data for a vispy.visuals.mesh.MeshVisual:

>>> # A triangle.
>>> vertices = np.array([(0, 0, 0), (1, 1, 1), (0, 1, 0)], dtype=float)
>>> faces = np.array([(0, 1, 2)], dtype=int)

Let the vispy.visuals.mesh.MeshVisual create and embed a shading filter:

>>> mesh = MeshVisual(vertices, faces, shading='smooth')
>>> # Configure the filter afterwards.
>>> mesh.shading_filter.shininess = 64
>>> mesh.shading_filter.specular_coefficient = 0.3

Create the shading filter manually and attach it to a vispy.visuals.mesh.MeshVisual:

>>> # With the default shading parameters.
>>> shading_filter = ShadingFilter()
>>> mesh = MeshVisual(vertices, faces)
>>> mesh.attach(shading_filter)

The filter can be configured at creation time and at run time:

>>> # Configure at creation time.
>>> shading_filter = ShadingFilter(
...     # A shiny surface (small specular highlight).
...     shininess=250,
...     # A blue higlight, at half intensity.
...     specular_coefficient=(0, 0, 1, 0.5),
...     # Equivalent to `(0.7, 0.7, 0.7, 1.0)`.
...     diffuse_coefficient=0.7,
...     # Same as `(0.2, 0.3, 0.3, 1.0)`.
...     ambient_coefficient=(0.2, 0.3, 0.3),
... )
>>> # Change the configuration at run time.
>>> shading_filter.shininess = 64
>>> shading_filter.specular_coefficient = 0.3

Disable the filter temporarily:

>>> # Turn off the shading.
>>> shading_filter.enabled = False
... # Some time passes...
>>> # Turn on the shading again.
>>> shading_filter.enabled = True

When using the WireframeFilter, the wireframe is shaded only if the wireframe filter is attached before the shading filter:

>>> shading_filter = ShadingFilter()
>>> wireframe_filter = WireframeFilter()
>>> # Option 1: Shade the wireframe.
>>> mesh1 = MeshVisual(vertices, faces)
>>> mesh1.attached(wireframe_filter)
>>> mesh1.attached(shading_filter)
>>> # Option 2: Do not shade the wireframe.
>>> mesh2 = MeshVisual(vertices, faces)
>>> mesh2.attached(shading_filter)
>>> mesh2.attached(wireframe_filter)

See also examples/basics/scene/mesh_shading.py example script.

property ambient_coefficient

The ambient reflection coefficient.

property ambient_light

The color and intensity of the ambient light.

property diffuse_coefficient

The diffuse reflection coefficient.

property diffuse_light

The color and intensity of the diffuse light.

property enabled

True to enable the filter, False to disable.

property light_dir

The light direction.

on_mesh_data_updated(event)

property shading

The shading method.

property shininess

The shininess controlling the spread of the specular highlight.

property specular_coefficient

The specular reflection coefficient.

property specular_light

The color and intensity of the specular light.

class vispy.visuals.filters.mesh.TextureFilter(texture, texcoords, enabled=True)

Bases: Filter

Filter to apply a texture to a mesh.

Note the texture is applied by multiplying the texture color by the Visual’s produced color. By specifying color=”white” when creating a MeshVisual the result will be the unaltered texture value. Any other color, including the default, will result in a blending of that color and the color of the texture.

Parameters:

texture(M, N) or (M, N, C) array

The 2D texture image.

texcoords(N, 2) array

The texture coordinates.

enabledbool

Whether the display of the texture is enabled.

Examples

See examples/basics/scene/mesh_texture.py example script.

property enabled

True to display the texture, False to disable.

property texcoords

The texture coordinates as an (N, 2) array of floats.

property texture

The texture image.

class vispy.visuals.filters.mesh.WireframeFilter(enabled=True, color='black', width=1.0, wireframe_only=False, faces_only=False)

Bases: Filter

Add wireframe to a mesh.

The wireframe filter should be attached before the shading filter for the wireframe to be shaded.

Parameters:

colorstr or tuple or Color

Line color of the wireframe

widthfloat

Line width of the wireframe

enabledbool

Whether the wireframe is drawn or not

Examples

See examples/basics/scene/mesh_shading.py example script.

property color

The wireframe color.

property enabled

True to enable the display of the wireframe, False to disable.

property faces_only

Make the wireframe transparent.

Draw only the interior of the faces.

on_data_updated(event)

property width

The wireframe width.

property wireframe_only

Draw only the wireframe and discard the interior of the faces.