Table of Contents

Struct Ellipse2

Namespace
Thunder.UnitsNET.Vectors.Geometry
Assembly
Thunder.UnitsNET.Vectors.Geometry.dll

A positioned, optionally-rotated ellipse in 2D space.

An ellipse is defined by a centre point, two semi-axes, and a rotation. The semi-major axis (a) is the half-length of the longest dimension; the semi-minor axis (b) is the half-length of the shortest. When both axes are equal the ellipse degenerates to a circle.

Rotation is expressed as a Direction2 that points along the positive end of the semi-major axis. At zero rotation (East) the major axis lies along +X and the minor axis along +Y.

Ellipse2 is a readonly record struct: value-type, immutable, and equality-by-value. All computed properties are derived on demand. 

public readonly record struct Ellipse2 : IEquatable<Ellipse2>
Implements
Inherited Members
Extension Methods

Examples

// An ellipse centred at the origin: 2 m wide (major), 1 m tall (minor)
var e = new Ellipse2(LengthPoint2.Origin, Length.FromMeters(2), Length.FromMeters(1), Direction2.East);

Area   area  = e.Area;          // π·2·1 ≈ 6.283 m²
double ecc   = e.Eccentricity;  // 0.866
bool   inside = e.Contains(LengthPoint2.FromMeters(1, 0.5)); // true

Constructors

Ellipse2(LengthPoint2, Length, Length, Direction2)

Constructs an Ellipse2 with the given position, axes, and orientation.

public Ellipse2(LengthPoint2 center, Length semiMajorAxis, Length semiMinorAxis, Direction2 rotation)

Parameters

center LengthPoint2

The centre of the ellipse.

semiMajorAxis Length

Half-length of the longest axis (must be > 0 and ≥ semiMinorAxis).

semiMinorAxis Length

Half-length of the shortest axis (must be > 0).

rotation Direction2

The direction of the semi-major axis.

Examples

// 2 m × 1 m ellipse at the origin, major axis along East (+X)
var e = new Ellipse2(LengthPoint2.Origin, Length.FromMeters(2), Length.FromMeters(1), Direction2.East);

// Same ellipse rotated 45°
var rotated = new Ellipse2(LengthPoint2.Origin, Length.FromMeters(2), Length.FromMeters(1), Direction2.NorthEast);

Exceptions

ArgumentException

Thrown if either axis is zero or negative, or if semiMinorAxis exceeds semiMajorAxis.

Properties

Area

The area of the ellipse: π · a · b, where a and b are the semi-major and semi-minor axes respectively.

When both axes are equal (a circle) this equals π · r², the familiar circle-area formula. 

public Area Area { get; }

Property Value

Area

Center

The position of the ellipse's centre in 2D space.

public LengthPoint2 Center { get; }

Property Value

LengthPoint2

Eccentricity

A dimensionless measure of how elongated the ellipse is, in the range [0, 1).

Computed as √(1 − (b/a)²). A value of 0 means the ellipse is a perfect circle. Values approaching 1 indicate a very flat, elongated ellipse (like a comet's orbit). Eccentricity cannot reach 1 for a closed ellipse — that would be a parabola. 

public double Eccentricity { get; }

Property Value

double

Perimeter

The approximate perimeter of the ellipse using Ramanujan's formula: π · (3(a + b) − √((3a + b)(a + 3b))).

Ramanujan's formula is accurate to within about 0.04% for any ellipse, far better than the naïve approximation π(a + b). For a circle it reduces exactly to 2πr. 

public Length Perimeter { get; }

Property Value

Length

Rotation

The orientation of the ellipse. This Direction2 points along the positive end of the semi-major axis.

At East (0°) the major axis lies along +X. A rotation of North (90°) tilts the major axis to +Y. 

public Direction2 Rotation { get; }

Property Value

Direction2

SemiMajorAxis

The half-length of the longest axis of the ellipse.

Must be greater than zero and greater than or equal to SemiMinorAxis. 

public Length SemiMajorAxis { get; }

Property Value

Length

SemiMinorAxis

The half-length of the shortest axis of the ellipse.

Must be greater than zero and less than or equal to SemiMajorAxis. 

public Length SemiMinorAxis { get; }

Property Value

Length

Methods

Contains(LengthPoint2)

Returns true if point is inside or on the boundary of this ellipse.

The algorithm transforms the point into the ellipse's local frame (rotating and translating so that the ellipse becomes a unit circle), then checks whether the normalised coordinates satisfy (localX/a)² + (localY/b)² ≤ 1. 

public bool Contains(LengthPoint2 point)

Parameters

point LengthPoint2

The world-space point to test.

Returns

bool

true if the point is inside or on the boundary; false otherwise.

Examples

var e = new Ellipse2(LengthPoint2.Origin, Length.FromMeters(2), Length.FromMeters(1), Direction2.East);
bool inside  = e.Contains(LengthPoint2.FromMeters(1, 0));   // true  — on major-axis boundary
bool outside = e.Contains(LengthPoint2.FromMeters(0, 1.1)); // false — just past minor-axis boundary

DistanceTo(LengthPoint2)

Returns the distance from this shape to point. Returns UnitsNet.Length.Zero if the point is inside or on the boundary.

public Length DistanceTo(LengthPoint2 point)

Parameters

point LengthPoint2

The point to measure distance to.

Returns

Length

The shortest distance from the shape's boundary to point, or UnitsNet.Length.Zero if the point is contained.

Examples

Length d = shape.DistanceTo(LengthPoint2.FromMeters(10, 0));

GetBoundingRectangle()

Returns the axis-aligned bounding rectangle (AABB) that tightly encloses this ellipse.

For a rotated ellipse with semi-axes a (major) and b (minor) and rotation angle θ, the AABB half-widths are:

  • halfW = √(a²·cos²θ + b²·sin²θ)
  • halfH = √(a²·sin²θ + b²·cos²θ)

This formula is exact — it accounts for the ellipse's orientation so that the bounding box is as tight as possible regardless of rotation.

public Rectangle2 GetBoundingRectangle()

Returns

Rectangle2

The smallest axis-aligned Rectangle2 that fully contains this ellipse.

Examples

var e = new Ellipse2(LengthPoint2.Origin, Length.FromMeters(2), Length.FromMeters(1), Direction2.East);
Rectangle2 bb = e.GetBoundingRectangle();
// bb.Dimensions.X ≈ 4 m (2 × semi-major), bb.Dimensions.Y ≈ 2 m (2 × semi-minor)

GetClosestPoint(LengthPoint2)

Returns the point on the ellipse's boundary nearest to point. Uses Newton's method to find the angle parameter t on the ellipse that minimises distance. If the point is inside the ellipse, the boundary point is still returned (i.e. this always returns a boundary point).

public LengthPoint2 GetClosestPoint(LengthPoint2 point)

Parameters

point LengthPoint2

The world-space query point.

Returns

LengthPoint2

The nearest point on the ellipse boundary.

Examples

var e = new Ellipse2(LengthPoint2.Origin, Length.FromMeters(3), Length.FromMeters(2), Direction2.Zero);
LengthPoint2 p = e.GetClosestPoint(LengthPoint2.FromMeters(5, 0)); // (3, 0)

MoveCenterTo(LengthPoint2)

Returns a new Ellipse2 with its centre moved to newCenter, preserving all other properties.

public Ellipse2 MoveCenterTo(LengthPoint2 newCenter)

Parameters

newCenter LengthPoint2

The new centre position.

Returns

Ellipse2

A translated Ellipse2 centred at newCenter.

Examples

var moved = shape.MoveCenterTo(LengthPoint2.FromMeters(5, 0));

Operators

operator +(Ellipse2, LengthVector2)

Returns a new Ellipse2 translated by right. The axes and rotation are preserved; only the centre moves.

public static Ellipse2 operator +(Ellipse2 left, LengthVector2 right)

Parameters

left Ellipse2

The ellipse to translate.

right LengthVector2

The displacement vector.

Returns

Ellipse2

A new Ellipse2 with the centre moved by right.

Examples

var e = new Ellipse2(LengthPoint2.Origin, Length.FromMeters(2), Length.FromMeters(1), Direction2.East);
Ellipse2 moved = e + LengthVector2.FromMeters(3, 0);
// moved.Center == (3 m, 0 m)
v0.7.0 ▼