uk.ac.starlink.ast

Class WcsMap

java.lang.Object

uk.ac.starlink.ast.AstObject

uk.ac.starlink.ast.Mapping

uk.ac.starlink.ast.WcsMap

public class WcsMap
extends Mapping

Java interface to the AST WcsMap class - implement a FITS-WCS sky projection. This class is used to represent sky coordinate projections as described in the FITS world coordinate system (FITS-WCS) paper II "Representations of Celestial Coordinates in FITS" by M. Calabretta and E.W. Griesen. This paper defines a set of functions, or sky projections, which transform longitude-latitude pairs representing spherical celestial coordinates into corresponding pairs of Cartesian coordinates (and vice versa).

A WcsMap is a specialised form of Mapping which implements these sky projections and applies them to a specified pair of coordinates. All the projections in the FITS-WCS paper are supported, plus the now deprecated "TAN with polynomial correction terms" projection which is refered to here by the code "TPN". Using the FITS-WCS terminology, the transformation is between "native spherical" and "projection plane" coordinates (also called "intermediate world coordinates". These coordinates may, optionally, be embedded in a space with more than two dimensions, the remaining coordinates being copied unchanged. Note, however, that for consistency with other AST facilities, a WcsMap handles coordinates that represent angles in radians (rather than the degrees used by FITS-WCS).

The type of FITS-WCS projection to be used and the coordinates (axes) to which it applies are specified when a WcsMap is first created. The projection type may subsequently be determined using the WcsType attribute and the coordinates on which it acts may be determined using the WcsAxis(lonlat) attribute.

Each WcsMap also allows up to 100 "projection parameters" to be associated with each axis. These specify the precise form of the projection, and are accessed using PVi_m attribute, where "i" is the integer axis index (starting at 1), and m is an integer "parameter index" in the range 0 to 99. The number of projection parameters required by each projection, and their meanings, are dependent upon the projection type (most projections either do not use any projection parameters, or use parameters 1 and 2 associated with the latitude axis). Before creating a WcsMap you should consult the FITS-WCS paper for details of which projection parameters are required, and which have defaults. When creating the WcsMap, you must explicitly set values for all those required projection parameters which do not have defaults defined in this paper.

Licence

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

This program 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 General Public Licence for more details.

You should have received a copy of the GNU General Public Licence along with this program; if not, write to the Free Software Foundation, Inc., 51 Franklin Street,Fifth Floor, Boston, MA 02110-1301, USA

See Also:

"the FITS-WCS paper", AST WcsMap

Nested Class Summary

Nested classes/interfaces inherited from class uk.ac.starlink.ast.Mapping

Mapping.Interpolator, Mapping.Spreader

Field Summary

Fields

Modifier and Type	Field and Description
static int	AST__AIR Indicates FITS-WCS mapping of type AIR.
static int	AST__AIT Indicates FITS-WCS mapping of type AIT.
static int	AST__ARC Indicates FITS-WCS mapping of type ARC.
static int	AST__AZP Indicates FITS-WCS mapping of type AZP.
static int	AST__BON Indicates FITS-WCS mapping of type BON.
static int	AST__CAR Indicates FITS-WCS mapping of type CAR.
static int	AST__CEA Indicates FITS-WCS mapping of type CEA.
static int	AST__COD Indicates FITS-WCS mapping of type COD.
static int	AST__COE Indicates FITS-WCS mapping of type COE.
static int	AST__COO Indicates FITS-WCS mapping of type COO.
static int	AST__COP Indicates FITS-WCS mapping of type COP.
static int	AST__CSC Indicates FITS-WCS mapping of type CSC.
static int	AST__CYP Indicates FITS-WCS mapping of type CYP.
static int	AST__GLS Indicates FITS-WCS mapping of type GLS.
static int	AST__MER Indicates FITS-WCS mapping of type MER.
static int	AST__MOL Indicates FITS-WCS mapping of type MOL.
static int	AST__NCP Indicates FITS-WCS mapping of type NCP.
static int	AST__PAR Indicates FITS-WCS mapping of type PAR.
static int	AST__PCO Indicates FITS-WCS mapping of type PCO.
static int	AST__QSC Indicates FITS-WCS mapping of type QSC.
static int	AST__SFL Indicates FITS-WCS mapping of type SFL.
static int	AST__SIN Indicates FITS-WCS mapping of type SIN.
static int	AST__STG Indicates FITS-WCS mapping of type STG.
static int	AST__SZP Indicates FITS-WCS mapping of type SZP.
static int	AST__TAN Indicates FITS-WCS mapping of type TAN.
static int	AST__TPN Indicates FITS-WCS mapping of type TPN.
static int	AST__TSC Indicates FITS-WCS mapping of type TSC.
static int	AST__WCSBAD Indicates FITS-WCS mapping of type WCSBAD.
static int	AST__ZEA Indicates FITS-WCS mapping of type ZEA.
static int	AST__ZPN Indicates FITS-WCS mapping of type ZPN.

Fields inherited from class uk.ac.starlink.ast.Mapping

LINEAR_INTERPOLATOR, LINEAR_SPREADER, NEAREST_INTERPOLATOR, NEAREST_SPREADER

Fields inherited from class uk.ac.starlink.ast.AstObject

AST__BAD, AST__TUNULL, pointer

Constructor Summary

Constructors

Constructor and Description
WcsMap(int ncoord, int type, int lonax, int latax) Creates a WcsMap.

Method Summary

Modifier and Type	Method and Description
float	getNatLat() Get native latitude of the reference point of a FITS-WCS projection.
float	getNatLon() Get native longitude of the reference point of a FITS-WCS projection.
float	getPVi_m() Get FITS-WCS projection parameters.
int	getWcsAxis(int lonlat) Get FITS-WCS projection axes.
int	getWcsType() Get FITS-WCS projection type.
void	setPVi_m(float pVi_m) Set FITS-WCS projection parameters.

Methods inherited from class uk.ac.starlink.ast.Mapping

decompose, getInvert, getNin, getNout, getReport, getTranForward, getTranInverse, invert, linearApprox, mapBox, mapSplit, rate, rebin, rebinD, rebinF, rebinI, resample, resampleB, resampleD, resampleF, resampleI, resampleL, resampleS, setInvert, setReport, simplify, tran1, tran2, tranGrid, tranN, tranP

Methods inherited from class uk.ac.starlink.ast.AstObject

annul, clear, copy, delete, equals, finalize, getAstConstantI, getB, getC, getD, getF, getI, getID, getIdent, getL, getNobject, getObjSize, getRefCount, hashCode, isThreaded, reportVersions, sameObject, set, setB, setC, setD, setF, setI, setID, setIdent, setL, show, test, tune

Methods inherited from class java.lang.Object

clone, getClass, notify, notifyAll, toString, wait, wait, wait

Field Detail

AST__AZP

public static final int AST__AZP

Indicates FITS-WCS mapping of type AZP.

AST__TAN

public static final int AST__TAN

Indicates FITS-WCS mapping of type TAN.

AST__SIN

public static final int AST__SIN

Indicates FITS-WCS mapping of type SIN.

AST__STG

public static final int AST__STG

Indicates FITS-WCS mapping of type STG.

AST__ARC

public static final int AST__ARC

Indicates FITS-WCS mapping of type ARC.

AST__ZPN

public static final int AST__ZPN

Indicates FITS-WCS mapping of type ZPN.

AST__ZEA

public static final int AST__ZEA

Indicates FITS-WCS mapping of type ZEA.

AST__AIR

public static final int AST__AIR

Indicates FITS-WCS mapping of type AIR.

AST__CYP

public static final int AST__CYP

Indicates FITS-WCS mapping of type CYP.

AST__CAR

public static final int AST__CAR

Indicates FITS-WCS mapping of type CAR.

AST__MER

public static final int AST__MER

Indicates FITS-WCS mapping of type MER.

AST__CEA

public static final int AST__CEA

Indicates FITS-WCS mapping of type CEA.

AST__COP

public static final int AST__COP

Indicates FITS-WCS mapping of type COP.

AST__COD

public static final int AST__COD

Indicates FITS-WCS mapping of type COD.

AST__COE

public static final int AST__COE

Indicates FITS-WCS mapping of type COE.

AST__COO

public static final int AST__COO

Indicates FITS-WCS mapping of type COO.

AST__BON

public static final int AST__BON

Indicates FITS-WCS mapping of type BON.

AST__PCO

public static final int AST__PCO

Indicates FITS-WCS mapping of type PCO.

AST__GLS

public static final int AST__GLS

Indicates FITS-WCS mapping of type GLS.

AST__SFL

public static final int AST__SFL

Indicates FITS-WCS mapping of type SFL.

AST__PAR

public static final int AST__PAR

Indicates FITS-WCS mapping of type PAR.

AST__AIT

public static final int AST__AIT

Indicates FITS-WCS mapping of type AIT.

AST__MOL

public static final int AST__MOL

Indicates FITS-WCS mapping of type MOL.

AST__CSC

public static final int AST__CSC

Indicates FITS-WCS mapping of type CSC.

AST__QSC

public static final int AST__QSC

Indicates FITS-WCS mapping of type QSC.

AST__NCP

public static final int AST__NCP

Indicates FITS-WCS mapping of type NCP.

AST__TSC

public static final int AST__TSC

Indicates FITS-WCS mapping of type TSC.

AST__TPN

public static final int AST__TPN

Indicates FITS-WCS mapping of type TPN.

AST__SZP

public static final int AST__SZP

Indicates FITS-WCS mapping of type SZP.

AST__WCSBAD

public static final int AST__WCSBAD

Indicates FITS-WCS mapping of type WCSBAD.

Constructor Detail

WcsMap

public WcsMap(int ncoord,
              int type,
              int lonax,
              int latax)

Creates a WcsMap.

Parameters:

ncoord - The number of coordinate values for each point to be transformed (i.e. the number of dimensions of the space in which the points will reside). This must be at least 2. The same number is applicable to both input and output points.

type - the type of FITS-WCS projection to apply. One of the WcsMap constants (static final int fields) should be given for this value, e.g. WcsMap.AST__TAN for a tangent plane projection. You should consult the FITS-WCS paper for the meaning of the available projections.

lonax - The index of the longitude axis. This should lie in the range 1 to "ncoord".

latax - The index of the latitude axis. This should lie in the range 1 to "ncoord" and be distinct from "lonax".

Throws:

AstException - if an error occurred in the AST library

Method Detail

getNatLat

public float getNatLat()

Get native latitude of the reference point of a FITS-WCS projection. This attribute gives the latitude of the reference point of the FITS-WCS projection implemented by a WcsMap. The value is in radians in the "native spherical" coordinate system. This value is fixed for most projections, for instance it is PI/2 (90 degrees) for all zenithal projections. For some projections (e.g. the conics) the value is not fixed, but is specified by parameter one on the latitude axis.

FITS-WCS paper II introduces the concept of a "fiducial point" which is logical distinct from the projection reference point. It is easy to confuse the use of these two points. The fiducial point is the point which has celestial coordinates given by the CRVAL FITS keywords. The native spherical coordinates for this point default to the values of the NatLat and NatLon, but these defaults mey be over-ridden by values stored in the PVi_j keywords. Put another way, the CRVAL keywords will by default give the celestial coordinates of the projection reference point, but may refer to some other point if alternative native longitude and latitude values are provided through the PVi_j keywords.

The NatLat attribute is read-only.

Notes

- A default value of AST__BAD is used if no latitude value is available.

Returns:

this object's NatLat attribute

getNatLon

public float getNatLon()

Get native longitude of the reference point of a FITS-WCS projection. This attribute gives the longitude of the reference point of the FITS-WCS projection implemented by a WcsMap. The value is in radians in the "native spherical" coordinate system, and will usually be zero. See the description of attribute NatLat for further information.

The NatLon attribute is read-only.

Returns:

this object's NatLon attribute

getPVi_m

public float getPVi_m()

Get FITS-WCS projection parameters. This attribute specifies the projection parameter values to be used by a WcsMap when implementing a FITS-WCS sky projection. Each PV attribute name should include two integers, i and m, separated by an underscore. The axis index is specified by i, and should be in the range 1 to 99. The parameter number is specified by m, and should be in the range 0 to 99. For example, "PV2_1=45.0" would specify a value for projection parameter 1 of axis 2 in a WcsMap.

These projection parameters correspond exactly to the values stored using the FITS-WCS keywords "PV1_1", "PV1_2", etc. This means that projection parameters which correspond to angles must be given in degrees (despite the fact that the angular coordinates and other attributes used by a WcsMap are in radians).

The set of projection parameters used by a WcsMap depends on the type of projection, which is determined by its WcsType parameter. Most projections either do not require projection parameters, or use parameters 1 and 2 associated with the latitude axis. You should consult the FITS-WCS paper for details.

Some projection parameters have default values (as defined in the FITS-WCS paper) which apply if no explicit value is given. You may omit setting a value for these "optional" parameters and the default will apply. Some projection parameters, however, have no default and a value must be explicitly supplied. This is most conveniently done using the "options" argument of astWcsMap (q.v.) when a WcsMap is first created. An error will result when a WcsMap is used to transform coordinates if any of its required projection parameters has not been set and lacks a default value.

A "get" operation for a parameter which has not been assigned a value will return the default value defined in the FITS-WCS paper, or AST__BAD if the paper indicates that the parameter has no default. A default value of zero is returned for parameters which are not accessed by the projection.

Note, the FITS-WCS paper reserves parameters 1 and 2 on the longitude axis to hold the native longitude and latitude of the fiducial point of the projection, in degrees. The default values for these parameters are determined by the projection type. The AST-specific TPN projection does not use this convention - all projection parameters for both axes are used to represent polynomical correction terms, and the native longitude and latitude at the fiducial point may not be changed from the default values of zero and 90 degrees.

Notes

- If the projection parameter values given for a WcsMap do not satisfy all the required constraints (as defined in the FITS-WCS paper), then an error will result when the WcsMap is used to transform coordinates.

Returns:

this object's PVi_m attribute

setPVi_m

public void setPVi_m(float pVi_m)

Set FITS-WCS projection parameters. This attribute specifies the projection parameter values to be used by a WcsMap when implementing a FITS-WCS sky projection. Each PV attribute name should include two integers, i and m, separated by an underscore. The axis index is specified by i, and should be in the range 1 to 99. The parameter number is specified by m, and should be in the range 0 to 99. For example, "PV2_1=45.0" would specify a value for projection parameter 1 of axis 2 in a WcsMap.

These projection parameters correspond exactly to the values stored using the FITS-WCS keywords "PV1_1", "PV1_2", etc. This means that projection parameters which correspond to angles must be given in degrees (despite the fact that the angular coordinates and other attributes used by a WcsMap are in radians).

The set of projection parameters used by a WcsMap depends on the type of projection, which is determined by its WcsType parameter. Most projections either do not require projection parameters, or use parameters 1 and 2 associated with the latitude axis. You should consult the FITS-WCS paper for details.

Some projection parameters have default values (as defined in the FITS-WCS paper) which apply if no explicit value is given. You may omit setting a value for these "optional" parameters and the default will apply. Some projection parameters, however, have no default and a value must be explicitly supplied. This is most conveniently done using the "options" argument of astWcsMap (q.v.) when a WcsMap is first created. An error will result when a WcsMap is used to transform coordinates if any of its required projection parameters has not been set and lacks a default value.

A "get" operation for a parameter which has not been assigned a value will return the default value defined in the FITS-WCS paper, or AST__BAD if the paper indicates that the parameter has no default. A default value of zero is returned for parameters which are not accessed by the projection.

Note, the FITS-WCS paper reserves parameters 1 and 2 on the longitude axis to hold the native longitude and latitude of the fiducial point of the projection, in degrees. The default values for these parameters are determined by the projection type. The AST-specific TPN projection does not use this convention - all projection parameters for both axes are used to represent polynomical correction terms, and the native longitude and latitude at the fiducial point may not be changed from the default values of zero and 90 degrees.

Notes

- If the projection parameter values given for a WcsMap do not satisfy all the required constraints (as defined in the FITS-WCS paper), then an error will result when the WcsMap is used to transform coordinates.

Parameters:

pVi_m - the PVi_m attribute of this object

getWcsType

public int getWcsType()

Get FITS-WCS projection type.

The WcsType attribute specifies which type of FITS-WCS projection will be performed by this WcsMap. Its value will be one of the constants (static final int fields) defined by this class, e.g. WcsMap.AST__TAN for a tangent plane projection. Its value is the one set when the WcsMap was created.

Returns:

this object's WcsType attribute

getWcsAxis

public int getWcsAxis(int lonlat)

Get FITS-WCS projection axes. This attribute gives the indices of the longitude and latitude coordinates of the FITS-WCS projection within the coordinate space used by a WcsMap. These indices are defined when the WcsMap is first created using astWcsMap and cannot subsequently be altered.

If "lonlat" is 1, the index of the longitude axis is returned. Otherwise, if it is 2, the index of the latitude axis is returned.

Parameters:

lonlat - if lonlat=1 the index of the longitude axis is returned, if lonlat=2 the index of the latitude axis is returned.

Returns:

the index of the longitude (lonlat=1) or latitude (lonlat=2) axis

Throws:

IndexOutOfBoundsException - if lonlat is neither 1 or 2.