`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_cylinder`([radius, height, sectors, capped])	Return vertices and triangles for a cylinder.
`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.
`prim_triangularprism`()	Return vertices and triangle for a regular triangular prism.
`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¶

Surface area of the convex hull when input dimension > 2. When input points are 2-dimensional, this is the perimeter of the convex hull.

New in version 0.17.0.

Type: float

volume¶

Volume of the convex hull when input dimension > 2. When input points are 2-dimensional, this is the area 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.

`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_cylinder¶

fury.primitive.prim_cylinder(radius=0.5, height=1, sectors=36, capped=True)[source]¶

Return vertices and triangles for a cylinder.

Parameters

radius (float) – Radius of the cylinder
height (float) – Height of the cylinder
sectors (int) – Sectors in the cylinder
capped (bool) – Whether the cylinder is capped at both ends or open

Returns

vertices (ndarray) – vertices coords that compose our cylinder
triangles (ndarray) – triangles that compose our cylinder

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

prim_triangularprism¶

fury.primitive.prim_triangularprism()[source]¶

Return vertices and triangle for a regular triangular prism.

Returns

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

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

primitive¶

ConvexHull¶

LooseVersion¶

cart2sphere¶

faces_from_sphere_vertices¶

fix_winding_order¶

pjoin¶

prim_box¶

prim_cylinder¶

prim_frustum¶

prim_icosahedron¶

prim_octagonalprism¶

prim_rhombicuboctahedron¶

prim_sphere¶

prim_square¶

prim_star¶

prim_superquadric¶

prim_tetrahedron¶

prim_triangularprism¶

repeat_primitive¶

repeat_primitive_function¶

`primitive`¶

`ConvexHull`¶

`LooseVersion`¶