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

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

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 distributions from the SciPy scipy.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

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 or numpy.ndarray) – Point or list of points.

Returns

Set to True for points in geometry.

Return type

bool or numpy.ndarray

property axes

the 3 semi-axes of the ellipsoid

Type

tuple

property bound_max

maximum bounding sphere, (x, y, z, r)

Type

tuple

property bound_min

minimum interior sphere, (x, y, z, r)

Type

tuple

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

tuple

property limits

List of (lower, upper) bounds for the bounding box

Type

list

property matrix

A 3x3 rotation matrix

Type

numpy.ndarray

property matrix_quadeq

Matrix of the quadratic equation

Type

numpy.ndarray

property matrix_quadform

Matrix of the quadratic form

Type

numpy.ndarray

property n_dim

number of dimensions, 3

Type

int

property orientation

A 3x3 rotation matrix

Type

numpy.ndarray

property ratio_ab

ratio of x-axis length to y-axis length

Type

float

property ratio_ac

ratio of x-axis length to z-axis length

Type

float

property ratio_ba

ratio of y-axis length to x-axis length

Type

float

property ratio_bc

ratio of y-axis length to z-axis length

Type

float

property ratio_ca

ratio of z-axis length to x-axis length

Type

float

property ratio_cb

ratio of z-axis length to y-axis length

Type

float

property rot_seq_deg

rotation sequence, with angles in degrees

Type

list

property rot_seq_rad

rotation sequence, with angles in radiands

Type

list

property sample_limits

List of (lower, upper) bounds for the sampling region

Type

list

property size

diameter of equivalent volume sphere

Type

float

property volume

volume of ellipsoid, \(V = \frac{4}{3}\pi a b c\)

Type

float