Skip to main content
`Ctrl`+`K`

# 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

  sphx_glr_gallery_scene_face_picking.py

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:
    shading str

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

    ambient_coefficient str or tuple or Color

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

    diffuse_coefficient str or tuple or Color

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

    specular_coefficient str or tuple or Color

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

    shininess float

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

    light_dir array_like

      Direction of the light. Assuming a directional light.

    ambient_light str or tuple or Color

      Color and intensity of the ambient light.

    diffuse_light str or tuple or Color

      Color and intensity of the diffuse light.

    specular_light str or tuple or Color

      Color and intensity of the specular light.

    enabled bool, 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.

    enabled bool

      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:
    color str or tuple or Color

      Line color of the wireframe

    width float

      Line width of the wireframe

    enabled bool

      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.