org.opensha.commons.geo
Class GriddedRegion

java.lang.Object
  org.opensha.commons.geo.Region
      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