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.

Version:

1.5

Author:

Bradford Castalia UA/PIRL

Field Summary

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

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.

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