`primitive`¶

Module dedicated for basic primitive.

`ConvexHull`(points[, incremental, qhull_options])	Convex hulls in N dimensions.
`cart2sphere`(x, y, z)	Return angles for Cartesian 3D coordinates x, y, and z.
`euler_matrix`(ai, aj, ak[, axes])	Return homogeneous rotation matrix from Euler angles and axis sequence.
`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_icosahedron`()	Return vertices and triangles for icosahedron.
`prim_sphere`([name, gen_faces])	Provide vertices and triangles of the spheres.
`prim_square`()	Return vertices and triangles for a square 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.

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

euler_matrix¶

fury.primitive.euler_matrix(ai, aj, ak, axes='sxyz')[source]¶

Return homogeneous rotation matrix from Euler angles and axis sequence.

Code modified from the work of Christoph Gohlke link provided here http://www.lfd.uci.edu/~gohlke/code/transformations.py.html

Parameters

aj, ak (ai,) –
axes (One of 24 axis sequences as string or encoded tuple) –

Returns

matrix (ndarray (4, 4))
Code modified from the work of Christoph Gohlke link provided here
http (//www.lfd.uci.edu/~gohlke/code/transformations.py.html)

Examples

>>> import numpy
>>> R = euler_matrix(1, 2, 3, 'syxz')
>>> numpy.allclose(numpy.sum(R[0]), -1.34786452)
True
>>> R = euler_matrix(1, 2, 3, (0, 1, 0, 1))
>>> numpy.allclose(numpy.sum(R[0]), -0.383436184)
True
>>> ai, aj, ak = (4.0*math.pi) * (numpy.random.random(3) - 0.5)
>>> for axes in _AXES2TUPLE.keys():
...    _ = euler_matrix(ai, aj, ak, axes)
>>> for axes in _TUPLE2AXES.keys():
...    _ = euler_matrix(ai, aj, ak, axes)

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_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_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_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=(1, 0, 0), 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

primitive¶

ConvexHull¶

cart2sphere¶

euler_matrix¶

faces_from_sphere_vertices¶

fix_winding_order¶

pjoin¶

prim_box¶

prim_icosahedron¶

prim_sphere¶

prim_square¶

prim_superquadric¶

prim_tetrahedron¶

repeat_primitive¶

repeat_primitive_function¶

`primitive`¶

`ConvexHull`¶