LSSTApplications
20.0.0
LSSTDataManagementBasePackage
|
Ellipse
is an elliptical region on the sphere.
More...
#include <Ellipse.h>
Public Member Functions | |
Ellipse () | |
This constructor creates an empty ellipse. More... | |
Ellipse (Circle const &c) | |
This constructor creates an ellipse corresponding to the given circle. More... | |
Ellipse (UnitVector3d const &v, Angle alpha=Angle(0.0)) | |
This constructor creates an ellipse corresponding to the circle with the given center and opening angle. More... | |
Ellipse (UnitVector3d const &f1, UnitVector3d const &f2, Angle alpha) | |
This constructor creates an ellipse with the given foci and semi-axis angle. More... | |
Ellipse (UnitVector3d const ¢er, Angle alpha, Angle beta, Angle orientation) | |
This constructor creates an ellipse with the given center, semi-axis angles, and orientation. More... | |
bool | operator== (Ellipse const &e) const |
bool | operator!= (Ellipse const &e) const |
bool | isEmpty () const |
bool | isFull () const |
bool | isGreatCircle () const |
bool | isCircle () const |
Matrix3d const & | getTransformMatrix () const |
getTransformMatrix returns the orthogonal matrix that maps vectors to the basis in which the quadratic form corresponding to this ellipse is diagonal. More... | |
UnitVector3d | getCenter () const |
getCenter returns the center of the ellipse as a unit vector. More... | |
UnitVector3d | getF1 () const |
getF1 returns the first focal point of the ellipse. More... | |
UnitVector3d | getF2 () const |
getF2 returns the second focal point of the ellipse. More... | |
Angle | getAlpha () const |
getAlpha returns α, the first semi-axis length of the ellipse. More... | |
Angle | getBeta () const |
getBeta returns β, the second semi-axis length of the ellipse. More... | |
Angle | getGamma () const |
getGamma returns ɣ ∈ [0, π/2], half of the angle between the foci. More... | |
Ellipse & | complement () |
complement sets this ellipse to the closure of its complement. More... | |
Ellipse | complemented () const |
complemented returns the closure of the complement of this ellipse. More... | |
std::unique_ptr< Region > | clone () const override |
clone returns a deep copy of this region. More... | |
Box | getBoundingBox () const override |
getBoundingBox returns a bounding-box for this region. More... | |
Box3d | getBoundingBox3d () const override |
getBoundingBox3d returns a 3-dimensional bounding-box for this region. More... | |
Circle | getBoundingCircle () const override |
getBoundingCircle returns a bounding-circle for this region. More... | |
bool | contains (UnitVector3d const &v) const override |
contains tests whether the given unit vector is inside this region. More... | |
Relationship | relate (Region const &r) const override |
Relationship | relate (Box const &) const override |
Relationship | relate (Circle const &) const override |
Relationship | relate (ConvexPolygon const &) const override |
Relationship | relate (Ellipse const &) const override |
std::vector< uint8_t > | encode () const override |
encode serializes this region into an opaque byte string. More... | |
Static Public Member Functions | |
static Ellipse | empty () |
static Ellipse | full () |
static std::unique_ptr< Ellipse > | decode (std::vector< uint8_t > const &s) |
static std::unique_ptr< Ellipse > | decode (uint8_t const *buffer, size_t n) |
Static Public Attributes | |
static constexpr uint8_t | TYPE_CODE = 'e' |
Ellipse
is an elliptical region on the sphere.
A spherical ellipse is defined as the set of unit vectors v such that:
d(v,f₁) + d(v,f₂) ≤ 2α (Eq. 1)
where f₁ and f₂ are unit vectors corresponding to the foci of the ellipse, d is the function that returns the angle between its two input vectors, and α is a constant.
If 2α < d(f₁,f₂), no point in S² satisfies the inequality, and the ellipse is empty. If f₁ = f₂, the ellipse is a circle with opening angle α. The ellipse defined by foci -f₁ and -f₂, and angle π - α satisfies:
d(v,-f₁) + d(v,-f₂) ≤ 2(π - α) → π - d(v,f₁) + π - d(v,f₂) ≤ 2π - 2α → d(v,f₁) + d(v,f₂) ≥ 2α
In other words, it is the closure of the complement of the ellipse defined by f₁, f₂ and α. Therefore if 2π - 2α ≤ d(f₁,f₂), all points in S² satisfy Eq 1. and we say that the ellipse is full.
Consider now the equation d(v,f₁) + d(v,f₂) = 2α for v ∈ ℝ³. We know that
cos(d(v,fᵢ)) = (v·fᵢ)/(‖v‖‖fᵢ‖) = (v·fᵢ)/‖v‖ (since ‖fᵢ‖ = 1)
and, because sin²θ + cos²θ = 1 and ‖v‖² = v·v,
sin(d(v,fᵢ)) = √(v·v - (v·fᵢ)²)/‖v‖
Starting with:
d(v,f₁) + d(v,f₂) = 2α
we take the cosine of both sides, apply the angle sum identity for cosine, and substitute the expressions above to obtain:
cos(d(v,f₁) + d(v,f₂)) = cos 2α → cos(d(v,f₁)) cos(d(v,f₂)) - sin(d(v,f₁)) sin(d(v,f₂)) = cos 2α → (v·f₁) (v·f₂) - √(v·v - (v·f₁)²) √(v·v - (v·f₂)²) = cos 2α (v·v)
Rearranging to place the square roots on the RHS, squaring both sides, and simplifying:
((v·f₁) (v·f₂) - cos 2α (v·v))² = (v·v - (v·f₁)²) (v·v - (v·f₂)²) → cos²2α (v·v) - 2 cos 2α (v·f₁) (v·f₂) = (v·v) - (v·f₁)² - (v·f₂)² → sin²2α (v·v) + 2 cos 2α (v·f₁) (v·f₂) - (v·f₁)² - (v·f₂)² = 0 (Eq. 2)
Note in particular that if α = π/2, the above simplifies to:
(v·f₁ + v·f₂)² = 0 ↔ v·(f₁ + f₂) = 0
That is, the equation describes the great circle obtained by intersecting S² with the plane having normal vector f₁ + f₂.
Writing v = (x, y, z) and substituting into Eq. 2, we see that the LHS is a homogeneous polynomial of degree two in 3 variables, or a ternary quadratic form. The matrix representation of this quadratic form is the symmetric 3 by 3 matrix Q such that:
vᵀ Q v = 0
is equivalent to Eq. 2. Consider now the orthonormal basis vectors:
b₀ = (f₁ - f₂)/‖f₁ - f₂‖ b₁ = (f₁ × f₂)/‖f₁ × f₂‖ b₂ = (f₁ + f₂)/‖f₁ + f₂‖
where x denotes the vector cross product. Let S be the matrix with these basis vectors as rows. Given coordinates u in this basis, we have v = Sᵀ u, and:
(Sᵀ u)ᵀ Q (Sᵀ u) = 0 ↔ uᵀ (S Q Sᵀ) u = 0
We now show that D = S Q Sᵀ is diagonal. Let d(f₁,f₂) = 2ɣ. The coordinates of f₁ and f₂ in this new basis are f₁ = (sin ɣ, 0, cos ɣ) and f₂ = (-sin ɣ, 0, cos ɣ). Writing u = (x, y, z) and substituting into Eq. 2:
sin²2α (u·u) + 2 cos 2α (u·f₁) (u·f₂) - (u·f₁)² - (u·f₂)² = 0
we obtain:
(sin²2α - 2 cos 2α sin²ɣ - 2 sin²ɣ) x² + (sin²2α) y² + (sin²2α + 2 cos 2α cos²ɣ - 2 cos²ɣ) z² = 0
Now sin²2α = 4 sin²α cos²α, cos 2α = cos²α - sin²α, so that:
(cos²α (sin²α - sin²ɣ)) x² + (sin²α cos²α) y² + (sin²α (cos²α - cos²ɣ)) z² = 0
Dividing by sin²α (cos²ɣ - cos²α), and letting cos β = cos α / cos ɣ:
x² cot²α + y² cot²β - z² = 0 (Eq. 3)
This says that the non-zero elements of S Q Sᵀ are on the diagonal and equal to (cot²α, cot²β, -1) up to scale. In other words, the boundary of a spherical ellipse is given by the intersection of S² and an elliptical cone in ℝ³ passing through the origin. Because z = 0 → x,y = 0 it is evident that the boundary of a spherical ellipse is hemispherical.
If 0 < α < π/2, then β ≤ α, and α is the semi-major axis angle of the ellipse while β is the semi-minor axis angle.
If α = π/2, then the spherical ellipse corresponds to a hemisphere.
If π/2 < α < π, then β ≥ α, and α is the semi-minor axis angle of the ellipse, while β is the semi-major axis angle.
Internal state consists of the orthogonal transformation matrix S that maps the ellipse center to (0, 0, 1), as well as |cot α| and |cot β| (enough to reconstruct D, and hence Q), and α, β, ɣ.
In fact, a = α - π/2, b = β - π/2 are stored instead of α and β. This is for two reasons. The first is that when taking the complement of an ellipse, α is mapped to π - α but a is mapped to -a (and b → -b). As a result, taking the complement can be implemented using only changes of sign, and is therefore exact. The other reason is that |cot(α)| = |tan(a)|, and tan is more convenient numerically. In particular, cot(0) is undefined, but tan is finite since a is rational and cannot be exactly equal to ±π/2.
|
inline |
|
inlineexplicit |
|
inlineexplicit |
lsst::sphgeom::Ellipse::Ellipse | ( | UnitVector3d const & | f1, |
UnitVector3d const & | f2, | ||
Angle | alpha | ||
) |
This constructor creates an ellipse with the given foci and semi-axis angle.
Definition at line 42 of file Ellipse.cc.
lsst::sphgeom::Ellipse::Ellipse | ( | UnitVector3d const & | center, |
Angle | alpha, | ||
Angle | beta, | ||
Angle | orientation | ||
) |
This constructor creates an ellipse with the given center, semi-axis angles, and orientation.
The orientation is defined as the position angle (east of north) of the first axis with respect to the north pole. Note that both alpha and beta must be less than, greater than, or equal to PI/2.
Definition at line 102 of file Ellipse.cc.
|
inlineoverridevirtual |
clone
returns a deep copy of this region.
Implements lsst::sphgeom::Region.
|
inline |
|
inline |
|
overridevirtual |
contains
tests whether the given unit vector is inside this region.
Implements lsst::sphgeom::Region.
Definition at line 160 of file Ellipse.cc.
|
inlinestatic |
|
static |
decode
deserializes an Ellipse from a byte string produced by encode.
Definition at line 357 of file Ellipse.cc.
|
inlinestatic |
|
overridevirtual |
encode
serializes this region into an opaque byte string.
Byte strings emitted by encode can be deserialized with decode.
Implements lsst::sphgeom::Region.
Definition at line 339 of file Ellipse.cc.
|
inlinestatic |
|
inline |
|
inline |
|
overridevirtual |
getBoundingBox
returns a bounding-box for this region.
Implements lsst::sphgeom::Region.
Definition at line 190 of file Ellipse.cc.
|
overridevirtual |
getBoundingBox3d
returns a 3-dimensional bounding-box for this region.
Implements lsst::sphgeom::Region.
Definition at line 237 of file Ellipse.cc.
|
overridevirtual |
getBoundingCircle
returns a bounding-circle for this region.
Implements lsst::sphgeom::Region.
Definition at line 241 of file Ellipse.cc.
|
inline |
getCenter
returns the center of the ellipse as a unit vector.
|
inline |
|
inline |
|
inline |
|
inline |
|
inline |
|
inline |
|
inline |
|
inline |
|
inline |
|
inline |
|
overridevirtual |
relate
computes the spatial relationships between this region A and another region B. The return value S is a bitset with the following properties:
S & DISJOINT
is set only if A and B do not have any points in common.S & CONTAINS
is set only if A contains all points in B.S & WITHIN
is set only if B contains all points in A.Said another way: if the CONTAINS, WITHIN or DISJOINT bit is set, then the corresponding spatial relationship between the two regions holds conclusively. If it is not set, the relationship may or may not hold.
These semantics allow for conservative relationship computations. In particular, a Region may choose to implement relate
by replacing itself and/or the argument with a simplified bounding region.
Implements lsst::sphgeom::Region.
Definition at line 246 of file Ellipse.cc.
|
overridevirtual |
relate
computes the spatial relationships between this region A and another region B. The return value S is a bitset with the following properties:
S & DISJOINT
is set only if A and B do not have any points in common.S & CONTAINS
is set only if A contains all points in B.S & WITHIN
is set only if B contains all points in A.Said another way: if the CONTAINS, WITHIN or DISJOINT bit is set, then the corresponding spatial relationship between the two regions holds conclusively. If it is not set, the relationship may or may not hold.
These semantics allow for conservative relationship computations. In particular, a Region may choose to implement relate
by replacing itself and/or the argument with a simplified bounding region.
Implements lsst::sphgeom::Region.
Definition at line 327 of file Ellipse.cc.
|
overridevirtual |
relate
computes the spatial relationships between this region A and another region B. The return value S is a bitset with the following properties:
S & DISJOINT
is set only if A and B do not have any points in common.S & CONTAINS
is set only if A contains all points in B.S & WITHIN
is set only if B contains all points in A.Said another way: if the CONTAINS, WITHIN or DISJOINT bit is set, then the corresponding spatial relationship between the two regions holds conclusively. If it is not set, the relationship may or may not hold.
These semantics allow for conservative relationship computations. In particular, a Region may choose to implement relate
by replacing itself and/or the argument with a simplified bounding region.
Implements lsst::sphgeom::Region.
Definition at line 331 of file Ellipse.cc.
|
overridevirtual |
relate
computes the spatial relationships between this region A and another region B. The return value S is a bitset with the following properties:
S & DISJOINT
is set only if A and B do not have any points in common.S & CONTAINS
is set only if A contains all points in B.S & WITHIN
is set only if B contains all points in A.Said another way: if the CONTAINS, WITHIN or DISJOINT bit is set, then the corresponding spatial relationship between the two regions holds conclusively. If it is not set, the relationship may or may not hold.
These semantics allow for conservative relationship computations. In particular, a Region may choose to implement relate
by replacing itself and/or the argument with a simplified bounding region.
Implements lsst::sphgeom::Region.
Definition at line 335 of file Ellipse.cc.
|
inlineoverridevirtual |
relate
computes the spatial relationships between this region A and another region B. The return value S is a bitset with the following properties:
S & DISJOINT
is set only if A and B do not have any points in common.S & CONTAINS
is set only if A contains all points in B.S & WITHIN
is set only if B contains all points in A.Said another way: if the CONTAINS, WITHIN or DISJOINT bit is set, then the corresponding spatial relationship between the two regions holds conclusively. If it is not set, the relationship may or may not hold.
These semantics allow for conservative relationship computations. In particular, a Region may choose to implement relate
by replacing itself and/or the argument with a simplified bounding region.
Implements lsst::sphgeom::Region.
|
staticconstexpr |