Package noaa.coastwatch.util

Class EarthArea

java.lang.Object
noaa.coastwatch.util.EarthArea
All Implemented Interfaces:
Cloneable, Iterable<int[]>
public class EarthArea extends Object implements Cloneable, Iterable<int[]>
The EarthArea class represents irregularly shaped areas on a sphere. In cases where simple north, south, east, and west bounds are inadequate for describing an area, the earth area class may be used to set up and query if a certain earth location is inside an irregular shape. The area information is maintained using a set of 1x1 degree grid squares covering the entire globe. Each grid square is referenced by its lower-left corner -- for example the grid square (10, 20) covers the area between 10N to 11N and 20E to 21E. All earth locations must have a latitude range of [-90..90] and longitude range of [-180..180).
Since:
3.1.1
Author:
Peter Hollemans

  • Constructor Details

    • EarthArea

      public EarthArea()
      Creates an empty earth area with no locations.

    • EarthArea

      public EarthArea(EarthTransform trans, DataLocation min, DataLocation max)
      Creates a new earth area from the specified parameters. The parameters are used to perform an exploration of the area to include all earth locations. The exploration is started at the center of the data location boundaries. After exploration, an expansion of one grid square is performed.
      Parameters:
      trans - an earth transform to use for exploration.
      min - the minimum data location to explore.
      max - the maximum data location to explore.

  • Method Details

    • getCoverage

      public double getCoverage()
      Gets the coverage of this area as a fraction of the total area of the earth. The coverage is an estimate based on the 1x1 degree grid squares coveraged by the area.
      Returns:
      the coverage of this area as a fraction in the range [0..1].
      Since:
      3.8.0

    • intersection

      public EarthArea intersection(EarthArea area)
      Computes the intersection between this area and another. The resulting area includes only grid squares which occur both in this area and in the other area.
      Parameters:
      area - the other earth area to compute the intersection.
      Returns:
      a new earth area containing only grid squares in common.

    • isEmpty

      public boolean isEmpty()
      Returns true if this earth area contains no grid squares.

    • getIterator

      public Iterator<int[]> getIterator()
      Returns an iterator over the grid square elements. Each object returned by the iterator contains the lower-left int[] coordinates of the grid square as [lat, lon].

    • iterator

      public Iterator<int[]> iterator()
      Specified by:
      iterator in interface Iterable<int[]>

    • contains

      public boolean contains(EarthLocation loc)
      Determines if an earth location is contained in this area.
      Parameters:
      loc - the earth location to search for.
      Returns:
      true if earth location is in this area, or false if not.

    • contains

      public boolean contains(int[] square)
      Determines if a grid square is contained in this area.
      Parameters:
      square - the grid square lower-left corner as [lat, lon].
      Returns:
      true if grid square is in this area, or false if not.

    • add

      public void add(EarthLocation loc)
      Adds an earth location to this area.
      Parameters:
      loc - the earth location to add.

    • addAll

      public void addAll()
      Adds all earth locations to this area.

    • remove

      public void remove(EarthLocation loc)
      Removes an earth location from this area.
      Parameters:
      loc - the earth location to remove.

    • getIndex

      public int getIndex(int lat, int lon)
      Computes a square index based on a grid square.
      Parameters:
      lat - the grid square lower-left corner latitude in the range [-90,89].
      lon - the grid square lower-left corner longitude in the range [-180,179].
      Returns:
      the index for the square or -1 if the grid square is invalid.

    • getIndex

      public int getIndex(EarthLocation loc)
      Computes a square index based on an earth location.
      Parameters:
      loc - the earth location to convert.
      Returns:
      the index for the square or -1 if the earth location is invalid.

    • expand

      public void expand()
      Expands the current area by 1 degree in all directions. If the current area is as follows: 
         . . . . . .
   . . . . . .
   . . * * . .
   . * * . . .
   . . * . . .
   . . . . . .
   . . . . . .
      then the expanded area includes the boundary points: 
         . . . . . .
   . x x x x .
   x x * * x .
   x * * x x .
   x x * x . .
   . x x x . .
   . . . . . .

    • explore

      public void explore(EarthTransform trans, DataLocation min, DataLocation max, EarthLocation start)
      Explores within data location boundaries using an earth transform to find all locations within an area. The new grid squares are added to the area. The exploration terminates when squares that are already part of the area are encountered, the data location boundaries are hit, or the earth transform returns an invalid data location.
      Parameters:
      trans - an earth transform to use for exploration.
      min - the minimum data location to explore.
      max - the maximum data location to explore.
      start - the starting earth location for exploration.

    • getExtremes

      public int[] getExtremes()
      Gets the geographic extremes in this area. If this earth area crosses the 180E/180W border, the east and west extremes are adjusted so they both fall in the range [0..360]. Otherwise they fall in the range [-180..180].
      Returns:
      the geographic extremes as [north, south, east, west].

    • equals

      public boolean equals(Object o)
      Returns true if this area exactly equals another area.
      Overrides:
      equals in class Object

    • clone

      public Object clone()
      Creates an independent copy of this area.
      Overrides:
      clone in class Object