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:

Peter Powers

Constructor Summary

Constructors

Constructor and Description
Regions()

Method Summary

Modifier and Type	Method and Description
static GriddedRegion	copyOf(GriddedRegion region) Creates a copy of a GriddedRegion.
static Region	copyOf(Region region) Creates an exact copy of a Region.
static Region	create(String name, LocationList border, BorderType type) Creates a Region from a list of border locations.
static Region	createBuffered(String name, LocationList line, double buffer) Creates a Region as a buffered area around a line.
static Region	createCircular(String name, Location center, double radius) Creates a circular Region.
static GriddedRegion	createGridded(String name, LocationList border, BorderType type, double latSpacing, double lonSpacing, Location anchor) Creates a GriddedRegion from a list of border locations.
static Region	createRectangular(String name, Location loc1, Location loc2) Creates a Region from a pair of Location s.
static GriddedRegion	createRectangularGridded(String name, Location loc1, Location loc2, double latSpacing, double lonSpacing, Location anchor) Creates a GriddedRegion from a pair of Location s.
static Region	global() Convenience method to return a Region spanning the entire globe.
static Region	intersectionOf(String name, Region r1, Region r2) Returns the intersection of two Regions.
static GriddedRegion	toGridded(Region region, double latSpacing, double lonSpacing, Location anchor) Creates a GriddedRegion with the same shape as the supplied Region.
static Region	unionOf(String name, Region r1, Region r2) Returns the union of two Regions.

Methods inherited from class java.lang.Object

clone, equals, finalize, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait

Constructor Detail

Regions

public Regions()

Method Detail

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