lsst::sphgeom::Circle Class Reference

Circle is a circular region on the unit sphere that contains its boundary. More...

#include <Circle.h>

Inheritance diagram for lsst::sphgeom::Circle:

Public Member Functions
	Circle ()
	This constructor creates an empty circle. More...
	Circle (UnitVector3d const &c)
	This constructor creates the circle with center c and squared chord length / opening angle of zero. More...
	Circle (UnitVector3d const &c, Angle a)
	This constructor creates a circle with center c and opening angle a. More...
	Circle (UnitVector3d const &c, double cl2)
	This constructor creates a circle with center c and squared chord length cl2. More...
bool	operator== (Circle const &c) const
bool	operator!= (Circle const &c) const
bool	isEmpty () const
bool	isFull () const
UnitVector3d const &	getCenter () const
	getCenter returns the center of this circle as a unit vector. More...
double	getSquaredChordLength () const
	getSquaredChordLength returns the squared length of chords between the circle center and points on the circle boundary. More...
Angle	getOpeningAngle () const
	getOpeningAngle returns the opening angle of this circle - that is, the angle between its center vector and points on its boundary. More...
bool	contains (Circle const &x) const
	contains returns true if the intersection of this circle and x is equal to x. More...
Circle &	dilateBy (Angle r)
	If r is positive, dilateBy increases the opening angle of this circle to include all points within angle r of its boundary. More...
Circle	dilatedBy (Angle r) const
Circle &	erodeBy (Angle r)
Circle	erodedBy (Angle r) const
double	getArea () const
	getArea returns the area of this circle in steradians. More...
Circle &	complement ()
	complement sets this circle to the closure of its complement. More...
Circle	complemented () const
	complemented returns the closure of the complement of this circle. More...
Relationship	relate (UnitVector3d const &v) const
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...
virtual bool	contains (UnitVector3d const &) const=0
	contains tests whether the given unit vector is inside this region. More...
bool	contains (double x, double y, double z) const
	contains tests whether the unit vector defined by the given (not necessarily normalized) coordinates is inside this region. More...
bool	contains (double lon, double lat) const
	contains tests whether the unit vector defined by the given longitude and latitude coordinates (in radians) is inside this region. More...
bool	isDisjointFrom (UnitVector3d const &x) const
bool	isDisjointFrom (Circle const &x) const
bool	intersects (UnitVector3d const &x) const
bool	intersects (Circle const &x) const
bool	isWithin (UnitVector3d const &) const
bool	isWithin (Circle const &x) const
Circle &	clipTo (UnitVector3d const &x)
Circle &	clipTo (Circle const &x)
Circle	clippedTo (UnitVector3d const &x) const
Circle	clippedTo (Circle const &x) const
Circle &	expandTo (UnitVector3d const &x)
Circle &	expandTo (Circle const &x)
Circle	expandedTo (UnitVector3d const &x) const
Circle	expandedTo (Circle const &x) const

Static Public Member Functions
static Circle	empty ()
static Circle	full ()
static double	squaredChordLengthFor (Angle openingAngle)
	squaredChordLengthFor computes and returns the squared chord length between points in S² that are separated by the given angle. More...
static Angle	openingAngleFor (double squaredChordLength)
	openingAngleFor computes and returns the angular separation between points in S² that are separated by the given squared chord length. More...
static std::unique_ptr< Circle >	decode (std::vector< uint8_t > const &s)
static std::unique_ptr< Circle >	decode (uint8_t const *buffer, size_t n)

Static Public Attributes
static constexpr uint8_t	TYPE_CODE = 'c'

Detailed Description

Circle is a circular region on the unit sphere that contains its boundary.

Internally, the circle is represented by its center vector and the squared length of the chords between its center and points on its boundary. This yields a fast point-in-circle test but, unlike a representation that uses the center vector and cosine of the circle opening angle, remains accurate for circles with very small opening angles.

Definition at line 46 of file Circle.h.

Constructor & Destructor Documentation

Circle() [1/4]

lsst::sphgeom::Circle::Circle ( )

inline

This constructor creates an empty circle.

Definition at line 65 of file Circle.h.

             :
        _center(UnitVector3d::Z()),
        _squaredChordLength(-1.0),
        _openingAngle(-1.0)
    {}

Circle() [2/4]

lsst::sphgeom::Circle::Circle ( UnitVector3d const &  c )

inlineexplicit

This constructor creates the circle with center c and squared chord length / opening angle of zero.

Because of rounding error, (v - c).squaredNorm() == 0.0 does not imply that v == c. Therefore calling contains(v) on the resulting circle may return true for unit vectors v != c.

Definition at line 76 of file Circle.h.

                                            :
        _center(c),
        _squaredChordLength(0.0),
        _openingAngle(0.0)
    {}

Circle() [3/4]

lsst::sphgeom::Circle::Circle ( UnitVector3d const &  c, Angle  a  )

inline

This constructor creates a circle with center c and opening angle a.

If a is negative or NaN, the circle will be empty, and if a is greater than or equal to PI, the circle will be full.

Definition at line 85 of file Circle.h.

                                            :
        _center(c),
        _squaredChordLength(squaredChordLengthFor(a)),
        _openingAngle(a)
    {}

Circle() [4/4]

lsst::sphgeom::Circle::Circle ( UnitVector3d const &  c, double  cl2  )

inline

This constructor creates a circle with center c and squared chord length cl2.

If cl2 is negative or NaN, the circle will be empty, and if cl2 is greater than or equal to 4, the circle will be full.

Definition at line 94 of file Circle.h.

                                               :
        _center(c),
        _squaredChordLength(cl2),
        _openingAngle(openingAngleFor(cl2))
    {}

Member Function Documentation

clippedTo() [1/2]

Circle lsst::sphgeom::Circle::clippedTo ( Circle const &  x ) const

inline

clippedTo returns the minimal bounding circle for the intersection of this circle and x.

Definition at line 169 of file Circle.h.

                                             {
        return Circle(*this).clipTo(x);
    }

clippedTo() [2/2]

Circle lsst::sphgeom::Circle::clippedTo ( UnitVector3d const &  x ) const

inline

clippedTo returns the minimal bounding circle for the intersection of this circle and x.

Definition at line 165 of file Circle.h.

                                                   {
        return Circle(*this).clipTo(x);
    }

clipTo() [1/2]

Circle & lsst::sphgeom::Circle::clipTo

(

Circle const &

x

)

clipTo sets this circle to the minimal bounding circle for the intersection of this circle and x.

Definition at line 96 of file Circle.cc.

                                        {
    if (isEmpty() || x.isFull()) {
        return *this;
    }
    if (isFull() || x.isEmpty()) {
        *this = x;
        return *this;
    }
    Angle a = _openingAngle;
    Angle b = x._openingAngle;
    NormalizedAngle cc(_center, x._center);
    if (cc > a + b + 4.0 * Angle(MAX_ASIN_ERROR)) {
        // This circle is disjoint from x.
        *this = empty();
        return *this;
    }
    // The circles (nearly) intersect, or one contains the other.
    // For now, take the easy route and just use the smaller of
    // the two circles as a bound on their intersection.
    //
    // TODO(smm): Compute the minimal bounding circle.
    if (b < a) {
        *this = x;
    }
    return *this;
}

clipTo() [2/2]

Circle & lsst::sphgeom::Circle::clipTo

(

UnitVector3d const &

x

)

clipTo sets this circle to the minimal bounding circle for the intersection of this circle and x.

Definition at line 91 of file Circle.cc.

                                              {
    *this = contains(x) ? Circle(x) : empty();
    return *this;
}

clone()

std::unique_ptr< Region > lsst::sphgeom::Circle::clone ( ) const

inlineoverridevirtual

clone returns a deep copy of this region.

Implements lsst::sphgeom::Region.

Definition at line 222 of file Circle.h.

                                                 {
        return std::unique_ptr<Circle>(new Circle(*this));
    }

complement()

Circle & lsst::sphgeom::Circle::complement

(

)

complement sets this circle to the closure of its complement.

Note that both the empty circle as well as all circles containing a single point are mapped to a full circle, so that taking the complement of a circle twice is not guaranteed to reproduce the original circle, even in the absence of rounding error.

Definition at line 197 of file Circle.cc.

                            {
    if (isEmpty()) {
        // The complement of an empty circle is a full circle.
        _squaredChordLength = 4.0;
        _openingAngle = Angle(PI);
    } else if (isFull()) {
        // The complement of a full circle is an empty circle.
        _squaredChordLength = -1.0;
        _openingAngle = Angle(-1.0);
    } else {
        _center = -_center;
        _squaredChordLength = 4.0 - _squaredChordLength;
        _openingAngle = Angle(PI) - _openingAngle;
    }
    return *this;
}

complemented()

Circle lsst::sphgeom::Circle::complemented ( ) const

inline

complemented returns the closure of the complement of this circle.

Definition at line 217 of file Circle.h.

{ return Circle(*this).complement(); }

contains() [1/5]

bool lsst::sphgeom::Circle::contains

(

Circle const &

x

)

const

contains returns true if the intersection of this circle and x is equal to x.

Definition at line 64 of file Circle.cc.

                                            {
    if (isFull() || x.isEmpty()) {
        return true;
    }
    if (isEmpty() || x.isFull()) {
        return false;
    }
    if (*this == x) {
        return true;
    }
    NormalizedAngle cc(_center, x._center);
    return _openingAngle >
           cc + x._openingAngle + 4.0 * Angle(MAX_ASIN_ERROR);
}

contains() [2/5]

bool lsst::sphgeom::Region::contains	(	double	lon,
		double	lat
	)		const

contains tests whether the unit vector defined by the given longitude and latitude coordinates (in radians) is inside this region.

Definition at line 104 of file Region.cc.

                                                  {
    return contains(UnitVector3d(LonLat::fromRadians(lon, lat)));
}

contains() [3/5]

bool lsst::sphgeom::Region::contains	(	double	x,
		double	y,
		double	z
	)		const

contains tests whether the unit vector defined by the given (not necessarily normalized) coordinates is inside this region.

Definition at line 100 of file Region.cc.

                                                        {
    return contains(UnitVector3d(x, y, z));
}

contains() [4/5]

virtual bool lsst::sphgeom::Region::contains ( UnitVector3d const &  ) const

virtual

contains tests whether the given unit vector is inside this region.

Implements lsst::sphgeom::Region.

contains() [5/5]

bool lsst::sphgeom::Circle::contains ( UnitVector3d const &  ) const

inlineoverridevirtual

contains tests whether the given unit vector is inside this region.

Implements lsst::sphgeom::Region.

Definition at line 230 of file Circle.h.

                                                         {
        return isFull() ||
               (v - _center).getSquaredNorm() <= _squaredChordLength;
    }

decode() [1/2]

static std::unique_ptr< Circle > lsst::sphgeom::Circle::decode ( std::vector< uint8_t > const &  s )

inlinestatic

decode deserializes a Circle from a byte string produced by encode.

Definition at line 251 of file Circle.h.

                                                                      {
        return decode(s.data(), s.size());
    }

decode() [2/2]

std::unique_ptr< Circle > lsst::sphgeom::Circle::decode ( uint8_t const *  buffer, size_t  n  )

static

decode deserializes a Circle from a byte string produced by encode.

Definition at line 345 of file Circle.cc.

                                                                     {
    if (buffer == nullptr || n != ENCODED_SIZE || *buffer != TYPE_CODE) {
        throw std::runtime_error("Byte-string is not an encoded Circle");
    }
    std::unique_ptr<Circle> circle(new Circle);
    ++buffer;
    double x = decodeDouble(buffer); buffer += 8;
    double y = decodeDouble(buffer); buffer += 8;
    double z = decodeDouble(buffer); buffer += 8;
    double squaredChordLength = decodeDouble(buffer); buffer += 8;
    double openingAngle = decodeDouble(buffer); buffer += 8;
    circle->_center = UnitVector3d::fromNormalized(x, y, z);
    circle->_squaredChordLength = squaredChordLength;
    circle->_openingAngle = Angle(openingAngle);
    return circle;
}

dilateBy()

Circle & lsst::sphgeom::Circle::dilateBy

(

Angle

r

)

If r is positive, dilateBy increases the opening angle of this circle to include all points within angle r of its boundary.

If r is negative, it decreases the opening angle to exclude those points instead.

If this circle is empty or full, or r is zero or NaN, there is no effect.

Definition at line 187 of file Circle.cc.

                                 {
    if (!isEmpty() && !isFull() &&
        (r.asRadians() > 0.0 || r.asRadians() < 0.0)) {
        Angle o = _openingAngle + r;
        _squaredChordLength = squaredChordLengthFor(o);
        _openingAngle = o;
    }
    return *this;
}

dilatedBy()

Circle lsst::sphgeom::Circle::dilatedBy ( Angle  r ) const

inline

Definition at line 200 of file Circle.h.

{ return Circle(*this).dilateBy(r); }

empty()

static Circle lsst::sphgeom::Circle::empty ( )

inlinestatic

Definition at line 50 of file Circle.h.

{ return Circle(); }

encode()

std::vector< uint8_t > lsst::sphgeom::Circle::encode ( ) const

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 332 of file Circle.cc.

                                        {
    std::vector<uint8_t> buffer;
    uint8_t tc = TYPE_CODE;
    buffer.reserve(ENCODED_SIZE);
    buffer.push_back(tc);
    encodeDouble(_center.x(), buffer);
    encodeDouble(_center.y(), buffer);
    encodeDouble(_center.z(), buffer);
    encodeDouble(_squaredChordLength, buffer);
    encodeDouble(_openingAngle.asRadians(), buffer);
    return buffer;
}

erodeBy()

Circle & lsst::sphgeom::Circle::erodeBy ( Angle  r )

inline

Definition at line 201 of file Circle.h.

{ return dilateBy(-r); }

erodedBy()

Circle lsst::sphgeom::Circle::erodedBy ( Angle  r ) const

inline

Definition at line 202 of file Circle.h.

{ return dilatedBy(-r); }

expandedTo() [1/2]

Circle lsst::sphgeom::Circle::expandedTo ( Circle const &  x ) const

inline

expandedTo returns the minimal bounding circle for the union of this circle and x.

Definition at line 187 of file Circle.h.

                                              {
        return Circle(*this).expandTo(x);
    }

expandedTo() [2/2]

Circle lsst::sphgeom::Circle::expandedTo ( UnitVector3d const &  x ) const

inline

expandedTo returns the minimal bounding circle for the union of this circle and x.

Definition at line 183 of file Circle.h.

                                                    {
        return Circle(*this).expandTo(x);
    }

expandTo() [1/2]

Circle & lsst::sphgeom::Circle::expandTo

(

Circle const &

x

)

expandTo minimally expands this circle to contain x.

Definition at line 147 of file Circle.cc.

                                          {
    if (isEmpty() || x.isFull()) {
        *this = x;
        return *this;
    }
    if (x.isEmpty() || isFull()) {
        return *this;
    }
    NormalizedAngle cc(_center, x._center);
    if (cc + x._openingAngle + 4.0 * Angle(MAX_ASIN_ERROR) <= _openingAngle) {
        // This circle contains x.
        return *this;
    }
    if (cc + _openingAngle + 4.0 * Angle(MAX_ASIN_ERROR) <= x._openingAngle) {
        // x contains this circle.
        *this = x;
        return *this;
    }
    // The circles intersect or are disjoint.
    Angle o = 0.5 * (cc + _openingAngle + x._openingAngle);
    if (o + 2.0 * Angle(MAX_ASIN_ERROR) >= Angle(PI)) {
        *this = full();
        return *this;
    }
    // Compute the normal vector for the plane defined by the circle centers.
    UnitVector3d n = UnitVector3d::orthogonalTo(_center, x._center);
    // The minimal bounding circle (MBC) includes unit vectors on the plane
    // with normal n that span from _center.rotatedAround(n, -_openingAngle)
    // to x._center.rotatedAround(n, x._openingAngle). The MBC center is the
    // midpoint of this interval.
    Angle r = o - _openingAngle;
    // Rotate _center by angle r around n to obtain the MBC center. This is
    // done using Rodriques' formula, simplified by taking advantage of the
    // orthogonality of _center and n.
    _center = UnitVector3d(_center * cos(r) + n.cross(_center) * sin(r));
    _squaredChordLength = squaredChordLengthFor(o + Angle(MAX_ASIN_ERROR));
    _openingAngle = o + Angle(MAX_ASIN_ERROR);
    return *this;
}

expandTo() [2/2]

Circle & lsst::sphgeom::Circle::expandTo

(

UnitVector3d const &

x

)

expandTo minimally expands this circle to contain x.

Definition at line 123 of file Circle.cc.

                                                {
    // For any circle c and unit vector x, c.expandTo(x).contains(x)
    // should return true.
    if (isEmpty()) {
        *this = Circle(x);
    } else if (!contains(x)) {
        // Compute the normal vector for the plane defined by _center and x.
        UnitVector3d n = UnitVector3d::orthogonalTo(_center, x);
        // The minimal bounding circle (MBC) includes unit vectors on the plane
        // with normal n that span from _center.rotatedAround(n, -_openingAngle)
        // to x. The MBC center is the midpoint of this interval.
        NormalizedAngle cx(_center, x);
        Angle o = 0.5 * (cx + _openingAngle);
        Angle r = 0.5 * (cx - _openingAngle);
        // Rotate _center by angle r around n to obtain the MBC center. This is
        // done using Rodriques' formula, simplified by taking advantage of the
        // orthogonality of _center and n.
        _center = UnitVector3d(_center * cos(r) + n.cross(_center) * sin(r));
        _squaredChordLength = squaredChordLengthFor(o + Angle(MAX_ASIN_ERROR));
        _openingAngle = o + Angle(MAX_ASIN_ERROR);
    }
    return *this;
}

full()

static Circle lsst::sphgeom::Circle::full ( )

inlinestatic

Definition at line 52 of file Circle.h.

{ return Circle(UnitVector3d::Z(), 4.0); }

getArea()

double lsst::sphgeom::Circle::getArea ( ) const

inline

getArea returns the area of this circle in steradians.

Definition at line 205 of file Circle.h.

                           {
        return PI * std::max(0.0, std::min(_squaredChordLength, 4.0));
    }

getBoundingBox()

Box lsst::sphgeom::Circle::getBoundingBox ( ) const

overridevirtual

getBoundingBox returns a bounding-box for this region.

Implements lsst::sphgeom::Region.

Definition at line 214 of file Circle.cc.

                                 {
    LonLat c(_center);
    Angle h = _openingAngle + 2.0 * Angle(MAX_ASIN_ERROR);
    NormalizedAngle w(Box::halfWidthForCircle(h, c.getLat()) +
                      Angle(MAX_ASIN_ERROR));
    return Box(c, w, h);
}

getBoundingBox3d()

Box3d lsst::sphgeom::Circle::getBoundingBox3d ( ) const

overridevirtual

getBoundingBox3d returns a 3-dimensional bounding-box for this region.

Implements lsst::sphgeom::Region.

Definition at line 222 of file Circle.cc.

                                     {
    static double const MAX_BOUNDARY_ERROR = 6.2e-16; // > 5.5ε, where ε = 2^-53
    if (isEmpty()) {
        return Box3d();
    }
    if (isFull()) {
        return Box3d::aroundUnitSphere();
    }
    // Given circle center c and standard basis vector eᵢ, to check whether
    // ±eᵢ is inside the circle we need to check that (c ∓ eᵢ)·(c ∓ eᵢ) ≤ s.
    // Since c·c = 1, eᵢ·eᵢ = 1 (c and eᵢ are unit vectors) this is the
    // same as checking that 2 ∓ 2c·eᵢ ≤ s, or 2 ∓ 2cᵢ ≤ s, where cᵢ is
    // the i-th component of c.
    //
    // Besides any standard basis vectors inside the circle, the bounding box
    // must also include the circle boundary. To find the extent of this
    // boundary along a particular axis, note that we can write the i-th
    // component of the circle center vector as the sine of a latitude angle
    // (treating the i-th standard basis vector as "north"). So given a circle
    // opening angle θ, the desired extent is
    //
    //     [min(sin(asin(cᵢ) ± θ)), max(sin(asin(cᵢ) ± θ))]
    //
    // which can be simplified using the usual trigonometric identities to
    // arrive at the code below.
    Interval1d e[3];
    double s = sin(_openingAngle);
    double c = cos(_openingAngle);
    for (int i = 0; i < 3; ++i) {
        double ci = _center(i);
        double di = std::sqrt(1.0 - ci * ci);
        double bmin = 1.0, bmax = -1.0;
        if (2.0 - 2.0 * ci <= _squaredChordLength) {
            bmax = 1.0;
        }
        if (2.0 + 2.0 * ci <= _squaredChordLength) {
            bmin = -1.0;
        }
        double b0 = ci * c + di * s;
        bmax = std::max(bmax, b0 + MAX_BOUNDARY_ERROR);
        bmin = std::min(bmin, b0 - MAX_BOUNDARY_ERROR);
        double b1 = ci * c - di * s;
        bmax = std::max(bmax, b1 + MAX_BOUNDARY_ERROR);
        bmin = std::min(bmin, b1 - MAX_BOUNDARY_ERROR);
        e[i] = Interval1d(std::max(-1.0, bmin), std::min(1.0, bmax));
    }
    return Box3d(e[0], e[1], e[2]);
}

getBoundingCircle()

Circle lsst::sphgeom::Circle::getBoundingCircle ( ) const

inlineoverridevirtual

getBoundingCircle returns a bounding-circle for this region.

Implements lsst::sphgeom::Region.

Definition at line 228 of file Circle.h.

{ return *this; }

getCenter()

UnitVector3d const & lsst::sphgeom::Circle::getCenter ( ) const

inline

getCenter returns the center of this circle as a unit vector.

It is arbitrary for empty and full circles.

Definition at line 118 of file Circle.h.

{ return _center; }

getOpeningAngle()

Angle lsst::sphgeom::Circle::getOpeningAngle ( ) const

inline

getOpeningAngle returns the opening angle of this circle - that is, the angle between its center vector and points on its boundary.

It is negative or NaN for empty circles, and at least PI for full circles.

Definition at line 128 of file Circle.h.

{ return _openingAngle; }

getSquaredChordLength()

double lsst::sphgeom::Circle::getSquaredChordLength ( ) const

inline

getSquaredChordLength returns the squared length of chords between the circle center and points on the circle boundary.

It is negative or NaN for empty circles, and at least 4 for full circles.

Definition at line 123 of file Circle.h.

{ return _squaredChordLength; }

intersects() [1/2]

bool lsst::sphgeom::Circle::intersects ( Circle const &  x ) const

inline

intersects returns true if the intersection of this circle and x is non-empty.

Definition at line 145 of file Circle.h.

{ return !isDisjointFrom(x); }

intersects() [2/2]

bool lsst::sphgeom::Circle::intersects ( UnitVector3d const &  x ) const

inline

intersects returns true if the intersection of this circle and x is non-empty.

Definition at line 144 of file Circle.h.

{ return contains(x); }

isDisjointFrom() [1/2]

bool lsst::sphgeom::Circle::isDisjointFrom

(

Circle const &

x

)

const

isDisjointFrom returns true if the intersection of this circle and x is empty.

Definition at line 79 of file Circle.cc.

                                                  {
    if (isEmpty() || x.isEmpty()) {
        return true;
    }
    if (isFull() || x.isFull()) {
        return false;
    }
    NormalizedAngle cc(_center, x._center);
    return cc > _openingAngle + x._openingAngle +
                4.0 * Angle(MAX_ASIN_ERROR);
}

isDisjointFrom() [2/2]

bool lsst::sphgeom::Circle::isDisjointFrom ( UnitVector3d const &  x ) const

inline

isDisjointFrom returns true if the intersection of this circle and x is empty.

Definition at line 137 of file Circle.h.

{ return !contains(x); }

isEmpty()

bool lsst::sphgeom::Circle::isEmpty ( ) const

inline

Definition at line 109 of file Circle.h.

                         {
        // Return true when _squaredChordLength is negative or NaN.
        return !(_squaredChordLength >= 0.0);
    }

isFull()

bool lsst::sphgeom::Circle::isFull ( ) const

inline

Definition at line 114 of file Circle.h.

{ return _squaredChordLength >= 4.0; }

isWithin() [1/2]

bool lsst::sphgeom::Circle::isWithin ( Circle const &  x ) const

inline

isWithin returns true if the intersection of this circle and x is this circle.

Definition at line 152 of file Circle.h.

{ return x.contains(*this); }

isWithin() [2/2]

bool lsst::sphgeom::Circle::isWithin ( UnitVector3d const &  ) const

inline

isWithin returns true if the intersection of this circle and x is this circle.

Definition at line 151 of file Circle.h.

{ return isEmpty(); }

openingAngleFor()

Angle lsst::sphgeom::Circle::openingAngleFor ( double  squaredChordLength )

static

openingAngleFor computes and returns the angular separation between points in S² that are separated by the given squared chord length.

The squared chord length l² and angle θ are related by l² = 4 sin²(θ/2).

Definition at line 52 of file Circle.cc.

                                                       {
    // Note: the maximum error in the opening angle (and circle bounding box
    // width) computations is ~ 2 * MAX_ASIN_ERROR.
    if (squaredChordLength < 0.0) {
        return Angle(-1.0);
    }
    if (squaredChordLength >= 4.0) {
        return Angle(PI);
    }
    return Angle(2.0 * std::asin(0.5 * std::sqrt(squaredChordLength)));
}

operator!=()

bool lsst::sphgeom::Circle::operator!= ( Circle const &  c ) const

inline

Definition at line 107 of file Circle.h.

{ return !(*this == c); }

operator==()

bool lsst::sphgeom::Circle::operator== ( Circle const &  c ) const

inline

Definition at line 100 of file Circle.h.

                                            {
        return (isEmpty() && c.isEmpty()) ||
               (isFull() && c.isFull()) ||
               (_center == c._center &&
                _squaredChordLength == c._squaredChordLength &&
                _openingAngle == c._openingAngle);
    }

relate() [1/6]

Relationship lsst::sphgeom::Circle::relate ( Box const &  ) const

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:

• Bit S & DISJOINT is set only if A and B do not have any points in common.
• Bit S & CONTAINS is set only if A contains all points in B.
• Bit 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 280 of file Circle.cc.

                                               {
    // Box-Circle relations are implemented by Box.
    return invert(b.relate(*this));
}

relate() [2/6]

Relationship lsst::sphgeom::Circle::relate ( Circle const &  ) const

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:

• Bit S & DISJOINT is set only if A and B do not have any points in common.
• Bit S & CONTAINS is set only if A contains all points in B.
• Bit 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 285 of file Circle.cc.

                                                  {
    if (isEmpty()) {
        if (c.isEmpty()) {
            return CONTAINS | DISJOINT | WITHIN;
        }
        return DISJOINT | WITHIN;
    } else if (c.isEmpty()) {
        return CONTAINS | DISJOINT;
    }
    // Neither circle is empty.
    if (isFull()) {
        if (c.isFull()) {
            return CONTAINS | WITHIN;
        }
        return CONTAINS;
    } else if (c.isFull()) {
        return WITHIN;
    }
    // Special case equality, which can be missed by logic below due to
    // round-off error.
    if (*this == c) {
        return CONTAINS | WITHIN;
    }
    // Neither circle is full.
    NormalizedAngle cc(_center, c._center);
    if (cc > _openingAngle + c._openingAngle + 4.0 * Angle(MAX_ASIN_ERROR)) {
        return DISJOINT;
    }
    if (cc + c._openingAngle + 4.0 * Angle(MAX_ASIN_ERROR) <= _openingAngle) {
        return CONTAINS;
    } else if (cc + _openingAngle + 4.0 * Angle(MAX_ASIN_ERROR) <=
               c._openingAngle) {
        return WITHIN;
    }
    return INTERSECTS;
}

relate() [3/6]

Relationship lsst::sphgeom::Circle::relate ( ConvexPolygon const &  ) const

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:

• Bit S & DISJOINT is set only if A and B do not have any points in common.
• Bit S & CONTAINS is set only if A contains all points in B.
• Bit 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 322 of file Circle.cc.

                                                         {
    // ConvexPolygon-Circle relations are implemented by ConvexPolygon.
    return invert(p.relate(*this));
}

relate() [4/6]

Relationship lsst::sphgeom::Circle::relate ( Ellipse const &  ) const

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:

• Bit S & DISJOINT is set only if A and B do not have any points in common.
• Bit S & CONTAINS is set only if A contains all points in B.
• Bit 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 Circle.cc.

                                                   {
    // Ellipse-Circle relations are implemented by Ellipse.
    return invert(e.relate(*this));
}

relate() [5/6]

Relationship lsst::sphgeom::Circle::relate ( Region const &  ) const

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:

• Bit S & DISJOINT is set only if A and B do not have any points in common.
• Bit S & CONTAINS is set only if A contains all points in B.
• Bit 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 237 of file Circle.h.

                                                         {
        // Dispatch on the type of r.
        return invert(r.relate(*this));
    }

relate() [6/6]

Relationship lsst::sphgeom::Circle::relate

(

UnitVector3d const &

v

)

const

Definition at line 271 of file Circle.cc.

                                                        {
    if (contains(v)) {
        return CONTAINS;
    } else if (isEmpty()) {
        return DISJOINT | WITHIN;
    }
    return DISJOINT;
}

squaredChordLengthFor()

double lsst::sphgeom::Circle::squaredChordLengthFor ( Angle  openingAngle )

static

squaredChordLengthFor computes and returns the squared chord length between points in S² that are separated by the given angle.

The squared chord length l² and angle θ are related by l² = 4 sin²(θ/2).

Definition at line 41 of file Circle.cc.

                                            {
    if (a.asRadians() < 0.0) {
        return -1.0;
    }
    if (a.asRadians() >= PI) {
        return 4.0;
    }
    double s = sin(0.5 * a);
    return 4.0 * s * s;
}

Member Data Documentation

TYPE_CODE

constexpr uint8_t lsst::sphgeom::Circle::TYPE_CODE = 'c'

staticconstexpr

Definition at line 48 of file Circle.h.

---

The documentation for this class was generated from the following files:

• /j/snowflake/release/lsstsw/stack/lsst-scipipe-4.0.1/Linux64/sphgeom/ga1cf026fa3+ac198e9f13/include/lsst/sphgeom/Circle.h
• /j/snowflake/release/lsstsw/stack/lsst-scipipe-4.0.1/Linux64/sphgeom/ga1cf026fa3+ac198e9f13/src/Circle.cc