skimage2.measure.EllipseModel#

class skimage2.measure.EllipseModel(center, axis_lengths, theta)[source]#

Bases: _BaseModel

Total least squares estimator for 2D ellipses.

The functional model of the ellipse is:

xt = xc + a*cos(theta)*cos(t) - b*sin(theta)*sin(t)
yt = yc + a*sin(theta)*cos(t) + b*cos(theta)*sin(t)
d = sqrt((x - xt)**2 + (y - yt)**2)

where (xt, yt) is the closest point on the ellipse to (x, y). Thus d is the shortest distance from the point to the ellipse.

The estimator is based on a least squares minimization. The optimal solution is computed directly, no iterations are required. This leads to a simple, stable and robust fitting method.

Parameters:

centerarray_like of shape (2,): Coordinates of ellipse center.
axis_lengthsarray_like of shape (2,): Length of first axis and length of second axis. Call these a and b.
thetafloat: Angle of first axis.

Raises:

ValueError: If center does not have length 2.

Examples

>>> em = EllipseModel((10, 15), (8, 4), np.deg2rad(30))
>>> xy = em.predict_xy(np.linspace(0, 2 * np.pi, 25))
>>> ellipse = EllipseModel.from_estimate(xy)
>>> ellipse.center
array([10., 15.])
>>> ellipse.axis_lengths
array([8., 4.])
>>> round(ellipse.theta, 2)
0.52
>>> np.round(abs(ellipse.residuals(xy)), 5)
array([0., 0., 0., 0., 0., 0., 0., 0., 0., 0., 0., 0., 0., 0., 0., 0., 0.,
       0., 0., 0., 0., 0., 0., 0., 0.])

The estimation can fail when — for example — all the input or output points are the same. If this happens, you will get an ellipse model for which bool(model) is False:

>>> # A successfully estimated model is truthy:
>>> if ellipse:
...     print("Estimation succeeded.")
Estimation succeeded.
>>> # Not so for a degenerate model with identical points.
>>> bad_data = np.ones((4, 2))
>>> bad_ellipse = EllipseModel.from_estimate(bad_data)
>>> if not bad_ellipse:
...     print("Estimation failed.")
Estimation failed.

Trying to use this failed estimation transform result will give a suitable error:

>>> bad_ellipse.residuals(xy)
Traceback (most recent call last):
  ...
FailedEstimationAccessError: No attribute "residuals" for failed estimation ...

__init__(center, axis_lengths, theta)[source]#

estimate(data)[source]#

Estimate ellipse model from data using total least squares.

Deprecated since version 0.26: estimate is deprecated since version 0.26 and will be removed in version 2.2. Please use EllipseModel.from_estimate class constructor instead.

Parameters:

datandarray of shape (N, 2): N points with (x, y) coordinates, respectively.

Returns:

successbool: True, if model estimation succeeds.

classmethod from_estimate(data)[source]#

Estimate ellipse model from data using total least squares.

Parameters:

datandarray of shape (N, 2): N points with (x, y) coordinates, respectively.

Returns:

modelSelf or FailedEstimation

An instance of the ellipse model if the estimation succeeded. Otherwise, we return a special FailedEstimation object to signal a failed estimation. Testing the truth value of the failed estimation object will return False. E.g.

model = EllipseModel.from_estimate(...)
if not model:
    raise RuntimeError(f"Failed estimation: {model}")

References

[1]

Halir, R.; Flusser, J. “Numerically stable direct least squares fitting of ellipses”. In Proc. 6th International Conference in Central Europe on Computer Graphics and Visualization. WSCG (Vol. 98, pp. 125-132).

property params#: Return model attributes center, axis_lengths, theta as 1D array.

Deprecated since version 0.26: params is deprecated since version 0.26 and will be removed in version 2.2. params attribute deprecated; use center, axis_lengths, theta attributes instead.

predict_xy(t, params=<DEPRECATED>)[source]#

Predict x- and y-coordinates using the estimated model.

Parameters:

tarray: Angles in circle in radians. Angles start to count from positive x-axis to positive y-axis in a right-handed system.

Returns:

xyndarray of shape (…, 2): Predicted x- and y-coordinates.

Other Parameters:

paramsDEPRECATED, optional: Optional ellipse model parameters in the following order xc, yc, a, b, theta.

Deprecated since version 0.26.

residuals(data)[source]#

Determine residuals of data to model.

For each point the shortest distance to the ellipse is returned.

Parameters:

datandarray of shape (N, 2): N points with (x, y) coordinates, respectively.

Returns:

residualsndarray of shape (N,): Residual for each data point.