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.
	Circle (UnitVector3d const &c)
	This constructor creates the circle with center c and squared chord length / opening angle of zero.
	Circle (UnitVector3d const &c, Angle a)
	This constructor creates a circle with center c and opening angle a.
	Circle (UnitVector3d const &c, double cl2)
	This constructor creates a circle with center c and squared chord length cl2.
bool	operator== (Circle const &c) const
bool	operator!= (Circle const &c) const
bool	isEmpty () const override
	isEmpty returns true when a region does not contain any points.
bool	isFull () const
UnitVector3d const &	getCenter () const
	getCenter returns the center of this circle as a unit vector.
double	getSquaredChordLength () const
	getSquaredChordLength returns the squared length of chords between the circle center and points on the circle boundary.
Angle	getOpeningAngle () const
	getOpeningAngle returns the opening angle of this circle - that is, the angle between its center vector and points on its boundary.
bool	contains (Circle const &x) const
	contains returns true if the intersection of this circle and x is equal to x.
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.
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.
Circle &	complement ()
	complement sets this circle to the closure of its complement.
Circle	complemented () const
	complemented returns the closure of the complement of this circle.
Relationship	relate (UnitVector3d const &v) const
std::unique_ptr< Region >	clone () const override
	clone returns a deep copy of this region.
Box	getBoundingBox () const override
	getBoundingBox returns a bounding-box for this region.
Box3d	getBoundingBox3d () const override
	getBoundingBox3d returns a 3-dimensional bounding-box for this region.
Circle	getBoundingCircle () const override
	getBoundingCircle returns a bounding-circle for this region.
bool	contains (UnitVector3d const &v) const override
	contains tests whether the given unit vector is inside this region.
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
TriState	overlaps (Region const &other) const override
TriState	overlaps (Box const &) const override
TriState	overlaps (Circle const &) const override
TriState	overlaps (ConvexPolygon const &) const override
TriState	overlaps (Ellipse const &) const override
std::vector< std::uint8_t >	encode () const override
	encode serializes this region into an opaque byte string.
virtual bool	contains (UnitVector3d const &) const=0
	contains tests whether the given unit vector is inside this region.
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.
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.
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.
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.
static std::vector< std::unique_ptr< Region > >	getRegions (Region const &region)
	getRegions returns a vector of Region.
static std::unique_ptr< Circle >	decode (std::vector< std::uint8_t > const &s)
static std::unique_ptr< Circle >	decode (std::uint8_t const *buffer, size_t n)
static std::unique_ptr< Region >	decodeBase64 (std::string const &s)
static std::unique_ptr< Region >	decodeBase64 (std::string_view const &s)
static TriState	decodeOverlapsBase64 (std::string const &s)
static TriState	decodeOverlapsBase64 (std::string_view const &s)

Static Public Attributes
static constexpr std::uint8_t	TYPE_CODE = 'c'

Static Protected Member Functions
static TriState	_relationship_to_overlaps (Relationship r)

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 54 of file Circle.h.

Constructor & Destructor Documentation

Circle() [1/4]

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

inline

This constructor creates an empty circle.

Definition at line 73 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 84 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 93 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 102 of file Circle.h.

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

Member Function Documentation

_relationship_to_overlaps()

static TriState lsst::sphgeom::Region::_relationship_to_overlaps ( Relationship r )

inlinestaticprotectedinherited

Definition at line 206 of file Region.h.

                                                              {
        // `relate` returns exact relation when specific bit is set, if it is
        // not then relation may be true or not.
        if ((r & DISJOINT) == DISJOINT) {
            return TriState(false);
        }
        if ((r & (WITHIN | CONTAINS)).any()) {
            return TriState(true);
        }
        return TriState();
    }

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 177 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 173 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 103 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 98 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 230 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 204 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 225 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 71 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 117 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 113 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 238 of file Circle.h.

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

decode() [1/2]

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

static

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

Definition at line 371 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;
}

decode() [2/2]

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

inlinestatic

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

Definition at line 267 of file Circle.h.

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

decodeBase64() [1/2]

static std::unique_ptr< Region > lsst::sphgeom::Region::decodeBase64 ( std::string const & s )

inlinestaticinherited

decodeBase64 deserializes a Region from an ASCII string produced by encode and then base64-encoding that result.

This method also interprets ':' as a delimiter for the elements of a UnionRegion, to support cases where a union of region is constructed server-side in a database as a concatenation with that delimiter.

Definition at line 176 of file Region.h.

                                                                   {
        return decodeBase64(s);
    }

decodeBase64() [2/2]

std::unique_ptr< Region > lsst::sphgeom::Region::decodeBase64 ( std::string_view const & s )

staticinherited

decodeBase64 deserializes a Region from an ASCII string produced by encode and then base64-encoding that result.

This method also interprets ':' as a delimiter for the elements of a UnionRegion, to support cases where a union of region is constructed server-side in a database as a concatenation with that delimiter.

Definition at line 93 of file Region.cc.

                                                                   {
    if (s.empty()) {
        return std::unique_ptr<UnionRegion>(new UnionRegion({}));
    }
    auto region_begin = s.begin();
    auto region_end = std::find(s.begin(), s.end(), ':');
    if (region_end != s.end()) {
        std::vector<std::unique_ptr<Region>> union_args;
        while (region_end != s.end()) {
            auto bytes = base64::decode_into<std::vector<std::uint8_t>>(region_begin, region_end);
            union_args.push_back(decode(bytes));
            region_begin = region_end;
            ++region_begin;
            region_end = std::find(region_begin, s.end(), ':');
        }
        auto bytes = base64::decode_into<std::vector<std::uint8_t>>(region_begin, region_end);
        union_args.push_back(decode(bytes));
        return std::unique_ptr<UnionRegion>(new UnionRegion(std::move(union_args)));
    } else {
        auto bytes = base64::decode_into<std::vector<std::uint8_t>>(region_begin, region_end);
        return decode(bytes);
    }
}

decodeOverlapsBase64() [1/2]

static TriState lsst::sphgeom::Region::decodeOverlapsBase64 ( std::string const & s )

inlinestaticinherited

decodeOverlapsBase64 evaluates an encoded overlap expression.

A single overlap expression is formed by concatenating a pair of base64-encoded regions (Region::encode then base64 encoding) with '&' as the delimiter. Multiple such pairwise overlap expressions can then be concatenated with '|' as the delimiter to form the logical OR.

Definition at line 190 of file Region.h.

                                                              {
        return decodeOverlapsBase64(s);
    }

decodeOverlapsBase64() [2/2]

TriState lsst::sphgeom::Region::decodeOverlapsBase64 ( std::string_view const & s )

staticinherited

decodeOverlapsBase64 evaluates an encoded overlap expression.

A single overlap expression is formed by concatenating a pair of base64-encoded regions (Region::encode then base64 encoding) with '&' as the delimiter. Multiple such pairwise overlap expressions can then be concatenated with '|' as the delimiter to form the logical OR.

Definition at line 117 of file Region.cc.

                                                              {
    TriState result(false);
    if (s.empty()) {
        // False makes the most sense as the limit of a logical OR of zero
        // terms (e.g. `any([])` in Python).
        return result;
    }
    auto begin = s.begin();
    while (result != true) {  // if result is known to be true, we're done.
        auto mid = std::find(begin, s.end(), '&');
        if (mid == s.end()) {
            throw std::runtime_error("No '&' found in encoded overlap expression term.");
        }
        auto a = Region::decode(base64::decode_into<std::vector<std::uint8_t>>(begin, mid));
        ++mid;
        auto end = std::find(mid, s.end(), '|');
        auto b = Region::decode(base64::decode_into<std::vector<std::uint8_t>>(mid, end));
        result = result | a->overlaps(*b);
        if (end == s.end()) {
            break;
        } else {
            begin = end;
            ++begin;
        }
    }
    return result;
}

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 194 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 208 of file Circle.h.

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

empty()

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

inlinestatic

Definition at line 58 of file Circle.h.

{ return Circle(); }

encode()

std::vector< std::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 358 of file Circle.cc.

                                           {
    std::vector<std::uint8_t> buffer;
    std::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 209 of file Circle.h.

{ return dilateBy(-r); }

erodedBy()

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

inline

Definition at line 210 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 195 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 191 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 154 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 130 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 60 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 213 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 221 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 229 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 236 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 126 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 136 of file Circle.h.

{ return _openingAngle; }

getRegions()

std::vector< std::unique_ptr< Region > > lsst::sphgeom::Region::getRegions ( Region const & region )

staticinherited

getRegions returns a vector of Region.

Definition at line 145 of file Region.cc.

                                                                        {
    std::vector<std::unique_ptr<Region>> result;
    if (auto union_region = dynamic_cast<UnionRegion const *>(&region)) {
        for(unsigned i = 0; i < union_region->nOperands(); ++i) {
            result.emplace_back(union_region->getOperand(i).clone());
        }
    } else if(auto intersection_region = dynamic_cast<IntersectionRegion const *>(&region)) {
        for(unsigned i = 0; i < intersection_region->nOperands(); ++i) {
            result.emplace_back(intersection_region->getOperand(i).clone());
        }
    } else {
        result.emplace_back(region.clone());
    }
    return result;
}

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 131 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 153 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 152 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 86 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 145 of file Circle.h.

{ return !contains(x); }

isEmpty()

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

inlineoverridevirtual

isEmpty returns true when a region does not contain any points.

Implements lsst::sphgeom::Region.

Definition at line 117 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 122 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 160 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 159 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 59 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 115 of file Circle.h.

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

operator==()

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

inline

Definition at line 108 of file Circle.h.

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

overlaps() [1/5]

TriState lsst::sphgeom::Circle::overlaps ( Box const & ) const

overridevirtual

overlaps tests whether two regions overlap. This method returns a TriState object, when the value is true it means that regions definitely overlap, false means they are definitely disjont, and unknown state means that they may or may not overlap.

Implements lsst::sphgeom::Region.

Definition at line 339 of file Circle.cc.

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

overlaps() [2/5]

TriState lsst::sphgeom::Circle::overlaps ( Circle const & ) const

overridevirtual

overlaps tests whether two regions overlap. This method returns a TriState object, when the value is true it means that regions definitely overlap, false means they are definitely disjont, and unknown state means that they may or may not overlap.

Implements lsst::sphgeom::Region.

Definition at line 344 of file Circle.cc.

                                                {
    return TriState(not this->isDisjointFrom(c));
}

overlaps() [3/5]

TriState lsst::sphgeom::Circle::overlaps ( ConvexPolygon const & ) const

overridevirtual

overlaps tests whether two regions overlap. This method returns a TriState object, when the value is true it means that regions definitely overlap, false means they are definitely disjont, and unknown state means that they may or may not overlap.

Implements lsst::sphgeom::Region.

Definition at line 348 of file Circle.cc.

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

overlaps() [4/5]

TriState lsst::sphgeom::Circle::overlaps ( Ellipse const & ) const

overridevirtual

overlaps tests whether two regions overlap. This method returns a TriState object, when the value is true it means that regions definitely overlap, false means they are definitely disjont, and unknown state means that they may or may not overlap.

Implements lsst::sphgeom::Region.

Definition at line 353 of file Circle.cc.

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

overlaps() [5/5]

TriState lsst::sphgeom::Circle::overlaps ( Region const & other ) const

inlineoverridevirtual

overlaps tests whether two regions overlap. This method returns a TriState object, when the value is true it means that regions definitely overlap, false means they are definitely disjont, and unknown state means that they may or may not overlap.

Implements lsst::sphgeom::Region.

Definition at line 255 of file Circle.h.

                                                          {
        return other.overlaps(*this);
    }

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 287 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 292 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 329 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 334 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 245 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 278 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 48 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 std::uint8_t lsst::sphgeom::Circle::TYPE_CODE = 'c'

staticconstexpr

Definition at line 56 of file Circle.h.

---

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

• /j/snowflake/release/lsstsw/stack/lsst-scipipe-9.0.0/Linux64/sphgeom/g3e8969e208+a8ce1bb630/include/lsst/sphgeom/Circle.h
• /j/snowflake/release/lsstsw/stack/lsst-scipipe-9.0.0/Linux64/sphgeom/g3e8969e208+a8ce1bb630/src/Circle.cc