lsst.geom.geometry.SphericalBox Class Reference

Inheritance diagram for lsst.geom.geometry.SphericalBox:

Public Member Functions
def	__init__ (self, args)
def	wraps (self)
def	getBoundingBox (self)
def	getMin (self)
def	getMax (self)
def	getThetaExtent (self)
def	getCenter (self)
def	isEmpty (self)
def	isFull (self)
def	containsPoint (self, p)
def	contains (self, pointOrRegion)
def	intersects (self, pointOrRegion)
def	extend (self, pointOrRegion)
def	shrink (self, box)
def	setEmpty (self)
def	setFull (self)
def	__repr__ (self)
def	__eq__ (self, other)
def	__hash__ (self)

Static Public Member Functions
def	edge (v1, v2, n)

Public Attributes
	min
	max

Detailed Description

A spherical coordinate space bounding box.

This is similar to a bounding box in cartesian space in that
it is specified by a pair of points; however, a spherical box may
correspond to the entire unit-sphere, a spherical cap, a lune or
the traditional rectangle. Additionally, spherical boxes can span
the 0/360 degree longitude angle discontinuity.

Note that points falling exactly on spherical box edges are
considered to be inside (contained by) the box.

Definition at line 371 of file geometry.py.

Constructor & Destructor Documentation

__init__()

def lsst.geom.geometry.SphericalBox.__init__	(		self,
			args
	)

Creates a new spherical box. If no arguments are supplied, then
an empty box is created. If the arguments consist of a single
SphericalRegion, then a copy of its bounding box is created.
Otherwise, the arguments must consist of a pair of 2 (spherical)
or 3 (cartesian 3-vector) element coordinate tuples/lists that
specify the minimum/maximum longitude/latitude angles for the box.
Latitude angles must be within [-90, 90] degrees, and the minimum
latitude angle must be less than or equal to the maximum. If both
minimum and maximum longitude angles lie in the range [0.0, 360.0],
then the maximum can be less than the minimum. For example, a box
with min/max longitude angles of 350/10 deg spans the longitude angle
ranges [350, 360) and [0, 10]. Otherwise, the minimum must be less
than or equal to the maximum, though values can be arbitrary. If
the two are are separated by 360 degrees or more, then the box
spans longitude angles [0, 360). Otherwise, both values are range
reduced. For example, a spherical box with min/max longitude angles
specified as 350/370 deg spans longitude angle ranges [350, 360) and
[0, 10].

Definition at line 384 of file geometry.py.

    def __init__(self, *args):
        """
        Creates a new spherical box. If no arguments are supplied, then
        an empty box is created. If the arguments consist of a single
        SphericalRegion, then a copy of its bounding box is created.
        Otherwise, the arguments must consist of a pair of 2 (spherical)
        or 3 (cartesian 3-vector) element coordinate tuples/lists that
        specify the minimum/maximum longitude/latitude angles for the box.
        Latitude angles must be within [-90, 90] degrees, and the minimum
        latitude angle must be less than or equal to the maximum. If both
        minimum and maximum longitude angles lie in the range [0.0, 360.0],
        then the maximum can be less than the minimum. For example, a box
        with min/max longitude angles of 350/10 deg spans the longitude angle
        ranges [350, 360) and [0, 10]. Otherwise, the minimum must be less
        than or equal to the maximum, though values can be arbitrary. If
        the two are are separated by 360 degrees or more, then the box
        spans longitude angles [0, 360). Otherwise, both values are range
        reduced. For example, a spherical box with min/max longitude angles
        specified as 350/370 deg spans longitude angle ranges [350, 360) and
        [0, 10].
        """
        if len(args) == 0:
            self.setEmpty()
            return
        elif len(args) == 1:
            if isinstance(args[0], SphericalRegion):
                bbox = args[0].getBoundingBox()
                self.min = tuple(bbox.getMin())
                self.max = tuple(bbox.getMax())
                return
            args = args[0]
        if len(args) == 2:
            self.min = sphericalCoords(args[0])
            self.max = sphericalCoords(args[1])
        else:
            raise TypeError('Expecting a spherical region, 2 points, '
                            'or a tuple/list containing 2 points')
        if self.min[1] > self.max[1]:
            raise RuntimeError(
                'Latitude angle minimum is greater than maximum')
        if (self.max[0] < self.min[0] and
                (self.max[0] < 0.0 or self.min[0] > 360.0)):
            raise RuntimeError(
                'Longitude angle minimum is greater than maximum')
        # Range-reduce longitude angles
        if self.max[0] - self.min[0] >= 360.0:
            self.min = (0.0, self.min[1])
            self.max = (360.0, self.max[1])
        else:
            self.min = (reduceTheta(self.min[0]), self.min[1])
            self.max = (reduceTheta(self.max[0]), self.max[1])

Member Function Documentation

__eq__()

def lsst.geom.geometry.SphericalBox.__eq__	(		self,
			other
	)

Definition at line 732 of file geometry.py.

    def __eq__(self, other):
        if isinstance(other, SphericalBox):
            if self.isEmpty() and other.isEmpty():
                return True
            return self.min == other.min and self.max == other.max
        return False

__hash__()

def lsst.geom.geometry.SphericalBox.__hash__

(

self

)

Definition at line 739 of file geometry.py.

    def __hash__(self):
        return hash((self.min, self.max))

__repr__()

def lsst.geom.geometry.SphericalBox.__repr__

(

self

)

Returns a string representation of this spherical box.

Definition at line 724 of file geometry.py.

    def __repr__(self):
        """Returns a string representation of this spherical box.
        """
        if self.isEmpty():
            return ''.join([self.__class__.__name__, '(', ')'])
        return ''.join([self.__class__.__name__, '(',
                        repr(self.min), ', ', repr(self.max), ')'])

contains()

def lsst.geom.geometry.SphericalBox.contains	(		self,
			pointOrRegion
	)

Returns True if this spherical box completely contains the given
point or spherical region. Note that the implementation is
conservative where ellipses are concerned: False may be returned
for an ellipse that is actually completely contained in this box.

Definition at line 503 of file geometry.py.

    def contains(self, pointOrRegion):
        """Returns True if this spherical box completely contains the given
        point or spherical region. Note that the implementation is
        conservative where ellipses are concerned: False may be returned
        for an ellipse that is actually completely contained in this box.
        """
        if self.isEmpty():
            return False
        if isinstance(pointOrRegion, SphericalRegion):
            b = pointOrRegion.getBoundingBox()
            if b.isEmpty():
                return False
            if b.min[1] < self.min[1] or b.max[1] > self.max[1]:
                return False
            if self.wraps():
                if b.wraps():
                    return b.min[0] >= self.min[0] and b.max[0] <= self.max[0]
                else:
                    return b.min[0] >= self.min[0] or b.max[0] <= self.max[0]
            else:
                if b.wraps():
                    return self.min[0] == 0.0 and self.max[0] == 360.0
                else:
                    return b.min[0] >= self.min[0] and b.max[0] <= self.max[0]
        else:
            return self.containsPoint(sphericalCoords(pointOrRegion))

containsPoint()

def lsst.geom.geometry.SphericalBox.containsPoint	(		self,
			p
	)

Returns True if this spherical box contains the given point,
which must be specified in spherical coordinates.

Definition at line 491 of file geometry.py.

    def containsPoint(self, p):
        """Returns True if this spherical box contains the given point,
        which must be specified in spherical coordinates.
        """
        if p[1] < self.min[1] or p[1] > self.max[1]:
            return False
        theta = reduceTheta(p[0])
        if self.wraps():
            return theta >= self.min[0] or theta <= self.max[0]
        else:
            return theta >= self.min[0] and theta <= self.max[0]

edge()

def lsst.geom.geometry.SphericalBox.edge (   v1,   v2,   n  )

static

Returns a spherical bounding box for the great circle edge
connecting v1 to v2 with plane normal n. All arguments must be
cartesian unit vectors.

Definition at line 743 of file geometry.py.

    def edge(v1, v2, n):
        """Returns a spherical bounding box for the great circle edge
        connecting v1 to v2 with plane normal n. All arguments must be
        cartesian unit vectors.
        """
        theta1, phi1 = sphericalCoords(v1)
        theta2, phi2 = sphericalCoords(v2)
        # Compute latitude angle range of the edge
        minPhi = min(phi1, phi2)
        maxPhi = max(phi1, phi2)
        d = n[0] * n[0] + n[1] * n[1]
        if abs(d) > MIN_FLOAT:
            # compute the 2 (antipodal) latitude angle extrema of n
            if abs(n[2]) <= SIN_MIN:
                ex = (0.0, 0.0, -1.0)
            else:
                ex = (n[0] * n[2] / d, n[1] * n[2] / d, -d)
            # check whether either extremum is inside the edge
            if between(ex, n, v1, v2):
                minPhi = min(minPhi, sphericalCoords(ex)[1])
            ex = (-ex[0], -ex[1], -ex[2])
            if between(ex, n, v1, v2):
                maxPhi = max(maxPhi, sphericalCoords(ex)[1])
        # Compute longitude angle range of the edge
        if abs(n[2]) <= SIN_MIN:
            # great circle is very close to a pole
            d = min(abs(theta1 - theta2), abs(360.0 - theta1 + theta2))
            if d >= 90.0 and d <= 270.0:
                # d is closer to 180 than 0/360: edge crosses over a pole
                minTheta = 0.0
                maxTheta = 360.0
            else:
                # theta1 and theta2 are nearly identical
                minTheta = min(theta1, theta2)
                maxTheta = max(theta1, theta2)
                if maxTheta - minTheta > 180.0:
                    # min/max on opposite sides of 0/360
                    # longitude angle discontinuity
                    tmp = maxTheta
                    maxTheta = minTheta
                    minTheta = tmp
        elif n[2] > 0.0:
            minTheta = theta1
            maxTheta = theta2
        else:
            minTheta = theta2
            maxTheta = theta1
        # return results
        return SphericalBox((minTheta, minPhi), (maxTheta, maxPhi))

extend()

def lsst.geom.geometry.SphericalBox.extend	(		self,
			pointOrRegion
	)

Extends this box to the smallest spherical box S containing
the union of this box with the specified point or spherical region.

Definition at line 559 of file geometry.py.

    def extend(self, pointOrRegion):
        """Extends this box to the smallest spherical box S containing
        the union of this box with the specified point or spherical region.
        """
        if self == pointOrRegion:
            return self
        if isinstance(pointOrRegion, SphericalRegion):
            b = pointOrRegion.getBoundingBox()
            if b.isEmpty():
                return self
            elif self.isEmpty():
                self.min = tuple(b.min)
                self.max = tuple(b.max)
            minPhi = min(self.min[1], b.min[1])
            maxPhi = max(self.max[1], b.max[1])
            minTheta = self.min[0]
            maxTheta = self.max[0]
            if self.wraps():
                if b.wraps():
                    minMinRa = min(self.min[0], b.min[0])
                    maxMaxRa = max(self.max[0], b.max[0])
                    if maxMaxRa >= minMinRa:
                        minTheta = 0.0
                        maxTheta = 360.0
                    else:
                        minTheta = minMinRa
                        maxTheta = maxMaxRa
                else:
                    if b.min[0] <= self.max[0] and b.max[0] >= self.min[0]:
                        minTheta = 0.0
                        maxTheta = 360.0
                    elif b.min[0] - self.max[0] > self.min[0] - b.max[0]:
                        minTheta = b.min[0]
                    else:
                        maxTheta = b.max[0]
            else:
                if b.wraps():
                    if self.min[0] <= b.max[0] and self.max[0] >= b.min[0]:
                        minTheta = 0.0
                        maxTheta = 360.0
                    elif self.min[0] - b.max[0] > b.min[0] - self.max[0]:
                        maxTheta = b.max[0]
                    else:
                        minTheta = b.min[0]
                else:
                    if b.min[0] > self.max[0]:
                        if (360.0 - b.min[0] + self.max[0] <
                                b.max[0] - self.min[0]):
                            minTheta = b.min[0]
                        else:
                            maxTheta = b.max[0]
                    elif self.min[0] > b.max[0]:
                        if (360.0 - self.min[0] + b.max[0] <
                                self.max[0] - b.min[0]):
                            maxTheta = b.max[0]
                        else:
                            minTheta = b.min[0]
                    else:
                        minTheta = min(self.min[0], b.min[0])
                        maxTheta = max(self.max[0], b.max[0])
            self.min = (minTheta, minPhi)
            self.max = (maxTheta, maxPhi)
        else:
            p = sphericalCoords(pointOrRegion)
            theta, phi = reduceTheta(p[0]), p[1]
            if self.containsPoint(p):
                return self
            elif self.isEmpty():
                self.min = (theta, phi)
                self.max = (theta, phi)
            else:
                minPhi = min(self.min[1], phi)
                maxPhi = max(self.max[1], phi)
                minTheta = self.min[0]
                maxTheta = self.max[0]
                if self.wraps():
                    if self.min[0] - theta > theta - self.max[0]:
                        maxTheta = theta
                    else:
                        minTheta = theta
                elif theta < self.min[0]:
                    if self.min[0] - theta <= 360.0 - self.max[0] + theta:
                        minTheta = theta
                    else:
                        maxTheta = theta
                elif theta - self.max[0] <= 360.0 - theta + self.min[0]:
                    maxTheta = theta
                else:
                    minTheta = theta
                self.min = (minTheta, minPhi)
                self.max = (maxTheta, maxPhi)
        return self

getBoundingBox()

def lsst.geom.geometry.SphericalBox.getBoundingBox

(

self

)

Returns a bounding box for this spherical region.

Definition at line 442 of file geometry.py.

    def getBoundingBox(self):
        """Returns a bounding box for this spherical region.
        """
        return self

getCenter()

def lsst.geom.geometry.SphericalBox.getCenter

(

self

)

Returns an 2-tuple of floats corresponding to the longitude/latitude
angles (in degrees) of the center of this spherical box.

Definition at line 467 of file geometry.py.

    def getCenter(self):
        """Returns an 2-tuple of floats corresponding to the longitude/latitude
        angles (in degrees) of the center of this spherical box.
        """
        centerTheta = 0.5 * (self.min[0] + self.max[0])
        centerPhi = 0.5 * (self.min[1] + self.max[1])
        if self.wraps():
            if centerTheta >= 180.0:
                centerTheta -= 180.0
            else:
                centerTheta += 180.0
        return (centerTheta, centerPhi)

getMax()

def lsst.geom.geometry.SphericalBox.getMax

(

self

)

Returns the maximum longitude and latitude angles of this
spherical box as a 2-tuple of floats (in units of degrees).

Definition at line 453 of file geometry.py.

    def getMax(self):
        """Returns the maximum longitude and latitude angles of this
        spherical box as a 2-tuple of floats (in units of degrees).
        """
        return self.max

getMin()

def lsst.geom.geometry.SphericalBox.getMin

(

self

)

Returns the minimum longitude and latitude angles of this
spherical box as a 2-tuple of floats (in units of degrees).

Definition at line 447 of file geometry.py.

    def getMin(self):
        """Returns the minimum longitude and latitude angles of this
        spherical box as a 2-tuple of floats (in units of degrees).
        """
        return self.min

getThetaExtent()

def lsst.geom.geometry.SphericalBox.getThetaExtent

(

self

)

Returns the extent in longitude angle of this box.

Definition at line 459 of file geometry.py.

    def getThetaExtent(self):
        """Returns the extent in longitude angle of this box.
        """
        if self.wraps():
            return 360.0 - self.min[0] + self.max[0]
        else:
            return self.max[0] - self.min[0]

intersects()

def lsst.geom.geometry.SphericalBox.intersects	(		self,
			pointOrRegion
	)

Returns True if this spherical box intersects the given point
or spherical region. Note that the implementation is conservative:
True may be returned for a region that does not actually intersect
this box.

Definition at line 530 of file geometry.py.

    def intersects(self, pointOrRegion):
        """Returns True if this spherical box intersects the given point
        or spherical region. Note that the implementation is conservative:
        True may be returned for a region that does not actually intersect
        this box.
        """
        if self.isEmpty():
            return False
        if isinstance(pointOrRegion, SphericalBox):
            b = pointOrRegion
            if b.isEmpty():
                return False
            if b.min[1] > self.max[1] or b.max[1] < self.min[1]:
                return False
            if self.wraps():
                if b.wraps():
                    return True
                else:
                    return b.min[0] <= self.max[0] or b.max[0] >= self.min[0]
            else:
                if b.wraps():
                    return self.min[0] <= b.max[0] or self.max[0] >= b.min[0]
                else:
                    return self.min[0] <= b.max[0] and self.max[0] >= b.min[0]
        elif isinstance(pointOrRegion, SphericalRegion):
            return pointOrRegion.intersects(self)
        else:
            return self.containsPoint(sphericalCoords(pointOrRegion))

isEmpty()

def lsst.geom.geometry.SphericalBox.isEmpty

(

self

)

Returns True if this spherical box contains no points.

Definition at line 480 of file geometry.py.

    def isEmpty(self):
        """Returns True if this spherical box contains no points.
        """
        return self.min[1] > self.max[1]

isFull()

def lsst.geom.geometry.SphericalBox.isFull

(

self

)

Returns True if this spherical box contains every point
on the unit sphere.

Definition at line 485 of file geometry.py.

    def isFull(self):
        """Returns True if this spherical box contains every point
        on the unit sphere.
        """
        return self.min == (0.0, -90.0) and self.max == (360.0, 90.0)

setEmpty()

def lsst.geom.geometry.SphericalBox.setEmpty

(

self

)

Empties this spherical box.

Definition at line 710 of file geometry.py.

    def setEmpty(self):
        """Empties this spherical box.
        """
        self.min = (0.0, 90.0)
        self.max = (0.0, -90.0)
        return self

setFull()

def lsst.geom.geometry.SphericalBox.setFull

(

self

)

Expands this spherical box to fill the unit sphere.

Definition at line 717 of file geometry.py.

    def setFull(self):
        """Expands this spherical box to fill the unit sphere.
        """
        self.min = (0.0, -90.0)
        self.max = (360.0, 90.0)
        return self

shrink()

def lsst.geom.geometry.SphericalBox.shrink	(		self,
			box
	)

Shrinks this box to the smallest spherical box containing
the intersection of this box and the specified one.

Definition at line 652 of file geometry.py.

    def shrink(self, box):
        """Shrinks this box to the smallest spherical box containing
        the intersection of this box and the specified one.
        """
        b = box
        if not isinstance(b, SphericalBox):
            raise TypeError('Expecting a SphericalBox object')
        if self == b or self.isEmpty():
            return self
        elif b.isEmpty():
            return self.setEmpty()
        minPhi = max(self.min[1], b.min[1])
        maxPhi = min(self.max[1], b.max[1])
        minTheta = self.min[0]
        maxTheta = self.max[0]
        if self.wraps():
            if b.wraps():
                minTheta = max(minTheta, b.min[0])
                maxTheta = min(maxTheta, b.max[0])
            else:
                if b.max[0] >= minTheta:
                    if b.min[0] <= maxTheta:
                        if b.max[0] - b.min[0] <= 360.0 - minTheta + maxTheta:
                            minTheta = b.min[0]
                            maxTheta = b.max[0]
                    else:
                        minTheta = max(minTheta, b.min[0])
                        maxTheta = b.max[0]
                elif b.min[0] <= maxTheta:
                    minTheta = b.min[0]
                    maxTheta = min(maxTheta, b.max[0])
                else:
                    minPhi = 90.0
                    maxPhi = -90.0
        else:
            if b.wraps():
                if maxTheta >= b.min[0]:
                    if minTheta <= b.max[0]:
                        if maxTheta - minTheta > 360.0 - b.min[0] + b.max[0]:
                            minTheta = b.min[0]
                            maxTheta = b.max[0]
                    else:
                        minTheta = max(minTheta, b.min[0])
                elif minTheta <= b.max[0]:
                    maxTheta = b.max[0]
                else:
                    minPhi = 90.0
                    maxPhi = -90.0
            elif minTheta > b.max[0] or maxTheta < b.min[0]:
                minPhi = 90.0
                maxPhi = -90.0
            else:
                minTheta = max(minTheta, b.min[0])
                maxTheta = min(maxTheta, b.max[0])
        self.min = (minTheta, minPhi)
        self.max = (maxTheta, maxPhi)
        return self

wraps()

def lsst.geom.geometry.SphericalBox.wraps

(

self

)

Returns True if this spherical box wraps across the 0/360
degree longitude angle discontinuity.

Definition at line 436 of file geometry.py.

    def wraps(self):
        """Returns True if this spherical box wraps across the 0/360
        degree longitude angle discontinuity.
        """
        return self.min[0] > self.max[0]

Member Data Documentation

max

lsst.geom.geometry.SphericalBox.max

Definition at line 412 of file geometry.py.

min

lsst.geom.geometry.SphericalBox.min

Definition at line 411 of file geometry.py.

---

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

• /home/jenkins-slave/snowflake/release/lsstsw/stack/Linux64/geom/15.0+10/python/lsst/geom/geometry.py