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)

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.

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.

Methods

get_bounds() Get the mesh bounds
get_edge_colors()
get_edges([indexed]) Edges of the mesh
get_face_colors([indexed]) Get the face colors
get_face_normals([indexed]) Get face normals
get_faces() Array (Nf, 3) of vertex indices, three per triangular face.
get_vertex_colors([indexed]) Get vertex colors
get_vertex_faces() List mapping each vertex index to a list of face indices that use it.
get_vertex_normals([indexed]) Get vertex normals
get_vertices([indexed]) Get 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
has_vertex_color() Return True if this data set has vertex color information
reset_normals()
restore(state) Restore the state of a mesh previously saved using save()
save() Serialize this mesh to a string appropriate for disk storage
set_face_colors(colors[, indexed]) Set the face color array
set_faces(faces) Set the faces
set_vertex_colors(colors[, indexed]) Set the vertex color array
set_vertices([verts, indexed, reset_normals]) Set the mesh vertices
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_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

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

Methods

add_vertex(vertex) Adds given vertex and retriangulates to generate new faces.
triangulate() Triangulates the set of vertices and stores the triangles in faces and the convex hull in convex_hull.
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).

Methods

contains(x, y) Query if the rectangle contains points
flipped([x, y]) Return a Rect with the same bounds but with axes inverted
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
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

Methods

triangulate() Do the 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_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, cols, radius=1.0, offset=True)

Create a sphere

Parameters:

rows : int

Number of rows.

cols : int

Number of columns.

radius : float

Sphere radius.

offset : bool

Rotate each row by half a column.

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.