vispy.geometry package#

Subpackages#

Submodules#

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:
verticesndarray, shape (Nv, 3)

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

facesndarray, shape (Nf, 3)

Indices into the vertex array.

edgesNone

[not available yet]

vertex_colorsndarray, shape (Nv, 4)

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

face_colorsndarray, shape (Nf, 4)

Face colors.

vertex_valuesndarray, 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:
boundslist

A list of tuples of mesh bounds.

get_edge_colors()#
get_edges(indexed=None)#

Edges of the mesh

Parameters:
indexedstr | 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:
edgesndarray

The edges.

get_face_colors(indexed=None)#

Get the face colors

Parameters:
indexedstr | 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:
colorsndarray

The colors.

get_face_normals(indexed=None)#

Get face normals

Parameters:
indexedstr | 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:
normalsndarray

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:
indexedstr | None

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

Returns:
colorsndarray

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:
indexedstr | 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:
normalsndarray

The normals.

get_vertex_values(indexed=None)#

Get vertex colors

Parameters:
indexedstr | None

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

Returns:
valuesndarray

The vertex values.

get_vertices(indexed=None)#

Get the vertices

Parameters:
indexedstr | 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:
verticesndarray

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:
statedict

The previous state.

save()#

Serialize this mesh to a string appropriate for disk storage

Returns:
statedict

The state.

set_face_colors(colors, indexed=None)#

Set the face color array

Parameters:
colorsarray

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

indexedstr | None

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

set_faces(faces)#

Set the faces

Parameters:
facesndarray

(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:
colorsarray

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

indexedstr | None

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

set_vertex_values(values, indexed=None)#

Set the vertex value array

Parameters:
valuesarray

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

indexedstr | None

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

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

Set the mesh vertices

Parameters:
vertsndarray | None

The array (Nv, 3) of vertex coordinates.

indexedstr | 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_normalsbool

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:
vertexarray-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:
*argsarguments

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:
xfloat

X coordinate.

yfloat

Y coordinate.

Returns:
containsbool

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:
xbool

Flip the X axis.

ybool

Flip the Y axis.

Returns:
rectinstance 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:
paddingfloat

The padding.

Returns:
rectinstance 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:
ptsarray

Nx2 array of points.

edgesarray

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:
rowsint

Number of rows.

colsint

Number of columns.

radiusfloat

Base cylinder radius.

lengthfloat

Length of the arrow.

cone_radiusfloat
Radius of the cone base.

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

cone_lengthfloat
Length of the cone.

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

Returns:
arrowMeshData

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:
widthfloat

Box width.

heightfloat

Box height.

depthfloat

Box depth.

width_segmentsint

Box segments count along the width.

height_segmentsfloat

Box segments count along the height.

depth_segmentsfloat

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:
verticesarray

Array of vertices suitable for use as a VertexBuffer.

facesarray

Indices to use to produce a filled box.

outlinearray

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:
colsint

Number of faces.

radiusfloat

Base cone radius.

lengthfloat

Length of the cone.

Returns:
coneMeshData

Vertices and faces computed for a cone surface.

vispy.geometry.create_cube()#

Generate vertices & indices for a filled and outlined cube

Returns:
verticesarray

Array of vertices suitable for use as a VertexBuffer.

filledarray

Indices to use to produce a filled cube.

outlinearray

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:
rowsint

Number of rows.

colsint

Number of columns.

radiustuple of float

Cylinder radii.

lengthfloat

Length of the cylinder.

offsetbool

Rotate each row by half a column.

Returns:
cylinderMeshData

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:
xsndarray

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

ysndarray

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

zsndarray

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

Returns:
verticesndarray

The array of vertices in the mesh.

indicesndarray

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:
widthfloat

Plane width.

heightfloat

Plane height.

width_segmentsint

Plane segments count along the width.

height_segmentsfloat

Plane segments count along the height.

direction: unicode

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

Returns:
verticesarray

Array of vertices suitable for use as a VertexBuffer.

facesarray

Indices to use to produce a filled plane.

outlinearray

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:
rowsint

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

colsint

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

depthint

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

radiusfloat

Sphere radius.

offsetbool

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

subdivisionsint

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

methodstr

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

Returns:
sphereMeshData

Vertices and faces computed for a spherical surface.

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

Resize an image

Parameters:
imagendarray

Array of shape (N, M, …).

shapetuple

2-element shape.

kindstr

Interpolation, either “linear” or “nearest”.

Returns:
scaled_imagendarray

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:
verticesarray-like

The vertices.

Returns:
verticesarray-like

The vertices.

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