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

##

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

##

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

##

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

##

pcode

      protected String pcode

  The projection type code (used only for error messages)

ref

      protected double ref[]

  a double array containing the coordinate system reference parameters. See the above section on reference parameters for more details.

euler

      protected double euler[]

  Euler angles and associated intermediaries derived from the coordinate reference values.

prj

      protected Projection prj

  The Projection transform object to use

##

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

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

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

##

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

rev

      public double[] rev(double x,
                          double y) throws InvalidCelestialTransformException

getProjectionCode

      public String getProjectionCode()

  return a copy of the projection code

getProjection

      public Projection getProjection()

  return the projection object currently in use

getRefParm

      public double[] getRefParm()

  return a copy of the reference system parameters

getEuler

      public double[] getEuler()

  return a copy of the Euler angles currently in use

    All Packages  Class Hierarchy  This Package  Previous  Next  Index