uk.ac.starlink.ast
Class WcsMap

java.lang.Object
  extended by uk.ac.starlink.ast.AstObject
      extended by uk.ac.starlink.ast.Mapping
          extended by 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
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
WcsMap(int ncoord, int type, int lonax, int latax)
          Creates a WcsMap.
 
Method Summary
 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.


Copyright © 2017 Central Laboratory of the Research Councils. All Rights Reserved.