org.opensha.commons.geo
Class GriddedRegion

java.lang.Object
  extended by org.opensha.commons.geo.Region
      extended by org.opensha.commons.geo.GriddedRegion
All Implemented Interfaces:
Serializable, Iterable<Location>, Named, XMLSaveable
Direct Known Subclasses:
CaliforniaRegions.CYBERSHAKE_MAP_GRIDDED, CaliforniaRegions.LA_BOX_GRIDDED, CaliforniaRegions.RELM_COLLECTION_GRIDDED, CaliforniaRegions.RELM_GRIDDED, CaliforniaRegions.RELM_NOCAL_GRIDDED, CaliforniaRegions.RELM_SOCAL_GRIDDED, CaliforniaRegions.RELM_TESTING_GRIDDED, CaliforniaRegions.SF_BOX_GRIDDED, CustomGriddedRegion, NSHMP_CEUS_SourceGenerator

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.

A GriddedRegion may be initialized several ways (e.g. as a circle, an area of uniform degree-width and -height, or a buffer around a linear feature). See constructor documentation for illustrative examples. Each constructor comes in two formats, one that takes a single 'spacing' value, and one that takes two spacing values, one each for latitude and longitude.

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().

To ensure grid nodes fall on specific lat-lon values, all constructors take an anchor Location argument. 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°. If an anchor Location is null, it is automatically set as the Location defined by the minimum latitude and longitude of the region's border.

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 getMinGridLat() 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.

Version:
$Id: GriddedRegion.java 9729 2012-11-07 21:33:01Z kmilner $
Author:
Nitin Gupta, Vipin Gupta, Peter Powers
See Also:
Region, Serialized Form

Field Summary
static Location ANCHOR_0_0
          Convenience reference for an anchor at (0°, 0°).
static String XML_METADATA_ANCHOR_NAME
           
static String XML_METADATA_GRID_SPACING_NAME
           
static String XML_METADATA_NAME
           
static String XML_METADATA_NUM_POINTS_NAME
           
 
Fields inherited from class org.opensha.commons.geo.Region
XML_METADATA_OUTLINE_NAME
 
Constructor Summary
GriddedRegion(Location center, double radius, double latSpacing, double lonSpacing, Location anchor)
          Initializes a circular GriddedRegion.
GriddedRegion(Location center, double radius, double spacing, Location anchor)
          Initializes a circular GriddedRegion.
GriddedRegion(LocationList border, BorderType type, double latSpacing, double lonSpacing, Location anchor)
          Initializes a GriddedRegion from a list of border locations.
GriddedRegion(LocationList border, BorderType type, double spacing, Location anchor)
          Initializes a GriddedRegion from a list of border locations.
GriddedRegion(LocationList line, double buffer, double latSpacing, double lonSpacing, Location anchor)
          Initializes a GriddedRegion as a buffered area around a line.
GriddedRegion(LocationList line, double buffer, double spacing, Location anchor)
          Initializes a GriddedRegion as a buffered area around a line.
GriddedRegion(Location loc1, Location loc2, double latSpacing, double lonSpacing, Location anchor)
          Initializes a GriddedRegion from a pair of Locations.
GriddedRegion(Location loc1, Location loc2, double spacing, Location anchor)
          Initializes a GriddedRegion from a pair of Locations.
GriddedRegion(Region region, double latSpacing, double lonSpacing, Location anchor)
          Initializes a GriddedRegion with a Region.
GriddedRegion(Region region, double spacing, Location anchor)
          Initializes a GriddedRegion with a Region.
 
Method Summary
 void addInterior(Region region)
          Overridden to throw an UnsupportedOperationException when called.
 Area areaForIndex(int index)
          Returns the Region that bounds a node
 GriddedRegion clone()
          Returns an exact, independent copy of this GriddedRegion.
 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.
static GriddedRegion fromXMLMetadata(Element root)
          Initializes a new Region from stored metadata.
 double getLatSpacing()
          Returns the longitudinal grid node spacing for this region.
 Location getLocation(int index)
          Alternative to locationForIndex(int index)
 double getLonSpacing()
          Returns the latitudinal grid node spacing for this region.
 double getMaxGridLat()
          Returns the maximum grid latitude.
 double getMaxGridLon()
          Returns the maximum grid longitude.
 double getMinGridLat()
          Returns the minimum grid latitude.
 double getMinGridLon()
          Returns the minimum grid longitude.
 int getNodeCount()
          Returns the total number of grid nodes in this region.
 LocationList getNodeList()
          Returns the locations of all the nodes in the region as a LocationList.
 int getNumLocations()
          Alternative to getNodeCount().
 double getSpacing()
          Returns the grid node spacing for this region.
 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.
 boolean isSpacingUniform()
          Returns whether the lat and lon spacing are the same.
 Iterator<Location> iterator()
           
 Location locationForIndex(int index)
          Returns the Location at a given grid index.
 int move(int idx, Direction dir)
          Returns the index of the node at the supplied Direction from the node at the supplied index.
 GriddedRegion subRegion(Region region)
          Creates a new GriddedRegion from this (the parent) and another Region.
 Element toXMLMetadata(Element root)
           
 
Methods inherited from class org.opensha.commons.geo.Region
contains, contains, distanceToLocation, equalsRegion, getBorder, getExtent, getGlobalRegion, getInteriors, getMaxLat, getMaxLon, getMinLat, getMinLon, getName, getShape, intersect, isRectangular, main, setName, toString, toXMLMetadata, union
 
Methods inherited from class java.lang.Object
finalize, getClass, notify, notifyAll, wait, wait, wait
 

Field Detail

XML_METADATA_NAME

public static final String XML_METADATA_NAME
See Also:
Constant Field Values

XML_METADATA_GRID_SPACING_NAME

public static final String XML_METADATA_GRID_SPACING_NAME
See Also:
Constant Field Values

XML_METADATA_ANCHOR_NAME

public static final String XML_METADATA_ANCHOR_NAME
See Also:
Constant Field Values

XML_METADATA_NUM_POINTS_NAME

public static final String XML_METADATA_NUM_POINTS_NAME
See Also:
Constant Field Values

ANCHOR_0_0

public static final Location ANCHOR_0_0
Convenience reference for an anchor at (0°, 0°).

Constructor Detail

GriddedRegion

public GriddedRegion(Location loc1,
                     Location loc2,
                     double latSpacing,
                     double lonSpacing,
                     Location anchor)
Initializes a GriddedRegion from a pair of Locations. When viewed in a Mercator projection, the region will be a rectangle. If either both latitude or both longitude values are the same, an exception is thrown.

Note: In an exception to the rules of insidedness defined in the Shape interface, Locations that fall on northern or eastern borders of this region are considered inside. See Region.Region(Location, Location) for implementation details.

Parameters:
loc1 - the first Location
loc2 - the second Location
latSpacing - of grid nodes
lonSpacing - of grid nodes
anchor - Location for grid; may be null
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
See Also:
Region.Region(Location, Location)

GriddedRegion

public GriddedRegion(Location loc1,
                     Location loc2,
                     double spacing,
                     Location anchor)
Initializes a GriddedRegion from a pair of Locations. When viewed in a Mercator projection, the region will be a rectangle. If either both latitude or both longitude values are the same, an exception is thrown.

Note: In an exception to the rules of insidedness defined in the Shape interface, Locations that fall on northern or eastern borders of this region are considered inside. See Region.Region(Location, Location) for implementation details.

Parameters:
loc1 - the first Location
loc2 - the second Location
spacing - of grid nodes
anchor - Location for grid; may be null
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
See Also:
Region.Region(Location, Location)

GriddedRegion

public GriddedRegion(LocationList border,
                     BorderType type,
                     double latSpacing,
                     double lonSpacing,
                     Location anchor)
Initializes 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.

Parameters:
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
Throws:
IllegalArgumentException - if the border does not have at least 3 points or spacing is outside the range 0° < spacing ≤ 5°
NullPointerException - if the border is null
See Also:
Region.Region(LocationList, BorderType)

GriddedRegion

public GriddedRegion(LocationList border,
                     BorderType type,
                     double spacing,
                     Location anchor)
Initializes 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.

Parameters:
border - Locations
type - the BorderType to use when initializing; a null value defaults to BorderType.MERCATOR_LINEAR
spacing - of grid nodes
anchor - Location for grid; may be null
Throws:
IllegalArgumentException - if the border does not have at least 3 points or spacing is outside the range 0° < spacing ≤ 5°
NullPointerException - if the border is null
See Also:
Region.Region(LocationList, BorderType)

GriddedRegion

public GriddedRegion(Location center,
                     double radius,
                     double latSpacing,
                     double lonSpacing,
                     Location anchor)
Initializes a circular GriddedRegion. Internally, the centerpoint and radius are used to create a circular region composed of straight line segments that span 10° wedges. 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.

Parameters:
center - of the circle
radius - of the circle
latSpacing - of grid nodes
lonSpacing - of grid nodes
anchor - Location for grid; may be null
Throws:
IllegalArgumentException - if radius is outside the range 0 km < radius ≤ 1000 km or spacing is outside the range 0° < spacing ≤ 5°
NullPointerException - if center is null
See Also:
Region.Region(Location, double)

GriddedRegion

public GriddedRegion(Location center,
                     double radius,
                     double spacing,
                     Location anchor)
Initializes a circular GriddedRegion. Internally, the centerpoint and radius are used to create a circular region composed of straight line segments that span 10° wedges. 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.

Parameters:
center - of the circle
radius - of the circle
spacing - of grid nodes
anchor - Location for grid; may be null
Throws:
IllegalArgumentException - if radius is outside the range 0 km < radius ≤ 1000 km or spacing is outside the range 0° < spacing ≤ 5°
NullPointerException - if center is null
See Also:
Region.Region(Location, double)

GriddedRegion

public GriddedRegion(LocationList line,
                     double buffer,
                     double latSpacing,
                     double lonSpacing,
                     Location anchor)
Initializes a GriddedRegion as a buffered area around a line. 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.


Parameters:
line - at center of buffered region
buffer - distance from line
latSpacing - of grid nodes
lonSpacing - of grid nodes
anchor - Location for grid; may be null
Throws:
NullPointerException - if line is null
IllegalArgumentException - if buffer is outside the range 0 km < buffer ≤ 500 km or spacing is outside the range 0° < spacing ≤ 5°
See Also:
Region.Region(LocationList, double)

GriddedRegion

public GriddedRegion(LocationList line,
                     double buffer,
                     double spacing,
                     Location anchor)
Initializes a GriddedRegion as a buffered area around a line. 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.


Parameters:
line - at center of buffered region
buffer - distance from line
spacing - of grid nodes
anchor - Location for grid; may be null
Throws:
NullPointerException - if line is null
IllegalArgumentException - if buffer is outside the range 0 km < buffer ≤ 500 km or spacing is outside the range 0° < spacing ≤ 5°
See Also:
Region.Region(LocationList, double)

GriddedRegion

public GriddedRegion(Region region,
                     double latSpacing,
                     double lonSpacing,
                     Location anchor)
Initializes a GriddedRegion with a Region.

Parameters:
region - to use as border for new GriddedRegion
latSpacing - of grid nodes
lonSpacing - of grid nodes
anchor - Location for grid; may be null
Throws:
IllegalArgumentException - if spacing is outside the range 0° < spacing ≤ 5°
NullPointerException - if region is null
See Also:
Region.Region(Region)

GriddedRegion

public GriddedRegion(Region region,
                     double spacing,
                     Location anchor)
Initializes a GriddedRegion with a Region.

Parameters:
region - to use as border for new GriddedRegion
spacing - of grid nodes
anchor - Location for grid; may be null
Throws:
IllegalArgumentException - if spacing is outside the range 0° < spacing ≤ 5°
NullPointerException - if region is null
See Also:
Region.Region(Region)
Method Detail

getLatSpacing

public double getLatSpacing()
Returns the longitudinal grid node spacing for this region.

Returns:
the longitudinal grid node spacing (in degrees)

getLonSpacing

public double getLonSpacing()
Returns the latitudinal grid node spacing for this region.

Returns:
the latitudinal grid node spacing (in degrees)

getSpacing

public double getSpacing()
Returns the grid node spacing for this region. If the lat and lon node spacing differs, method defaults to getLatSpacing().

Returns:
the grid node spacing (in degrees)

isSpacingUniform

public boolean isSpacingUniform()
Returns whether the lat and lon spacing are the same.

Returns:
true if lat and lon spacing are the same; false otherwise.

getNodeCount

public int getNodeCount()
Returns the total number of grid nodes in this region.

Returns:
the number of grid nodes

getNumLocations

public int getNumLocations()
Alternative to getNodeCount().

Returns:

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 idx,
                Direction dir)
Returns the index of the node at the supplied Direction from the node at the supplied index.

Parameters:
idx - 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

clone

public GriddedRegion clone()
Returns an exact, independent copy of this GriddedRegion.

Overrides:
clone in class Region
Returns:
a copy of this Region

subRegion

public GriddedRegion subRegion(Region region)
Creates a new GriddedRegion from this (the parent) and another Region. The border of the new region is the intersection of the borders of the parent and the passed-in region. The new region also inherits the grid spacing and node-alignment of the parent. The method returns null if the two regions do not overlap.

Note that the returned GriddedRegion may be devoid of grid nodes, e.g. in cases where the sub-region is too small to contain any nodes of the parent grid. Such a situation may arise if the sub-region represents the area of influence of a small magnitude earthquake or aftershock. If the closest point to the sub-region in the parent grid is desired, then compute the subRegionCentroid and use:
 if (newGriddedRegion.isEmpty()) {
        int idx = indexForLocation(subRegionCentroid);
        if (idx != -1) {
                Location loc = locationForIndex(idx);
        }
 }
 

Parameters:
region - to use as border for sub-region
Returns:
a new GriddedRegion or null if the the sub-region does not intersect its parent (this)
See Also:
isEmpty()

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>

getNodeList

public LocationList getNodeList()
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

getLocation

public Location getLocation(int index)
Alternative to locationForIndex(int index)

Parameters:
index -
Returns:

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

getMinGridLat

public double getMinGridLat()
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)

getMaxGridLat

public double getMaxGridLat()
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)

getMinGridLon

public double getMinGridLon()
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)

getMaxGridLon

public double getMaxGridLon()
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)

toXMLMetadata

public Element toXMLMetadata(Element root)
Specified by:
toXMLMetadata in interface XMLSaveable
Overrides:
toXMLMetadata in class Region

fromXMLMetadata

public static GriddedRegion fromXMLMetadata(Element root)
Initializes a new Region from stored metadata.

Parameters:
root - metadata element
Returns:
a GriddedRegion