## PIRL.Image_Tools Class Projection

```java.lang.Object
PIRL.Image_Tools.Projection
```
Direct Known Subclasses:
Equirectangular_Projection, Polar_Stereographic_Elliptical_Projection, Polar_Stereographic_Spherical_Projection

`public class Projectionextends Object`

A Projection is used to algorithmically map, or "project", from one image coordinate system to another while maintaining the spatial relationships of all coordinates.

Spatial projections are used in many contexts. The typical example is when a camera image of curved surface is to be mapped as if the surface were flat. The commonly known Mercator projection of a map of the Earth is such a projection. There are many map projections. See Snyder, John P., "Map Projections - A Working Manual", U.S Geological Survey Professional Paper 1395, 1987 for a discussion of the map projection algorithm used in these classes.

The core projection characteristic is an algorithm that maps coordinates from one coordinate system to another. The specific projection algorithms used - the implementation of a set of equations - will, of course, vary from one type of projection to another to achieve the desired mapping effect. In addition, the choice of projection is likey to depend on the range of coordinate values to be mapped - projections are likely to have increasing visual distortion effects as boundary conditions are approached - or the accuracy to be achieved - the implementing equations are like to make various simplifying assumptions. Nevertheless, all projections are expected to map coordinates between image and world coordinate systems. The former is in image pixel units of sample - horizontal distance from the left-most pixel - and and line - vertical distance from the top-most line - of a rectangular array of pixels. The latter is typically in planetary longitude - angular angular distance about the center of the planet relative to a zero-reference longitude - and latitude - angular angular distance about the center of the planet relative to the equator - usually measured in decimal degrees. However, other "world" coordinate systems are quite possible. In order to accommodate images of arbitrary location, an intermediate projeciton coordinate system is typically used by the projection equations, with a simple translational equation used to map between the projection coordinate system and the location of the image raster in that system.

A specific projection, implemented as a subclass of Projection, will require various parameters need by the projection equations. These are supplied by a PVL Parameter Aggregate. Because this Projection implementation assumes that planetary projections are to be implemented by subclasses, the Parameter group used to construct a Projection collects the common set of parameter values required by the specific projection algorithms. If all the required parameters are not provided the default identity projection - in which coordinate values are not changed - is used.

Version:
1.5
Author:

Field Summary
`protected  double` `Center_Latitude`
Projection planetographic center latitude in radians.
`static String` `CENTER_LATITUDE_PARAMETER_NAME`

`protected  double` `Center_Longitude`
`static String` `CENTER_LONGITUDE_PARAMETER_NAME`

`static double` `DBL_EPSILON`

`static double` `DEFAULT_NA`

`static boolean` `DEFAULT_USE_SPHERICAL`

`protected  double` `Eccentricity`

`static String` `EQUIRECTANGULAR_PROJECTION_NAME`

`protected  double` `Equitorial_Radius`

`static String` `EQUITORIAL_RADIUS_PARAMETER_NAME`

`static String` `ID`
Class name and version identification.
`protected  double` `Line_Offset`

`static String` `LINE_OFFSET_PARAMETER_NAME`

`protected  double` `Meters_per_Pixel`

`static String` `METERS_PER_PIXEL_PARAMETER_NAME`

`protected  double` `NA`

`static String` `NOT_APPLICABLE_CONSTANT_PARAMETER_NAME`

`protected  boolean` `Not_Identity`

`static double` `PI_OVER_2`

`static double` `PI_OVER_4`

`protected  boolean` `Planetocentric`

`static String` `PLANETOCENTRIC_PROJECTION_NAME`

`protected  double` `Polar_Radius`

`static String` `POLAR_RADIUS_PARAMETER_NAME`

`static String` `POLAR_STEREOGRAPHIC_PROJECTION_NAME`

`static String` `POLARSTEREOGRAPHIC_PROJECTION_NAME`

`static String` `POSITIVE_LONGITUDE_EAST_NAME`

`static String` `POSITIVE_LONGITUDE_PARAMETER_NAME`

`static String` `POSITIVE_LONGITUDE_WEST_NAME`

`protected  boolean` `Positive_West`

`static String` `PROJECTION_LATITUDE_PARAMETER_NAME`

`static String` `PROJECTION_PARAMETER_NAME`

`protected  double` `Sample_Offset`

`static String` `SAMPLE_OFFSET_PARAMETER_NAME`

Constructor Summary
`Projection()`
Constructs a default identity Projection.
`Projection(Parameter parameters)`
Constructs a Projection from a Parameter Aggregate.

Method Summary
` double` `Center_Latitude()`

` double` `Center_Longitude()`

`static Projection` `Create(Parameter parameters)`
Creates a Projection object that uses an appropriate specific Projection subclass projection implementation.
`static double` `Decimal_Degrees(String parts)`

`static String` `Degrees_Minutes_Seconds(double angle)`
Converts an angle in decimal degrees, to a degrees, minutes, seconds representation.
` double` `Eccentricity()`

`static double` ```Eccentricity(double polar_radius, double equitorial_radius)```
Calculate the planet eccentricity.
` double` `Equitorial_Radius()`

`protected static Parameter` ```Find_Parameter(Parameter label, String name)```
Find a named parameter in PDS label parameters.
`static String` `Hours_Minutes_Seconds(double angle)`
Converts an angle in decimal degrees, to an hours, minutes, seconds representation.
` boolean` `Is_Identity()`

` double` `Line_Offset()`

`protected  double` `Line_to_Projection_Y(double line)`

` double` `Local_Radius(double latitude)`
Calculate the radius of the planet at some latitude.
`static void` `main(String[] args)`

` String` `Name()`

` double` `Planetocentric_to_Planetographic(double latitude)`
Convert planetocentric latitude to planetographic latitude.
` boolean` `Planetocentric()`

` Projection` `Planetocentric(boolean planetocentric)`

` double` `Planetographic_to_Planetocentric(double latitude)`
Convert planetographic latitude to planetocentric latitude.
` double` `Polar_Radius()`

` boolean` `Positive_West()`

` Projection` `Positive_West(boolean positive_west)`

`static String` `Projection_Class_Name(String projection_name)`
Produce a class name for a projection name.
`protected  double` `Projection_X_to_Sample(double projection_x)`

`protected  double` `Projection_Y_to_Line(double projection_y)`

` double` `Resolution()`

` double` `Sample_Offset()`

`protected  double` `Sample_to_Projection_X(double sample)`

`static double` `To_180(double longitude)`
Ensure that a longitude value is in the range -180 to 180 degrees.
`static double` `To_360(double longitude)`
Ensure that a longitude value is in the range 0 to 360 degrees.
` Point` `to_Image(Point2D world_coordinate)`
Get the image sample,line coordinate for a world longitude,latitude coordinate.
` Point2D.Double` `to_World(Point2D image_coordinate)`
Get the world longitude,latitude coordinate for an image sample.line coordinate.
`static void` `Usage()`

`static boolean` `Use_Spherical(boolean enabled)`

Methods inherited from class java.lang.Object
`clone, equals, finalize, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait`

Field Detail

### ID

`public static final String ID`
Class name and version identification.

Constant Field Values

### PROJECTION_PARAMETER_NAME

`public static final String PROJECTION_PARAMETER_NAME`
Constant Field Values

### EQUIRECTANGULAR_PROJECTION_NAME

`public static final String EQUIRECTANGULAR_PROJECTION_NAME`
Constant Field Values

### POLAR_STEREOGRAPHIC_PROJECTION_NAME

`public static final String POLAR_STEREOGRAPHIC_PROJECTION_NAME`
Constant Field Values

### POLARSTEREOGRAPHIC_PROJECTION_NAME

`public static final String POLARSTEREOGRAPHIC_PROJECTION_NAME`
Constant Field Values

### PROJECTION_LATITUDE_PARAMETER_NAME

`public static final String PROJECTION_LATITUDE_PARAMETER_NAME`
Constant Field Values

### PLANETOCENTRIC_PROJECTION_NAME

`public static final String PLANETOCENTRIC_PROJECTION_NAME`
Constant Field Values

`public static final String EQUITORIAL_RADIUS_PARAMETER_NAME`
Constant Field Values

`public static final String POLAR_RADIUS_PARAMETER_NAME`
Constant Field Values

### METERS_PER_PIXEL_PARAMETER_NAME

`public static final String METERS_PER_PIXEL_PARAMETER_NAME`
Constant Field Values

### POSITIVE_LONGITUDE_PARAMETER_NAME

`public static final String POSITIVE_LONGITUDE_PARAMETER_NAME`
Constant Field Values

### POSITIVE_LONGITUDE_EAST_NAME

`public static final String POSITIVE_LONGITUDE_EAST_NAME`
Constant Field Values

### POSITIVE_LONGITUDE_WEST_NAME

`public static final String POSITIVE_LONGITUDE_WEST_NAME`
Constant Field Values

### CENTER_LATITUDE_PARAMETER_NAME

`public static final String CENTER_LATITUDE_PARAMETER_NAME`
Constant Field Values

### CENTER_LONGITUDE_PARAMETER_NAME

`public static final String CENTER_LONGITUDE_PARAMETER_NAME`
Constant Field Values

### SAMPLE_OFFSET_PARAMETER_NAME

`public static final String SAMPLE_OFFSET_PARAMETER_NAME`
Constant Field Values

### LINE_OFFSET_PARAMETER_NAME

`public static final String LINE_OFFSET_PARAMETER_NAME`
Constant Field Values

### NOT_APPLICABLE_CONSTANT_PARAMETER_NAME

`public static final String NOT_APPLICABLE_CONSTANT_PARAMETER_NAME`
Constant Field Values

### Not_Identity

`protected boolean Not_Identity`

### Positive_West

`protected boolean Positive_West`

### Planetocentric

`protected boolean Planetocentric`

### DEFAULT_NA

`public static final double DEFAULT_NA`
Constant Field Values

### Meters_per_Pixel

`protected double Meters_per_Pixel`

`protected double Equitorial_Radius`

`protected double Polar_Radius`

### NA

`protected double NA`

### Center_Latitude

`protected double Center_Latitude`
Projection planetographic center latitude in radians.

### Center_Longitude

`protected double Center_Longitude`

### Sample_Offset

`protected double Sample_Offset`

### Line_Offset

`protected double Line_Offset`

### Eccentricity

`protected double Eccentricity`

### PI_OVER_2

`public static final double PI_OVER_2`
Constant Field Values

### PI_OVER_4

`public static final double PI_OVER_4`
Constant Field Values

### DBL_EPSILON

`public static final double DBL_EPSILON`
Constant Field Values

### DEFAULT_USE_SPHERICAL

`public static final boolean DEFAULT_USE_SPHERICAL`
Constant Field Values
Constructor Detail

### Projection

```public Projection(Parameter parameters)
throws PVL_Exception```
Constructs a Projection from a Parameter Aggregate.

Parameters:
`parameters` - The Parameter Aggregate containing (at least) the minimally required parameter values. If all required parameters are not provided - including if the argument is null - the `identity projection flag` is set.
Throws:
`PVL_Exception` - If there is a problem reading the parameters or a parameter is found to have an invalid value.

### Projection

`public Projection()`
Constructs a default identity Projection.

The `identity projection flag` is set.

Method Detail

### Create

```public static Projection Create(Parameter parameters)
throws PVL_Exception,
NoSuchElementException,
UnsupportedOperationException,
Throwable```
Creates a Projection object that uses an appropriate specific Projection subclass projection implementation.

The choice of specific projection implementation is based on the value of the Parameter having the `PROJECTION_PARAMETER_NAME`. This name is used to assemble a `projection specific class name` to be loaded. Once loaded, a new instance is constructed using the parameters argument.

As a special case, if the projection name is `POLAR_STEREOGRAPHIC_PROJECTION_NAME` the "_Spherical" suffix is appended if `Use_Spherical(boolean)` is enabled so the faster but slightly less accurate spherical form of the projection will be used; otherwise the "_Elliptical" suffix is appended so the elliptical form will be used. Also, if the name is `POLARSTEREOGRAPHIC_PROJECTION_NAME` it will be converted to the `POLAR_STEREOGRAPHIC_PROJECTION_NAME`

Parameters:
`parameters` - The Parameter Aggregate containing the projection definition parameter values. These parameters will be passed to the specific projection class to be constructed. If null, not an Aggregate Parameter, or there is no `PROJECTION_PARAMETER_NAME` parameter a default Projection is constructed which will have the ```identity projection flag``` set.
Returns:
A Projection or Projection subclass, Object.
Throws:
`PVL_Exception` - If there is a problem reading the parameters or a parameter is found to have an invalid value.
`NoSuchElementException` - If any required parameter was missing from the provided parameters.
`UnsupportedOperationException` - If the expected Projection subclass could not be loaded or instantiated.
`Throwable` - If the constructor of the loaded projection class throws an unexpected exception.
`Equirectangular_Projection`, `Polar_Stereographic_Elliptical_Projection`, `Polar_Stereographic_Spherical_Projection`

### Name

`public String Name()`

### Is_Identity

`public boolean Is_Identity()`

### Resolution

`public double Resolution()`

`public double Equitorial_Radius()`

`public double Polar_Radius()`

### Eccentricity

`public double Eccentricity()`

### Sample_Offset

`public double Sample_Offset()`

### Line_Offset

`public double Line_Offset()`

### Positive_West

`public boolean Positive_West()`

### Positive_West

`public Projection Positive_West(boolean positive_west)`

### Planetocentric

`public boolean Planetocentric()`

### Planetocentric

`public Projection Planetocentric(boolean planetocentric)`

### Center_Latitude

`public double Center_Latitude()`

### Center_Longitude

`public double Center_Longitude()`

### Use_Spherical

`public static boolean Use_Spherical(boolean enabled)`

### to_World

`public Point2D.Double to_World(Point2D image_coordinate)`
Get the world longitude,latitude coordinate for an image sample.line coordinate.

This method simply returns a copy of the coordinate argument. A projection specific subclass will override this method.

Parameters:
`image_coordinate` - The image sample,line coordinate.
Returns:
A copy of the image_coordinate.

### to_Image

`public Point to_Image(Point2D world_coordinate)`
Get the image sample,line coordinate for a world longitude,latitude coordinate.

This method simply returns a copy of the coordinate argument. A projection specific subclass will override this method.

Parameters:
`world_coordinate` - The world longitude,latitude coordinate.
Returns:
A copy of the world_coordinate.

### Degrees_Minutes_Seconds

`public static String Degrees_Minutes_Seconds(double angle)`
Converts an angle in decimal degrees, to a degrees, minutes, seconds representation.

The format of the degrees, minutes, seconds String representation is:

DDDd MMm SS.SSSs where DDD is integer degrees, MM is integer minutes in the range 0 to 59, and SS.SSS is seconds with fractional seconds in the range 0.0 to 59.999 For example, 206.291 degrees is represented as "206d 17m 27.600s". N.B.: A fixed field format is used in which leading spaces and trailing zeros are used to each value occurs at a specific location in the String representation.

Parameters:
`angle` - The angle in degrees to be represented.
Returns:
The String representation.

### Hours_Minutes_Seconds

`public static String Hours_Minutes_Seconds(double angle)`
Converts an angle in decimal degrees, to an hours, minutes, seconds representation.

The format of the hours, minutes, seconds String representation is:

HHh MMm SS.SSSs where HH is integer hours in the range 0 to 24, MM is integer minutes in the range 0 to 59, and SS.SSS is seconds with fractional seconds in the range 0.0 to 59.999 For example, 206.291 degrees is represented as "13h 45m 9.840s". N.B.: A fixed field format is used in which leading spaces and trailing zeros are used to each value occurs at a specific location in the String representation.

Parameters:
`angle` - The angle in degrees to be represented.
Returns:
The String representation.

### Decimal_Degrees

```public static double Decimal_Degrees(String parts)
throws IllegalArgumentException,
NumberFormatException```
Throws:
`IllegalArgumentException`
`NumberFormatException`

### Planetocentric_to_Planetographic

`public double Planetocentric_to_Planetographic(double latitude)`
Convert planetocentric latitude to planetographic latitude.

Parameters:
`latitude` - The latitude, in radians, to convert.
Returns:
The converted latitude value.

### Planetographic_to_Planetocentric

`public double Planetographic_to_Planetocentric(double latitude)`
Convert planetographic latitude to planetocentric latitude.

Parameters:
`latitude` - The latitude, in radians, to convert.
Returns:
The converted latitude value.

### Projection_X_to_Sample

`protected double Projection_X_to_Sample(double projection_x)`

### Projection_Y_to_Line

`protected double Projection_Y_to_Line(double projection_y)`

### Sample_to_Projection_X

`protected double Sample_to_Projection_X(double sample)`

### Line_to_Projection_Y

`protected double Line_to_Projection_Y(double line)`

### Eccentricity

```public static double Eccentricity(double polar_radius,
Calculate the planet eccentricity.

Parameters:
`equitorial_radius` - The planet equitorial radius.
`polar_radius` - The planet polar radius.
Returns:
The planet eccentricity.

`public double Local_Radius(double latitude)`
Calculate the radius of the planet at some latitude.

R = Re * Rp / sqrt (a**2 + b**2)
where:

Re = `Equitorial_Radius` Rp = `Polar_Radius` a = Re * sin (latitude)
b = Rp * cos (latitude)

Parameters:
`latitude` - The latitude, in radians, at which the local radius is to be calculated.
Returns:
The radius of the planet at the specified latitude.

### To_360

`public static double To_360(double longitude)`
Ensure that a longitude value is in the range 0 to 360 degrees.

A negative longitude value is repeatedly increased by 360 until it is no longer negative. A longitude value greater than or equal to 360 is repeatedly decreased by 360 until it is less than 360.

Parameters:
`longitude` - The longitude value to map to the 0 to 360 degree domain.
Returns:
The longitude value in the 0-360 degree domain.

### To_180

`public static double To_180(double longitude)`
Ensure that a longitude value is in the range -180 to 180 degrees.

A longitude value less than -180 is repeatedly increased by 360 until it is greater than or equal to -180. A longitude value greater than or equal to 180 is repeatedly decreased by 360 until it is less than 180.

Parameters:
`longitude` - The longitude value to map to the -180 to 180 degree domain.
Returns:
The longitude value in the -180 to 180 degree domain.

### Projection_Class_Name

`public static String Projection_Class_Name(String projection_name)`
Produce a class name for a projection name.

The projection name is first trimmed of leading and trailing whitespace and all characters are set to lowercase. If the result starts with "polar" but is not followed by a space (' ') or underbar ('_') character an underbar is inserted following the "polar" prefix. Then any remaining space characters are changed to '_' characters. The first character and every character following an underbar character is set to uppercase. Finally the "_Projection" String is appended.

Parameters:
`projection_name` - The projection name String.
Returns:
The class name String.

### Find_Parameter

```protected static Parameter Find_Parameter(Parameter label,
String name)
throws NoSuchElementException```
Find a named parameter in PDS label parameters.

Parameters:
`label` - The PDS label parameters.
`name` - The name of the parameter to find.
Returns:
The Parameter that was found.
Throws:
`NoSuchElementException` - If the parameter was not found.

### main

`public static void main(String[] args)`

### Usage

`public static void Usage()`