`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.
`faces_from_sphere_vertices`(vertices)	Triangulate a set of vertices on the sphere.
`fix_winding_order`(vertices, triangles[, ...])	Return corrected triangles.
`parse`(version)	Parse the given version string.
`pjoin`(a, *p)	Join two or more pathname components, inserting '/' as needed.
`prim_arrow`([height, resolution, tip_length, ...])	Return vertices and triangle for arrow geometry.
`prim_box`()	Return vertices and triangle for a box geometry.
`prim_cone`([radius, height, sectors])	Return vertices and triangle of a Cone.
`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_pentagonalprism`()	Return vertices and triangles for a pentagonal prism.
`prim_rhombicuboctahedron`()	Return vertices and triangles for rhombicuboctahedron.
`prim_sphere`([name, gen_faces, phi, theta])	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.
`sphere2cart`(r, theta, phi)	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 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
>>> import numpy as np
>>> rng = np.random.default_rng()
>>> points = rng.random((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__(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.

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

parse#

fury.primitive.parse(version: str) → Version[source]#

Parse the given version string.

>>> parse('1.0.dev1')
<Version('1.0.dev1')>

Parameters:: version – The version string to parse.
Raises:: InvalidVersion – When the version string is not a valid version.

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#

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_cone#

fury.primitive.prim_cone(radius=0.5, height=1, sectors=10)[source]#

Return vertices and triangle of a Cone.

Parameters:

radius (float, optional) – Radius of the cone
height (float, optional) – Height of the cone
sectors (int, optional) – Sectors in the cone

Returns:

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

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_pentagonalprism#

fury.primitive.prim_pentagonalprism()[source]#

Return vertices and triangles for a pentagonal 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 triangles for rhombicuboctahedron.

Returns:

vertices (numpy.ndarray) – 24 vertices coordinates to the rhombicuboctahedron
triangles (numpy.ndarray) – 44 triangles representing the 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#

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

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 south-north, the y axis running west-east and the x axis from posterior to anterior. theta (the inclination angle) is the angle to rotate from the z-axis (the zenith) around the y-axis, towards the x axis. Thus the rotation is counter-clockwise from the point of view of positive y. phi (azimuth) gives the angle of rotation around the z-axis towards the y axis. The rotation is counter-clockwise 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 z-axis, and phi is the angle between the projection of P onto the XY plane, and the X axis.

Geographical nomenclature designates theta as ‘co-latitude’, 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 than sph2cart 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.

Table of Contents

`primitive`#

`ConvexHull`#

cart2sphere#

faces_from_sphere_vertices#

fix_winding_order#

parse#

pjoin#

prim_arrow#

prim_box#

prim_cone#

prim_cylinder#

prim_frustum#

prim_icosahedron#

prim_octagonalprism#

prim_pentagonalprism#

prim_rhombicuboctahedron#

prim_sphere#

prim_square#

prim_star#

prim_superquadric#

prim_tetrahedron#

prim_triangularprism#

repeat_primitive#

repeat_primitive_function#

sphere2cart#

About

Friends

Support

Table of Contents

primitive#

ConvexHull#

cart2sphere#

faces_from_sphere_vertices#

fix_winding_order#

parse#

pjoin#

prim_arrow#

prim_box#

prim_cone#

prim_cylinder#

prim_frustum#

prim_icosahedron#

prim_octagonalprism#

prim_pentagonalprism#

prim_rhombicuboctahedron#

prim_sphere#

prim_square#

prim_star#

prim_superquadric#

prim_tetrahedron#

prim_triangularprism#

repeat_primitive#

repeat_primitive_function#

sphere2cart#

`primitive`#

`ConvexHull`#