microstructpy.geometry.ellipse module¶
-
class
microstructpy.geometry.ellipse.
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