# The geometry module

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)

  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_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_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

  property `n_faces`

    The number of faces in the mesh

  property `n_vertices`

    The number of vertices in the mesh

  `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)

  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)

  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).

  `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.

  `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.

class `vispy.geometry.``Triangulation`(pts, edges)

  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

  Parameters:

  vertices array-like

    The vertices.

  Returns:

  vertices array-like

    The vertices.

  tringles array-like

    The triangles.