primitive

Module dedicated for basic primitive.

ConvexHull(points[, incremental, qhull_options])

Convex hulls in N dimensions.

LooseVersion([vstring])

Version numbering for anarchists and software realists.

cart2sphere(x, y, z)

Return angles for Cartesian 3D coordinates x, y, and z.

faces_from_sphere_vertices(vertices)

Triangulate a set of vertices on the sphere.

fix_winding_order(vertices, triangles[, …])

Return corrected triangles.

pjoin(a, *p)

Join two or more pathname components, inserting ‘/’ as needed.

prim_box()

Return vertices and triangle for a box geometry.

prim_frustum()

Return vertices and triangle for a square frustum prism.

prim_icosahedron()

Return vertices and triangles for icosahedron.

prim_octagonalprism()

Return vertices and triangle for an octagonal prism.

prim_rhombicuboctahedron()

Return vertices and triangle for rhombicuboctahedron geometry.

prim_sphere([name, gen_faces])

Provide vertices and triangles of the spheres.

prim_square()

Return vertices and triangles for a square geometry.

prim_star([dim])

Return vertices and triangle for star geometry.

prim_superquadric([roundness, sphere_name])

Provide vertices and triangles of a superquadrics.

prim_tetrahedron()

Return vertices and triangles for a tetrahedron.

repeat_primitive(vertices, faces, centers[, …])

Repeat Vertices and triangles of a specific primitive shape.

repeat_primitive_function(func, centers[, …])

Repeat Vertices and triangles of a specific primitive function.

ConvexHull

class fury.primitive.ConvexHull(points, incremental=False, qhull_options=None)

Bases: scipy.spatial.qhull._QhullUser

Convex hulls in N dimensions.

New in version 0.12.0.

Parameters
  • points (ndarray of floats, shape (npoints, ndim)) – Coordinates of points to construct a convex hull from

  • incremental (bool, optional) – Allow adding new points incrementally. This takes up some additional resources.

  • qhull_options (str, optional) – Additional options to pass to Qhull. See Qhull manual for details. (Default: “Qx” for ndim > 4 and “” otherwise) Option “Qt” is always enabled.

points

Coordinates of input points.

Type

ndarray of double, shape (npoints, ndim)

vertices

Indices of points forming the vertices of the convex hull. For 2-D convex hulls, the vertices are in counterclockwise order. For other dimensions, they are in input order.

Type

ndarray of ints, shape (nvertices,)

simplices

Indices of points forming the simplical facets of the convex hull.

Type

ndarray of ints, shape (nfacet, ndim)

neighbors

Indices of neighbor facets for each facet. The kth neighbor is opposite to the kth vertex. -1 denotes no neighbor.

Type

ndarray of ints, shape (nfacet, ndim)

equations

[normal, offset] forming the hyperplane equation of the facet (see Qhull documentation for more).

Type

ndarray of double, shape (nfacet, ndim+1)

coplanar

Indices of coplanar points and the corresponding indices of the nearest facets and nearest vertex indices. Coplanar points are input points which were not included in the triangulation due to numerical precision issues.

If option “Qc” is not specified, this list is not computed.

Type

ndarray of int, shape (ncoplanar, 3)

good

A one-dimensional Boolean array indicating which facets are good. Used with options that compute good facets, e.g. QGn and QG-n. Good facets are defined as those that are visible (n) or invisible (-n) from point n, where n is the nth point in ‘points’. The ‘good’ attribute may be used as an index into ‘simplices’ to return the good (visible) facets: simplices[good]. A facet is visible from the outside of the hull only, and neither coplanarity nor degeneracy count as cases of visibility.

If a “QGn” or “QG-n” option is not specified, None is returned.

New in version 1.3.0.

Type

ndarray of bool or None

area

Area of the convex hull.

New in version 0.17.0.

Type

float

volume

Volume of the convex hull.

New in version 0.17.0.

Type

float

Raises
  • QhullError – Raised when Qhull encounters an error condition, such as geometrical degeneracy when options to resolve are not enabled.

  • ValueError – Raised if an incompatible array is given as input.

Notes

The convex hull is computed using the Qhull library.

Examples

Convex hull of a random set of points:

>>> from scipy.spatial import ConvexHull, convex_hull_plot_2d
>>> points = np.random.rand(30, 2)   # 30 random points in 2-D
>>> hull = ConvexHull(points)

Plot it:

>>> import matplotlib.pyplot as plt
>>> plt.plot(points[:,0], points[:,1], 'o')
>>> for simplex in hull.simplices:
...     plt.plot(points[simplex, 0], points[simplex, 1], 'k-')

We could also have directly used the vertices of the hull, which for 2-D are guaranteed to be in counterclockwise order:

>>> plt.plot(points[hull.vertices,0], points[hull.vertices,1], 'r--', lw=2)
>>> plt.plot(points[hull.vertices[0],0], points[hull.vertices[0],1], 'ro')
>>> plt.show()

Facets visible from a point:

Create a square and add a point above the square.

>>> generators = np.array([[0.2, 0.2],
...                        [0.2, 0.4],
...                        [0.4, 0.4],
...                        [0.4, 0.2],
...                        [0.3, 0.6]])

Call ConvexHull with the QG option. QG4 means compute the portions of the hull not including point 4, indicating the facets that are visible from point 4.

>>> hull = ConvexHull(points=generators,
...                   qhull_options='QG4')

The “good” array indicates which facets are visible from point 4.

>>> print(hull.simplices)
    [[1 0]
     [1 2]
     [3 0]
     [3 2]]
>>> print(hull.good)
    [False  True False False]

Now plot it, highlighting the visible facets.

>>> fig = plt.figure()
>>> ax = fig.add_subplot(1,1,1)
>>> for visible_facet in hull.simplices[hull.good]:
...     ax.plot(hull.points[visible_facet, 0],
...             hull.points[visible_facet, 1],
...             color='violet',
...             lw=6)
>>> convex_hull_plot_2d(hull, ax=ax)
    <Figure size 640x480 with 1 Axes> # may vary
>>> plt.show()

References

Qhull

http://www.qhull.org/

__init__()
add_points

Process a set of additional new points.

Parameters
  • points (ndarray) – New points to add. The dimensionality should match that of the initial points.

  • restart (bool, optional) – Whether to restart processing from scratch, rather than adding points incrementally.

Raises

QhullError – Raised when Qhull encounters an error condition, such as geometrical degeneracy when options to resolve are not enabled.

See also

close

Notes

You need to specify incremental=True when constructing the object to be able to add points incrementally. Incremental addition of points is also not possible after close has been called.

property points
property vertices

LooseVersion

class fury.primitive.LooseVersion(vstring=None)[source]

Bases: distutils.version.Version

Version numbering for anarchists and software realists. Implements the standard interface for version number classes as described above. A version number consists of a series of numbers, separated by either periods or strings of letters. When comparing version numbers, the numeric components will be compared numerically, and the alphabetic components lexically. The following are all valid version numbers, in no particular order:

1.5.1 1.5.2b2 161 3.10a 8.02 3.4j 1996.07.12 3.2.pl0 3.1.1.6 2g6 11g 0.960923 2.2beta29 1.13++ 5.5.kw 2.0b1pl0

In fact, there is no such thing as an invalid version number under this scheme; the rules for comparison are simple and predictable, but may not always give the results you want (for some definition of “want”).

__init__(vstring=None)[source]

Initialize self. See help(type(self)) for accurate signature.

component_re = re.compile('(\\d+ | [a-z]+ | \\.)', re.VERBOSE)
parse(vstring)[source]

cart2sphere

fury.primitive.cart2sphere(x, y, z)[source]

Return angles for Cartesian 3D coordinates x, y, and z.

See doc for sphere2cart for angle conventions and derivation of the formulae.

$0lethetamathrm{(theta)}lepi$ and $-pilephimathrm{(phi)}lepi$

Parameters
  • x (array_like) – x coordinate in Cartesian space

  • y (array_like) – y coordinate in Cartesian space

  • z (array_like) – z coordinate

Returns

  • r (array) – radius

  • theta (array) – inclination (polar) angle

  • phi (array) – azimuth angle

faces_from_sphere_vertices

fury.primitive.faces_from_sphere_vertices(vertices)[source]

Triangulate a set of vertices on the sphere.

Parameters

vertices ((M, 3) ndarray) – XYZ coordinates of vertices on the sphere.

Returns

faces – Indices into vertices; forms triangular faces.

Return type

(N, 3) ndarray

fix_winding_order

fury.primitive.fix_winding_order(vertices, triangles, clockwise=False)[source]

Return corrected triangles.

Given an ordering of the triangle’s three vertices, a triangle can appear to have a clockwise winding or counter-clockwise winding. Clockwise means that the three vertices, in order, rotate clockwise around the triangle’s center.

Parameters
  • vertices (ndarray) – array of vertices corresponding to a shape

  • triangles (ndarray) – array of triangles corresponding to a shape

  • clockwise (bool) – triangle order type: clockwise (default) or counter-clockwise.

Returns

corrected_triangles – The corrected order of the vert parameter

Return type

ndarray

pjoin

fury.primitive.pjoin(a, *p)

Join two or more pathname components, inserting ‘/’ as needed. If any component is an absolute path, all previous path components will be discarded. An empty last part will result in a path that ends with a separator.

prim_box

fury.primitive.prim_box()[source]

Return vertices and triangle for a box geometry.

Returns

  • vertices (ndarray) – 8 vertices coords that composed our box

  • triangles (ndarray) – 12 triangles that composed our box

prim_frustum

fury.primitive.prim_frustum()[source]

Return vertices and triangle for a square frustum prism.

Returns

  • vertices (ndarray) – vertices coords that compose our prism

  • triangles (ndarray) – triangles that compose our prism

prim_icosahedron

fury.primitive.prim_icosahedron()[source]

Return vertices and triangles for icosahedron.

Returns

  • icosahedron_vertices (numpy.ndarray) – 12 vertices coordinates to the icosahedron

  • icosahedron_mesh (numpy.ndarray) – 20 triangles representing the tetrahedron

prim_octagonalprism

fury.primitive.prim_octagonalprism()[source]

Return vertices and triangle for an octagonal prism.

Returns

  • vertices (ndarray) – vertices coords that compose our prism

  • triangles (ndarray) – triangles that compose our prism

prim_rhombicuboctahedron

fury.primitive.prim_rhombicuboctahedron()[source]

Return vertices and triangle for rhombicuboctahedron geometry.

Returns

  • my_vertices (ndarray) – vertices coords that composed our rhombicuboctahedron

  • my_triangles (ndarray) – Triangles that composed our rhombicuboctahedron

prim_sphere

fury.primitive.prim_sphere(name='symmetric362', gen_faces=False)[source]

Provide vertices and triangles of the spheres.

Parameters
  • name (str) – which sphere - one of: * ‘symmetric362’ * ‘symmetric642’ * ‘symmetric724’ * ‘repulsion724’ * ‘repulsion100’ * ‘repulsion200’

  • gen_faces (bool, optional) – If True, triangulate a set of vertices on the sphere to get the faces. Otherwise, we load the saved faces from a file. Default: False

Returns

  • vertices (ndarray) – vertices coords that composed our sphere

  • triangles (ndarray) – triangles that composed our sphere

Examples

>>> import numpy as np
>>> from fury.primitive import prim_sphere
>>> verts, faces = prim_sphere('symmetric362')
>>> verts.shape == (362, 3)
True
>>> faces.shape == (720, 3)
True

prim_square

fury.primitive.prim_square()[source]

Return vertices and triangles for a square geometry.

Returns

  • vertices (ndarray) – 4 vertices coords that composed our square

  • triangles (ndarray) – 2 triangles that composed our square

prim_star

fury.primitive.prim_star(dim=2)[source]

Return vertices and triangle for star geometry.

Parameters

dim (int) – Represents the dimension of the wanted star

Returns

  • vertices (ndarray) – vertices coords that composed our star

  • triangles (ndarray) – Triangles that composed our star

prim_superquadric

fury.primitive.prim_superquadric(roundness=(1, 1), sphere_name='symmetric362')[source]

Provide vertices and triangles of a superquadrics.

Parameters
  • roundness (tuple, optional) – parameters (Phi and Theta) that control the shape of the superquadric

  • sphere_name (str, optional) – which sphere - one of: * ‘symmetric362’ * ‘symmetric642’ * ‘symmetric724’ * ‘repulsion724’ * ‘repulsion100’ * ‘repulsion200’

Returns

  • vertices (ndarray) – vertices coords that composed our sphere

  • triangles (ndarray) – triangles that composed our sphere

Examples

>>> import numpy as np
>>> from fury.primitive import prim_superquadric
>>> verts, faces = prim_superquadric(roundness=(1, 1))
>>> verts.shape == (362, 3)
True
>>> faces.shape == (720, 3)
True

prim_tetrahedron

fury.primitive.prim_tetrahedron()[source]

Return vertices and triangles for a tetrahedron.

This shape has a side length of two units.

Returns

  • pyramid_vert (numpy.ndarray) – 4 vertices coordinates

  • triangles (numpy.ndarray) – 4 triangles representing the tetrahedron

repeat_primitive

fury.primitive.repeat_primitive(vertices, faces, centers, directions=None, colors=(255, 0, 0), scale=1, have_tiled_verts=False)[source]

Repeat Vertices and triangles of a specific primitive shape.

It could be seen as a glyph.

Parameters
  • vertices (ndarray) – vertices coords to duplicate at the centers positions

  • triangles (ndarray) – triangles that composed our shape to duplicate

  • centers (ndarray, shape (N, 3)) – Superquadrics positions

  • directions (ndarray, shape (N, 3) or tuple (3,), optional) – The orientation vector of the cone.

  • colors (ndarray (N,3) or (N, 4) or tuple (3,) or tuple (4,)) – RGB or RGBA (for opacity) R, G, B and A should be at the range [0, 1]

  • scale (ndarray, shape (N) or (N,3) or float or int, optional) – The height of the cone.

  • have_tiled_verts (bool) – option to control if we need to duplicate vertices of a shape or not

Returns

  • big_vertices (ndarray) – Expanded vertices at the centers positions

  • big_triangles (ndarray) – Expanded triangles that composed our shape to duplicate

  • big_colors (ndarray) – Expanded colors applied to all vertices/faces

  • big_centers (ndarray) – Expanded centers for all vertices/faces

repeat_primitive_function

fury.primitive.repeat_primitive_function(func, centers, func_args=[], directions=(1, 0, 0), colors=(255, 0, 0), scale=1)[source]

Repeat Vertices and triangles of a specific primitive function.

It could be seen as a glyph. The primitive function should generate and return vertices and faces

Parameters
  • func (callable) – primitive functions

  • centers (ndarray, shape (N, 3)) – Superquadrics positions

  • func_args (args) – primitive functions arguments/parameters

  • directions (ndarray, shape (N, 3) or tuple (3,), optional) – The orientation vector of the cone.

  • colors (ndarray (N,3) or (N, 4) or tuple (3,) or tuple (4,)) – RGB or RGBA (for opacity) R, G, B and A should be at the range [0, 1]

  • scale (ndarray, shape (N) or (N,3) or float or int, optional) – The height of the cone.

Returns

  • big_vertices (ndarray) – Expanded vertices at the centers positions

  • big_triangles (ndarray) – Expanded triangles that composed our shape to duplicate

  • big_colors (ndarray) – Expanded colors applied to all vertices/faces