Skip to main content
`Ctrl`+`K`

# vispy.geometry package

## Subpackages

- vispy.geometry.tests package
  - Submodules
    - vispy.geometry.tests.test_calculations module
    - vispy.geometry.tests.test_generation module
    - vispy.geometry.tests.test_meshdata module
    - vispy.geometry.tests.test_triangulation module
  - Module contents

## Submodules

- vispy.geometry.calculations module
  - `resize()`
- vispy.geometry.curves module
  - `calc_sq_distance()`
  - `curve3_bezier()`
  - `curve4_bezier()`
- vispy.geometry.generation module
  - `create_arrow()`
  - `create_box()`
  - `create_cone()`
  - `create_cube()`
  - `create_cylinder()`
  - `create_grid_mesh()`
  - `create_plane()`
  - `create_sphere()`
- vispy.geometry.isocurve module
  - `isocurve()`
- vispy.geometry.isosurface module
  - `isosurface()`
- vispy.geometry.meshdata module
  - `MeshData`
    - `MeshData.get_bounds()`
    - `MeshData.get_edge_colors()`
    - `MeshData.get_edges()`
    - `MeshData.get_face_colors()`
    - `MeshData.get_face_normals()`
    - `MeshData.get_faces()`
    - `MeshData.get_vertex_colors()`
    - `MeshData.get_vertex_faces()`
    - `MeshData.get_vertex_normals()`
    - `MeshData.get_vertex_values()`
    - `MeshData.get_vertices()`
    - `MeshData.has_edge_indexed_data()`
    - `MeshData.has_face_color()`
    - `MeshData.has_face_indexed_data()`
    - `MeshData.has_vertex_color()`
    - `MeshData.has_vertex_value()`
    - `MeshData.is_empty()`
    - `MeshData.n_faces`
    - `MeshData.n_vertices`
    - `MeshData.reset_normals()`
    - `MeshData.restore()`
    - `MeshData.save()`
    - `MeshData.set_face_colors()`
    - `MeshData.set_faces()`
    - `MeshData.set_vertex_colors()`
    - `MeshData.set_vertex_values()`
    - `MeshData.set_vertices()`
- vispy.geometry.normals module
  - `compact()`
  - `normals()`
- vispy.geometry.parametric module
  - `surface()`
- vispy.geometry.polygon module
  - `PolygonData`
    - `PolygonData.add_vertex()`
    - `PolygonData.convex_hull`
    - `PolygonData.edges`
    - `PolygonData.faces`
    - `PolygonData.triangulate()`
    - `PolygonData.vertices`
- vispy.geometry.rect module
  - `Rect`
    - `Rect.bottom`
    - `Rect.center`
    - `Rect.contains()`
    - `Rect.flipped()`
    - `Rect.height`
    - `Rect.left`
    - `Rect.normalized()`
    - `Rect.padded()`
    - `Rect.pos`
    - `Rect.right`
    - `Rect.size`
    - `Rect.top`
    - `Rect.width`
- vispy.geometry.torusknot module
  - `TorusKnot`
    - `TorusKnot.components`
    - `TorusKnot.first_component`
    - `TorusKnot.major_radius`
    - `TorusKnot.minor_radius`
    - `TorusKnot.num_components`
    - `TorusKnot.num_points`
    - `TorusKnot.p`
    - `TorusKnot.q`
- vispy.geometry.triangulation module
  - `Triangulation`
    - `Triangulation.triangulate()`
  - `triangulate()`

## Module contents

This module implements classes and methods for handling geometric data.

class vispy.geometry.MeshData(vertices=None, faces=None, edges=None, vertex_colors=None, face_colors=None, vertex_values=None)

  Bases: `object`

  Class for storing and operating on 3D mesh data.

  Parameters:
    vertices ndarray, shape (Nv, 3)

      Vertex coordinates. If faces is not specified, then this will instead be interpreted as (Nf, 3, 3) array of coordinates.

    faces ndarray, shape (Nf, 3)

      Indices into the vertex array.

    edges None

      [not available yet]

    vertex_colors ndarray, shape (Nv, 4)

      Vertex colors. If faces is not specified, this will be interpreted as (Nf, 3, 4) array of colors.

    face_colors ndarray, shape (Nf, 4)

      Face colors.

    vertex_values ndarray, shape (Nv,)

      Vertex values.

  Notes

  All arguments are optional.

  The object may contain:

  - list of vertex locations

  - list of edges

  - list of triangles

  - colors per vertex, edge, or tri

  - normals per vertex or tri

  This class handles conversion between the standard [list of vertices, list of faces] format (suitable for use with glDrawElements) and ‘indexed’ [list of vertices] format (suitable for use with glDrawArrays). It will automatically compute face normal vectors as well as averaged vertex normal vectors.

  The class attempts to be as efficient as possible in caching conversion results and avoiding unnecessary conversions.

  get_bounds()

    Get the mesh bounds

    Returns:
      bounds list

        A list of tuples of mesh bounds.

  get_edge_colors()
  get_edges(indexed=None)

    Edges of the mesh

    Parameters:
      indexed str | None

        If indexed is None, return (Nf, 3) array of vertex indices, two per edge in the mesh. If indexed is ‘faces’, then return (Nf, 3, 2) array of vertex indices with 3 edges per face, and two vertices per edge.

    Returns:
      edges ndarray

        The edges.

  get_face_colors(indexed=None)

    Get the face colors

    Parameters:
      indexed str | None

        If indexed is None, return (Nf, 4) array of face colors. If indexed==’faces’, then instead return an indexed array (Nf, 3, 4) (note this is just the same array with each color repeated three times).

    Returns:
      colors ndarray

        The colors.

  get_face_normals(indexed=None)

    Get face normals

    Parameters:
      indexed str | None

        If None, return an array (Nf, 3) of normal vectors for each face. If ‘faces’, then instead return an indexed array (Nf, 3, 3) (this is just the same array with each vector copied three times).

    Returns:
      normals ndarray

        The normals.

  get_faces()

    Array (Nf, 3) of vertex indices, three per triangular face.

    If faces have not been computed for this mesh, returns None.

  get_vertex_colors(indexed=None)

    Get vertex colors

    Parameters:
      indexed str | None

        If None, return an array (Nv, 4) of vertex colors. If indexed==’faces’, then instead return an indexed array (Nf, 3, 4).

    Returns:
      colors ndarray

        The vertex colors.

  get_vertex_faces()

    List mapping each vertex index to a list of face indices that use it.

  get_vertex_normals(indexed=None)

    Get vertex normals

    Parameters:
      indexed str | None

        If None, return an (N, 3) array of normal vectors with one entry per unique vertex in the mesh. If indexed is ‘faces’, then the array will contain three normal vectors per face (and some vertices may be repeated).

    Returns:
      normals ndarray

        The normals.

  get_vertex_values(indexed=None)

    Get vertex colors

    Parameters:
      indexed str | None

        If None, return an array (Nv,) of vertex values. If indexed==’faces’, then instead return an indexed array (Nf, 3).

    Returns:
      values ndarray

        The vertex values.

  get_vertices(indexed=None)

    Get the vertices

    Parameters:
      indexed str | None

        If Note, return an array (N,3) of the positions of vertices in the mesh. By default, each unique vertex appears only once. If indexed is ‘faces’, then the array will instead contain three vertices per face in the mesh (and a single vertex may appear more than once in the array).

    Returns:
      vertices ndarray

        The vertices.

  has_edge_indexed_data()
  has_face_color()

    Return True if this data set has face color information

  has_face_indexed_data()

    Return True if this object already has vertex positions indexed by face

  has_vertex_color()

    Return True if this data set has vertex color information

  has_vertex_value()

    Return True if this data set has vertex value information

  is_empty()

    Check if any vertices or faces are defined.

  property n_faces

    The number of faces in the mesh

  property n_vertices

    The number of vertices in the mesh

  reset_normals()
  restore(state)

    Restore the state of a mesh previously saved using save()

    Parameters:
      state dict

        The previous state.

  save()

    Serialize this mesh to a string appropriate for disk storage

    Returns:
      state dict

        The state.

  set_face_colors(colors, indexed=None)

    Set the face color array

    Parameters:
      colors array

        Array of colors. Must have shape (Nf, 4) (indexed by face), or shape (Nf, 3, 4) (face colors indexed by faces).

      indexed str | None

        Should be ‘faces’ if colors are indexed by faces.

  set_faces(faces)

    Set the faces

    Parameters:
      faces ndarray

        (Nf, 3) array of faces. Each row in the array contains three indices into the vertex array, specifying the three corners of a triangular face.

  set_vertex_colors(colors, indexed=None)

    Set the vertex color array

    Parameters:
      colors array

        Array of colors. Must have shape (Nv, 4) (indexing by vertex) or shape (Nf, 3, 4) (vertices indexed by face).

      indexed str | None

        Should be ‘faces’ if colors are indexed by faces.

  set_vertex_values(values, indexed=None)

    Set the vertex value array

    Parameters:
      values array

        Array of values. Must have shape (Nv,) (indexing by vertex) or shape (Nf, 3) (vertices indexed by face).

      indexed str | None

        Should be ‘faces’ if colors are indexed by faces.

  set_vertices(verts=None, indexed=None, reset_normals=True)

    Set the mesh vertices

    Parameters:
      verts ndarray | None

        The array (Nv, 3) of vertex coordinates.

      indexed str | None

        If indexed==’faces’, then the data must have shape (Nf, 3, 3) and is assumed to be already indexed as a list of faces. This will cause any pre-existing normal vectors to be cleared unless reset_normals=False.

      reset_normals bool

        If True, reset the normals.

class vispy.geometry.PolygonData(vertices=None, edges=None, faces=None)

  Bases: `object`

  Polygon class for data handling

  Parameters:
    vertices(Nv, 3) array

      Vertex coordinates. If faces is not specified, then this will instead be interpreted as (Nf, 3, 3) array of coordinates.

    edges(Nv, 2) array

      Constraining edges specified by vertex indices.

    faces(Nf, 3) array

      Indexes into the vertex array.

  Notes

  All arguments are optional.

  add_vertex(vertex)

    Adds given vertex and retriangulates to generate new faces.

    Parameters:
      vertex array-like

        The vertex to add.

  property convex_hull

    Return an array of vertex indexes representing the convex hull.

    If faces have not been computed for this mesh, the function computes them. If no vertices or faces are specified, the function returns None.

  property edges

    Return an array (Nv, 2) of vertex indices.

    If no vertices or faces are specified, the function returns None.

  property faces

    Return an array (Nf, 3) of vertex indexes, three per triangular face in the mesh.

    If faces have not been computed for this mesh, the function computes them. If no vertices or faces are specified, the function returns None.

  triangulate()

    Triangulates the set of vertices and stores the triangles in faces and the convex hull in convex_hull.

  property vertices

    Return an array (Nf, 3) of vertices.

    If only faces exist, the function computes the vertices and returns them. If no vertices or faces are specified, the function returns None.

class vispy.geometry.Rect(*args, **kwargs)

  Bases: `object`

  Representation of a rectangular area in a 2D coordinate system.

  Parameters:
    *args arguments

      Can be in the form Rect(x, y, w, h), Rect(pos, size), or Rect(Rect).

  property bottom
  property center
  contains(x, y)

    Query if the rectangle contains points

    Parameters:
      x float

        X coordinate.

      y float

        Y coordinate.

    Returns:
      contains bool

        True if the point is within the rectangle.

  flipped(x=False, y=True)

    Return a Rect with the same bounds but with axes inverted

    Parameters:
      x bool

        Flip the X axis.

      y bool

        Flip the Y axis.

    Returns:
      rect instance of Rect

        The flipped rectangle.

  property height
  property left
  normalized()

    Return a Rect covering the same area, but with height and width guaranteed to be positive.

  padded(padding)

    Return a new Rect padded (smaller) by padding on all sides

    Parameters:
      padding float

        The padding.

    Returns:
      rect instance of Rect

        The padded rectangle.

  property pos
  property right
  property size
  property top
  property width

class vispy.geometry.Triangulation(pts, edges)

  Bases: `object`

  Constrained delaunay triangulation

  Implementation based on [1].

  Parameters:
    pts array

      Nx2 array of points.

    edges array

      Nx2 array of edges (dtype=int).

  Notes

  - Delaunay legalization is not yet implemented. This produces a proper triangulation, but adding legalisation would produce fewer thin triangles.

  - The pts and edges arrays may be modified.

  References

  [1]

  Domiter, V. and Žalik, B. Sweep‐line algorithm for constrained Delaunay triangulation

  triangulate()

    Do the triangulation.

vispy.geometry.create_arrow(rows, cols, radius=0.1, length=1.0, cone_radius=None, cone_length=None)

  Create a 3D arrow using a cylinder plus cone

  Parameters:
    rows int

      Number of rows.

    cols int

      Number of columns.

    radius float

      Base cylinder radius.

    length float

      Length of the arrow.

    cone_radius float
      Radius of the cone base.

        If None, then this defaults to 2x the cylinder radius.

    cone_length float
      Length of the cone.

        If None, then this defaults to 1/3 of the arrow length.

  Returns:
    arrow MeshData

      Vertices and faces computed for a cone surface.

vispy.geometry.create_box(width=1, height=1, depth=1, width_segments=1, height_segments=1, depth_segments=1, planes=None)

  Generate vertices & indices for a filled and outlined box.

  Parameters:
    width float

      Box width.

    height float

      Box height.

    depth float

      Box depth.

    width_segments int

      Box segments count along the width.

    height_segments float

      Box segments count along the height.

    depth_segments float

      Box segments count along the depth.

    planes: array_like

      Any combination of `{'-x', '+x', '-y', '+y', '-z', '+z'}` Included planes in the box construction.

  Returns:
    vertices array

      Array of vertices suitable for use as a VertexBuffer.

    faces array

      Indices to use to produce a filled box.

    outline array

      Indices to use to produce an outline of the box.

vispy.geometry.create_cone(cols, radius=1.0, length=1.0)

  Create a cone

  Parameters:
    cols int

      Number of faces.

    radius float

      Base cone radius.

    length float

      Length of the cone.

  Returns:
    cone MeshData

      Vertices and faces computed for a cone surface.

vispy.geometry.create_cube()

  Generate vertices & indices for a filled and outlined cube

  Returns:
    vertices array

      Array of vertices suitable for use as a VertexBuffer.

    filled array

      Indices to use to produce a filled cube.

    outline array

      Indices to use to produce an outline of the cube.

vispy.geometry.create_cylinder(rows, cols, radius=[1.0, 1.0], length=1.0, offset=False)

  Create a cylinder

  Parameters:
    rows int

      Number of rows.

    cols int

      Number of columns.

    radius tuple of float

      Cylinder radii.

    length float

      Length of the cylinder.

    offset bool

      Rotate each row by half a column.

  Returns:
    cylinder MeshData

      Vertices and faces computed for a cylindrical surface.

vispy.geometry.create_grid_mesh(xs, ys, zs)

  Generate vertices and indices for an implicitly connected mesh.

  The intention is that this makes it simple to generate a mesh from meshgrid data.

  Parameters:
    xs ndarray

      A 2d array of x coordinates for the vertices of the mesh. Must have the same dimensions as ys and zs.

    ys ndarray

      A 2d array of y coordinates for the vertices of the mesh. Must have the same dimensions as xs and zs.

    zs ndarray

      A 2d array of z coordinates for the vertices of the mesh. Must have the same dimensions as xs and ys.

  Returns:
    vertices ndarray

      The array of vertices in the mesh.

    indices ndarray

      The array of indices for the mesh.

vispy.geometry.create_plane(width=1, height=1, width_segments=1, height_segments=1, direction='+z')

  Generate vertices & indices for a filled and outlined plane.

  Parameters:
    width float

      Plane width.

    height float

      Plane height.

    width_segments int

      Plane segments count along the width.

    height_segments float

      Plane segments count along the height.

    direction: unicode

      `{'-x', '+x', '-y', '+y', '-z', '+z'}` Direction the plane will be facing.

  Returns:
    vertices array

      Array of vertices suitable for use as a VertexBuffer.

    faces array

      Indices to use to produce a filled plane.

    outline array

      Indices to use to produce an outline of the plane.

  References

  [1]

  Cabello, R. (n.d.). PlaneBufferGeometry.js. Retrieved May 12, 2015, from http://git.io/vU1Fh

vispy.geometry.create_sphere(rows=10, cols=10, depth=10, radius=1.0, offset=True, subdivisions=3, method='latitude')

  Create a sphere

  Parameters:
    rows int

      Number of rows (for method=’latitude’ and ‘cube’).

    cols int

      Number of columns (for method=’latitude’ and ‘cube’).

    depth int

      Number of depth segments (for method=’cube’).

    radius float

      Sphere radius.

    offset bool

      Rotate each row by half a column (for method=’latitude’).

    subdivisions int

      Number of subdivisions to perform (for method=’ico’)

    method str

      Method for generating sphere. Accepts ‘latitude’ for latitude- longitude, ‘ico’ for icosahedron, and ‘cube’ for cube based tessellation.

  Returns:
    sphere MeshData

      Vertices and faces computed for a spherical surface.

vispy.geometry.resize(image, shape, kind='linear')

  Resize an image

  Parameters:
    image ndarray

      Array of shape (N, M, …).

    shape tuple

      2-element shape.

    kind str

      Interpolation, either “linear” or “nearest”.

  Returns:
    scaled_image ndarray

      New image, will have dtype np.float64.

vispy.geometry.triangulate(vertices)

  Triangulate a set of vertices.

  This uses a pure Python implementation based on [1].

  If Triangle by Jonathan R. Shewchuk [2] and the Python bindings triangle [3] are installed, this will be used instead. Users need to acknowledge and adhere to the licensing terms of these packages.

  In the VisPy PolygonCollection Example [4] a speedup of 97% using Triangle/triangle can be achieved compared to the pure Python implementation.

  Parameters:
    vertices array-like

      The vertices.

  Returns:
    vertices array-like

      The vertices.

    triangles array-like

      The triangles.

  References

  [1]

  Domiter, V. and Žalik, B. Sweep‐line algorithm for constrained Delaunay triangulation

  [2]

  Shewchuk J.R. (1996) Triangle: Engineering a 2D quality mesh generator and Delaunay triangulator. In: Lin M.C., Manocha D. (eds) Applied Computational Geometry Towards Geometric Engineering. WACG 1996. Lecture Notes in Computer Science, vol 1148. Springer, Berlin, Heidelberg. https://doi.org/10.1007/BFb0014497

  [3]

  https://rufat.be/triangle/

  [4]

  vispy/vispy