lsst.sphgeom ga1cf026fa3+ac198e9f13
Public Member Functions | Static Public Member Functions | Static Public Attributes | List of all members
lsst::sphgeom::Box Class Reference

#include <Box.h>

Inheritance diagram for lsst::sphgeom::Box:
lsst::sphgeom::Region

Public Member Functions

 Box ()
 This constructor creates an empty box.
 
 Box (LonLat const &p)
 This constructor creates a box containing a single point.
 
 Box (LonLat const &p1, LonLat const &p2)
 
 Box (LonLat const &p, Angle w, Angle h)
 
 Box (NormalizedAngleInterval const &lon, AngleInterval const &lat)
 
bool operator== (Box const &b) const
 Two boxes are equal if they contain the same points.
 
bool operator!= (Box const &b) const
 
bool operator== (LonLat const &p) const
 A box is equal to a point p if it contains only p.
 
bool operator!= (LonLat const &p) const
 
NormalizedAngleInterval const & getLon () const
 getLon returns the longitude interval of this box.
 
AngleInterval const & getLat () const
 getLat returns the latitude interval of this box.
 
bool isEmpty () const
 isEmpty returns true if this box does not contain any points.
 
bool isFull () const
 
LonLat getCenter () const
 
NormalizedAngle getWidth () const
 
Angle getHeight () const
 
BoxclipTo (LonLat const &x)
 
BoxclipTo (Box const &x)
 
Box clippedTo (LonLat const &x) const
 clippedTo returns the intersection of this box and x.
 
Box clippedTo (Box const &x) const
 
BoxdilateBy (Angle r)
 
Box dilatedBy (Angle r) const
 
BoxdilateBy (Angle w, Angle h)
 
Box dilatedBy (Angle w, Angle h) const
 
BoxerodeBy (Angle r)
 
BoxerodeBy (Angle w, Angle h)
 
Box erodedBy (Angle r) const
 
Box erodedBy (Angle w, Angle h) const
 
Relationship relate (LonLat const &p) const
 
double getArea () const
 getArea returns the area of this box in steradians.
 
std::unique_ptr< Regionclone () const override
 clone returns a deep copy of this region. More...
 
Box getBoundingBox () const override
 getBoundingBox returns a bounding-box for this region. More...
 
Box3d getBoundingBox3d () const override
 getBoundingBox3d returns a 3-dimensional bounding-box for this region. More...
 
Circle getBoundingCircle () const override
 getBoundingCircle returns a bounding-circle for this region. More...
 
bool contains (UnitVector3d const &v) const override
 contains tests whether the given unit vector is inside this region. More...
 
Relationship relate (Region const &r) const override
 
Relationship relate (Box const &b) const override
 
Relationship relate (Circle const &) const override
 
Relationship relate (ConvexPolygon const &) const override
 
Relationship relate (Ellipse const &) const override
 
std::vector< uint8_t > encode () const override
 
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
 
bool contains (double lon, double lat) const
 
bool contains (LonLat const &x) const
 
bool contains (Box const &x) const
 
bool isDisjointFrom (LonLat const &x) const
 
bool isDisjointFrom (Box const &x) const
 
bool intersects (LonLat const &x) const
 
bool intersects (Box const &x) const
 
bool isWithin (LonLat const &x) const
 
bool isWithin (Box const &x) const
 
BoxexpandTo (LonLat const &x)
 
BoxexpandTo (Box const &x)
 
Box expandedTo (LonLat const &x) const
 
Box expandedTo (Box const &x) const
 
- Public Member Functions inherited from lsst::sphgeom::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
 
bool contains (double lon, double lat) const
 
virtual std::vector< uint8_t > encode () const =0
 

Static Public Member Functions

static Box fromDegrees (double lon1, double lat1, double lon2, double lat2)
 
static Box fromRadians (double lon1, double lat1, double lon2, double lat2)
 
static Box empty ()
 
static Box full ()
 
static NormalizedAngle halfWidthForCircle (Angle r, Angle lat)
 
static NormalizedAngleInterval allLongitudes ()
 
static AngleInterval allLatitudes ()
 
static std::unique_ptr< Boxdecode (std::vector< uint8_t > const &s)
 
static std::unique_ptr< Boxdecode (uint8_t const *buffer, size_t n)
 
- Static Public Member Functions inherited from lsst::sphgeom::Region
static std::unique_ptr< Regiondecode (std::vector< uint8_t > const &s)
 
static std::unique_ptr< Regiondecode (uint8_t const *buffer, size_t n)
 

Static Public Attributes

static constexpr uint8_t TYPE_CODE = 'b'
 

Detailed Description

Box represents a rectangle in spherical coordinate space that contains its boundary. A box can be empty or full (equal to the entire unit sphere), and may contain just a single point. Besides the usual rectangular regions, a box can also represent polar caps or annuli (i.e. when the box spans all longitudes).

For any instance b of this class, the following properties hold:

Constructor & Destructor Documentation

◆ Box() [1/3]

lsst::sphgeom::Box::Box ( LonLat const &  p1,
LonLat const &  p2 
)
inline

This constructor creates a box spanning the longitude interval [p1.getLon(), p2.getLon()] and latitude interval [p1.getLat(), p2.getLat()].

◆ Box() [2/3]

lsst::sphgeom::Box::Box ( LonLat const &  p,
Angle  w,
Angle  h 
)
inline

This constructor creates a box with center p, half-width (in longitude angle) w and half-height (in latitude angle) h.

◆ Box() [3/3]

lsst::sphgeom::Box::Box ( NormalizedAngleInterval const &  lon,
AngleInterval const &  lat 
)
inline

This constructor creates a box spanning the given longitude and latitude intervals.

Member Function Documentation

◆ allLatitudes()

static AngleInterval lsst::sphgeom::Box::allLatitudes ( )
inlinestatic

allLatitudes returns an angle interval containing all valid latitude angles.

◆ allLongitudes()

static NormalizedAngleInterval lsst::sphgeom::Box::allLongitudes ( )
inlinestatic

allLongitudes returns a normalized angle interval containing all valid longitude angles.

◆ clippedTo()

Box lsst::sphgeom::Box::clippedTo ( Box const &  x) const
inline

clippedTo returns the smallest box containing the intersection of this box and x. The result is not always unique, and x.clippedTo(y) is not guaranteed to equal y.clippedTo(x).

◆ clipTo() [1/2]

Box & lsst::sphgeom::Box::clipTo ( Box const &  x)
inline

x.clipTo(y) sets x to the smallest box containing the intersection of x and y. The result is not always unique, and x.clipTo(y) is not guaranteed to equal y.clipTo(x).

◆ clipTo() [2/2]

Box & lsst::sphgeom::Box::clipTo ( LonLat const &  x)
inline

clipTo shrinks this box until it contains only x. If this box does not contain x, it is emptied.

◆ clone()

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

clone returns a deep copy of this region.

Implements lsst::sphgeom::Region.

◆ contains() [1/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.

◆ contains() [2/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.

◆ contains() [3/5]

bool lsst::sphgeom::Box::contains ( LonLat const &  x) const
inline

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

◆ 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::Box::contains ( UnitVector3d const &  ) const
inlineoverridevirtual

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

Implements lsst::sphgeom::Region.

◆ decode()

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

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

◆ dilateBy() [1/2]

Box & lsst::sphgeom::Box::dilateBy ( Angle  r)

dilateBy minimally expands this Box to include all points within angular separation r of its boundary.

If this box is empty or full, or if r is non-positive, there is no effect.

◆ dilateBy() [2/2]

Box & lsst::sphgeom::Box::dilateBy ( Angle  w,
Angle  h 
)

dilateBy morphologically dilates or erodes the longitude interval of this box by w, and the latitude interval of this box by h. If w is positive, the longitude interval is dilated by [-w,w]. If w is zero, the corresponding interval is not modified, and if it is negative, the longitude interval is eroded by [w,-w]. The action of h on the latitude interval is analogous.

If this box is empty or full, there is no effect. Furthermore, a box containing the north or south pole is not considered to have a latitude boundary there, so that eroding it will not necessarily remove the pole.

If the desired outcome is the bounding box of points within some angular separation r of this box, then dilateBy(r) must be called, not dilateBy(r, r).

◆ encode()

std::vector< uint8_t > lsst::sphgeom::Box::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.

◆ expandedTo()

Box lsst::sphgeom::Box::expandedTo ( LonLat const &  x) const
inline

expandedTo returns the smallest box containing the union of this box and x. The result is not always unique, and x.expandedTo(y) is not guaranteed to equal y.expandedTo(x).

◆ expandTo()

Box & lsst::sphgeom::Box::expandTo ( LonLat const &  x)
inline

expandTo minimally expands this box to contain x. The result is not always unique, and x.expandTo(y) is not guaranteed to equal y.expandTo(x).

◆ getBoundingBox()

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

getBoundingBox returns a bounding-box for this region.

Implements lsst::sphgeom::Region.

◆ getBoundingBox3d()

Box3d lsst::sphgeom::Box::getBoundingBox3d ( ) const
overridevirtual

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

Implements lsst::sphgeom::Region.

◆ getBoundingCircle()

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

getBoundingCircle returns a bounding-circle for this region.

Implements lsst::sphgeom::Region.

◆ getCenter()

LonLat lsst::sphgeom::Box::getCenter ( ) const
inline

getCenter returns the center of this box. It is NaN for empty boxes and arbitrary for full boxes.

◆ getHeight()

Angle lsst::sphgeom::Box::getHeight ( ) const
inline

getHeight returns the height in latitude angle of this box. It is negative or NaN for empty boxes.

◆ getWidth()

NormalizedAngle lsst::sphgeom::Box::getWidth ( ) const
inline

getWidth returns the width in longitude angle of this box. It is NaN for empty boxes.

◆ halfWidthForCircle()

NormalizedAngle lsst::sphgeom::Box::halfWidthForCircle ( Angle  r,
Angle  lat 
)
static

halfWidthForCircle computes the half-width of bounding boxes for circles with radius r and centers at the given latitude. If r is non-positive, the result is zero, and if |lat| + r >= PI/2, the result is PI.

◆ intersects()

bool lsst::sphgeom::Box::intersects ( LonLat const &  x) const
inline

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

◆ isDisjointFrom()

bool lsst::sphgeom::Box::isDisjointFrom ( LonLat const &  x) const
inline

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

◆ isFull()

bool lsst::sphgeom::Box::isFull ( ) const
inline

isFull returns true if this box contains all points on the unit sphere.

◆ isWithin()

bool lsst::sphgeom::Box::isWithin ( LonLat const &  x) const
inline

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

◆ relate() [1/5]

Relationship lsst::sphgeom::Box::relate ( Box const &  b) const
inlineoverridevirtual

Implements lsst::sphgeom::Region.

◆ relate() [2/5]

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

Implements lsst::sphgeom::Region.

◆ relate() [3/5]

Relationship lsst::sphgeom::Box::relate ( ConvexPolygon const &  p) const
overridevirtual

Implements lsst::sphgeom::Region.

◆ relate() [4/5]

Relationship lsst::sphgeom::Box::relate ( Ellipse const &  e) const
overridevirtual

Implements lsst::sphgeom::Region.

◆ relate() [5/5]

Relationship lsst::sphgeom::Box::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.


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