WCSTools Sky World Coordinate Systems

NOAO IRAF TNX World Coordinate System

The TNX World Coordinate System is a non-standard system for evaluating celestial coordinates from the image pixel coordinates. It follows the the FITS conventions for undistorted tangent plane projections but adds a non-linear distortion term to the evaluation. This discussion concentrates on the non-linear extension and assumes the reader understands the FITS WCS conventions including applying a tangent plane projection. The reference for the FITS WCS standard for undistorted celestial coordinates systems is Representations of celestial coordinates in FITS Calabretta, M. R., and Greisen, E. W., Astronomy & Astrophysics, 395, 1077-1122, 2002. (PDF, HTML). (These links to the publisher's web site are currently available by subscription only. Reprints are available from the author's web site in PDF format.)

The TNX World Coordinate System projection has a FITS keyword representation as illustrated in figure 1.

Figure 1: Sample header with TNX WCS projection

WCSASTRM= 'ct4m.19990714T012701 (USNO-K V) by F. Valdes 1999-08-02' / WCS Source
WCSDIM  =                    2 / WCS dimensionality
CTYPE1  = 'RA---TNX'           / Coordinate type
CTYPE2  = 'DEC--TNX'           / Coordinate type
CRVAL1  =   310.08145293602507 / Coordinate reference value
CRVAL2  =   20.663666538998399 / Coordinate reference value
CRPIX1  =            4268.3258 / Coordinate reference pixel
CRPIX2  =            2256.2481 / Coordinate reference pixel
CD1_1   =       -6.8295807e-08 / Coordinate matrix
CD2_1   =        7.3313414e-05 / Coordinate matrix
CD1_2   =         7.374228e-05 / Coordinate matrix
CD2_2   =       -1.1927219e-06 / Coordinate matrix
WAT0_001= 'system=image'       / Coordinate system
WAT1_001= 'wtype=tnx axtype=ra lngcor = "3. 4. 4. 2. -0.3171856965643079 -0.015'
WAT1_002= '0652479325533 -0.3126038394350166 -0.1511955040928311 0.002318100364'
WAT1_003= '838772 0.01749134520424022 -0.01082784423020123 -0.1387962673564234 '
WAT1_004= '-4.307309762939804E-4 0.009069288008295441 0.002875265278754504 -0.0'
WAT1_005= '4487658756007625 -0.1058043162287004 -0.0686214765375767 "          '
WAT2_001= 'wtype=tnx axtype=dec latcor = "3. 4. 4. 2. -0.3171856965643079 -0.01'
WAT2_002= '50652479325533 -0.3126038394350166 -0.1511955040928311 0.00553481957'
WAT2_003= '8784082 0.01258790793029932 0.01016780085575339 0.01541083298696018 '
WAT2_004= '0.03531979587941362 0.0150096457430599 -0.1086479352595234 0.0399806'
WAT2_005= '086902122 0.02341002785565408 -0.07773808393244387 "                '

The WCSASTRM keyword is just for documentation. The WCSDIM keyword will always be 2. That this is a TNX projection is indicated by the CTYPE keywords. These keywords also indicate that the first image axis corresponds to RA and the second to DEC.

The TNX projection is evaluated as follows.

  1. Compute the first order standard coordinates xi and eta from the linear part of the solution stored in CRPIX and the CD matrix.
             xi = CD1_1 * (x - CRPIX1) + CD1_2 * (y - CRPIX2)
            eta = CD2_1 * (x - CRPIX1) + CD2_2 * (y - CRPIX2)
    
  2. Add the non-linear part of the projection using the coefficients in the WAT keywords as described below.
            xi' =  xi + lngcor (xi, eta)
           eta' = eta + latcor (xi, eta)
    
  3. Apply the standard tangent plane projection to xi' amd eta' using the CRVAL values as the tangent point to get the RA and DEC in degrees. Note that the units of xi, eta, lngcor, and latcor are also degrees.

The non-linear functions lngcor(xi,eta) and latcor(xi,eta) are polynomial functions with coefficients stored as FITS keywords under the indexed WATj_nnn keywords. The j refers to the image axis and the nnn give a sequence number. The cards for a particular image axis are sorted by the sequence number and then concatenated together into one long string. Take care not to add spaces between the concatenated strings since the coefficients may be split across strings.

The long string for each image axis is composed of a set of keyword/value pairs where the value is quoted if it contains whitespace. Figure 2 shows how the WAT keywords in figure 1 would be decomposed into parameters and coefficients.

Figure 2: Decomposing the WAT keywords from figure 1

    AXIS 1			    AXIS 2
    ----------------------------    --------------------------
    wtype=tnx			    wtype=tnx
    axtype=ra			    axtype=dec
    lngcor =			    latcor =
	    3.				3.
	    4.				4.
	    4.				4.
	    2.				2.
	    -0.3171856965643079		-0.3171856965643079
	    -0.0150652479325533		-0.0150652479325533
	    -0.3126038394350166		-0.3126038394350166
	    -0.1511955040928311		-0.1511955040928311
	     0.002318100364838772	 0.005534819578784082
	     0.01749134520424022	 0.01258790793029932
	    -0.01082784423020123	 0.01016780085575339
	    -0.1387962673564234		 0.01541083298696018
	    -4.307309762939804E-4	 0.03531979587941362
	     0.009069288008295441	 0.0150096457430599
	     0.002875265278754504	-0.1086479352595234
	    -0.04487658756007625	 0.0399806086902122
	    -0.1058043162287004		 0.02341002785565408
	    -0.0686214765375767		-0.07773808393244387

The list of coefficients are interpreted as follows.

  1. The first number is the function type encoded as 1=chebyshev, 2=legendre, 3=polynomial. The example has a function of type 3 which is the simple polynomial.
  2. The next two numbers represent the "order" of the function in xi and eta. The order is the one less than the highest polynomial power. The powers are represented below by m and n such at m = 0 to xiorder-1 and n = 0 to etaorder-1. In the example the orders are 4 which means cubic polynomials (m=0 to 3 and n=0 to 3).
  3. The next (fourth) number specifies the type of cross-terms encoded as 0=no cross-terms, 1=full cross-terms, 2=half-cross terms. The cross-terms are terms of xi^m*eta^n where m and n are non-zero. Full cross-terms mean that both m and n will go to the their maximum values independently while half-cross terms mean that m + n will only go to the maximum of xiorder-1 and etaorder-1.
  4. The next 4 numbers describe the region of validity of the fits in xi and eta space, e.g. ximin, ximax, etamin, etamax. They are used to compute normalized values for xi and eta used in the chebyshev and legendre polynomial functions:
        xin = (2 * xi - (ximax + ximin)) / (ximax - ximin)
        etan = (2 * eta - (etamax + etamin)) / (etamax - etamin)
    
  5. The remaining terms are the coefficients of the polynomial terms. The functions are evaluated by summing polynomial terms Pmn(xi,eta) multiplied by the coefficients Cmn as
         lngcor(xi,eta) = sum (Cmn * Pmn(xi,eta))
         latcor(xi,eta) = sum (Cmn * Pmn(xi,eta))
    

    Representing the coeffients as Cmn for the polynomials Pmn, where m and n are the powers of xi and eta, they are ordered as

                C00
                C10
                C20
                C30
    	    ...
                C01
                C11
                C21
                C31
    	    ...
                C02
                C12
                C22
                C32
    	    ...
                C03
                C13
                C23
                C33
    	    ...
    

    In the example with the half cross-terms and orders of 4 the ten coefficients would be C00, C10, C20, C30, C01, C11, C21, C02, C12, and C03.

    The polynomials Pmn are defined below. The chebyshev and legendre polynomials are define iteratively as functions of the normalized coordinates defined earlier.

        Pmn = xi ** m * eta ** n    (polynomial)
    
        Pmn = Pm(xin) * Pn(etan)     (chebyshev)
    
    	P0(xin) = 1.0
    	P1(xin) = xin
    	Pm+1(xin) = 2.0 * xin * Pm(xin) - Pm-1(xin) 
    
    	P0(etan) = 1.0
    	P1(etan) = etan
    	Pn+1(etan) = 2.0 * etan * Pn(etan) - Pn-1(etan) 
    
        Pmn = Pm(xin) * Pn(etan)     (legendgre)
    
    	P0(xin) = 1.0
    	P1(xin) = xin
    	Pm+1(xin) = ((2m+1) * xin * Pm(xin) - m * Pm-1(xin))/ (m+1)   
    
    	P0(etan) = 1.0
    	P1(etan) = etan
    	Pn+1(etan) = ((2n+1) * etan * Pn(etan) - n * Pn-1(etan))/ (n+1)   
    

    In the example with with a simple polynomial the functions would be given as follows.

        lngcor/latcor = C00
            + C10 * xi     + C20*xi^2       + C30 * xi^3
    	+ C01 * eta    + C02*eta^2      + C03 * eta^3
    	+ C11 * xi*eta + C21 * xi^2*eta + C12 * xi*eta^2
        
(copied from NOAO