Class Sector

  • Direct Known Subclasses:
    MercatorSector

    public class Sector
    extends java.lang.Object
    Geographic rectangular region in degrees.
    • Constructor Summary

      Constructors 
      Constructor Description
      Sector()
      Constructs an empty sector with minimum and maximum latitudes and longitudes all NaN.
      Sector​(double minLatitude, double minLongitude, double deltaLatitude, double deltaLongitude)
      Constructs a sector with the specified latitude and longitude values in degrees.
      Sector​(Sector sector)
      Constructs a sector with the minimum and maximum latitudes and longitudes of a specified sector.
    • Method Summary

      All Methods Static Methods Instance Methods Concrete Methods 
      Modifier and Type Method Description
      Location centroid​(Location result)
      Computes the location of the angular center of this sector, which is the mid-angle of each of this sector's latitude and longitude dimensions.
      double centroidLatitude()
      Returns the angle midway between this sector's minimum and maximum latitudes.
      double centroidLongitude()
      Returns the angle midway between this sector's minimum and maximum longitudes.
      boolean contains​(double latitude, double longitude)
      Indicates whether this sector contains a specified geographic location.
      boolean contains​(double minLatitude, double minLongitude, double deltaLatitude, double deltaLongitude)
      Indicates whether this sector fully contains a specified sector.
      boolean contains​(Sector sector)
      Indicates whether this sector fully contains a specified sector.
      double deltaLatitude()
      Returns the angle between this sector's minimum and maximum latitudes.
      double deltaLongitude()
      Returns the angle between this sector's minimum and maximum longitudes.
      boolean equals​(java.lang.Object o)  
      static Sector fromDegrees​(double latitudeDegrees, double longitudeDegrees, double deltaLatitudeDegrees, double deltaLongitudeDegrees)  
      static Sector fromRadians​(double latitudeRadians, double longitudeRadians, double deltaLatitudeRadians, double deltaLongitudeRadians)  
      int hashCode()  
      boolean intersect​(double minLatitude, double minLongitude, double deltaLatitude, double deltaLongitude)
      Computes the intersection of this sector and a specified sector, storing the result in this sector and returning whether or not the sectors intersect.
      boolean intersect​(Sector sector)
      Computes the intersection of this sector and a specified sector, storing the result in this sector and returning whether or not the sectors intersect.
      boolean intersects​(double minLatitude, double minLongitude, double deltaLatitude, double deltaLongitude)
      Indicates whether this sector intersects a specified sector.
      boolean intersects​(Sector sector)
      Indicates whether this sector intersects a specified sector.
      boolean intersectsOrNextTo​(Sector sector)
      Indicates if this sector is next to, or intersects, a specified sector.
      boolean isEmpty()
      Indicates whether this sector has non-zero width and height.
      boolean isFullSphere()
      Indicates whether this sector contains the full range of latitude [90 to +90] and longitude [-180 to +180].
      double maxLatitude()
      Returns this sector's maximum latitude.
      double maxLongitude()
      Returns this sector's maximum longitude.
      double minLatitude()
      Returns the this sector's minimum latitude.
      double minLongitude()
      Returns this sector's minimum longitude.
      Sector set​(double minLatitude, double minLongitude, double deltaLatitude, double deltaLongitude)
      Sets this sector to the specified latitude, longitude and dimension in degrees.
      Sector set​(Sector sector)
      Sets this sector to the minimum and maximum latitudes and longitudes of a specified sector.
      Sector setEmpty()
      Sets this sector to an empty sector.
      Sector setFullSphere()
      Sets this sector to the full range of latitude [90 to +90] and longitude [-180 to +180].
      java.lang.String toString()  
      Sector translate​(double deltaLatitude, double deltaLongitude)
      Translates this sector by a specified geographic increment.
      Sector union​(double latitude, double longitude)
      Sets this sector to the union of itself and a specified location.
      Sector union​(double minLatitude, double minLongitude, double deltaLatitude, double deltaLongitude)
      Sets this sector to the union of itself and a specified sector.
      Sector union​(float[] array, int count, int stride)
      Sets this sector to the union of itself and an array of specified locations.
      Sector union​(Sector sector)
      Sets this sector to the union of itself and a specified sector.
      • Methods inherited from class java.lang.Object

        getClass, notify, notifyAll, wait, wait, wait
    • Constructor Detail

      • Sector

        public Sector()
        Constructs an empty sector with minimum and maximum latitudes and longitudes all NaN.
      • Sector

        public Sector​(double minLatitude,
                      double minLongitude,
                      double deltaLatitude,
                      double deltaLongitude)
        Constructs a sector with the specified latitude and longitude values in degrees.
        Parameters:
        minLatitude - the minimum latitude, i.e., the latitude at the southwest corner of the sector.
        minLongitude - the minimum longitude, i.e., the longitude at the southwest corner of the sector.
        deltaLatitude - the width of the sector, specified in degrees; must equal to or greater than zero.
        deltaLongitude - the height of the sector, specified in degrees; must equal to or greater than zero.
      • Sector

        public Sector​(Sector sector)
        Constructs a sector with the minimum and maximum latitudes and longitudes of a specified sector.
        Parameters:
        sector - the sector specifying the coordinates
        Throws:
        java.lang.IllegalArgumentException - If the sector is null
    • Method Detail

      • fromDegrees

        public static Sector fromDegrees​(double latitudeDegrees,
                                         double longitudeDegrees,
                                         double deltaLatitudeDegrees,
                                         double deltaLongitudeDegrees)
      • fromRadians

        public static Sector fromRadians​(double latitudeRadians,
                                         double longitudeRadians,
                                         double deltaLatitudeRadians,
                                         double deltaLongitudeRadians)
      • equals

        public boolean equals​(java.lang.Object o)
        Overrides:
        equals in class java.lang.Object
      • hashCode

        public int hashCode()
        Overrides:
        hashCode in class java.lang.Object
      • toString

        @NonNull
        public java.lang.String toString()
        Overrides:
        toString in class java.lang.Object
      • isEmpty

        public boolean isEmpty()
        Indicates whether this sector has non-zero width and height.
        Returns:
        true if either of this sector's delta latitude and/or delta longitude are zero, false otherwise.
      • isFullSphere

        public boolean isFullSphere()
        Indicates whether this sector contains the full range of latitude [90 to +90] and longitude [-180 to +180].
        Returns:
        true if this sector's coordinates are set to the full range of latitude and longitude
      • minLatitude

        public double minLatitude()
        Returns the this sector's minimum latitude.
        Returns:
        the minimum latitude of this sector or NaN if this sector's location is nas not been defined.
      • maxLatitude

        public double maxLatitude()
        Returns this sector's maximum latitude.
        Returns:
        the maximum latitude of this sector or NaN if this sector's location is nas not been defined.
      • minLongitude

        public double minLongitude()
        Returns this sector's minimum longitude.
        Returns:
        the minimum longitude of this sector or NaN if this sector's location is nas not been defined.
      • maxLongitude

        public double maxLongitude()
        Returns this sector's maximum longitude.
        Returns:
        the maximum longitude of this sector or NaN if this sector's location is nas not been defined.
      • deltaLatitude

        public double deltaLatitude()
        Returns the angle between this sector's minimum and maximum latitudes.
        Returns:
        the difference between this sector's minimum and maximum latitudes in degrees
      • deltaLongitude

        public double deltaLongitude()
        Returns the angle between this sector's minimum and maximum longitudes.
        Returns:
        the difference between this sector's minimum and maximum longitudes in degrees
      • centroidLatitude

        public double centroidLatitude()
        Returns the angle midway between this sector's minimum and maximum latitudes.
        Returns:
        the mid-angle of this sector's minimum and maximum latitudes in degrees
      • centroidLongitude

        public double centroidLongitude()
        Returns the angle midway between this sector's minimum and maximum longitudes.
        Returns:
        the mid-angle of this sector's minimum and maximum longitudes in degrees
      • centroid

        public Location centroid​(Location result)
        Computes the location of the angular center of this sector, which is the mid-angle of each of this sector's latitude and longitude dimensions.
        Parameters:
        result - a pre-allocated Location in which to return the computed centroid
        Returns:
        the specified result argument containing the computed centroid
        Throws:
        java.lang.IllegalArgumentException - If the result is null
      • set

        public Sector set​(double minLatitude,
                          double minLongitude,
                          double deltaLatitude,
                          double deltaLongitude)
        Sets this sector to the specified latitude, longitude and dimension in degrees.
        Parameters:
        minLatitude - the minimum latitude, i.e., the latitude at the southwest corner of the sector.
        minLongitude - the minimum longitude, i.e., the longitude at the southwest corner of the sector.
        deltaLatitude - the width of the sector, specified in degrees; must equal to or greater than zero.
        deltaLongitude - the height of the sector, specified in degrees; must equal to or greater than zero.
        Returns:
        this sector with its coordinates set to the specified values
      • set

        public Sector set​(Sector sector)
        Sets this sector to the minimum and maximum latitudes and longitudes of a specified sector.
        Parameters:
        sector - the sector specifying the new coordinates
        Returns:
        this sector with its coordinates set to that of the specified sector
        Throws:
        java.lang.IllegalArgumentException - If the sector is null
      • setEmpty

        public Sector setEmpty()
        Sets this sector to an empty sector.
        Returns:
        this sector with its coordinates set to an empty sector
      • setFullSphere

        public Sector setFullSphere()
        Sets this sector to the full range of latitude [90 to +90] and longitude [-180 to +180].
        Returns:
        this sector with its coordinates set to the full range of latitude and longitude
      • intersects

        public boolean intersects​(double minLatitude,
                                  double minLongitude,
                                  double deltaLatitude,
                                  double deltaLongitude)
        Indicates whether this sector intersects a specified sector. Two sectors intersect when both the latitude boundaries and the longitude boundaries overlap by a non-zero amount. An empty sector never intersects another sector.
        The sectors are assumed to have normalized angles (angles within the range [-90, +90] latitude and [-180, +180] longitude).
        Parameters:
        minLatitude - the minimum latitude of the sector to test intersection with, in degrees
        minLongitude - the minimum longitude of the sector to test intersection with, in degrees
        deltaLatitude - the width of the sector to test intersection with, in degrees
        deltaLongitude - the height of the sector to test intersection with, in degrees
        Returns:
        true if the specified sector intersections this sector, false otherwise
      • intersects

        public boolean intersects​(Sector sector)
        Indicates whether this sector intersects a specified sector. Two sectors intersect when both the latitude boundaries and the longitude boundaries overlap by a non-zero amount. An empty sector never intersects another sector.
        The sectors are assumed to have normalized angles (angles within the range [-90, +90] latitude and [-180, +180] longitude).
        Parameters:
        sector - the sector to test intersection with
        Returns:
        true if the specified sector intersections this sector, false otherwise
        Throws:
        java.lang.IllegalArgumentException - If the sector is null
      • intersectsOrNextTo

        public boolean intersectsOrNextTo​(Sector sector)
        Indicates if this sector is next to, or intersects, a specified sector. Two sectors intersect when the conditions of the intersects(Sector) methods have been met, and if the boundary or corner is shared with the specified sector. This is a temporary implementation and will be deprecated in future releases.
        Parameters:
        sector - the sector to test intersection with
        Returns:
        true if the specified sector intersects or is next to this sector, false otherwise
        Throws:
        java.lang.IllegalArgumentException - If the sector is null
      • intersect

        public boolean intersect​(double minLatitude,
                                 double minLongitude,
                                 double deltaLatitude,
                                 double deltaLongitude)
        Computes the intersection of this sector and a specified sector, storing the result in this sector and returning whether or not the sectors intersect. Two sectors intersect when both the latitude boundaries and the longitude boundaries overlap by a non-zero amount. An empty sector never intersects another sector. When there is no intersection, this returns false and leaves this sector unchanged.
        The sectors are assumed to have normalized angles (angles within the range [-90, +90] latitude and [-180, +180] longitude).
        Parameters:
        minLatitude - the minimum latitude of the sector to intersect with, in degrees
        minLongitude - the minimum longitude of the sector to intersect with, in degrees
        deltaLatitude - the width of the sector to intersect with, in degrees
        deltaLongitude - the height of the sector to intersect with, in degrees
        Returns:
        true if the specified sector intersections this sector, false otherwise
      • intersect

        public boolean intersect​(Sector sector)
        Computes the intersection of this sector and a specified sector, storing the result in this sector and returning whether or not the sectors intersect. Two sectors intersect when both the latitude boundaries and the longitude boundaries overlap by a non-zero amount. An empty sector never intersects another sector. When there is no intersection, this returns false and leaves this sector unchanged.
        The sectors are assumed to have normalized angles (angles within the range [-90, +90] latitude and [-180, +180] longitude).
        Parameters:
        sector - the sector to intersect with
        Returns:
        this true if this sector intersects the specified sector, false otherwise
        Throws:
        java.lang.IllegalArgumentException - If the sector is null
      • contains

        public boolean contains​(double latitude,
                                double longitude)
        Indicates whether this sector contains a specified geographic location. An empty sector never contains a location.
        Parameters:
        latitude - the location's latitude in degrees
        longitude - the location's longitude in degrees
        Returns:
        true if this sector contains the location, false otherwise
      • contains

        public boolean contains​(double minLatitude,
                                double minLongitude,
                                double deltaLatitude,
                                double deltaLongitude)
        Indicates whether this sector fully contains a specified sector. This sector contains the specified sector when the specified sector's boundaries are completely contained within this sector's boundaries, or are equal to this sector's boundaries. An empty sector never contains another sector.
        The sectors are assumed to have normalized angles (angles within the range [-90, +90] latitude and [-180, +180] longitude).
        Parameters:
        minLatitude - the minimum latitude of the sector to test containment with, in degrees
        minLongitude - the minimum longitude of the sector to test containment with, in degrees
        deltaLatitude - the width of the sector to test containment with, in degrees
        deltaLongitude - the height of the sector to test containment with, in degrees
        Returns:
        true if the specified sector contains this sector, false otherwise
      • contains

        public boolean contains​(Sector sector)
        Indicates whether this sector fully contains a specified sector. This sector contains the specified sector when the specified sector's boundaries are completely contained within this sector's boundaries, or are equal to this sector's boundaries. An empty sector never contains another sector.
        The sectors are assumed to have normalized angles (angles within the range [-90, +90] latitude and [-180, +180] longitude).
        Parameters:
        sector - the sector to test containment with
        Returns:
        true if the specified sector contains this sector, false otherwise
        Throws:
        java.lang.IllegalArgumentException - If the sector is null
      • union

        public Sector union​(double latitude,
                            double longitude)
        Sets this sector to the union of itself and a specified location.
        Parameters:
        latitude - the location's latitude in degrees
        longitude - the location's longitude in degrees
        Returns:
        this sector, set to its union with the specified location
      • union

        public Sector union​(float[] array,
                            int count,
                            int stride)
        Sets this sector to the union of itself and an array of specified locations. If this sector is empty, it bounds the specified locations. The array is understood to contain location of at least two coordinates organized as (longitude, latitude, ...), where stride indicates the number of coordinates between longitude values.
        Parameters:
        array - the array of locations to consider
        count - the number of array elements to consider
        stride - the number of coordinates between the first coordinate of adjacent locations - must be at least 2
        Returns:
        This bounding box set to contain the specified array of locations.
        Throws:
        java.lang.IllegalArgumentException - If the array is null or empty, if the count is less than 0, or if the stride is less than 2
      • union

        public Sector union​(double minLatitude,
                            double minLongitude,
                            double deltaLatitude,
                            double deltaLongitude)
        Sets this sector to the union of itself and a specified sector. This has no effect if the specified sector is empty. If this sector is empty, it is set to the specified sector.
        Parameters:
        minLatitude - the minimum latitude of the sector to union with, in degrees
        minLongitude - the minimum longitude of the sector to union with, in degrees
        deltaLatitude - the width of the sector to union with, in degrees
        deltaLongitude - the height of the sector to union with, in degrees
        Returns:
        this sector, set to its union with the specified sector
      • union

        public Sector union​(Sector sector)
        Sets this sector to the union of itself and a specified sector. This has no effect if the specified sector is empty. If this sector is empty, it is set to the specified sector.
        Parameters:
        sector - the sector to union with
        Returns:
        this sector, set to its union with the specified sector
        Throws:
        java.lang.IllegalArgumentException - If the sector is null
      • translate

        public Sector translate​(double deltaLatitude,
                                double deltaLongitude)
        Translates this sector by a specified geographic increment.
        The translated sector is assumed to have normalized angles (angles within the range [-90, +90] latitude and [-180, +180] longitude).
        Parameters:
        deltaLatitude - the translation's latitude increment in degrees
        deltaLongitude - the translation's longitude increment in degrees
        Returns:
        this sector, translated by the specified increment