microstructpy.geometry.Ellipsoid¶
-
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
a (float) – (optional) First semi-axis of ellipsoid. Default is 1.
b (float) – (optional) Second semi-axis of ellipsoid. Default is 1.
c (float) – (optional) Third semi-axis of ellipsoid. Default is 1.
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 (numpy.ndarray) – (optional) A 3x3 rotation matrix expressing the orientation of the ellipsoid. Defaults to the identity.
position – (optional) Alias for
center
.orientation – (optional) 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) – (optional) Center position of the first sphere. Default is 0.75x the minimum semi-axis.
- Returns
An Nx4 list of the (x, y, z, r) data of the spheres that approximate the ellipsoid.
- Return type
-
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
- 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
mpl_toolkits.mplot3d.Axes3D.plot_surface()
method to add an ellipsoid to the current axes. The keyword arguments are passes 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 or numpy.ndarray) – Points to reflect.
- Returns
Reflected points.
- Return type
-
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 distributions from the SciPyscipy.stats
module.The expected value is computed by the following formula:
\[\begin{split}\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{split}\]If the ellisoid is specified by size and aspect ratios, then the expected volume is computed by:
\[\begin{split}\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{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
.- Returns
Expected value of the volume of the sphere.
- Return type
-
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 or numpy.ndarray) – Point or list of points.
- Returns
Set to True for points in geometry.
- Return type
-
property
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
-
property
matrix
¶ A 3x3 rotation matrix
- Type
-
property
matrix_quadeq
¶ Matrix of the quadratic equation
- Type
-
property
matrix_quadform
¶ Matrix of the quadratic form
- Type
-
property
orientation
¶ A 3x3 rotation matrix
- Type