LSST Applications g0b6bd0c080+a72a5dd7e6,g1182afd7b4+2a019aa3bb,g17e5ecfddb+2b8207f7de,g1d67935e3f+06cf436103,g38293774b4+ac198e9f13,g396055baef+6a2097e274,g3b44f30a73+6611e0205b,g480783c3b1+98f8679e14,g48ccf36440+89c08d0516,g4b93dc025c+98f8679e14,g5c4744a4d9+a302e8c7f0,g613e996a0d+e1c447f2e0,g6c8d09e9e7+25247a063c,g7271f0639c+98f8679e14,g7a9cd813b8+124095ede6,g9d27549199+a302e8c7f0,ga1cf026fa3+ac198e9f13,ga32aa97882+7403ac30ac,ga786bb30fb+7a139211af,gaa63f70f4e+9994eb9896,gabf319e997+ade567573c,gba47b54d5d+94dc90c3ea,gbec6a3398f+06cf436103,gc6308e37c7+07dd123edb,gc655b1545f+ade567573c,gcc9029db3c+ab229f5caf,gd01420fc67+06cf436103,gd877ba84e5+06cf436103,gdb4cecd868+6f279b5b48,ge2d134c3d5+cc4dbb2e3f,ge448b5faa6+86d1ceac1d,gecc7e12556+98f8679e14,gf3ee170dca+25247a063c,gf4ac96e456+ade567573c,gf9f5ea5b4d+ac198e9f13,gff490e6085+8c2580be5c,w.2022.27
LSST Data Management Base Package
Public Member Functions | List of all members
lsst::sphgeom::Region Class Referenceabstract

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

#include <Region.h>

Inheritance diagram for lsst::sphgeom::Region:
lsst::sphgeom::Box lsst::sphgeom::Circle lsst::sphgeom::CompoundRegion lsst::sphgeom::ConvexPolygon lsst::sphgeom::Ellipse lsst::sphgeom::IntersectionRegion lsst::sphgeom::UnionRegion

Public Member Functions

virtual ~Region ()
 
virtual std::unique_ptr< Regionclone () const =0
 clone returns a deep copy of this region. More...
 
virtual Box getBoundingBox () const =0
 getBoundingBox returns a bounding-box for this region. More...
 
virtual Box3d getBoundingBox3d () const =0
 getBoundingBox3d returns a 3-dimensional bounding-box for this region. More...
 
virtual Circle getBoundingCircle () const =0
 getBoundingCircle returns a bounding-circle for this region. 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...
 
virtual std::vector< uint8_t > encode () const =0
 encode serializes this region into an opaque byte string. More...
 
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
 

Static Public Member Functions

static std::unique_ptr< Regiondecode (std::vector< uint8_t > const &s)
 
static std::unique_ptr< Regiondecode (uint8_t const *buffer, size_t n)
 

Detailed Description

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

It provides three core pieces of functionality:

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 79 of file Region.h.

Constructor & Destructor Documentation

◆ ~Region()

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

Definition at line 81 of file Region.h.

81{}

Member Function Documentation

◆ clone()

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

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

44 {
45 return contains(UnitVector3d(LonLat::fromRadians(lon, lat)));
46}
static LonLat fromRadians(double lon, double lat)
Definition: LonLat.h:55
virtual bool contains(UnitVector3d const &) const =0
contains tests whether the given unit vector is inside this region.

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

40 {
41 return contains(UnitVector3d(x, y, z));
42}
double x
double z
Definition: Match.cc:44
int y
Definition: SpanSet.cc:48

◆ contains() [3/3]

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

◆ decode() [1/2]

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

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

Definition at line 137 of file Region.h.

137 {
138 return decode(s.data(), s.size());
139 }
static std::unique_ptr< Region > decode(std::vector< uint8_t > const &s)
Definition: Region.h:137
T data(T... args)
T size(T... args)

◆ decode() [2/2]

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

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

Definition at line 48 of file Region.cc.

48 {
49 if (buffer == nullptr || n == 0) {
50 throw std::runtime_error("Byte-string is not an encoded Region");
51 }
52 uint8_t type = *buffer;
53 if (type == Box::TYPE_CODE) {
54 return Box::decode(buffer, n);
55 } else if (type == Circle::TYPE_CODE) {
56 return Circle::decode(buffer, n);
57 } else if (type == ConvexPolygon::TYPE_CODE) {
58 return ConvexPolygon::decode(buffer, n);
59 } else if (type == Ellipse::TYPE_CODE) {
60 return Ellipse::decode(buffer, n);
61 } else if (type == UnionRegion::TYPE_CODE) {
62 return UnionRegion::decode(buffer, n);
63 } else if (type == IntersectionRegion::TYPE_CODE) {
64 return IntersectionRegion::decode(buffer, n);
65 }
66 throw std::runtime_error("Byte-string is not an encoded Region");
67}
table::Key< int > type
Definition: Detector.cc:163
static std::unique_ptr< Box > decode(std::vector< uint8_t > const &s)
Definition: Box.h:340
static constexpr uint8_t TYPE_CODE
Definition: Box.h:56
static std::unique_ptr< Circle > decode(std::vector< uint8_t > const &s)
Definition: Circle.h:251
static constexpr uint8_t TYPE_CODE
Definition: Circle.h:48
static constexpr uint8_t TYPE_CODE
Definition: ConvexPolygon.h:59
static std::unique_ptr< ConvexPolygon > decode(std::vector< uint8_t > const &s)
static constexpr uint8_t TYPE_CODE
Definition: Ellipse.h:172
static std::unique_ptr< Ellipse > decode(std::vector< uint8_t > const &s)
Definition: Ellipse.h:303
static std::unique_ptr< IntersectionRegion > decode(std::vector< uint8_t > const &s)
static constexpr uint8_t TYPE_CODE
static std::unique_ptr< UnionRegion > decode(std::vector< uint8_t > const &s)
static constexpr uint8_t TYPE_CODE

◆ encode()

virtual std::vector< 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

◆ 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

◆ relate() [1/5]

virtual Relationship lsst::sphgeom::Region::relate ( Box const &  ) const
pure virtual

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.

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

◆ relate() [2/5]

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

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.

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

◆ relate() [3/5]

virtual Relationship lsst::sphgeom::Region::relate ( ConvexPolygon const &  ) const
pure virtual

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.

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

◆ relate() [4/5]

virtual Relationship lsst::sphgeom::Region::relate ( Ellipse const &  ) const
pure virtual

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.

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

◆ relate() [5/5]

virtual Relationship lsst::sphgeom::Region::relate ( Region const &  ) const
pure virtual

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.

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


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