Region (nshmp-haz)

java.lang.Object
- gov.usgs.earthquake.nshmp.geo.Region

All Implemented Interfaces:

Named

Direct Known Subclasses:

GriddedRegion
```
public class Region
extends Object
implements Named
```
A Region is a polygonal area on the surface of the earth. The vertices comprising the border of each Region are stored internally as latitude-longitude coordinate pairs in an Area, facilitating operations such as union, intersect, and contains. Insidedness rules follow those defined in the Shape interface.
New Regions are created exclusively through static factory methods, some of which require the specification of a BorderType. If one wishes to create a geographic Region that represents a rectangle in a Mercator projection, BorderType.MERCATOR_LINEAR should be used, otherwise, the border will follow a BorderType.GREAT_CIRCLE between two points. Over small distances, great circle paths are approximately the same as linear, Mercator paths. Over longer distances, a great circle is a better representation of a line on a globe. Internally, great circles are approximated by multiple straight line segments that have a maximum length of 100km.
A Region may also have interior (or negative) areas. Any call to contains(Location) for a Location within or on the border of such an interior area will return false, subject to the rules of insidedness.
Note: The current implementation does not support regions that are intended to span ±180°. Any such regions will wrap the long way around the earth and results are undefined. Regions that encircle either pole are not supported either.
Note: Due to rounding errors and the use of an Area internally to define a Region's border, contains(Location) may not always return the expected result near a border. See contains(Location) for further details.
Use the Regions factory class to create new regions.

Author:

Peter Powers

See Also:

Shape, Area, BorderType, Regions

Method Summary

All Methods Instance Methods Concrete Methods
Modifier and Type	Method and Description
`void`	`addInterior(Region region)` Adds an interior (donut-hole) to this `Region`.
`Area`	`area()` Returns a deep copy of the internal `Area` used to manage this `Region`.
`LocationList`	`border()` Returns a reference to the internal, immutable `LocationList` of points that decribe the border of this `Region`.
`Bounds`	`bounds()` Lazily create the bounds of this region.
`boolean`	`contains(Location loc)` Returns whether the given `Location` is inside this `Region`.
`boolean`	`contains(Region region)` Tests whether another `Region` is entirely contained within this `Region`.
`double`	`distanceToLocation(Location loc)` Returns the minimum horizonatal distance (in km) between the border of this `Region` and the `Location` specified.
`boolean`	`equals(Object obj)`
`boolean`	`equalsRegion(Region r)` Compares the geometry of this `Region` to another and returns `true` if they are the same, ignoring any differences in name.
`double`	`extent()` Returns a flat-earth estimate of the area of this region in km².
`int`	`hashCode()`
`List<LocationList>`	`interiors()` Returns an unmodifiable `List` view of the internal `LocationList`s (also unmodifiable) of points that decribe the interiors of this `Region`, if such exist.
`boolean`	`isRectangular()` Returns whether this `Region` is rectangular in shape when represented in a Mercator projection.
`String`	`name()` Returns an object's display name.
`String`	`toString()`

Methods inherited from class java.lang.Object
clone, finalize, getClass, notify, notifyAll, wait, wait, wait

- Method Detail
  - contains
```
public boolean contains(Location loc)
```
    Returns whether the given Location is inside this Region. The determination follows the rules of insidedness defined in the Shape interface.
    Note: By using an Area internally to manage this Region's geometry, there are instances where rounding errors may cause this method to yield unexpected results. For instance, although a Region's southernmost point might be initially defined as 40.0°, the internal Area may return 40.0000000000001 on a call to getMinLat() and calls to contains(new Location(40,*)) will return false.
    
    Parameters:
    
    loc - the Location to test
    
    Returns:
    
    true if the Location is inside the Region, false otherwise
    
    See Also:
    
    Shape
  - contains
```
public boolean contains(Region region)
```
    Tests whether another Region is entirely contained within this Region.
    
    Parameters:
    
    region - to check
    
    Returns:
    
    true if this contains the Region; false otherwise
  - isRectangular
```
public boolean isRectangular()
```
    Returns whether this Region is rectangular in shape when represented in a Mercator projection.
    
    Returns:
    
    true if rectangular, false otherwise
  - addInterior
```
public void addInterior(Region region)
```
    Adds an interior (donut-hole) to this Region. Any call to contains(Location) for a Location within this interior area will return false. Any interior Region must lie entirely inside this Region. Moreover, any interior may not overlap or enclose any existing interior region. Internally, the border of the supplied Region is copied and stored as an unmodifiable List. No reference to the supplied Region is retained.
    
    Parameters:
    
    region - to use as an interior or negative space
    
    Throws:
    
    NullPointerException - if the supplied Region is null
    
    IllegalArgumentException - if the supplied Region is not entirly contained within this Region
    
    IllegalArgumentException - if the supplied Region is not singular (i.e. already has an interior itself)
    
    IllegalArgumentException - if the supplied Region overlaps any existing interior Region
    
    See Also:
    
    interiors()
  - interiors
```
public List<LocationList> interiors()
```
    Returns an unmodifiable List view of the internal LocationLists (also unmodifiable) of points that decribe the interiors of this Region, if such exist. If no interior is defined, the method returns null.
    
    Returns:
    
    a List the interior LocationLists or null if no interiors are defined
  - border
```
public LocationList border()
```
    Returns a reference to the internal, immutable LocationList of points that decribe the border of this Region.
    
    Returns:
    
    the immutable border LocationList
  - area
```
public Area area()
```
    Returns a deep copy of the internal Area used to manage this Region.
    
    Returns:
    
    a copy of the Area used by this Region
  - extent
```
public double extent()
```
    Returns a flat-earth estimate of the area of this region in km². Method uses the center of this Region's bounding polygon as the origin of an orthogonal coordinate system. This method is not appropriate for use with very large Regions where the curvature of the earth is more significant.
    
    Returns:
    
    the area of this region in km²
  - equalsRegion
```
public boolean equalsRegion(Region r)
```
    Compares the geometry of this Region to another and returns true if they are the same, ignoring any differences in name. Use Region.equals(Object) to include name comparison.
    
    Parameters:
    
    r - the Regions to compare
    
    Returns:
    
    true if this Region has the same geometry as the supplied Region, false otherwise
    
    See Also:
    
    equals(Object)
  - equals
```
public boolean equals(Object obj)
```
    Overrides:
    
    equals in class Object
  - hashCode
```
public int hashCode()
```
    Overrides:
    
    hashCode in class Object
  - bounds
```
public Bounds bounds()
```
    Lazily create the bounds of this region.
  - distanceToLocation
```
public double distanceToLocation(Location loc)
```
    Returns the minimum horizonatal distance (in km) between the border of this Region and the Location specified. If the given Location is inside the Region, the method returns 0. The distance algorithm used only works well at short distances (e.g. ≤250 km).
    
    Parameters:
    
    loc - the Location to compute a distance to
    
    Returns:
    
    the minimum distance between this Region and a point
    
    Throws:
    
    NullPointerException - if supplied location is null
    
    See Also:
    
    Locations.minDistanceToLine(Location, LocationList), Locations.distanceToSegmentFast(Location, Location, Location)
  - name
```
public String name()
```
    Description copied from interface: Named
    
    Returns an object's display name.
    
    Specified by:
    
    name in interface Named
    
    Returns:
    
    the name
  - toString
```
public String toString()
```
    Overrides:
    
    toString in class Object

Class Region

Method Summary

Methods inherited from class java.lang.Object

Method Detail

contains

contains

isRectangular

addInterior

interiors

border

area

extent

equalsRegion

equals

hashCode

bounds

distanceToLocation

name

toString