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

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

Parameters
verticesarray-like

The vertices.

Returns
verticesarray-like

The vertices.

tringlesarray-like

The triangles.