microstructpy.geometry package¶
-
class
microstructpy.geometry.
Box
(**kwargs)[source]¶ Bases:
microstructpy.geometry.n_box.NBox
This class contains a generic, 3D box. The position and dimensions of the box can be specified using any of the parameters below.
Parameters: - side_lengths (list, optional) – Side lengths.
- center (list, optional) – Center of box.
- corner (list, optional) – bottom-left corner.
- limits (list, optional) – Bounds of box.
- bounds (list, optional) – Alias for limits.
-
plot
(**kwargs)[source]¶ Plot the box.
This function adds an mpl_toolkits.mplot3d.art3d.Poly3DCollection to the current axes. The keyword arguments are passed through to the Poly3DCollection.
Parameters: **kwargs (dict) – Keyword arguments for Poly3DCollection.
-
n_dim
¶ number of dimensions, 3
Type: int
-
volume
¶ volume of box, \(V=l_1 l_2 l_3\)
Type: float
-
class
microstructpy.geometry.
Cube
(**kwargs)[source]¶ Bases:
microstructpy.geometry.box.Box
A cube.
This class contains a generic, 3D cube. It is derived from the Box and contains the
side_length
property, rather than multiple side lengths.Parameters: - side_length (float, optional) – Side length.
- center (list, tuple, numpy.ndarray, optional) – Center of box.
- corner (list, tuple, numpy.ndarray, optional) – bottom-left corner.
-
side_length
¶ length of the side of the cube.
Type: float
-
class
microstructpy.geometry.
Circle
(**kwargs)[source]¶ Bases:
microstructpy.geometry.n_sphere.NSphere
A 2D circle.
This class represents a two-dimensional circle. It is defined by a center point and size parameter, which can be either radius or diameter.
Parameters: - r (float, optional) – The radius of the circle. Defaults to 1.
- center (list, optional) – The coordinates of the center. Defaults to (0, 0).
- diameter – Alias for 2x r.
- radius – Alias for r.
- d – Alias for 2x r.
- size – Alias for 2x r.
- position – Alias for center.
-
classmethod
area_expectation
(**kwargs)[source]¶ Expected value of area.
This function computes the expected value for the area of a circle. The keyword arguments are the same as the class parameters. The values can be constants (ints or floats), or scipy.stats distributions.
The expected value is computed by the following formula:
\[\mathbb{E}[A] = \pi \mathbb{E}[R^2] = \pi (\mu_R^2 + \sigma_R^2)\]For example:
>>> from microstructpy.geometry import Circle >>> Circle.area_expectation(r=1) 3.141592653589793 >>> from scipy.stats import norm >>> Circle.area_expectation(r=norm(1, 1)) 6.283185307179586
Parameters: **kwargs – Keyword arguments, see microstructpy.geometry.Circle
.Returns: Expected value of the area of the circle. Return type: float
-
plot
(**kwargs)[source]¶ Plot the circle.
This function adds a matplotlib.patches.Circle to the current axes. The keyword arguments are passed through to the circle patch.
Parameters: **kwargs (dict) – Keyword arguments for matplotlib.
-
area
¶ area of cirle, \(A=\pi r^2\)
Type: float
-
n_dim
¶ number of dimensions, 2
Type: int
-
volume
¶ alias for area
Type: float
-
class
microstructpy.geometry.
Ellipse
(**kwargs)[source]¶ Bases:
object
A 2-D ellipse geometry.
This class contains a 2-D ellipse. It is defined by a center point, axes and an orientation.
Parameters: - center (list, optional) – The ellipse center. Defaults to (0, 0).
- axes (list, optional) – A 2-element list of semi-axes. Defaults to [1, 1].
- size (float, optional) – The diameter of a circle with equivalent area. Defaults to 1.
- aspect_ratio (float, optional) – The ratio of x-axis to y-axis length Defaults to 1.
- angle (float, optional) – The rotation angle, in degrees.
- angle_deg (float, optional) – The rotation angle, in degrees.
- angle_rad (float, optional) – The rotation angle, in radians.
- matrix (2x2 array, optional) – The rotation matrix.
- a – Alias for axes[0].
- b – Alias for axes[1].
- angle_deg – Alias for angle.
- angel_rad – Alias for pi * angle / 180.
- orientation – Alias for matrix.
-
approximate
(x1=None)[source]¶ Approximate ellipse with a set of circles.
This function converts an ellipse into a set of circles. It implements a published algorithm. [1]
Parameters: x1 (float) – Center position of first circle. Returns: An Nx3 list of the (x, y, r) data of each circle approximating the ellipse. Return type: numpy.ndarray Raises: AssertionError
– Thrown if max(a, b) < x1.[1] Ilin, D.N., and Bernacki, M., “Advancing Layer Algorithm of Dense Ellipse Packing for Generating Statistically Equivalent Polygonal Structures,” Granular Matter, vol. 18(3), pp. 43, 2016.
-
classmethod
area_expectation
(**kwargs)[source]¶ Expected value of area.
This function computes the expected value for the area of an ellipse. The keyword arguments are the same as the input parameters of the class. The keyword values can be either constants (ints or floats) or scipy.stats distributions.
If an ellipse is specified by size, the expected value is computed as follows.
\[\begin{split}\begin{align} \mathbb{E}[A] &= \frac{\pi}{4} \mathbb[S^2] \\ &= \frac{\pi}{4} (\mu_S^2 + \sigma_S^2) \end{align}\end{split}\]If the ellipse is specified by independent distributions for each semi-axis, the expected value is computed by:
\[\mathbb{E}[A] = \pi \mathbb{E}[A B] = \pi \mu_A \mu_B\]If the ellipse is specified by the second semi-axis and the aspect ratio, the expected value is computed by:
\[\begin{split}\begin{align} \mathbb{E}[A] &= \pi \mathbb{E}[K B^2] \\ &= \pi \mu_K (\mu_B^2 + \sigma_B^2) \end{align}\end{split}\]Finally, if the ellipse is specified by the first semi-axis and the aspect ratio, the expected value is computed by Monte Carlo:
\[\begin{split}\begin{align} \mathbb{E}[A] &= \pi \mathbb{E}\left[\frac{A^2}{K}\right] \\ &\approx \frac{\pi}{n} \sum_{i=1}^n \frac{A_i}{K_i} \end{align}\end{split}\]where \(n=1000\).
Parameters: **kwargs – Keyword arguments, see microstructpy.geometry.Ellipse
.Returns: Expected value of the area of the ellipse. Return type: float
-
best_fit
(points)[source]¶ Find ellipse of best fit for points
This function computes the ellipse of best fit for a set of points. It is heavily adapted from the least-squares-ellipse-fitting repository on GitHub. This repository implements a published fitting algorithm in Python. [2]
The current instance of the class is used as an initial guess for the ellipse of best fit. Since an ellipse can be expressed multiple ways (e.g. rotate 90 degrees and flip the axes), this initial guess is used to choose from the multiple parameter sets.
Parameters: points (list) – List of points to fit. Returns: An instance of the class that best fits the points. Return type: Ellipse [2] Halir, R., Flusser, J., “Numerically Stable Direct Least Squares Fitting of Ellipses,” 6th International Conference in Central Europe on Computer Graphics and Visualization, Vol. 98, 1998. (http://citeseerx.ist.psu.edu/viewdoc/download?doi=10.1.1.1.7559&rep=rep1&type=pdf)
-
plot
(**kwargs)[source]¶ Plot the ellipse.
This function adds a matplotlib.patches.Ellipse patch to the current axes using matplotlib. The keyword arguments are passed to the patch.
Parameters: **kwargs (dict) – Keyword arguments for matplotlib.
-
reflect
(points)[source]¶ Reflect points across surface.
This function reflects a point or set of points across the surface of the ellipse. Points at the center of the ellipse are not reflected.
Parameters: points (list) – Points to reflect. Returns: Reflected points. Return type: numpy.ndarray
-
within
(points)[source]¶ Test if points are within ellipse.
This function tests whether a point or set of points are within the ellipse. For the set of points, a list of booleans is returned to indicate which points are within the ellipse.
Parameters: points (list) – Point or list of points. Returns: Set to True for points in ellipse. Return type: bool or numpy.ndarray
-
angle_deg
¶ rotation angle, in degrees
Type: float
-
angle_rad
¶ rotation angle, in radians
Type: float
-
area
¶ area of ellipse, \(A = \pi a b\)
Type: float
-
aspect_ratio
¶ ratio of x-axis length to y-axis length
Type: float
-
axes
¶ list of semi-axes.
Type: tuple
-
bound_max
¶ maximum bounding circle of ellipse, (x, y, r)
Type: tuple
-
bound_min
¶ minimum interior circle of ellipse, (x, y, r)
Type: tuple
-
limits
¶ list of (lower, upper) bounds for the bounding box
Type: list
-
matrix
¶ rotation matrix
Type: numpy.ndarray
-
n_dim
¶ number of dimensions, 2
Type: int
-
orientation
¶ rotation matrix
Type: numpy.ndarray
-
sample_limits
¶ list of (lower, upper) bounds for the sampling region
Type: list
-
size
¶ diameter of equivalent area circle
Type: float
-
volume
¶ alias for area
Type: float
-
class
microstructpy.geometry.
Ellipsoid
(**kwargs)[source]¶ Bases:
object
A 3D Ellipsoid
This class contains the data and functions for a 3D ellispoid. It is defined by its center, axes, and orientation.
If multiple keywords are given for the shape of the ellipsoid, there is no guarantee for which keywords are used.
Parameters: - center (list, optional) – The ellipsoid center. Defaults to (0, 0, 0).
- axes (list, optional) – List of 3 semi-axes. Defaults to (1, 1, 1).
- size (float, optional) – The diameter of a sphere with equal volume. Defaults to 2.
- ratio_ab (float, optional) – The ratio of a to b.
- ratio_ac (float, optional) – The ratio of a to c.
- ratio_bc (float, optional) – The ratio of b to c.
- ratio_ba (float, optional) – The ratio of b to a.
- ratio_ca (float, optional) – The ratio of c to a.
- ratio_cb (float, optional) – The ratio of c to b.
- rot_seq (list, optional) –
List of rotations (deg). Each element of the list should be an (axis, angle) tuple. The options for the axis are: ‘x’, ‘y’, ‘z’, 1, 2, or 3. For example:
rot_seq = [('x', 10), (2, -20), ('z', 85), ('x', 21)]
- rot_seq_deg (list, optional) – Alias for rot_seq, with degrees stated explicitly.
- rot_seq_rad (list, optional) – Same format as rot_seq, except the angles are expressed in radians.
- matrix (3x3 numpy.ndarray, optional) – A 3x3 rotation matrix expressing the orientation of the ellipsoid. Defaults to the identity.
- position – Alias for center.
- a – Alias for axes[0].
- b – Alias for axes[1].
- c – Alias for axes[2].
- orientation – Alias for matrix.
-
approximate
(x1=None)[source]¶ Approximate Ellipsoid with Spheres
This function approximates the ellipsoid by a set of spheres. It does so by approximating the x-z and y-z elliptical cross sections with circles, then scaling those circles and promoting them to spheres.
See the documentation for
microstructpy.geometry.Ellipse.approximate()
for more details.Parameters: x1 (float) – Center position of the first sphere. Returns: An Nx4 list of the (x, y, z, r) data of the spheres that approximate the ellipsoid. Return type: numpy.ndarray
-
best_fit
(points)[source]¶ Find ellipsoid of best fit.
This function takes a list of 3D points and computes the ellipsoid of best fit for the points. It uses a published algorithm to fit the ellipsoid, then attempts to define the axes in such a way that they most align with this ellipsoid’s axes. [3]
Parameters: points (list) – Points to fit ellipsoid Returns: The ellipsoid that best fits the points. Return type: Ellipsoid [3] Turner, D. A., Anderson, I. J., Mason, J. C., and Cox, M. G., “An Algorithm for Fitting an Ellipsoid to Data,” National Physical Laboratory, 1999, The United Kingdom. (http://citeseerx.ist.psu.edu/viewdoc/download?doi=10.1.1.36.2773&rep=rep1&type=pdf)
-
plot
(**kwargs)[source]¶ Plot the ellipsoid.
This function uses the Axes3D.plot_surface method to add an ellipsoid to the current axes. The keyword arguments are passed through to the plot_surface function.
Parameters: **kwargs (dict) – Keyword arguments for matplotlib.
-
reflect
(points)[source]¶ Reflect points across surface.
This function reflects a point or set of points across the surface of the ellipsoid. Points at the center of the ellipsoid are not reflected.
Parameters: points (list) – Points to reflect. Returns: Reflected points. Return type: numpy.ndarray
-
classmethod
volume_expectation
(**kwargs)[source]¶ Expected value of volume.
This function computes the expected value for the volume of an ellipsoid. The keyword arguments are the same as the input parameters for the class,
microstructpy.geometry.Ellipsoid
. The values for these keywords can be either constants or scipy.stats distributions.The expected value is computed by the following formula:
\[\begin{split}\begin{align} \mathbb{E}[V] &= \mathbb{E}[\frac{4}{3}\pi A B C] \\ &= \frac{4}{3}\pi \mathbb{E}[A] \mathbb{E}[B] \mathbb{E}[C] \\ &= \frac{4}{3}\pi \mu_A \mu_B \mu_C \end{align}\end{split}\]If the ellisoid is specified by size and aspect ratios, then the expected volume is computed by:
\[\begin{split}\begin{align} \mathbb{E}[V] &= \mathbb{E}[\frac{\pi}{6} S^3] \\ &= \frac{\pi}{6} (\mu_S^3 + 3 \mu_S \sigma_S^2 + \gamma_{1, S} \sigma_S^3) \end{align}\end{split}\]If the ellipsoid is specified using a combination of semi-axes and aspect ratios, then the expected volume is the mean of 1000 random samples:
\[\mathbb{E}[V] \approx \frac{1}{n} \sum_{i=1}^n V_i\]where \(n=1000\).
Parameters: **kwargs – Keyword arguments, see microstructpy.geometry.ellipsoid.Ellipsoid
.Returns: Expected value of the volume of the sphere. Return type: float
-
within
(points)[source]¶ Test if points are within ellipsoid.
This function tests whether a point or set of points are within the ellipsoid. For the set of points, a list of booleans is returned to indicate which points are within the ellipsoid.
Parameters: points (list) – Point or list of points. Returns: Set to True for points in geometry. Return type: bool or numpy.ndarray
-
axes
¶ the 3 semi-axes of the ellipsoid
Type: tuple
-
bound_max
¶ maximum bounding sphere, (x, y, z, r)
Type: tuple
-
bound_min
¶ minimum interior sphere, (x, y, z, r)
Type: tuple
-
coefficients
¶ coeffificients of equation, \((A, B, C, D, E, F, G, H, K, L)\) in \(Ax^2 + Bxy + Cxz + Dy^2 + Eyz + Fz^2 + Gx + Hy + Kz + L = 0\)
Type: tuple
-
limits
¶ list of (lower, upper) bounds for the bounding box
Type: list
-
matrix
¶ A 3x3 rotation matrix
Type: numpy.ndarray
-
matrix_quadeq
¶ Matrix of the quadratic equation
Type: numpy.ndarray
-
matrix_quadform
¶ Matrix of the quadratic form
Type: numpy.ndarray
-
n_dim
¶ number of dimensions, 3
Type: int
-
orientation
¶ A 3x3 rotation matrix
Type: numpy.ndarray
-
ratio_ab
¶ ratio of x-axis length to y-axis length
Type: float
-
ratio_ac
¶ ratio of x-axis length to z-axis length
Type: float
-
ratio_ba
¶ ratio of y-axis length to x-axis length
Type: float
-
ratio_bc
¶ ratio of y-axis length to z-axis length
Type: float
-
ratio_ca
¶ ratio of z-axis length to x-axis length
Type: float
-
ratio_cb
¶ ratio of z-axis length to y-axis length
Type: float
-
rot_seq_deg
¶ rotation sequence, with angles in degrees
Type: list
-
rot_seq_rad
¶ rotation sequence, with angles in radiands
Type: list
-
sample_limits
¶ list of (lower, upper) bounds for the sampling region
Type: list
-
size
¶ diameter of equivalent volume sphere
Type: float
-
volume
¶ volume of ellipsoid, \(V = \frac{4}{3}\pi a b c\)
Type: float
-
class
microstructpy.geometry.
Rectangle
(**kwargs)[source]¶ Bases:
microstructpy.geometry.n_box.NBox
This class contains a generic, 2D rectangle. The position and dimensions of the box can be specified using any of the parameters below.
Parameters: - length (float, optional) – Length of the rectangle.
- width (float, optional) – Width of the rectangle.
- side_lengths (list, optional) – Side lengths. Defaults to (1, 1).
- center (list, optional) – Center of rectangle. Defaults to (0, 0).
- corner (list, optional) – bottom-left corner.
- bounds (list, optional) – Bounds of rectangle. Expected to be in the format [(xmin, xmax), (ymin, ymax)].
- limits – Alias for bounds.
- angle (float, optional) – The rotation angle, in degrees.
- angle_deg (float, optional) – The rotation angle, in degrees.
- angle_rad (float, optional) – The rotation angle, in radians.
- matrix (2x2 array, optional) – The rotation matrix.
-
best_fit
(points)[source]¶ Find rectangle of best fit for points
Parameters: points (list) – List of points to fit. Returns: - an instance of the class
- that best fits the points.
Return type: microstructpy.geometry.Rectangle
-
plot
(**kwargs)[source]¶ Plot the rectangle.
This function adds a matplotlib.patches.Rectangle patch to the current axes. The keyword arguments are passed through to the patch.
Parameters: **kwargs (dict) – Keyword arguments for the patch.
-
angle
¶
-
angle_deg
¶
-
angle_rad
¶
-
area
¶ area of rectangle
Type: float
-
length
¶
-
n_dim
¶ number of dimensions, 2
Type: int
-
width
¶
-
class
microstructpy.geometry.
Square
(**kwargs)[source]¶ Bases:
microstructpy.geometry.rectangle.Rectangle
A square.
This class contains a generic, 2D square. It is derived from the
microstructpy.geometry.Rectangle
class and contains theside_length
property, rather than multiple side lengths.Parameters: - side_length (float, optional) – Side length. Defaults to 1.
- center (list, optional) – Center of rectangle. Defaults to (0, 0).
- corner (list, optional) – bottom-left corner.
-
side_length
¶ length of the side of the square.
Type: float
-
class
microstructpy.geometry.
Sphere
(**kwargs)[source]¶ Bases:
microstructpy.geometry.n_sphere.NSphere
A 3D sphere.
This class represents a three-dimensional circle. It is defined by a center point and size parameter, which can be either radius or diameter.
Parameters: - r (float, optional) – The radius of the n-sphere.
- radius (float, optional) – The radius of the n-sphere.
- d (float, optional) – The diameter of the n-sphere.
- diameter (float, optional) – The diameter of the n-sphere.
- size (float, optional) – The size of the n-sphere.
- center (list, float, numpy.ndarray) – The coordinates of the center.
- position (list, float, numpy.ndarray) – The coordinates of the center.
-
plot
(**kwargs)[source]¶ Plot the sphere.
This function uses the Axes3D.plot_surface method to add the sphere to the current axes. The keyword arguments are passed through to plot_surface.
Parameters: **kwargs (dict) – Keyword arguments for plot_surface.
-
classmethod
volume_expectation
(**kwargs)[source]¶ Expected value of volume.
This function computes the expected value for the volume of a sphere. The keyword arguments are identical to the __init__ function. The values for these keywords can be either constants or scip.stats distributions.
The expected value is computed by the following formula:
\[\begin{split}\begin{align} \mathbb{E}[V] &= \mathbb{E}[\frac{4}{3}\pi R^3] \\ &= \frac{4}{3}\pi \mathbb{E}[R^3] \\ &= \frac{4}{3}\pi (\mu_R^3 + 3 \mu_R \sigma_R^2 + \gamma_{1, R} \sigma_R^3) \end{align}\end{split}\]Parameters: **kwargs – Keyword arguments, see microstructpy.geometry.Sphere
.Returns: Expected value of the volume of the sphere. Return type: float
-
n_dim
¶ number of dimensions, 3
Type: int
-
volume
¶ volume of sphere
Type: float
Submodules¶
- microstructpy.geometry.box module
- microstructpy.geometry.circle module
- microstructpy.geometry.ellipse module
- microstructpy.geometry.ellipsoid module
- microstructpy.geometry.n_box module
- microstructpy.geometry.n_sphere module
- microstructpy.geometry.rectangle module
- microstructpy.geometry.sphere module