microstructpy.geometry.ellipsoid module¶
-
class
microstructpy.geometry.ellipsoid.
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. [1]
Parameters: points (list) – Points to fit ellipsoid Returns: The ellipsoid that best fits the points. Return type: Ellipsoid [1] 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