Class FITSWCS.CelestialTransform
All Packages  Class Hierarchy  This Package  Previous  Next  Index

Class FITSWCS.CelestialTransform

java.lang.Object
   |
   +----FITSWCS.CelestialTransform

public class CelestialTransform
extends Object
This class provides support for celestial coordinate transformations (encapsulating spherical coordinate and projection transformations) used by the FITS "World Coordinate System" (WCS) convention.

The FITSWCS package was translated from the WCSLIB C library This original library was written in support for coordinate systems used by astronomical data stored in FITS format. For more information on these coordinate systems, refer to the paper by Greisen and Calabretta at:

ftp://fits.cv.nrao.edu/fits/documents/wcs/wcs.all.ps.Z
Coordinate System Reference Parameters

This class can be instantiated by passing to the constructor an array of four double values representing the coordinate system reference data. The first two elements should be set to the celestial longitude and latitude (usually right ascension and declination) of the reference point of the projection.

The two values are the native longitude and latitude of the pole of the celestial coordinate system and correspond to the FITS keywords LONGPOLE and LATPOLE.

LONGPOLE defaults to 0 degrees if the celestial latitude of the reference point of the projection is greater than the native latitude, otherwise 180 degrees. (This is the condition for the celestial latitude to increase in the same direction as the native latitude at the reference point.) ref[2] may be set to 999.0 to indicate that the correct default should be substituted.

In some circumstances the latitude of the native pole may be determined by the first three values only to within a sign and LATPOLE is used to choose between the two solutions. LATPOLE is set in ref[3] and the solution closest to this value is used to reset ref[3]. It is therefore legitimate, for example, to set ref[3] to 999.0 to choose the more northerly solution - the default if the LATPOLE card is omitted from the FITS header. For the special case where the reference point of the projection is at native latitude zero, its celestial latitude is zero, and LONGPOLE = +/- 90 then the native latitude of the pole is not determined by the first three reference values and LATPOLE specifies it completely.

Nomenclature

In WCSLIB the "forward" direction is from (lng,lat) celestial coordinates to (x,y) coordinates in the plane of projection. This accords with the notion that spherical projections are a projection of the sphere onto a plane, the "reverse" direction is therefore that of deprojection from plane to sphere.

Unfortunately, this is opposite to what is generally understood to be the forward direction for FITS, namely that of transforming pixel coordinates to world coordinates. However, the ordering of function argument lists should make it clear what is intended.


COPYRIGHT NOTICE

This library is free software; you can redistribute it and/or modify it under the terms of the GNU Library General Public License as published by the Free Software Foundation; either version 2 of the License, or (at your option) any later version.

This library is distributed in the hope that it will be useful, but WITHOUT ANY WARRANTY; without even the implied warranty of MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the GNU Library General Public License for more details.

You should have received a copy of the GNU Library General Public License along with this library; if not, write to the Free Software Foundation, Inc., 675 Mass Ave, Cambridge, MA 02139, USA.

Correspondence concerning WCSLIB may be directed to:

     Internet email: mcalabre@atnf.csiro.au
     Postal address: Dr. Mark Calabretta,
                     Australia Telescope National Facility,
                     P.O. Box 76,
                     Epping, NSW, 2121,
                     AUSTRALIA
Correspondence concerning the Java implementation may be directed to Raymond L. Plante (rplante@ncsa.uiuc.edu).

Variable Index

 o euler
Euler angles and associated intermediaries derived from the coordinate reference values.
 o pcode
The projection type code (used only for error messages)
 o prj
The Projection transform object to use
 o ref
a double array containing the coordinate system reference parameters.

Constructor Index

 o CelestialTransform(String, double[], double, double[])
Construct a CelestialTransform object
 o CelestialTransform(String, double[], double[])
Construct a CelestialTransform object
 o CelestialTransform(String, double, double, double, double, double[])
Construct a CelestialTransform object taking the reference parameters as four seperate arguments (reflong, reflat, longpole, latpole).

Method Index

 o fwd(double, double)
Compute (x,y) coordinates in the plane of projection from celestial coordinates (lng,lat).
 o getEuler()
return a copy of the Euler angles currently in use
 o getProjection()
return the projection object currently in use
 o getProjectionCode()
return a copy of the projection code
 o getRefParm()
return a copy of the reference system parameters
 o rev(double, double)

Variables

 o pcode
  protected String pcode
The projection type code (used only for error messages)
 o ref
  protected double ref[]
a double array containing the coordinate system reference parameters. See the above section on reference parameters for more details.
 o euler
  protected double euler[]
Euler angles and associated intermediaries derived from the coordinate reference values.
 o prj
  protected Projection prj
The Projection transform object to use

Constructors

 o CelestialTransform
  public CelestialTransform(String pcode,
                            double ref[],
                            double r0,
                            double p[]) throws ArrayIndexOutOfBoundsException, BadProjectionParameterException, UnsupportedProjectionException, BadReferenceParameterException
Construct a CelestialTransform object
Parameters:
pcode - 3-character code indicating desired projection
ref - 4-element array containing coordinate reference parameters (see above for more details).
r0 - sphere radius, if 0 defaults to 180/PI.
p - array containing projection parameters (up to 10 elements may be used, depending on pcode).
Throws: ArrayIndexOutOfBoundsException
if ref.length < 4 or if p.length < number needed for particular pcode.
Throws: BadProjectionParameterException
if p contains one or more bad values for the given pcode
Throws: UnsupportedProjectionException
if pcode is refers to an unrecognized projection type.
Throws: BadReferenceParameterException
if ref contains one or more bad values for the given pcode
 o CelestialTransform
  public CelestialTransform(String pcode,
                            double ref[],
                            double p[]) throws ArrayIndexOutOfBoundsException, BadProjectionParameterException, UnsupportedProjectionException, BadReferenceParameterException
Construct a CelestialTransform object
Parameters:
pcode - 3-character code indicating desired projection
ref - 4-element array containing coordinate reference parameters (see above for more details).
p - array containing projection parameters (up to 10 elements may be used, depending on pcode).
Throws: ArrayIndexOutOfBoundsException
if ref.length < 4 or if p.length < number needed for particular pcode.
Throws: BadProjectionParameterException
if p contains one or more bad values for the given pcode
Throws: UnsupportedProjectionException
if pcode is refers to an unrecognized projection type.
Throws: BadReferenceParameterException
if ref contains one or more bad values for the given pcode
 o CelestialTransform
  public CelestialTransform(String pcode,
                            double reflong,
                            double reflat,
                            double longpole,
                            double latpole,
                            double p[]) throws ArrayIndexOutOfBoundsException, BadProjectionParameterException, UnsupportedProjectionException, BadReferenceParameterException
Construct a CelestialTransform object taking the reference parameters as four seperate arguments (reflong, reflat, longpole, latpole). See the above section on reference parameters for more details.
Parameters:
pcode - 3-character code indicating desired projection
reflong - celestial longitude (usually right ascension) of the reference point of the projection, in degrees
reflat - celestial latitude (usually declination) of the reference point of the projection, in degrees
longpole - native longitude of the celestial coordinate system, in degrees; a value of 999.0 indicates that this should be set to a default value (either 0 or 180, so that celestial and native latitudes increase in the same direction).
latpole - native latiitude of the celestial coordinate system, in degrees; a value of 999.0 indicates that this should be set to a default value (derived from reflong, reflat, & longpole).
p - array containing projection parameters (up to 10 elements may be used, depending on pcode).
Throws: ArrayIndexOutOfBoundsException
if p.length < number needed for particular pcode.
Throws: BadProjectionParameterException
if p contains one or more bad values for the given pcode
Throws: UnsupportedProjectionException
if pcode is refers to an unrecognized projection type.
Throws: BadReferenceParameterException
if any of reflong, reflat, longpole, or latpole contains a bad value for the given pcode

Methods

 o fwd
  public double[] fwd(double lng,
                      double lat) throws InvalidCelestialTransformException
Compute (x,y) coordinates in the plane of projection from celestial coordinates (lng,lat).
Throws: InvalidCelestialTransformException
if the given coordinates are invalid for this system
 o rev
  public double[] rev(double x,
                      double y) throws InvalidCelestialTransformException
 o getProjectionCode
  public String getProjectionCode()
return a copy of the projection code
 o getProjection
  public Projection getProjection()
return the projection object currently in use
 o getRefParm
  public double[] getRefParm()
return a copy of the reference system parameters
 o getEuler
  public double[] getEuler()
return a copy of the Euler angles currently in use

All Packages  Class Hierarchy  This Package  Previous  Next  Index