## 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:

- At the center point of the projection, North is to the top of the screen.
- LatLon Polygon Restrictions.
- LatLon Line Restrictions.

#### Implementation Notes:

- This methods in this interface are safe to use among different threads, BUT the underlying classes may not be. Use with care.

#### 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.
  - `pan(±180, c)` pan south `c' degrees
  - `pan(-90, c)` pan west `c' degrees
  - `pan(0, c)` pan north `c' degrees
  - `pan(90, c)` pan east `c' degrees

  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.
  - `pan(±180)` pan south
  - `pan(-90)` pan west
  - `pan(0)` pan north
  - `pan(90)` pan east

  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:

  - Polygons should not touch or encompass the poles unless you will be viewing them with azimuthal projections, such as Orthographic.
  - Polygons should not encompass more area than one hemisphere.
  - Polygon vertices should be specified in "clockwise", fill-on-right order to ensure proper filling.
  - Polygon edges are also restricted by the restrictions on LatLon lines .

  ### 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