[fitswcs] WCS -TAB complexities

[William Pence]

Mark Calabretta and I recently had an email discussion about the -TAB WCS 
convention defined in Paper III that may be of wider interest, so I'll try 
to summarize it here:

There now exists a very simple way for application program developers to 
calculate the coordinates within any FITS image, as long as the FITS image 
uses any of the WCS coordinate conventions defined in Papers II and III 
*except* the -TAB convention.  The application program only has to make 3 
subroutine calls:

1.  call the fits_hdr2str routine in CFITSIO to read the image header 
keywords into a long character string variable.

2.  pass this string variable to the wscpih routine in WCSLIB, which then 
parses all the WCS keywords and creates internal structures that will be 
used in subsequent transforms between pixel and world coordinates.

3.  call the wcsp2s routine in WCSLIB to convert any input pixel coordinate 
into world coordinates.

(This example specifically refers to routines in the WCSLIB and CFITSIO 
libraries, but in principle this same 3 step procedure could be supported by 
any other WCS library and FITS data I/O library).

One of the key features of this implementation is that there is a clean 
separation between the WCS library and the FITS I/O library; the WCSLIB 
routines never directly call a CFITSIO routine, and vice versa.  Keeping the 
2 libraries independent is important so that they can be maintained and 
distributed separately, and allows developers to choose alternate WCS or I/O 
libraries if they wish.

The reason the -TAB WCS convention cannot be supported in this same simple 
way is that the WCS information is spread out over 2 FITS headers (the image 
and the associated WCS table) and in the body of the table.  To support the 
-TAB algorithm and also preserve the independence of the WCS and FITS I/O 
library, several additional steps need to be taken:

- after parsing the image header information and seeing that the -TAB 
convention is being used, the WCS routine would need to send back a request 
to the application program to send it an additional string containing the 
table header.

- the application program would then need to find and read the table header 
and send the string back to the WCS routine.

- the WCS routine would then see that it still needs more information, this 
time contained in certain fields in the -TAB table itself.  The WCS routine 
would need to tell the application program which table fields to read, and 
where in memory to store the values.

- the application program would then read the appropriate table fields as 
requested by the WCS routine.

- Now, finally, the application program can call the wcsp2s routine to 
calculate the world coordinate corresponding to any input pixel coordinate
in the image.

The exact procedure for how the WCS and FITS I/O library will communicate 
back and forth in this way has yet to be implemented.  I have no doubt that 
eventually this can be made to work, but it seems inevitable that this will 
be a much more complicated procedure than when dealing with any of the other 
types of WCS projections.

The main conclusion I have drawn from this is that supporting the -TAB 
projection will likely require much more effort by software developers than 
any of the other projections.   I still support the -TAB projection as 
described in Paper III, but suggest adding a little more discussion of the 
likely implementation complexities that are associated with using it and a 
warning to FITS file designers to not over use the -TAB convention if a 
simpler WCS convention could be used instead.  This could be similar to the 
warning that was recently added on the use of the variable-length array 
convention in binary tables.

Bill
-- 
____________________________________________________________________
Dr. William Pence                          William.D.Pence at nasa.gov
NASA/GSFC Code 662         HEASARC         +1-301-286-4599 (voice)
Greenbelt MD 20771                         +1-301-286-1684 (fax)