vispy 0.15.0__cp313-cp313-manylinux_2_17_aarch64.manylinux2014_aarch64.whl

vispy/visuals/filters/mesh.py

@@ -0,0 +1,801 @@
+# -*- coding: utf-8 -*-
+# Copyright (c) Vispy Development Team. All Rights Reserved.
+# Distributed under the (new) BSD License. See LICENSE.txt for more info.
+import numbers
+
+import numpy as np
+
+from vispy.gloo import Texture2D, VertexBuffer
+from vispy.visuals.shaders import Function, Varying
+from vispy.visuals.filters import Filter, PrimitivePickingFilter
+from ...color import Color
+
+
+class TextureFilter(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
+    <https://github.com/vispy/vispy/blob/main/examples/basics/scene/mesh_texture.py>`_
+    example script.
+
+    """
+
+    def __init__(self, texture, texcoords, enabled=True):
+        """Apply a texture on a mesh."""
+        vfunc = Function("""
+            void pass_coords() {
+                $v_texcoords = $texcoords;
+            }
+        """)
+        ffunc = Function("""
+            void apply_texture() {
+                if ($enabled == 1) {
+                    gl_FragColor *= texture2D($u_texture, $texcoords);
+                }
+            }
+        """)
+        self._texcoord_varying = Varying('v_texcoord', 'vec2')
+        vfunc['v_texcoords'] = self._texcoord_varying
+        ffunc['texcoords'] = self._texcoord_varying
+        self._texcoords_buffer = VertexBuffer(
+            np.zeros((0, 2), dtype=np.float32)
+        )
+        vfunc['texcoords'] = self._texcoords_buffer
+        super().__init__(vcode=vfunc, vhook='pre', fcode=ffunc)
+
+        self.enabled = enabled
+        self.texture = texture
+        self.texcoords = texcoords
+
+    @property
+    def enabled(self):
+        """True to display the texture, False to disable."""
+        return self._enabled
+
+    @enabled.setter
+    def enabled(self, enabled):
+        self._enabled = enabled
+        self.fshader['enabled'] = 1 if enabled else 0
+
+    @property
+    def texture(self):
+        """The texture image."""
+        return self._texture
+
+    @texture.setter
+    def texture(self, texture):
+        self._texture = texture
+        self.fshader['u_texture'] = Texture2D(texture)
+
+    @property
+    def texcoords(self):
+        """The texture coordinates as an (N, 2) array of floats."""
+        return self._texcoords
+
+    @texcoords.setter
+    def texcoords(self, texcoords):
+        self._texcoords = texcoords
+        self._update_texcoords_buffer(texcoords)
+
+    def _update_texcoords_buffer(self, texcoords):
+        if not self._attached or self._visual is None:
+            return
+
+        # FIXME: Indices for texture coordinates might be different than face
+        # indices, although in some cases they are the same. Currently,
+        # vispy.io.read_mesh assumes face indices and texture coordinates are
+        # the same.
+        # TODO:
+        # 1. Add reading and returning of texture coordinate indices in
+        #    read_mesh.
+        # 2. Add texture coordinate indices in MeshData from
+        #    vispy.geometry.meshdata
+        # 3. Use mesh_data.get_texcoords_indices() here below.
+        tc = texcoords[self._visual.mesh_data.get_faces()]
+        self._texcoords_buffer.set_data(tc, convert=True)
+
+    def _attach(self, visual):
+        super()._attach(visual)
+        self._update_texcoords_buffer(self._texcoords)
+
+
+shading_vertex_template = """
+varying vec3 v_normal_vec;
+varying vec3 v_light_vec;
+varying vec3 v_eye_vec;
+varying vec4 v_pos_scene;
+
+void prepare_shading() {
+    vec4 pos_scene = $render2scene(gl_Position);
+    v_pos_scene = pos_scene;
+
+    // Calculate normal
+    vec4 normal_scene = $visual2scene(vec4($normal, 1.0));
+    vec4 origin_scene = $visual2scene(vec4(0.0, 0.0, 0.0, 1.0));
+    normal_scene /= normal_scene.w;
+    origin_scene /= origin_scene.w;
+    v_normal_vec = normalize(normal_scene.xyz - origin_scene.xyz);
+
+    // Calculate eye vector per-vertex (to account for perspective)
+    vec4 pos_doc = $scene2doc(pos_scene);
+    pos_doc /= pos_doc.w;
+    vec4 pos_front = pos_doc;
+    vec4 pos_back = pos_doc;
+    pos_front.z -= 1e-5;
+    pos_back.z += 1e-5;
+    pos_front = $doc2scene(pos_front);
+    pos_back = $doc2scene(pos_back);
+    // The eye vec eminates from the eye, pointing towards what is being viewed
+    v_eye_vec = normalize(pos_back.xyz / pos_back.w - pos_front.xyz / pos_front.w);
+
+    // Pass on light direction (the direction that the "photons" travel)
+    v_light_vec = normalize($light_dir.xyz);
+}
+"""
+
+
+shading_fragment_template = """
+varying vec3 v_normal_vec;
+varying vec3 v_light_vec;
+varying vec3 v_eye_vec;
+varying vec4 v_pos_scene;
+
+void shade() {
+    if ($shading_enabled != 1) {
+        return;
+    }
+
+    vec3 base_color = gl_FragColor.rgb;
+    vec4 ambient_coeff = $ambient_coefficient;
+    vec4 diffuse_coeff = $diffuse_coefficient;
+    vec4 specular_coeff = $specular_coefficient;
+    vec4 ambient_light = $ambient_light;
+    vec4 diffuse_light = $diffuse_light;
+    vec4 specular_light = $specular_light;
+    float shininess = $shininess;
+
+    vec3 normal = v_normal_vec;
+    if ($flat_shading == 1) {
+        vec3 u = dFdx(v_pos_scene.xyz);
+        vec3 v = dFdy(v_pos_scene.xyz);
+        normal = cross(u, v);
+    } else {
+        // Note(asnt): The normal calculated above always points in the
+        // direction of the camera. Reintroduce the original orientation of the
+        // face.
+        normal = gl_FrontFacing ? normal : -normal;
+    }
+    normal = normalize(normal);
+
+    vec3 light_vec = normalize(v_light_vec);
+    vec3 eye_vec = normalize(v_eye_vec);
+
+    // Ambient illumination.
+    vec3 ambient = ambient_coeff.rgb * ambient_coeff.a
+                   * ambient_light.rgb * ambient_light.a;
+
+    // Diffuse illumination (light vec points towards the surface)
+    float diffuse_factor = dot(-light_vec, normal);
+    diffuse_factor = max(diffuse_factor, 0.0);
+    vec3 diffuse = diffuse_factor
+                   * diffuse_coeff.rgb * diffuse_coeff.a
+                   * diffuse_light.rgb * diffuse_light.a;
+
+    // Specular illumination. Both light_vec and eye_vec point towards the surface.
+    float specular_factor = 0.0;
+    bool is_illuminated = diffuse_factor > 0.0;
+    if (is_illuminated && shininess > 0.0) {
+        // Phong reflection
+        //vec3 reflection = reflect(-light_vec, normal);
+        //float reflection_factor = max(dot(reflection, eye_vec), 0.0);
+        // Blinn-Phong reflection
+        vec3 halfway = -normalize(light_vec + eye_vec);
+        float reflection_factor = clamp(dot(halfway, normal), 0.0, 1.0);
+        specular_factor = pow(reflection_factor, shininess);
+    }
+    vec3 specular = specular_factor
+                    * specular_coeff.rgb * specular_coeff.a
+                    * specular_light.rgb * specular_light.a;
+
+    // Blend the base color and combine the illuminations.
+    vec3 color = base_color * (ambient + diffuse) + specular;
+    gl_FragColor.rgb = color;
+}
+"""  # noqa
+
+
+def _as_rgba(intensity_or_color, default_rgb=(1.0, 1.0, 1.0)):
+    """Create an RGBA color from a color or a scalar intensity.
+
+    Examples
+    --------
+    >>> # Specify the full RGBA color.
+    >>> _as_rgba((0.2, 0.3, 0.4, 0.25))
+    ... <Color: (0.2, 0.3, 0.4, 0.25)>
+    >>> # Specify an RGB color. (Default intensity `1.0` is used.)
+    >>> _as_rgba((0.2, 0.3, 0.4))
+    ... <Color: (0.2, 0.3, 0.4, 1.0)>
+    >>> # Specify an intensity only. (Default color `(1.0, 1.0, 1.0)` is used.)
+    >>> _as_rgba(0.25)
+    ... <Color: (1.0, 1.0, 1.0, 0.25)>
+    """
+    if isinstance(intensity_or_color, numbers.Number):
+        intensity = intensity_or_color
+        return Color(default_rgb, alpha=intensity)
+    color = intensity_or_color
+    return Color(color)
+
+
+class ShadingFilter(Filter):
+    """Apply shading to a :class:`~vispy.visuals.mesh.MeshVisual` using the Phong reflection model.
+
+    For convenience, a :class:`~vispy.visuals.mesh.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 :class:`~vispy.visuals.mesh.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 :obj:`~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 :class:`~vispy.visuals.mesh.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 :class:`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 :class:`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
+    :class:`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 :class:`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
+    <https://github.com/vispy/vispy/blob/main/examples/basics/scene/mesh_shading.py>`_
+    example script.
+    """
+    _shaders = {
+        'vertex': shading_vertex_template,
+        'fragment': shading_fragment_template,
+    }
+
+    def __init__(self, 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, .25),
+                 diffuse_light=(1, 1, 1, 0.7),
+                 specular_light=(1, 1, 1, .25),
+                 enabled=True):
+        self._shading = shading
+
+        self._ambient_coefficient = _as_rgba(ambient_coefficient)
+        self._diffuse_coefficient = _as_rgba(diffuse_coefficient)
+        self._specular_coefficient = _as_rgba(specular_coefficient)
+        self._shininess = shininess
+
+        self._light_dir = light_dir
+        self._ambient_light = _as_rgba(ambient_light)
+        self._diffuse_light = _as_rgba(diffuse_light)
+        self._specular_light = _as_rgba(specular_light)
+
+        self._enabled = enabled
+
+        vfunc = Function(self._shaders['vertex'])
+        ffunc = Function(self._shaders['fragment'])
+
+        self._normals = VertexBuffer(np.zeros((0, 3), dtype=np.float32))
+        self._normals_cache = None
+        vfunc['normal'] = self._normals
+
+        super().__init__(vcode=vfunc, fcode=ffunc)
+
+    @property
+    def enabled(self):
+        """True to enable the filter, False to disable."""
+        return self._enabled
+
+    @enabled.setter
+    def enabled(self, enabled):
+        self._enabled = enabled
+        self._update_data()
+
+    @property
+    def shading(self):
+        """The shading method."""
+        return self._shading
+
+    @shading.setter
+    def shading(self, shading):
+        assert shading in (None, 'flat', 'smooth')
+        self._shading = shading
+        self._update_data()
+
+    @property
+    def light_dir(self):
+        """The light direction."""
+        return self._light_dir
+
+    @light_dir.setter
+    def light_dir(self, direction):
+        direction = np.array(direction, float).ravel()
+        if direction.size != 3 or not np.isfinite(direction).all():
+            raise ValueError('Invalid direction %s' % direction)
+        self._light_dir = tuple(direction)
+        self._update_data()
+
+    @property
+    def ambient_light(self):
+        """The color and intensity of the ambient light."""
+        return self._ambient_light
+
+    @ambient_light.setter
+    def ambient_light(self, light_color):
+        self._ambient_light = _as_rgba(light_color)
+        self._update_data()
+
+    @property
+    def diffuse_light(self):
+        """The color and intensity of the diffuse light."""
+        return self._diffuse_light
+
+    @diffuse_light.setter
+    def diffuse_light(self, light_color):
+        self._diffuse_light = _as_rgba(light_color)
+        self._update_data()
+
+    @property
+    def specular_light(self):
+        """The color and intensity of the specular light."""
+        return self._specular_light
+
+    @specular_light.setter
+    def specular_light(self, light_color):
+        self._specular_light = _as_rgba(light_color)
+        self._update_data()
+
+    @property
+    def ambient_coefficient(self):
+        """The ambient reflection coefficient."""
+        return self._ambient_coefficient
+
+    @ambient_coefficient.setter
+    def ambient_coefficient(self, color):
+        self._ambient_coefficient = _as_rgba(color)
+        self._update_data()
+
+    @property
+    def diffuse_coefficient(self):
+        """The diffuse reflection coefficient."""
+        return self._diffuse_coefficient
+
+    @diffuse_coefficient.setter
+    def diffuse_coefficient(self, diffuse_coefficient):
+        self._diffuse_coefficient = _as_rgba(diffuse_coefficient)
+        self._update_data()
+
+    @property
+    def specular_coefficient(self):
+        """The specular reflection coefficient."""
+        return self._specular_coefficient
+
+    @specular_coefficient.setter
+    def specular_coefficient(self, specular_coefficient):
+        self._specular_coefficient = _as_rgba(specular_coefficient)
+        self._update_data()
+
+    @property
+    def shininess(self):
+        """The shininess controlling the spread of the specular highlight."""
+        return self._shininess
+
+    @shininess.setter
+    def shininess(self, shininess):
+        self._shininess = float(shininess)
+        self._update_data()
+
+    def _update_data(self):
+        if not self._attached:
+            return
+
+        self.vshader['light_dir'] = self._light_dir
+
+        self.fshader['ambient_light'] = self._ambient_light.rgba
+        self.fshader['diffuse_light'] = self._diffuse_light.rgba
+        self.fshader['specular_light'] = self._specular_light.rgba
+
+        self.fshader['ambient_coefficient'] = self._ambient_coefficient.rgba
+        self.fshader['diffuse_coefficient'] = self._diffuse_coefficient.rgba
+        self.fshader['specular_coefficient'] = self._specular_coefficient.rgba
+        self.fshader['shininess'] = self._shininess
+
+        self.fshader['flat_shading'] = 1 if self._shading == 'flat' else 0
+        self.fshader['shading_enabled'] = (
+            1 if self._enabled and self._shading is not None else 0
+        )
+
+        normals = self._visual.mesh_data.get_vertex_normals(indexed='faces')
+        if normals is not self._normals_cache:
+            # limit how often we upload new normal arrays
+            # gotcha: if normals are changed in place then this won't invalidate this cache
+            self._normals_cache = normals
+            self._normals.set_data(self._normals_cache, convert=True)
+
+    def on_mesh_data_updated(self, event):
+        self._update_data()
+
+    def _attach(self, visual):
+        super()._attach(visual)
+
+        render2scene = visual.transforms.get_transform('render', 'scene')
+        visual2scene = visual.transforms.get_transform('visual', 'scene')
+        scene2doc = visual.transforms.get_transform('scene', 'document')
+        doc2scene = visual.transforms.get_transform('document', 'scene')
+        self.vshader['render2scene'] = render2scene
+        self.vshader['visual2scene'] = visual2scene
+        self.vshader['scene2doc'] = scene2doc
+        self.vshader['doc2scene'] = doc2scene
+
+        if self._visual.mesh_data is not None:
+            self._update_data()
+
+        visual.events.data_updated.connect(self.on_mesh_data_updated)
+
+    def _detach(self, visual):
+        visual.events.data_updated.disconnect(self.on_mesh_data_updated)
+        super()._detach(visual)
+
+
+instanced_shading_vertex_template = shading_vertex_template.replace(
+    "$normal",
+    "mat3($instance_transform_x, $instance_transform_y, $instance_transform_z) * $normal"
+)
+
+
+class InstancedShadingFilter(ShadingFilter):
+    """Shading filter modified for use with :class:`~vispy.visuals.InstancedMeshVisual`.
+
+    See :class:`ShadingFilter` for details and usage.
+    """
+    _shaders = {
+        'vertex': instanced_shading_vertex_template,
+        'fragment': ShadingFilter._shaders['fragment'],
+    }
+
+    def _attach(self, visual):
+        super()._attach(visual)
+        self.vshader['instance_transform_x'] = visual._instance_transforms_vbos[0]
+        self.vshader['instance_transform_y'] = visual._instance_transforms_vbos[1]
+        self.vshader['instance_transform_z'] = visual._instance_transforms_vbos[2]
+
+
+wireframe_vertex_template = """
+varying vec3 v_bc;
+
+void prepare_wireframe() {
+    v_bc = $bc;
+}
+"""  # noqa
+
+
+wireframe_fragment_template = """
+varying vec3 v_bc;
+
+void draw_wireframe() {
+    if ($enabled != 1) {
+        return;
+    }
+
+    vec3 d = fwidth(v_bc);  // relative distance to edge
+    vec3 fading3 = smoothstep(vec3(0.0), $width * d, v_bc);
+    float opacity = 1.0 - min(min(fading3.x, fading3.y), fading3.z);
+
+    if ($wireframe_only == 1) {
+        if (opacity == 0.0) {
+            // Inside a triangle.
+            discard;
+        }
+        // On the edge.
+        gl_FragColor = $color;
+        gl_FragColor.a = opacity;
+    } else if ($faces_only == 1) {
+        if (opacity == 1.0) {
+            // Inside an edge.
+            discard;
+        }
+        // Inside a triangle.
+        gl_FragColor.a = 1.0 - opacity;
+    } else {
+        gl_FragColor = mix(gl_FragColor, $color, opacity);
+    }
+
+}
+"""  # noqa
+
+
+class WireframeFilter(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
+    <https://github.com/vispy/vispy/blob/main/examples/basics/scene/mesh_shading.py>`_
+    example script.
+
+    """
+
+    def __init__(self, enabled=True, color='black', width=1.0,
+                 wireframe_only=False, faces_only=False):
+        self._attached = False
+        self._color = Color(color)
+        self._width = width
+        self._enabled = enabled
+        self._wireframe_only = wireframe_only
+        self._faces_only = faces_only
+
+        vfunc = Function(wireframe_vertex_template)
+        ffunc = Function(wireframe_fragment_template)
+
+        self._bc = VertexBuffer(np.zeros((0, 3), dtype=np.float32))
+        vfunc['bc'] = self._bc
+
+        super().__init__(vcode=vfunc, fcode=ffunc)
+        self.enabled = enabled
+
+    @property
+    def enabled(self):
+        """True to enable the display of the wireframe, False to disable."""
+        return self._enabled
+
+    @enabled.setter
+    def enabled(self, enabled):
+        self._enabled = enabled
+        self.fshader['enabled'] = 1 if enabled else 0
+        self._update_data()
+
+    @property
+    def color(self):
+        """The wireframe color."""
+        return self._color
+
+    @color.setter
+    def color(self, color):
+        self._color = Color(color)
+        self._update_data()
+
+    @property
+    def width(self):
+        """The wireframe width."""
+        return self._width
+
+    @width.setter
+    def width(self, width):
+        if width < 0:
+            raise ValueError("width must be greater than zero")
+        self._width = width
+        self._update_data()
+
+    @property
+    def wireframe_only(self):
+        """Draw only the wireframe and discard the interior of the faces."""
+        return self._wireframe_only
+
+    @wireframe_only.setter
+    def wireframe_only(self, wireframe_only):
+        self._wireframe_only = wireframe_only
+        self._update_data()
+
+    @property
+    def faces_only(self):
+        """Make the wireframe transparent.
+
+        Draw only the interior of the faces.
+        """
+        return self._faces_only
+
+    @faces_only.setter
+    def faces_only(self, faces_only):
+        self._faces_only = faces_only
+        self._update_data()
+
+    def _update_data(self):
+        if not self.attached:
+            return
+        self.fshader['color'] = self._color.rgba
+        self.fshader['width'] = self._width
+        self.fshader['wireframe_only'] = 1 if self._wireframe_only else 0
+        self.fshader['faces_only'] = 1 if self._faces_only else 0
+        if self._visual.mesh_data.is_empty():
+            n_faces = 0
+        else:
+            n_faces = len(self._visual.mesh_data.get_faces())
+        bc = np.array([[1, 0, 0], [0, 1, 0], [0, 0, 1]], dtype='float')
+        bc = np.tile(bc[None, ...], (n_faces, 1, 1))
+        self._bc.set_data(bc, convert=True)
+
+    def on_data_updated(self, event):
+        self._update_data()
+
+    def _attach(self, visual):
+        super()._attach(visual)
+        visual.events.data_updated.connect(self.on_data_updated)
+
+    def _detach(self, visual):
+        visual.events.data_updated.disconnect(self.on_data_updated)
+        super()._detach(visual)
+
+
+class FacePickingFilter(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
+    --------
+    :ref:`sphx_glr_gallery_scene_face_picking.py`
+    """
+
+    def _get_picking_ids(self):
+        if self._visual.mesh_data.is_empty():
+            n_faces = 0
+        else:
+            n_faces = len(self._visual.mesh_data.get_faces())
+
+        # we only care about the number of faces changing
+        if self._n_primitives == n_faces:
+            return None
+        self._n_primitives = n_faces
+
+        ids = np.arange(1, n_faces + 1, dtype=np.uint32)
+        ids = np.repeat(ids, 3, axis=0)  # repeat id for each vertex
+        return ids