gov.usgs.earthquake.nshmp.geo

Class GriddedRegion

java.lang.Object

gov.usgs.earthquake.nshmp.geo.Region

gov.usgs.earthquake.nshmp.geo.GriddedRegion

All Implemented Interfaces:

Named, Iterable<Location>

public class GriddedRegion
extends Region
implements Iterable<Location>

A GriddedRegion is a Region that has been discretized in latitude and longitude. Each node in a gridded region represents a small area that is some number of degrees in width and height and is identified by a unique Location at the geographic (lat-lon) center of the node. 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 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.

The Locations of the grid nodes are indexed internally in order of increasing longitude then latitude starting with the node at the lowest latitude and longitude in the region. GriddedRegions are iterable as a shorthand for getNodeList().iterator().

Internally, GriddedRegions use an anchor Location to ensure grid nodes fall on specific lat-lon values. This location can be anywhere in- or outside the region to be gridded. If the region contains the anchor location, the anchor will coincide with a grid node. For example, given a grid spacing of 1° and an anchor Location of 22.1°N -134.7°W, grid nodes within any region will fall at whole valued latitudes + 0.1° and longitudes - 0.7°.

Note: Due to rounding errors and the use of an Area internally to define a Region's border, Region.contains(Location) may not always return the expected result near a border. See Region.contains(Location) for further details. For a GriddedRegion, this results in values returned by calls minGridLat() etc. for which there may not be any grid nodes. To guarantee node coverage for a GriddedRegion, say for eventual map output, 'best-practice' dictates expanding a region slightly.

Use the Regions factory class to create new gridded regions.

Author:

Nitin Gupta, Vipin Gupta, Peter Powers

See Also:

Region, Regions

Field Summary

Fields

Modifier and Type	Field and Description
static Location	ANCHOR_0_0 Convenience reference for an anchor at (0°, 0°).

Method Summary

Modifier and Type	Method and Description
void	addInterior(Region region) Overridden to throw an UnsupportedOperationException when called.
Area	areaForIndex(int index) Returns the Region that bounds a node
boolean	equals(Object obj)
boolean	equalsRegion(GriddedRegion gr) Compares this GriddedRegion to another and returns true if they are the same with respect to aerial extent (both exterior and interior borders), grid node spacing, and location.
int	hashCode()
int	indexForLocation(Location loc) Returns the index of the grid node associated with a given Location or -1 if the associated grid node is ouside this gridded region.
List<Integer>	indicesForBounds(Rectangle2D rect) Returns the list of grid indices spanned by the bounds of the supplied region.
boolean	isEmpty() Returns whether this region contains any grid nodes.
Iterator<Location>	iterator()
double	latSpacing() Returns the longitudinal grid node spacing for this region.
Location	locationForIndex(int index) Returns the Location at a given grid index.
double	lonSpacing() Returns the latitudinal grid node spacing for this region.
double	maxGridLat() Returns the maximum grid latitude.
double	maxGridLon() Returns the maximum grid longitude.
double	minGridLat() Returns the minimum grid latitude.
double	minGridLon() Returns the minimum grid longitude.
int	move(int index, gov.usgs.earthquake.nshmp.geo.Direction dir) Returns the index of the node at the supplied Direction from the node at the supplied index.
LocationList	nodes() Returns the locations of all the nodes in the region as a LocationList.
int	size() Returns the total number of grid nodes in this region.

Methods inherited from class gov.usgs.earthquake.nshmp.geo.Region

area, border, bounds, contains, contains, distanceToLocation, equalsRegion, extent, interiors, isRectangular, name, toString

Methods inherited from class java.lang.Object

clone, finalize, getClass, notify, notifyAll, wait, wait, wait

Methods inherited from interface java.lang.Iterable

forEach, spliterator

Field Detail

ANCHOR_0_0

public static final Location ANCHOR_0_0

Convenience reference for an anchor at (0°, 0°).

Method Detail

latSpacing

public double latSpacing()

Returns the longitudinal grid node spacing for this region.

Returns:

the longitudinal grid node spacing (in degrees)

lonSpacing

public double lonSpacing()

Returns the latitudinal grid node spacing for this region.

Returns:

the latitudinal grid node spacing (in degrees)

size

public int size()

Returns the total number of grid nodes in this region.

Returns:

the number of grid nodes

isEmpty

public boolean isEmpty()

Returns whether this region contains any grid nodes. If a regions dimensions are smaller than the grid spacing, it may be empty.

Returns:

true if region has no grid nodes; false otherwise

move

public int move(int index,
                gov.usgs.earthquake.nshmp.geo.Direction dir)

Returns the index of the node at the supplied Direction from the node at the supplied index.

Parameters:

index - to move from

dir - to move

Returns:

index at Direction or -1 if no node exists

Throws:

NullPointerException - if supplied index is not a valid grid index

equalsRegion

public boolean equalsRegion(GriddedRegion gr)

Compares this GriddedRegion to another and returns true if they are the same with respect to aerial extent (both exterior and interior borders), grid node spacing, and location. This method ignores the names of the GriddedRegions. Use GriddedRegion.equals(Object) to include name comparison.

Parameters:

gr - 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 Region

hashCode

public int hashCode()

Overrides:

hashCode in class Region

addInterior

public void addInterior(Region region)

Overridden to throw an UnsupportedOperationException when called. The border of a GriddedRegion may only be set on initialization. To create a GriddedRegion that has interiors (donut-holes), first create a Region with the required border and interiors using Region.addInterior(Region) and then use it to initialize a GriddedRegion.

Overrides:

addInterior in class Region

Parameters:

region - to use as an interior or negative space

Throws:

UnsupportedOperationException

See Also:

Region.addInterior(Region)

iterator

public Iterator<Location> iterator()

Specified by:

iterator in interface Iterable<Location>

nodes

public LocationList nodes()

Returns the locations of all the nodes in the region as a LocationList.

Returns:

a list of all the node locations in the region.

locationForIndex

public Location locationForIndex(int index)

Returns the Location at a given grid index. This method is intended for random access of nodes in this gridded region; to cycle over all nodes, iterate over the region.

Parameters:

index - of location to retrieve

Returns:

the Location or null if index is out of range

indicesForBounds

public List<Integer> indicesForBounds(Rectangle2D rect)

Returns the list of grid indices spanned by the bounds of the supplied region. Bounds refers to the rectangle that completely encloses a region. Note that this is a list of all nodes for which any part, however small, overlaps the supplied rectangle and is not restricted to grid centers.

Parameters:

rect - to process

Returns:

the list of grid indices that intersect the bounding box of the supplied region

Throws:

IllegalArgumentException - if the supplied rectangle is not completely enclosed by thei Region

areaForIndex

public Area areaForIndex(int index)

Returns the Region that bounds a node

Parameters:

index - of the node of interest

Returns:

the bounding region of the specified node

indexForLocation

public int indexForLocation(Location loc)

Returns the index of the grid node associated with a given Location or -1 if the associated grid node is ouside this gridded region. For a Location to be associated with a node, it must fall within the square region on which the node is centered. Note that this allows for some Locations that are outside the region border to still be associated with a node. Conversely, a Region.contains(Location) may return true while this method returns -1. Users interested in node association should always use this method alone and test for -1 return value. Region.contains(Location) should NOT be used a as a test prior to calling this method.

The figure and table below indicate the results produced by calling contains() or indexForLocation(). The arrows in the figure point towards the interior of the Region. The dots mark the centered Location of each grid node and the numbers indicate the index value of each. Remember that both methods test for insidedness according to the rules defined in the Shape interface.

Location	contains(Location)	indexForLocation(Location)
A	true	-1
B	false	3
C	false	3
D	false	-1
E	true	3
F	true	3
G	true	4

Parameters:

loc - the Location to match to a grid node index

Returns:

the index of the associated node or -1 if no such node exists

minGridLat

public double minGridLat()

Returns the minimum grid latitude. Note that there may not actually be any nodes at this latitude. See class note. If the region is devoid of nodes, method will return Double.NaN.

Returns:

the minimum grid latitude

See Also:

Region.contains(Location)

maxGridLat

public double maxGridLat()

Returns the maximum grid latitude. Note that there may not actually be any nodes at this latitude. See class note. If the region is devoid of nodes, method will return Double.NaN.

Returns:

the maximum grid latitude

See Also:

Region.contains(Location)

minGridLon

public double minGridLon()

Returns the minimum grid longitude. Note that there may not actually be any nodes at this longitude. See class note. If the region is devoid of nodes, method will return Double.NaN.

Returns:

the minimum grid longitude

See Also:

Region.contains(Location)

maxGridLon

public double maxGridLon()

Returns the maximum grid longitude. Note that there may not actually be any nodes at this longitude. See class note. If the region is devoid of nodes, method will return Double.NaN.

Returns:

the maximum grid longitude

See Also:

Region.contains(Location)