lsst::sphgeom::UnionRegion Class Reference

UnionRegion is a lazy point-set union of its operands. More...

#include <CompoundRegion.h>

Inheritance diagram for lsst::sphgeom::UnionRegion:

Public Member Functions
	UnionRegion (std::vector< std::unique_ptr< Region > > operands)
	Construct by taking ownership of operands.
std::unique_ptr< Region >	clone () const override
	clone returns a deep copy of this region.
bool	isEmpty () const override
	isEmpty returns true when a region does not contain any points.
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
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.
size_t	nOperands () const
Region const &	getOperand (std::size_t n) const
Relationship	relate (Box const &b) const override
Relationship	relate (Circle const &c) const override
Relationship	relate (ConvexPolygon const &p) const override
Relationship	relate (Ellipse const &e) const override

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< UnionRegion >	decode (std::vector< std::uint8_t > const &s)
static std::unique_ptr< UnionRegion >	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 = 'u'

Protected Member Functions
std::vector< std::uint8_t >	_encode (std::uint8_t tc) const
std::vector< std::unique_ptr< Region > > const &	operands () const
template<typename Compound >
void	flatten_operands ()

Static Protected Member Functions
static std::vector< std::unique_ptr< Region > >	_decode (std::uint8_t tc, std::uint8_t const *buffer, std::size_t nBytes)
static TriState	_relationship_to_overlaps (Relationship r)

Detailed Description

UnionRegion is a lazy point-set union of its operands.

All operations on a UnionRegion are implementing by delegating to its nested operand regions and combining the results.

Definition at line 118 of file CompoundRegion.h.

Constructor & Destructor Documentation

UnionRegion()

lsst::sphgeom::UnionRegion::UnionRegion ( std::vector< std::unique_ptr< Region > > operands )

explicit

Construct by taking ownership of operands.

Definition at line 171 of file CompoundRegion.cc.

    : CompoundRegion(std::move(operands))
{
    flatten_operands<UnionRegion>();
}

Member Function Documentation

_decode()

std::vector< std::unique_ptr< Region > > lsst::sphgeom::CompoundRegion::_decode ( std::uint8_t tc, std::uint8_t const * buffer, std::size_t nBytes )

staticprotectedinherited

Definition at line 135 of file CompoundRegion.cc.

                                                               {
    std::uint8_t const *end = buffer + nBytes;
    if (nBytes == 0) {
        throw std::runtime_error("Encoded CompoundRegion is truncated.");
    }
    if (buffer[0] != tc) {
        throw std::runtime_error("Byte string is not an encoded CompoundRegion.");
    }
    ++buffer;
    std::vector<std::unique_ptr<Region>> result;
    while (buffer != end) {
        std::uint64_t nBytes = consumeDecodeU64(buffer, end);
        if (buffer + nBytes > end) {
            throw std::runtime_error("Encoded CompoundRegion is truncated.");
        }
        result.push_back(Region::decode(buffer, nBytes));
        buffer += nBytes;
    }
    return result;
}

_encode()

std::vector< std::uint8_t > lsst::sphgeom::CompoundRegion::_encode ( std::uint8_t tc ) const

protectedinherited

Definition at line 124 of file CompoundRegion.cc.

                                                                 {
    std::vector<std::uint8_t> buffer;
    buffer.push_back(tc);
    for (auto&& operand: _operands) {
        auto operand_buffer = operand->encode();
        encodeU64(operand_buffer.size(), buffer);
        buffer.insert(buffer.end(), operand_buffer.begin(), operand_buffer.end());
    }
    return buffer;
}

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

clone()

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

inlineoverridevirtual

clone returns a deep copy of this region.

Implements lsst::sphgeom::Region.

Definition at line 126 of file CompoundRegion.h.

{ return std::make_unique<UnionRegion>(*this); }

contains() [1/4]

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() [2/4]

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() [3/4]

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() [4/4]

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

overridevirtual

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

Implements lsst::sphgeom::Region.

Definition at line 199 of file CompoundRegion.cc.

                                                      {
    for (auto&& operand: operands()) {
        if (operand->contains(v)) {
            return true;
        }
    }
    return false;
}

decode() [1/2]

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

inlinestatic

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

Definition at line 147 of file CompoundRegion.h.

                                                                                 {
        return std::make_unique<UnionRegion>(_decode(TYPE_CODE, buffer, n));
    }

decode() [2/2]

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

inlinestatic

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

Definition at line 144 of file CompoundRegion.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;
}

encode()

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

inlineoverridevirtual

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 139 of file CompoundRegion.h.

{ return _encode(TYPE_CODE); }

flatten_operands()

template<typename Compound >

void lsst::sphgeom::CompoundRegion::flatten_operands ( )

protectedinherited

Definition at line 103 of file CompoundRegion.cc.

                                      {
    for (size_t i = 0; i != _operands.size(); ) {
        if (auto compound = dynamic_cast<Compound*>(_operands[i].get())) {
            // Move all regions from this operand, then remove it.
            std::move(
                compound->_operands.begin(),
                compound->_operands.end(),
                std::inserter(_operands, _operands.begin() + i + 1)
            );
            _operands.erase(_operands.begin() + i);
        } else {
            ++ i;
        }
    }
}

getBoundingBox()

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

overridevirtual

getBoundingBox returns a bounding-box for this region.

Implements lsst::sphgeom::Region.

Definition at line 187 of file CompoundRegion.cc.

                                      {
    return getUnionBounds(*this, [](Region const &r) { return r.getBoundingBox(); });
}

getBoundingBox3d()

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

overridevirtual

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

Implements lsst::sphgeom::Region.

Definition at line 191 of file CompoundRegion.cc.

                                          {
    return getUnionBounds(*this, [](Region const &r) { return r.getBoundingBox3d(); });
}

getBoundingCircle()

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

overridevirtual

getBoundingCircle returns a bounding-circle for this region.

Implements lsst::sphgeom::Region.

Definition at line 195 of file CompoundRegion.cc.

                                            {
    return getUnionBounds(*this, [](Region const &r) { return r.getBoundingCircle(); });
}

getOperand()

Region const & lsst::sphgeom::CompoundRegion::getOperand ( std::size_t n ) const

inlineinherited

Definition at line 74 of file CompoundRegion.h.

                                                 {
        return *_operands[n];
    }

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

isEmpty()

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

overridevirtual

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

Implements lsst::sphgeom::Region.

Definition at line 177 of file CompoundRegion.cc.

                                {
    // It can be empty when there are no operands or all operands are empty.
    for (auto&& operand: operands()) {
        if (not operand->isEmpty()) {
            return false;
        }
    }
    return true;
}

nOperands()

size_t lsst::sphgeom::CompoundRegion::nOperands ( ) const

inlineinherited

Definition at line 71 of file CompoundRegion.h.

{ return _operands.size(); }

operands()

std::vector< std::unique_ptr< Region > > const & lsst::sphgeom::CompoundRegion::operands ( ) const

inlineprotectedinherited

Definition at line 104 of file CompoundRegion.h.

{ return _operands; }

overlaps() [1/5]

TriState lsst::sphgeom::UnionRegion::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 263 of file CompoundRegion.cc.

                                                 {
    return overlaps(static_cast<Region const&>(b));
}

overlaps() [2/5]

TriState lsst::sphgeom::UnionRegion::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 267 of file CompoundRegion.cc.

                                                    {
    return overlaps(static_cast<Region const&>(c));
}

overlaps() [3/5]

TriState lsst::sphgeom::UnionRegion::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 271 of file CompoundRegion.cc.

                                                           {
    return overlaps(static_cast<Region const&>(p));
}

overlaps() [4/5]

TriState lsst::sphgeom::UnionRegion::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 275 of file CompoundRegion.cc.

                                                     {
    return overlaps(static_cast<Region const&>(e));
}

overlaps() [5/5]

TriState lsst::sphgeom::UnionRegion::overlaps ( Region const & other ) 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 239 of file CompoundRegion.cc.

                                                        {
    // Union overlaps if any operand overlaps, and disjoint when all are
    // disjoint. Empty union is disjoint with anyhting.
    if (nOperands() == 0) {
        return TriState(false);
    }
    bool may_overlap = false;
    for (auto&& operand: operands()) {
        auto state = operand->overlaps(other);
        if (state == true) {
            // Definitely overlap.
            return TriState(true);
        } if (not state.known()) {
            // May or may not overlap.
            may_overlap = true;
        }
    }
    if (may_overlap) {
        return TriState();
    }
    // None overlaps.
    return TriState(false);
}

relate() [1/5]

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

overridevirtualinherited

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 119 of file CompoundRegion.cc.

{ return relate(static_cast<Region const &>(b)); }

relate() [2/5]

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

overridevirtualinherited

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 120 of file CompoundRegion.cc.

{ return relate(static_cast<Region const &>(c)); }

relate() [3/5]

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

overridevirtualinherited

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 121 of file CompoundRegion.cc.

{ return relate(static_cast<Region const &>(p)); }

relate() [4/5]

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

overridevirtualinherited

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 122 of file CompoundRegion.cc.

{ return relate(static_cast<Region const &>(e)); }

relate() [5/5]

Relationship lsst::sphgeom::UnionRegion::relate ( Region 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::CompoundRegion.

Definition at line 208 of file CompoundRegion.cc.

                                                        {
    if (nOperands() == 0) {
        return DISJOINT;
    }
    auto result = DISJOINT | WITHIN;
    // When result becomes CONTAINS we can stop checking.
    auto const stop = CONTAINS;
    for (auto&& operand: operands()) {
        auto rel = operand->relate(rhs);
        // All operands must be disjoint with the given region for the union
        // to be disjoint with it.
        if ((rel & DISJOINT) != DISJOINT) {
            result &= ~DISJOINT;
        }
        // All operands must be within the given region for the union to be
        // within it.
        if ((rel & WITHIN) != WITHIN) {
            result &= ~WITHIN;
        }
        // If any operand contains the given region, the union contains it.
        if ((rel & CONTAINS) == CONTAINS) {
            result |= CONTAINS;
        }
        if (result == stop) {
            break;
        }
    }
 
    return result;
}

Member Data Documentation

TYPE_CODE

constexpr std::uint8_t lsst::sphgeom::UnionRegion::TYPE_CODE = 'u'

staticconstexpr

Definition at line 120 of file CompoundRegion.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/CompoundRegion.h
• /j/snowflake/release/lsstsw/stack/lsst-scipipe-9.0.0/Linux64/sphgeom/g3e8969e208+a8ce1bb630/src/CompoundRegion.cc