primitive
#
Module dedicated for basic primitive.

Convex hulls in N dimensions. 

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

Triangulate a set of vertices on the sphere. 

Return corrected triangles. 

Parse the given version string. 

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

Return vertices and triangle for arrow geometry. 

Return vertices and triangle for a box geometry. 

Return vertices and triangle of a Cone. 

Return vertices and triangles for a cylinder. 
Return vertices and triangle for a square frustum prism. 

Return vertices and triangles for icosahedron. 

Return vertices and triangle for an octagonal prism. 

Return vertices and triangles for a pentagonal prism. 

Return vertices and triangles for rhombicuboctahedron. 


Provide vertices and triangles of the spheres. 
Return vertices and triangles for a square geometry. 


Return vertices and triangle for star geometry. 

Provide vertices and triangles of a superquadrics. 
Return vertices and triangles for a tetrahedron. 

Return vertices and triangle for a regular triangular prism. 


Repeat Vertices and triangles of a specific primitive shape. 

Repeat Vertices and triangles of a specific primitive function. 

Spherical to Cartesian coordinates. 
ConvexHull
#
 class fury.primitive.ConvexHull(points, incremental=False, qhull_options=None)#
Bases:
_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 2D 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 onedimensional Boolean array indicating which facets are good. Used with options that compute good facets, e.g. QGn and QGn. 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 “QGn” option is not specified, None is returned.
New in version 1.3.0.
 Type:
ndarray of bool or None
 area#
Surface area of the convex hull when input dimension > 2. When input points are 2dimensional, this is the perimeter of the convex hull.
New in version 0.17.0.
 Type:
 volume#
Volume of the convex hull when input dimension > 2. When input points are 2dimensional, this is the area of the convex hull.
New in version 0.17.0.
 Type:
 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 >>> import numpy as np >>> rng = np.random.default_rng() >>> points = rng.random((30, 2)) # 30 random points in 2D >>> 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 2D 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] __init__(points, incremental=False, qhull_options=None)#
 add_points(points, restart=False)#
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#
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#
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 counterclockwise 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 counterclockwise.
 Returns:
corrected_triangles – The corrected order of the vert parameter
 Return type:
ndarray
parse#
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_arrow#
 fury.primitive.prim_arrow(height=1.0, resolution=10, tip_length=0.35, tip_radius=0.1, shaft_radius=0.03)[source]#
Return vertices and triangle for arrow geometry.
 Parameters:
height (float) – The height of the arrow (default: 1.0).
resolution (int) – The resolution of the arrow.
tip_length (float) – The tip size of the arrow (default: 0.35)
tip_radius (float) – the tip radius of the arrow (default: 0.1)
shaft_radius (float) – The shaft radius of the arrow (default: 0.03)
 Returns:
vertices (ndarray) – vertices of the Arrow
triangles (ndarray) – Triangles of the Arrow
prim_box#
prim_cone#
prim_cylinder#
prim_frustum#
prim_icosahedron#
prim_octagonalprism#
prim_pentagonalprism#
prim_rhombicuboctahedron#
prim_sphere#
 fury.primitive.prim_sphere(name='symmetric362', gen_faces=False, phi=None, theta=None)[source]#
Provide vertices and triangles of the spheres.
 Parameters:
name (str, optional) – 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
phi (int, optional) – Set the number of points in the latitude direction
theta (int, optional) – Set the number of points in the longitude direction
 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#
prim_star#
prim_superquadric#
 fury.primitive.prim_superquadric(roundness=(1, 1), sphere_name='symmetric362')[source]#
Provide vertices and triangles of a superquadrics.
 Parameters:
 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#
prim_triangularprism#
repeat_primitive#
 fury.primitive.repeat_primitive(vertices, faces, centers, directions=None, colors=(1, 0, 0), scales=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]
scales (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=(1, 0, 0), scales=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]
scales (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
sphere2cart#
 fury.primitive.sphere2cart(r, theta, phi)[source]#
Spherical to Cartesian coordinates.
This is the standard physics convention where theta is the inclination (polar) angle, and phi is the azimuth angle.
Imagine a sphere with center (0,0,0). Orient it with the z axis running southnorth, the y axis running westeast and the x axis from posterior to anterior. theta (the inclination angle) is the angle to rotate from the zaxis (the zenith) around the yaxis, towards the x axis. Thus the rotation is counterclockwise from the point of view of positive y. phi (azimuth) gives the angle of rotation around the zaxis towards the y axis. The rotation is counterclockwise from the point of view of positive z.
Equivalently, given a point P on the sphere, with coordinates x, y, z, theta is the angle between P and the zaxis, and phi is the angle between the projection of P onto the XY plane, and the X axis.
Geographical nomenclature designates theta as ‘colatitude’, and phi as ‘longitude’
 Parameters:
r (array_like) – radius
theta (array_like) – inclination or polar angle
phi (array_like) – azimuth angle
 Returns:
x (array) – x coordinate(s) in Cartesion space
y (array) – y coordinate(s) in Cartesian space
z (array) – z coordinate
Notes
See these pages:
for excellent discussion of the many different conventions possible. Here we use the physics conventions, used in the wikipedia page.
Derivations of the formulae are simple. Consider a vector x, y, z of length r (norm of x, y, z). The inclination angle (theta) can be found from: cos(theta) == z / r > z == r * cos(theta). This gives the hypotenuse of the projection onto the XY plane, which we will call Q. Q == r*sin(theta). Now x / Q == cos(phi) > x == r * sin(theta) * cos(phi) and so on.
We have deliberately named this function
sphere2cart
rather thansph2cart
to distinguish it from the Matlab function of that name, because the Matlab function uses an unusual convention for the angles that we did not want to replicate. The Matlab function is trivial to implement with the formulae given in the Matlab help.