com.bbn.openmap.proj
Interface Projection

All Superinterfaces:
java.io.Serializable
All Known Subinterfaces:
EqualArc
All Known Implementing Classes:
CADRG, LLXY, Proj

public interface Projection
extends java.io.Serializable

Projection interface to the OpenMap projection library.

This is a READONLY interface to the projection object. See the Proj class for read/write access.

A projection is an object that is maintained by the map, and represents a abstract "view" of the data. The projection has the properties of x-width, * y-height, scale (in pixels/meters), and latitude/longitude center point.

Projection Notes/Assumptions:

Implementation Notes:

Bibliography:


Many of the specific projection equations were taken from Map Projections --A Working Manual , by John Synder.

See Also:
Proj, Cylindrical, Mercator, CADRG, Azimuth, Orthographic

Method Summary
 java.awt.Point forward(float lat, float lon)
          Forward project lat,lon coordinates into xy space.
 java.awt.Point forward(float lat, float lon, java.awt.Point pt)
          Forward projects lat,lon coordinates into XY space and returns a Point.
 java.awt.Point forward(float lat, float lon, java.awt.Point pt, boolean isRadian)
          Forward projects lat,lon coordinates into XY space and returns a Point.
 java.awt.Point forward(LatLonPoint llpoint)
          Forward project a LatLonPoint into XY space.
 java.awt.Point forward(LatLonPoint llp, java.awt.Point pt)
          Forward projects a LatLonPoint into XY space and return a Point.
 java.util.ArrayList forwardArc(LatLonPoint c, boolean radians, float radius, int nverts, float start, float extent, int arcType)
          Forward project a LatLon Arc.
 java.util.ArrayList forwardCircle(LatLonPoint c, boolean radians, float radius, int nverts, boolean isFilled)
          Forward project a LatLon Circle.
 java.util.ArrayList forwardLine(LatLonPoint ll1, LatLonPoint ll2, int ltype, int nsegs)
          Forward project a LatLon Line.
 java.util.ArrayList forwardPoly(float[] rawllpts, int ltype, int nsegs, boolean isFilled)
          Forward project a LatLon Poly.
 java.util.ArrayList forwardRaster(LatLonPoint llNW, LatLonPoint llSE, java.awt.Image image)
          Forward projects a raster.
 boolean forwardRaw(float[] rawllpts, int rawoff, int[] xcoords, int[] ycoords, boolean[] visible, int copyoff, int copylen)
          Forward project a raw array of radian points.
 java.util.ArrayList forwardRect(LatLonPoint ll1, LatLonPoint ll2, int ltype, int nsegs, boolean isFilled)
          Forward project a LatLon Rectangle.
 LatLonPoint getCenter()
          Get the center LatLonPoint.
 int getHeight()
          Get the height of the map.
 LatLonPoint getLowerRight()
          Get the lower right (southeast) point of the projection.
 float getMaxScale()
          Get the maximum scale.
 float getMinScale()
          Get the minimum scale.
 java.lang.String getName()
          Get the String used as a name, usually as a type.
 java.lang.String getProjectionID()
          Get the projection ID string.
 int getProjectionType()
          Get the type of projection.
 float getScale()
          Get the scale.
 float getScale(LatLonPoint ll1, LatLonPoint ll2, java.awt.Point point1, java.awt.Point point2)
          Given a couple of points representing a bounding box, find out what the scale should be in order to make those points appear at the corners of the projection.
 LatLonPoint getUpperLeft()
          Get the upper left (northwest) point of the projection.
 int getWidth()
          Get the width of the map.
 LatLonPoint inverse(int x, int y)
          Inverse project x,y coordinates.
 LatLonPoint inverse(int x, int y, LatLonPoint llpt)
          Inverse project x,y coordinates into a LatLonPoint.
 LatLonPoint inverse(java.awt.Point point)
          Inverse project a Point.
 LatLonPoint inverse(java.awt.Point point, LatLonPoint llpt)
          Inverse project a point with llpt.
 boolean isPlotable(float lat, float lon)
          Checks if a LatLonPoint is plot-able.
 boolean isPlotable(LatLonPoint llpoint)
          Checks if a LatLonPoint is plot-able.
 Projection makeClone()
          Clone the projection.
 void pan(float Az)
          Pan the map/projection.
 void pan(float Az, float c)
          Pan the map/projection.
 

Method Detail

getScale

public float getScale()
Get the scale.

Returns:
float scale

getMaxScale

public float getMaxScale()
Get the maximum scale.

Returns:
float maxscale

getMinScale

public float getMinScale()
Get the minimum scale.

Returns:
float minscale

getCenter

public LatLonPoint getCenter()
Get the center LatLonPoint.

Returns:
center point

getWidth

public int getWidth()
Get the width of the map.

Returns:
int width.

getHeight

public int getHeight()
Get the height of the map.

Returns:
int height.

getProjectionType

public int getProjectionType()
Get the type of projection.

Returns:
int type

getProjectionID

public java.lang.String getProjectionID()
Get the projection ID string.

Returns:
String projID

getUpperLeft

public LatLonPoint getUpperLeft()
Get the upper left (northwest) point of the projection.

Returns the upper left point (or closest equivalent) of the projection based on the center point and height and width of screen.

This is trivial for most cylindrical projections, but much more complicated for azimuthal projections.

Returns:
LatLonPoint

getLowerRight

public LatLonPoint getLowerRight()
Get the lower right (southeast) point of the projection.

Returns the lower right point (or closest equivalent) of the projection based on the center point and height and width of screen.

This is trivial for most cylindrical projections, but much more complicated for azimuthal projections.

Returns:
LatLonPoint

isPlotable

public boolean isPlotable(LatLonPoint llpoint)
Checks if a LatLonPoint is plot-able.

Call this to check and see if a LatLonPoint can be plotted. This is meant to be used for checking before projecting and rendering Point objects (bitmaps or text objects tacked at a LatLonPoint for instance).

Parameters:
llpoint - LatLonPoint
Returns:
boolean

isPlotable

public boolean isPlotable(float lat,
                          float lon)
Checks if a LatLonPoint is plot-able.

Call this to check and see if a LatLonPoint can be plotted. This is meant to be used for checking before projecting and rendering Point objects (bitmaps or text objects tacked at a LatLonPoint for instance).

Parameters:
lat - float latitude in decimal degrees
lon - float longitude in decimal degrees
Returns:
boolean

forward

public java.awt.Point forward(LatLonPoint llpoint)
Forward project a LatLonPoint into XY space.

Parameters:
llpoint - LatLonPoint
Returns:
Point (new)

forward

public java.awt.Point forward(LatLonPoint llp,
                              java.awt.Point pt)
Forward projects a LatLonPoint into XY space and return a Point.

Parameters:
llp - LatLonPoint to be projected
pt - Resulting XY Point
Returns:
Point pt

forward

public java.awt.Point forward(float lat,
                              float lon)
Forward project lat,lon coordinates into xy space.

Parameters:
lat - float latitude in decimal degrees
lon - float longitude in decimal degrees decimal degrees
Returns:
Point (new)

forward

public java.awt.Point forward(float lat,
                              float lon,
                              java.awt.Point pt)
Forward projects lat,lon coordinates into XY space and returns a Point.

Parameters:
lat - float latitude in decimal degrees
lon - float longitude in decimal degrees
pt - Resulting XY Point
Returns:
Point pt

forward

public java.awt.Point forward(float lat,
                              float lon,
                              java.awt.Point pt,
                              boolean isRadian)
Forward projects lat,lon coordinates into XY space and returns a Point.

Parameters:
lat - float latitude in radians
lon - float longitude in radians
pt - Resulting XY Point
isRadian - placeholder argument indicating that lat,lon arguments are in radians (can be true or false)
Returns:
Point pt
See Also:
forward(float,float,Point)

inverse

public LatLonPoint inverse(java.awt.Point point)
Inverse project a Point.

Parameters:
point - XY Point
Returns:
LatLonPoint (new)

inverse

public LatLonPoint inverse(java.awt.Point point,
                           LatLonPoint llpt)
Inverse project a point with llpt.

Parameters:
point - x,y Point
llpt - resulting LatLonPoint
Returns:
LatLonPoint llpt

inverse

public LatLonPoint inverse(int x,
                           int y)
Inverse project x,y coordinates.

Parameters:
x -
y -
Returns:
LatLonPoint (new)

inverse

public LatLonPoint inverse(int x,
                           int y,
                           LatLonPoint llpt)
Inverse project x,y coordinates into a LatLonPoint.

Parameters:
x - integer x coordinate
y - integer y coordinate
llpt - LatLonPoint
Returns:
LatLonPoint llpt
See Also:
Proj.inverse(Point)

pan

public void pan(float Az,
                float c)
Pan the map/projection.

Parameters:
Az - azimuth "east of north" in decimal degrees: -180 <= Az <= 180
c - arc distance in decimal degrees

pan

public void pan(float Az)
Pan the map/projection.

Parameters:
Az - azimuth "east of north" in decimal degrees: -180 <= Az <= 180

forwardPoly

public java.util.ArrayList forwardPoly(float[] rawllpts,
                                       int ltype,
                                       int nsegs,
                                       boolean isFilled)
Forward project a LatLon Poly.

Returns a ArrayList of (x[], y[]) coordinate pair(s) of the projected poly.

RESTRICTIONS:


All the following restrictions apply to LatLon polygons (either filled or non-filled). Many of these restrictions apply to other poly-like ArrayList graphics (Lines, Rectangles, Circles, Ellipses, ...). See also restrictions on LatLon lines.

For the cylindrical projections, (e.g. Mercator), your polygons should not include or touch the poles. This is because a polygon or polyline that includes a pole becomes a non-continuous straight line on the map. "So what about Antarctica", you say, "after all it's a polygon that is draped over the South Pole". Well, if you want to see it in a cylindrical projection, you will need to "augment" the vertices to turn it into a valid x-y polygon. You could do this by removing the segment which crosses the dateline, and instead add two extra edges down along both sides of the dateline to very near the south pole and then connect these ends back the other way around the world (not across the dateline) with a few extra line segments (remember the line length restrictions ). This way you've removed the polar anomaly from the data set. On the screen, all you see is a sliver artifact down along the dateline. This is the very method that our DCW data server shows Antarctica.

There is a fundamental ambiguity with filled polygons on a sphere: which side do you draw the fill-color? The Cylindrical family will draw the polygon as if it were in x-y space. For the Azimuthal projections, (e.g. Orthographic), you can have polygons that cover the pole, but it's important to specify the vertices in a clockwise order so that we can do the correct clipping along the hemisphere edge. We traverse the vertices assuming that the fill will be to the right hand side if the polygon straddles the edge of the projection. (This default can be changed).

To Be (Mostly) Safe:

Optimization Notes:

The projection library deals internally in radians, and so you're required to pass in an array of radian points. See ProjMath.arrayDegToRad(float[]) for an efficient in-place conversion.

For no-frills, no-assumptions, fast and efficient projecting, see forwardRaw() .

Parameters:
rawllpts - float[] of lat,lon,lat,lon,... in RADIANS!
ltype - line type (straight, rhumbline, greatcircle)
nsegs - number of segment points (only for greatcircle or rhumbline line types, and if < 1, this value is generated internally)
isFilled - poly is filled? or not
Returns:
ArrayList of x[], y[], x[], y[], ... projected poly
See Also:
forwardRaw(float[], int, int[], int[], boolean[], int, int), LineType.Straight, LineType.Rhumb, LineType.GreatCircle

forwardLine

public java.util.ArrayList forwardLine(LatLonPoint ll1,
                                       LatLonPoint ll2,
                                       int ltype,
                                       int nsegs)
Forward project a LatLon Line.

Returns a ArrayList of (x[], y[]) coordinate pair(s) of the projected line(s).

RESTRICTIONS:

A line segment must be less than 180 degrees of arc (half the circumference of the world). If you need to draw a longer line, then draw several several individual segments of less than 180 degrees, or draw a single polyline of those segments.

We make this restriction because from any point on a sphere, you can reach any other point with a maximum traversal of 180degrees of arc.

Furthermore, for the Cylindrical family of projections, a line must be < 180 degrees of arc in longitudinal extent. In other words, the difference of longitudes between both vertices must be < 180 degrees. Same as above: if you need a long line, you must break it into several segments.

Parameters:
ll1 - LatLonPoint
ll2 - LatLonPoint
ltype - line type (straight, rhumbline, greatcircle)
nsegs - number of segment points (only for greatcircle or rhumbline line types, and if < 1, this value is generated internally)
Returns:
ArrayList
See Also:
LineType.Straight, LineType.Rhumb, LineType.GreatCircle

forwardRect

public java.util.ArrayList forwardRect(LatLonPoint ll1,
                                       LatLonPoint ll2,
                                       int ltype,
                                       int nsegs,
                                       boolean isFilled)
Forward project a LatLon Rectangle.

Returns a ArrayList of (x[], y[]) coordinate pairs of the projected points.

Rects have the same restrictions as polys and lines .

Parameters:
ll1 - LatLonPoint of northwest corner
ll2 - LatLonPoint of southeast corner
ltype - line type (straight, rhumbline, greatcircle)
nsegs - number of segment points (only for greatcircle or rhumbline line types, and if < 1, this value is generated internally)
Returns:
ArrayList
See Also:
forwardPoly(float[], int, int, boolean)

forwardArc

public java.util.ArrayList forwardArc(LatLonPoint c,
                                      boolean radians,
                                      float radius,
                                      int nverts,
                                      float start,
                                      float extent,
                                      int arcType)
Forward project a LatLon Arc.

Arcss have the same restrictions as polys .

Parameters:
c - LatLonPoint center of circle
radians - radius in radians or decimal degrees?
radius - radius of circle (0 < radius < 180)
nverts - number of vertices of the circle poly.
start - the starting angle of the arc in decimal degrees.
extent - the angular extent of the arc in decimal degrees.
arcType - type of arc to create - see java.awt.geom.Arc2D for (OPEN, CHORD, PIE). Arc2D.OPEN means that the just the points for the curved edge will be provided. Arc2D.PIE means that addition lines from the edge of the curve to the center point will be added. Arc2D.CHORD means a single line from each end of the curve will be drawn.
See Also:
forwardPoly(float[], int, int, boolean)

forwardCircle

public java.util.ArrayList forwardCircle(LatLonPoint c,
                                         boolean radians,
                                         float radius,
                                         int nverts,
                                         boolean isFilled)
Forward project a LatLon Circle.

Circles have the same restrictions as polys .

Parameters:
c - LatLonPoint center of circle
radians - radius in radians or decimal degrees?
radius - radius of circle (0 < radius < 180)
nverts - number of vertices of the circle poly.
See Also:
forwardPoly(float[], int, int, boolean)

forwardRaster

public java.util.ArrayList forwardRaster(LatLonPoint llNW,
                                         LatLonPoint llSE,
                                         java.awt.Image image)
Forward projects a raster.

This is currently unimplemented in the projection implementations.

Parameters:
llNW - LatLonPoint of NorthWest corner of Image
llSE - LatLonPoint of SouthEast corner of Image
image - raster image

forwardRaw

public boolean forwardRaw(float[] rawllpts,
                          int rawoff,
                          int[] xcoords,
                          int[] ycoords,
                          boolean[] visible,
                          int copyoff,
                          int copylen)
Forward project a raw array of radian points. This assumes nothing about the array of coordinates. In no way does it assume the points are connected or that the composite figure is to be filled.

It does populate a visible array indicating whether the points are visible on the projected view of the world.

Parameters:
rawllpts - array of lat,lon,... in RADIANS!
rawoff - offset into rawllpts
xcoords - x coordinates
ycoords - y coordinates
visible - coordinates visible?
copyoff - offset into x,y,visible arrays
copylen - number of coordinates (coordinate arrays should be at least this long, rawllpts should be at least twice as long).
Returns:
boolean true if all points visible, false if some points not visible.

makeClone

public Projection makeClone()
Clone the projection.

Returns:
Projection clone of this one.

getName

public java.lang.String getName()
Get the String used as a name, usually as a type.


getScale

public float getScale(LatLonPoint ll1,
                      LatLonPoint ll2,
                      java.awt.Point point1,
                      java.awt.Point point2)
Given a couple of points representing a bounding box, find out what the scale should be in order to make those points appear at the corners of the projection.

Parameters:
ll1 - the upper left coordinates of the bounding box.
ll2 - the lower right coordinates of the bounding box.
point1 - a java.awt.Point reflecting a pixel spot on the projection that matches the ll1 coordinate, the upper left corner of the area of interest.
point2 - a java.awt.Point reflecting a pixel spot on the projection that matches the ll2 coordinate, usually the lower right corner of the area of interest.


Copyright (C) BBNT Solutions LLC; See http://openmap.bbn.com/ for details