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 Projection
    extends 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.

### Field Summary

Fields
`protected double` `Center_Latitude` Projection planetographic center latitude in radians.
`static String` `CENTER_LATITUDE_PARAMETER_NAME`
`protected double` `Center_Longitude` Projection center longitude in radians.
`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

Constructors
Constructor and Description
`Projection()` Constructs a default identity Projection.
`Projection(Parameter parameters)` Constructs a Projection from a Parameter Aggregate.

### Method Summary

Methods
`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.

See Also:
  Constant Field Values

#### PROJECTION_PARAMETER_NAME

    public static final String PROJECTION_PARAMETER_NAME

See Also:
  Constant Field Values

#### EQUIRECTANGULAR_PROJECTION_NAME

    public static final String EQUIRECTANGULAR_PROJECTION_NAME

See Also:
  Constant Field Values

#### POLAR_STEREOGRAPHIC_PROJECTION_NAME

    public static final String POLAR_STEREOGRAPHIC_PROJECTION_NAME

See Also:
  Constant Field Values

#### POLARSTEREOGRAPHIC_PROJECTION_NAME

    public static final String POLARSTEREOGRAPHIC_PROJECTION_NAME

See Also:
  Constant Field Values

#### PROJECTION_LATITUDE_PARAMETER_NAME

    public static final String PROJECTION_LATITUDE_PARAMETER_NAME

See Also:
  Constant Field Values

#### PLANETOCENTRIC_PROJECTION_NAME

    public static final String PLANETOCENTRIC_PROJECTION_NAME

See Also:
  Constant Field Values

#### EQUITORIAL_RADIUS_PARAMETER_NAME

    public static final String EQUITORIAL_RADIUS_PARAMETER_NAME

See Also:
  Constant Field Values

#### POLAR_RADIUS_PARAMETER_NAME

    public static final String POLAR_RADIUS_PARAMETER_NAME

See Also:
  Constant Field Values

#### METERS_PER_PIXEL_PARAMETER_NAME

    public static final String METERS_PER_PIXEL_PARAMETER_NAME

See Also:
  Constant Field Values

#### POSITIVE_LONGITUDE_PARAMETER_NAME

    public static final String POSITIVE_LONGITUDE_PARAMETER_NAME

See Also:
  Constant Field Values

#### POSITIVE_LONGITUDE_EAST_NAME

    public static final String POSITIVE_LONGITUDE_EAST_NAME

See Also:
  Constant Field Values

#### POSITIVE_LONGITUDE_WEST_NAME

    public static final String POSITIVE_LONGITUDE_WEST_NAME

See Also:
  Constant Field Values

#### CENTER_LATITUDE_PARAMETER_NAME

    public static final String CENTER_LATITUDE_PARAMETER_NAME

See Also:
  Constant Field Values

#### CENTER_LONGITUDE_PARAMETER_NAME

    public static final String CENTER_LONGITUDE_PARAMETER_NAME

See Also:
  Constant Field Values

#### SAMPLE_OFFSET_PARAMETER_NAME

    public static final String SAMPLE_OFFSET_PARAMETER_NAME

See Also:
  Constant Field Values

#### LINE_OFFSET_PARAMETER_NAME

    public static final String LINE_OFFSET_PARAMETER_NAME

See Also:
  Constant Field Values

#### NOT_APPLICABLE_CONSTANT_PARAMETER_NAME

    public static final String NOT_APPLICABLE_CONSTANT_PARAMETER_NAME

See Also:
  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

See Also:
  Constant Field Values

#### Meters_per_Pixel

    protected double Meters_per_Pixel

#### Equitorial_Radius

    protected double Equitorial_Radius

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

Projection center longitude in radians.

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

See Also:
  Constant Field Values

#### PI_OVER_4

    public static final double PI_OVER_4

See Also:
  Constant Field Values

#### DBL_EPSILON

    public static final double DBL_EPSILON

See Also:
  Constant Field Values

#### DEFAULT_USE_SPHERICAL

    public static final boolean DEFAULT_USE_SPHERICAL

See Also:
  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.
See Also:
  `Equirectangular_Projection`, `Polar_Stereographic_Elliptical_Projection`, `Polar_Stereographic_Spherical_Projection`

#### Name

    public String Name()

#### Is_Identity

    public boolean Is_Identity()

#### Resolution

    public double Resolution()

#### Equitorial_Radius

    public double Equitorial_Radius()

#### Polar_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,
                      double equitorial_radius)

Calculate the planet eccentricity.

> E = sqrt (1 - polar_radius**2 / equitorial_radius**2)

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

#### Local_Radius

    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()