Package gov.usgs.earthquake.nshmp.geo

Class Regions

java.lang.Object
gov.usgs.earthquake.nshmp.geo.Regions
public class Regions extends Object
Utility methods pertaining to geographic regions.

Note that intersection and union operations will discard any grid information if GriddedRegions are supplied as arguments.

To build complex gridded regions (e.g. circular or buffered, or via intersections and unions) create a Region first and use toGridded(Region, double, double, Location).

Author:
U.S. Geological Survey

  • Constructor Details

    • Regions

      public Regions()

  • Method Details

    • create

      public static Region create(String name, LocationList border, BorderType type)
      Creates a Region from a list of border locations. The border type specifies whether lat-lon values are treated as points in an orthogonal coordinate system or as connecting great circles. The border LocationList does not need to repeat the first Location at the end of the list.
      Parameters:
      name - of the Region; may be null
      border - Locations
      type - the BorderType to use when initializing; a null value defaults to BorderType.MERCATOR_LINEAR
      Returns:
      a new Region
      Throws:
      IllegalArgumentException - if the border does not have at least 3 points, defines a Region that is empty, or consists of more than a single closed path.
      NullPointerException - if the border is null

    • createGridded

      public static GriddedRegion createGridded(String name, LocationList border, BorderType type, double latSpacing, double lonSpacing, Location anchor)
      Creates a GriddedRegion from a list of border locations.

      The border type specifies whether lat-lon values are treated as points in an orthogonal coordinate system or as connecting great circles. The border LocationList does not need to repeat the first Location at the end of the list. If the supplied anchor Location is null, it is automatically set to the Location defined by the minimum latitude and longitude of the region's border.

      Parameters:
      name - of the GriddedRegion; may be null
      border - Locations
      type - the BorderType to use when initializing; a null value defaults to BorderType.MERCATOR_LINEAR
      latSpacing - of grid nodes
      lonSpacing - of grid nodes
      anchor - Location for grid; may be null
      Returns:
      a new GriddedRegion
      Throws:
      IllegalArgumentException - if the border does not have at least 3 points, defines a Region that is empty, or consists of more than a single closed path; or spacing is outside the range 0° < spacing ≤ 5°
      NullPointerException - if the border is null

    • createRectangular

      public static Region createRectangular(String name, Location loc1, Location loc2)
      Creates a Region from a pair of Location s. When viewed in a Mercator projection, the Region will be a rectangle. If either both latitude or both longitude values in the Locations are the same, an exception is thrown.

      Note: Internally, the size of the region is expanded by a very small value (~1m) to ensure that calls to Region.contains(Location) for any Location on the north or east border of the region will return true and that any double precision rounding issues do not clip the south and west borders (e.g. 45.0 may be interpreted as 44.9999...). See also the rules governing insidedness in the Shape interface.

      Parameters:
      name - of the Region; may be null
      loc1 - the first Location
      loc2 - the second Location
      Returns:
      a new rectangular (broadly-defined) Region
      Throws:
      IllegalArgumentException - if the latitude or longitude values in the Locations provided are the same
      NullPointerException - if either Location argument is null

    • createRectangularGridded

      public static GriddedRegion createRectangularGridded(String name, Location loc1, Location loc2, double latSpacing, double lonSpacing, Location anchor)
      Creates a GriddedRegion from a pair of Location s. When viewed in a Mercator projection, the Region will be a rectangle. If either both latitude or both longitude values in the Locations are the same, an exception is thrown. If the supplied anchor Location is null, it is automatically set to the Location defined by the minimum latitude and longitude of the region's border.

      Note: Internally, the size of the region is expanded by a very small value (~1m) to ensure that calls to Region.contains(Location) for any Location on the north or east border of the region will return true and that any double precision rounding issues do not clip the south and west borders (e.g. 45.0 may be interpreted as 44.9999...). See also the rules governing insidedness in the Shape interface.

      Parameters:
      name - of the GriddedRegion; may be null
      loc1 - the first Location
      loc2 - the second Location
      latSpacing - of grid nodes
      lonSpacing - of grid nodes
      anchor - Location for grid; may be null
      Returns:
      a new rectangular (broadly-defined) GriddedRegion
      Throws:
      IllegalArgumentException - if the latitude or longitude values in the Locations provided are the same or spacing is outside the range 0° < spacing ≤ 5°
      NullPointerException - if either Location argument is null

    • createCircular

      public static Region createCircular(String name, Location center, double radius)
      Creates a circular Region. Internally, the centerpoint and radius are used to create a circular region composed of straight line segments that span 10° wedges.

      Passing the resultant region toGridded(Region, double, double, Location) yields a GriddedRegion like that in the adjacent figure. The heavy black line marks the border of the Region. The light gray dots mark the Locations of nodes outside the region, and black dots those inside the region. The dashed grey line marks the border, inside which, a Location will be associated with a grid node. See GriddedRegion.indexForLocation(Location) for more details on rules governing whether a grid node is inside a region and whether a Location will be associated with a grid node.

      Parameters:
      name - of the Region; may be null
      center - of the circle
      radius - of the circle
      Returns:
      a new circular Region
      Throws:
      IllegalArgumentException - if radius is outside the range 0 km < radius ≤ 1000 km
      NullPointerException - if center is null

    • createBuffered

      public static Region createBuffered(String name, LocationList line, double buffer)
      Creates a Region as a buffered area around a line.

      Passing the resultant region toGridded(Region, double, double, Location) yields a GriddedRegion like that in the adjacent figure. The light gray dots mark the Locations of nodes outside the region, and black dots those inside the region. The dashed grey line marks the border, inside which, a Location will be associated with a grid node. See GriddedRegion.indexForLocation(Location) for more details on rules governing whether a grid node is inside a region and whether a Location will be associated with a grid node.

      Parameters:
      name - of the Region; may be null
      line - at center of buffered Region
      buffer - distance from line
      Returns:
      a new buffered Region around a line
      Throws:
      NullPointerException - if line is null
      IllegalArgumentException - if buffer is outside the range 0 km < buffer ≤ 500 km

    • copyOf

      public static Region copyOf(Region region)
      Creates an exact copy of a Region.
      Parameters:
      region - to copy
      Returns:
      a copy of the supplied Region
      Throws:
      NullPointerException - if the supplied Region is null

    • copyOf

      public static GriddedRegion copyOf(GriddedRegion region)
      Creates a copy of a GriddedRegion.
      Parameters:
      region - to copy
      Returns:
      a copy of the supplied GriddedRegion
      Throws:
      NullPointerException - if the supplied GriddedRegion is null

    • toGridded

      public static GriddedRegion toGridded(Region region, double latSpacing, double lonSpacing, Location anchor)
      Creates a GriddedRegion with the same shape as the supplied Region. If the supplied anchor Location is null, it is automatically set to the Location defined by the minimum latitude and longitude of the region's border.
      Parameters:
      region - to use as basis for new GriddedRegion
      latSpacing - of grid nodes
      lonSpacing - of grid nodes
      anchor - Location for grid; may be null
      Returns:
      a new GriddedRegion
      Throws:
      IllegalArgumentException - if spacing is outside the range 0° < spacing ≤ 5°
      NullPointerException - if the supplied Region is null

    • intersectionOf

      public static Region intersectionOf(String name, Region r1, Region r2)
      Returns the intersection of two Regions. If the Regions do not overlap, the method returns null.
      Parameters:
      name - of the Region; may be null
      r1 - the first Region
      r2 - the second Region
      Returns:
      a new Region defined by the intersection of r1 and r2 or null if they do not overlap
      Throws:
      IllegalArgumentException - if either supplied Region is not a single closed Region
      NullPointerException - if either supplied Region is null

    • unionOf

      public static Region unionOf(String name, Region r1, Region r2)
      Returns the union of two Regions. If the Regions do not overlap, the method returns null.
      Parameters:
      name - of the Region; may be null
      r1 - the first Region
      r2 - the second Region
      Returns:
      a new Region defined by the union of r1 and r2 or null if they do not overlap
      Throws:
      IllegalArgumentException - if either supplied Region is not a single closed Region
      NullPointerException - if either supplied Region is null

    • global

      public static Region global()
      Convenience method to return a Region spanning the entire globe.
      Returns:
      a Region extending from -180° to +180° longitude and -90° to +90° latitude