ellipse_indices#

emg3d.maps.ellipse_indices(coo, p0, p1, radius, factor=1.0, minor=1.0, check_foci=True)[source]#

Return bool which points fall within a general ellipse.

The general ellipse is given by

(32)#\[ A (x-x_0)^2 + B (x-x_0) (y-y_0) + C (y-y_0)^2 = 1 \ ,\]

where

\[\begin{split}A &= \cos^2\theta / a^2 + \sin^2\theta / b^2 \ , \\ B &= 2 \cos\theta \sin\theta (1/a^2 - 1/b^2) \ , \\ C &= \sin^2\theta / a^2 + \cos^2\theta / b^2 \ . \\\end{split}\]

Here,

  • \((x_0;y_0)\) is the center, the midpoint between the two provided points p0 and p1;

  • \(a\) is the semi-major axis, defined as

    (33)#\[a = \max(f c, c + r)\ ,\]

    where \(c\) is the distance between the center and either of the points {p0;p1}, \(r\) is the provided radius, and \(f\) the provided factor;

  • \(b\) is the semi-minor axis, defined as \(b = m a\), where \(m\) is provided as minor;

  • \(\theta\) is the angle between the two points.

The following figure explains it graphically (only visible in the web version of the API docs on https://emg3d.emsig.xyz).

Sketch for ellipse indices.

Fig. 17 Definition of the ellipse as a function of two points (black dots), a certain radius \(r\) around them, a factor \(f\), and a minor factor \(m\).#

Parameters:
cootuple of two ndarrays

Tuple of two arrays defining the points in x and y:

  • If two vectors are given (of same or different size), they are taken as the x- and y-values of a regular grid.

  • If two 2D-arrays are given of the same shape, they are taken as the (regular or irregular) x- and y-values.

p0, p1array_like

(x, y)-coordinates of two points.

radiusfloat

Radius of the circle around the points that should be included in the ellipse. This defines also the minimum value for the major and minor axes of the ellipse.

factorfloat, default: 1.0

The semi-major axis length is defined as a = max(f c, c + r), where f is this factor.

minorfloat, default: 1.0

The semi-minor axis is defined as the semi-major axis multiplied by minor, usually a value <= 1.0, where 1.0 defines a circle. The enforced lower limit of the minor axis is the radius. The provided minor might be overruled if check_foci=True.

check_focibool, default: True

If True, it is ensured that {p0;p1} are at least as far from the center as the foci of the ellipse; minor is adjusted accordingly if necessary.

Returns:
indndarray

Boolean with same shape as the provided coordinates containing True where (x;y) are inside or on the ellipse, and False otherwise.