# 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

  `n_faces`

    The number of faces in the mesh

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

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

  `edges`

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

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

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

  `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 [R1].

  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

  [R1] | (1, 2) Domiter, V. and Žalik, B. Sweep‐line algorithm for constrained Delaunay triangulation

  `triangulate`()

    Do the triangulation.

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

`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

  [R2] | 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.