nsidc.spheres
Class SphericalPolygon

java.lang.Object
  nsidc.spheres.Sphere
      nsidc.spheres.SphericalPolygon

public class SphericalPolygon

extends Sphere

SphericalPolygon class - provide services and information relating to a spherical polygon.

A spherical polygon is a polygon on a sphere with corner points connected by great circle arcs.

This class assumes a spherical earth.

This class connects corner points with the shortest great circle arc and makes no assumptions about convexity. A poorly defined spherical polygon may well have sides that cross.

Field Summary

Point[]	corner_point Array for polygon corner point locations.
Point	external_point A point (probably) outside the polygon.
LatRange	lat_range Latitude range of the arcs that make up the polygon
LonRange	lon_range Longitude range of the polygon
double	perimeter_deg Perimeter of the polygon in degrees.
double	perimeter_rad Perimeter of the polygon in radians.

Fields inherited from class nsidc.spheres.Sphere

radius, Re_km

Constructor Summary

SphericalPolygon(double[] given_lat, double[] given_lon)
Given lat and lon arrays.

SphericalPolygon(Point[] given_points)
Given an array of points.

Method Summary

boolean	contains(Point given_point) Determine if this polygon contains a given point.
boolean	containsSTP(Point given_point) Determine if this polygon contains a given point using STP.
SphericalPolygon	densify(double distance_rad) Densify the polygon
Point	getExternalPoint() Return the point currently being used as the "external" point.
Point	guessExternalPoint() Guess a point that is outside the polygon.
boolean	overlaps(LatLonBoundingBox box) Determine if this polygon overlaps a lat/lon bounding box.
boolean	overlaps(Scene scene) Determine if this polygon overlaps a scene.
boolean	overlaps(SphericalPolygon other) Determine if this polygon overlaps another.
double	rangeMax(double[] array)
double	rangeMin(double[] array)
void	setExternalPoint(Point given_point) Set the point that is to be used as the "external" point.
protected void	systemLog(java.lang.String msg, int level) Log diagnostic messages
java.lang.String	toString()

Methods inherited from class nsidc.spheres.Sphere

degrees, degrees, getRadius, normalize, normalize, radians, radians, scalarTripleProductTest, setRadius, systemLog

Methods inherited from class java.lang.Object

clone, equals, finalize, getClass, hashCode, notify, notifyAll, wait, wait, wait

Field Detail

corner_point

public Point[] corner_point

Array for polygon corner point locations.

lon_range

public LonRange lon_range

Longitude range of the polygon

lat_range

public LatRange lat_range

Latitude range of the arcs that make up the polygon

perimeter_rad

public double perimeter_rad

Perimeter of the polygon in radians.

perimeter_deg

public double perimeter_deg

Perimeter of the polygon in degrees.

external_point

public Point external_point

A point (probably) outside the polygon.

Constructor Detail

SphericalPolygon

public SphericalPolygon(double[] given_lat,
                        double[] given_lon)

Given lat and lon arrays.

SphericalPolygon

public SphericalPolygon(Point[] given_points)

Given an array of points.

Method Detail

guessExternalPoint

public Point guessExternalPoint()

Guess a point that is outside the polygon.

This method has to assume that the polygon is somewhat reasonable.

If the lon range is the full 360 we're guessing the polygon includes a pole. We're also guessing the included pole is the pole nearest the edges, so the other pole and the surrounding area would be excluded.

For most purposes those are reasonable guesses, but if you are using a polygon with an unusual shape you should set the external point yourself. If your polygon covers more than a hemisphere, or won't fit within a hemisphere, it counts as "unusual".

If the lon range is not the full 360 the task is much easier and the guess should be correct.

getExternalPoint

public Point getExternalPoint()

Return the point currently being used as the "external" point.

setExternalPoint

public void setExternalPoint(Point given_point)

Set the point that is to be used as the "external" point.

contains

public boolean contains(Point given_point)

Determine if this polygon contains a given point.

This method creates a great circle arc between the point of interest and the "known" external point and counts how many times that arc crosses the edges of the polygon. Iff the arc crosses an odd number of edges the point of interest must be inside the polygon.

The corner points are assumed to be in some order. This should work with both convex and concave polygons, but make sure the external point actually is external.

For corner points and points on the edge of the polygon the behavior is undefined. It "should" be that corner points are "outside" (two edge crossings) and edge points are "inside" (one edge crossing) but it's really down to the precision of the math processor and which way the rounding goes.

Parameters:

given_point - Point of interest.

containsSTP

public boolean containsSTP(Point given_point)

Determine if this polygon contains a given point using STP.

This method checks the scalar triple product of the point and consective corner points all the way around the polygon. If the point is on the same side of every edge, the point must be inside the polygon.

The corner points are assumed to be in some order and the polygon has to be convex for this to work.

Parameters:

given_point - Point of interest.

overlaps

public boolean overlaps(SphericalPolygon other)

Determine if this polygon overlaps another. After determining if it's even possible, and we don't have the trivial case where one polygon is entirely inside the other, this method checks for arc instersections between the sides of the two polygons. If any arcs intersect the polygons overlap.

Returns:

true if the polygons overlap.
false if the polygons do not overlap.

See Also:

GreatCircleArc

overlaps

public boolean overlaps(LatLonBoundingBox box)

Determine if this polygon overlaps a lat/lon bounding box.

After determining if it's even possible, and we don't have the trivial case where one area is entirely inside the other, this method checks for arc intersections between the sides of the two areas. If any arcs intersect the areas overlap.

Returns:

true if the areas overlap.
false if the areas do not overlap.

See Also:

LatLonBoundingBox, GreatCircleArc

overlaps

public boolean overlaps(Scene scene)

Determine if this polygon overlaps a scene.

After determining if it's even possible, and we don't have the trivial case where one area is entirely inside the other, this method checks for arc instersections between the sides of the two areas. If any arcs intersect the areas overlap.

Returns:

true if the areas overlap.
false if the areas do not overlap.

See Also:

Scene, GreatCircleArc

densify

public SphericalPolygon densify(double distance_rad)

Densify the polygon

Densify each arc of the spherical polygon to

Parameters:

distance_rad - The maximum distance in radians between points in the densified polygon.

Returns:

SphericalPolygon dense_spherical_polygon A denser spherical polygon defining the same area.

toString

public java.lang.String toString()

rangeMax

public double rangeMax(double[] array)

rangeMin

public double rangeMin(double[] array)

systemLog

protected void systemLog(java.lang.String msg,
                         int level)

Log diagnostic messages

Overrides:

systemLog in class Sphere

Parameters:

msg - Message to log.

level - Debug sensitivity.