Region is a minimal interface for 2-dimensional regions on the unit sphere. More...

#include <Region.h>

Inheritance diagram for lsst::sphgeom::Region:

Public Member Functions
virtual	~Region ()=default

virtual std::unique_ptr< Region >	clone () const =0
	`clone` returns a deep copy of this region.

virtual Box	getBoundingBox () const =0
	`getBoundingBox` returns a bounding-box for this region.

virtual Box3d	getBoundingBox3d () const =0
	`getBoundingBox3d` returns a 3-dimensional bounding-box for this region.

virtual Circle	getBoundingCircle () const =0
	`getBoundingCircle` returns a bounding-circle for this region.

virtual bool	isEmpty () const =0
	`isEmpty` returns true when a region does not contain any points.

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.

virtual std::vector< std::uint8_t >	encode () const =0
	`encode` serializes this region into an opaque byte string.


virtual Relationship	relate (Region const &) const =0

virtual Relationship	relate (Box const &) const =0

virtual Relationship	relate (Circle const &) const =0

virtual Relationship	relate (ConvexPolygon const &) const =0

virtual Relationship	relate (Ellipse const &) const =0


virtual TriState	overlaps (Region const &other) const =0

virtual TriState	overlaps (Box const &) const =0

virtual TriState	overlaps (Circle const &) const =0

virtual TriState	overlaps (ConvexPolygon const &) const =0

virtual TriState	overlaps (Ellipse const &) const =0

Static Public Member Functions
static std::vector< std::unique_ptr< Region > >	getRegions (Region const &region)
	`getRegions` returns a vector of Region.


static std::unique_ptr< Region >	decode (std::vector< std::uint8_t > const &s)

static std::unique_ptr< Region >	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 Protected Member Functions
static TriState	_relationship_to_overlaps (Relationship r)

Detailed Description

Region is a minimal interface for 2-dimensional regions on the unit sphere.

It provides three core pieces of functionality:

It allows a region to be approximated with a simpler one.
It allows for inexact (but conservative) computation of the spatial relationships between two regions.
It provides transformation between objects and binary strings.

Given a pixelization of the unit sphere with pixels that can be bounded by Regions, this provides all the necessary functionality for determining which pixels may intersect a Region.

When implementing a new concrete region subclass R, the Region interface should be extended with:

virtual Relationship relate(R const &) const = 0;

All other Region subclasses must then implement this method. In addition, R is expected to contain the following implementation of the generic relate method:

virtual Relationship relate(Region const & r) const {
    return invert(r.relate(*this));
}

where invert is defined in Relationship.h.

Given two Region references r1 and r2 of type R1 and R2, the net effect is that r1.relate(r2) will end up calling R2::relate(R1 const &). In other words, the call is polymorphic in the types of both r1 and r2.

One negative consequence of this design is that one cannot implement new Region types outside of this library.

Definition at line 89 of file Region.h.

Constructor & Destructor Documentation

◆ ~Region()

virtual lsst::sphgeom::Region::~Region ( )

virtualdefault

Member Function Documentation

◆ _relationship_to_overlaps()

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

inlinestaticprotected

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();
    }

◆ clone()

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

pure virtual

clone returns a deep copy of this region.

Implemented in lsst::sphgeom::Box, lsst::sphgeom::Circle, lsst::sphgeom::UnionRegion, lsst::sphgeom::IntersectionRegion, lsst::sphgeom::ConvexPolygon, and lsst::sphgeom::Ellipse.

◆ contains() [1/3]

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 54 of file Region.cc.

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

◆ contains() [2/3]

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 50 of file Region.cc.

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

◆ contains() [3/3]

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

pure virtual

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

Implemented in lsst::sphgeom::Box, lsst::sphgeom::Circle, lsst::sphgeom::UnionRegion, lsst::sphgeom::IntersectionRegion, lsst::sphgeom::ConvexPolygon, lsst::sphgeom::Ellipse, lsst::sphgeom::Box, lsst::sphgeom::Circle, lsst::sphgeom::UnionRegion, lsst::sphgeom::IntersectionRegion, lsst::sphgeom::ConvexPolygon, and lsst::sphgeom::Ellipse.

◆ decode() [1/2]

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

static

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

Definition at line 72 of file Region.cc.

                                                                        {
    if (buffer == nullptr || n == 0) {
        throw std::runtime_error("Byte-string is not an encoded Region");
    }
    std::uint8_t type = *buffer;
    if (type == Box::TYPE_CODE) {
        return Box::decode(buffer, n);
    } else if (type == Circle::TYPE_CODE) {
        return Circle::decode(buffer, n);
    } else if (type == ConvexPolygon::TYPE_CODE) {
        return ConvexPolygon::decode(buffer, n);
    } else if (type == Ellipse::TYPE_CODE) {
        return Ellipse::decode(buffer, n);
    } else if (type == UnionRegion::TYPE_CODE) {
        return UnionRegion::decode(buffer, n);
    } else if (type == IntersectionRegion::TYPE_CODE) {
        return IntersectionRegion::decode(buffer, n);
    }
    throw std::runtime_error("Byte-string is not an encoded Region");
}

◆ decode() [2/2]

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

inlinestatic

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

Definition at line 162 of file Region.h.

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

◆ decodeBase64() [1/2]

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

inlinestatic

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 )

static

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 )

inlinestatic

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 )

static

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;
}

◆ encode()

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

pure virtual

encode serializes this region into an opaque byte string.

Byte strings emitted by encode can be deserialized with decode.

Implemented in lsst::sphgeom::Box, lsst::sphgeom::Circle, lsst::sphgeom::UnionRegion, lsst::sphgeom::IntersectionRegion, lsst::sphgeom::ConvexPolygon, and lsst::sphgeom::Ellipse.

◆ getBoundingBox()

virtual Box lsst::sphgeom::Region::getBoundingBox ( ) const

pure virtual

getBoundingBox returns a bounding-box for this region.

Implemented in lsst::sphgeom::Box, lsst::sphgeom::Circle, lsst::sphgeom::UnionRegion, lsst::sphgeom::IntersectionRegion, lsst::sphgeom::ConvexPolygon, and lsst::sphgeom::Ellipse.

◆ getBoundingBox3d()

virtual Box3d lsst::sphgeom::Region::getBoundingBox3d ( ) const

pure virtual

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

Implemented in lsst::sphgeom::Box, lsst::sphgeom::Circle, lsst::sphgeom::UnionRegion, lsst::sphgeom::IntersectionRegion, lsst::sphgeom::ConvexPolygon, and lsst::sphgeom::Ellipse.

◆ getBoundingCircle()

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

pure virtual

getBoundingCircle returns a bounding-circle for this region.

Implemented in lsst::sphgeom::Box, lsst::sphgeom::Circle, lsst::sphgeom::UnionRegion, lsst::sphgeom::IntersectionRegion, lsst::sphgeom::ConvexPolygon, and lsst::sphgeom::Ellipse.

◆ getRegions()

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

static

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;
}

◆ isEmpty()

virtual bool lsst::sphgeom::Region::isEmpty ( ) const

pure virtual

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

Implemented in lsst::sphgeom::Box, lsst::sphgeom::Circle, lsst::sphgeom::UnionRegion, lsst::sphgeom::IntersectionRegion, lsst::sphgeom::ConvexPolygon, and lsst::sphgeom::Ellipse.