Added NPOL and D2IM file examples as Appendices to fits_conventions TSR.

git-svn-id: http://svn.stsci.edu/svn/ssb/stsci_python/stsci_python/trunk/stwcs@19552 fe389314-cf27-0410-b35b-8c050e845b92

1 files changed, 180 insertions, 4 deletions

diff --git a/doc/source/fits_conventions.rst b/doc/source/fits_conventions.rst
index 6f3ed44..a751383 100644
--- a/doc/source/fits_conventions.rst
+++ b/doc/source/fits_conventions.rst
@@ -163,7 +163,7 @@ so that any original DGEOFILE reference filename can be retained in parallel for
 backwards compatibility with the current software. This reference file will also 
 have a unique suffix, _npl.fits, as another means of identifying it as a new r
 eference file separate from the current DGEOFILE files. The header for this new 
-reference file also remains very simple, as illustrated in Appendix 1.
+reference file also remains very simple, as illustrated in :ref:`Appendix1`.
 
 The two 65 x 33 arrays get read into memory with each input ACS/WFC chip (one for 
 X offsets and one for Y offsets). Bi-linear interpolation based on the input pixel 
@@ -223,7 +223,7 @@ corresponding to the 1-D correction to be applied. Header keywords in the refere
 then specify what axis gets this correction. As a result, this new reference file remains 
 small enough to easily be added to an input image without significant change in size. An 
 initial D2IMFILE for ACS has been generated for testing with a sample header provided in 
-the Appendix. 
+:ref:`Appendix2`. 
 
 .. figure:: /images/d2im_bar.png
    :width: 95 %
@@ -302,5 +302,181 @@ the CTYPE keyword.
 .. figure:: /images/pipeline.png
 
    Coordinate Transformation Pipeline
-   
-   
+
+.. _Appendix1:
+
+*************************************
+Appendix 1 - NPOLFILE Example 
+*************************************
+The NPOLFILE reference file format includes a PRIMARY header describing what kind of 
+image should be corrected by this file, along with extensions containing the corrections
+for each chip.  A sample NPOLFILE applicable to ACS/WFC F475W images has the FITS extensions::
+
+ Filename: /grp/hst/cdbs/jref/v971826aj_npl.fits
+ No.    Name         Type      Cards   Dimensions   Format
+ 0    PRIMARY     PrimaryHDU      35   ()           int16   
+ 1    DX          ImageHDU       180   (65, 33)     float32   
+ 2    DY          ImageHDU       215   (65, 33)     float32   
+ 3    DX          ImageHDU       215   (65, 33)     float32   
+ 4    DY          ImageHDU       215   (65, 33)     float32   
+
+The extensions with the name 'DX' provide the corrections in X for each of the 
+ACS/WFC's 2 chips, while the 'DY' extensions provide the corrections in Y for each chip.
+
+The PRIMARY header of this file only includes the minimum information necessary to describe
+what exposures should be corrected by this reference file and how it was generated. A full
+listing of the PRIMARY header includes::
+
+ SIMPLE  =                    T / Fits standard                                  
+ BITPIX  =                   16 / Bits per pixel                                 
+ NAXIS   =                    0 / Number of axes                                 
+ EXTEND  =                    T / File may contain extensions                    
+ ORIGIN  = 'NOAO-IRAF FITS Image Kernel July 2003' / FITS file originator        
+ IRAF-TLM= '2011-09-09T13:24:40'                                                 
+ NEXTEND =                    4 / Number of standard extensions                  
+ DATE    = '2010-04-02T19:53:08'                                                 
+ FILENAME= 'v971826aj_npl.fits' / name of file                                   
+ FILETYPE= 'DXY GRID'           / type of data found in data file                
+ OBSTYPE = 'IMAGING '           / type of observation                            
+ TELESCOP= 'HST'                / telescope used to acquire data                 
+ INSTRUME= 'ACS   '             / identifier for instrument used to acquire data 
+ DETECTOR= 'WFC'                / detector in use: WFC, HRC, or SBC              
+ FILTER1 = 'F475W   '           / element selected from filter wheel 1           
+ FILTER2 = 'CLEAR2L '           / element selected from filter wheel 2           
+ USEAFTER= 'Mar 01 2002 00:00:00'                                                
+ COMMENT = 'NPOL calibration file created by Ray A. Lucas 29 APR 2010'           
+ DESCRIP = 'Residual geometric distortion file for use with astrodrizzle-------' 
+ PEDIGREE= 'INFLIGHT 11/11/2002 11/11/2002'                                      
+ HISTORY   Non-polynomial offset file generated from qbu16420j_dxy.fits          
+ HISTORY   Only added to the flt.fits file and used in coordinate                
+ HISTORY   transformations if the npol reference filename is specified in        
+ HISTORY   the header.  The offsets are copied from the reference file into      
+ HISTORY   two arrays for each chip.  Each array is stored as a 65x33 pixel      
+ HISTORY   image that gets interpolated up to the full chip size. Two new        
+ HISTORY   extensions for each chip are also appended to the flt file            
+ HISTORY   (WCSDVARR).                                                           
+ HISTORY qbu16420j_npl.fits renamed to v9615069j_npl.fits on Sep 6 2011          
+ HISTORY v9615069j_npl.fits renamed to v971826aj_npl.fits on Sep 7 2011          
+
+
+Each ACS/WFC chip has a shape of 4096 x 2048 pixels,
+yet the data arrays in this specific reference file only have 65x33 values.
+Each data extension ('DX' and 'DY') contains only those keywords necessary to 
+properly interpolate the sub-sampled values from the arrays to apply to each individual
+pixel in the full ACS/WFC exposure. The full header for the ['DX',1] extension contains::
+
+ XTENSION= 'IMAGE   '           / Image extension                                
+ BITPIX  =                  -32 / Bits per pixel                                 
+ NAXIS   =                    2 / Number of axes                                 
+ NAXIS1  =                   65 / Axis length                                    
+ NAXIS2  =                   33 / Axis length                                    
+ PCOUNT  =                    0 / No 'random' parameters                         
+ GCOUNT  =                    1 / Only one group                                 
+ EXTNAME = 'DX      '           / Extension name                                 
+ EXTVER  =                    1 / Extension version                              
+ ORIGIN  = 'NOAO-IRAF FITS Image Kernel July 2003' / FITS file originator        
+ INHERIT =                    F / Inherits global header                         
+ DATE    = '2004-04-28T16:44:21'                                                 
+ IRAF-TLM= '16:42:00 (30/11/2006)'                                               
+ WCSDIM  =                    2                                                  
+ LTM1_1  =                   1.                                                  
+ LTM2_2  =                   1.                                                  
+ WAT0_001= 'system=physical'                                                     
+ WAT1_001= 'wtype=linear'                                                        
+ WAT2_001= 'wtype=linear'                                                        
+ CCDCHIP =                    2 / CCDCHIP from full size dgeo file               
+ LTV1    =                    0                                                  
+ LTV2    =                    0                                                  
+ ONAXIS1 =                 4096 / NAXIS1 of full size dgeo file                  
+ ONAXIS2 =                 2048 / NAXIS2 of full size dgeo file                  
+ CDELT1  =                   64 / Coordinate increment along axis                
+ CDELT2  =                   64 / Coordinate increment along axis                
+
+
+.. _Appendix2:
+
+*************************************
+Appendix 2 - D2IMFILE Example 
+*************************************
+
+The D2IMFILE reference file only contains a single 1-D array that should correct the
+column (row) values based on the value of the 'AXISCORR' keyword in the SCI header. This 
+simple reference file, therefore, contains only 2 extensions; namely,
+
+::
+
+ Filename: /grp/hst/cdbs/jref/v971826mj_d2i.fits
+ No.    Name         Type      Cards   Dimensions   Format
+ 0    PRIMARY     PrimaryHDU      35   ()           int16   
+ 1    DX          ImageHDU        18   (4096,)      float32   
+
+The PRIMARY header only needs to contain information on what detector this file corrects,
+along with any available information on how this file was generated.  The ACS/WFC D2IMFILE
+PRIMARY header only includes::
+
+ SIMPLE  =                    T / Fits standard                                  
+ BITPIX  =                   16 / Bits per pixel                                 
+ NAXIS   =                    0 / Number of axes                                 
+ EXTEND  =                    T / File may contain extensions                    
+ ORIGIN  = 'NOAO-IRAF FITS Image Kernel July 2003' / FITS file originator        
+ DATE    = '2010-02-01T20:19:11' / Date FITS file was generated                  
+ IRAF-TLM= '2011-09-02T13:04:07' / Time of last modification                     
+ NEXTEND =                    1 / number of extensions in file                   
+ FILENAME= 'v971826mj_d2i.fits' / name of file                                   
+ FILETYPE= 'WFC D2I FILE'          / type of data found in data file             
+ OBSTYPE = 'IMAGING '              / type of observation                         
+ TELESCOP= 'HST'                / telescope used to acquire data                 
+ INSTRUME= 'ACS   '             / identifier for instrument used to acquire data 
+ DETECTOR= 'WFC     '                                                            
+ USEAFTER= 'Mar 01 2002 00:00:00'                                                
+ COMMENT = 'D2I calibration file created by Warren Hack 29 APR 2010'             
+ DESCRIP = 'Column-width correction file for WFC images------------------------' 
+ PEDIGREE= 'INFLIGHT 11/11/2002 11/11/2002'                                      
+ HISTORY                                                                         
+ HISTORY   Fixed column (or row) width correction file. This is applied          
+ HISTORY   as a correction to the input pixel position and the output of         
+ HISTORY   this correction is to be used as input to the polynomial and          
+ HISTORY   non-polynomial distortion corrections.                                
+ HISTORY                                                                         
+ HISTORY   For ACS WFC data, the correction is stored as an image extension      
+ HISTORY   (D2IMARR) with one row. Each element in the row specifies the         
+ HISTORY   correction in pixels for every pixel in the column (or row) in        
+ HISTORY   the science extension; for ACS WFC, the correction is in the X        
+ HISTORY   direction.                                                            
+ HISTORY                                                                         
+ HISTORY   For a more in-depth explanation of this file, please see the          
+ HISTORY   draft writeup at:                                                     
+ HISTORY http://stsdas.stsci.edu/stsci_python_epydoc/stwcs/fits_conventions.html 
+ HISTORY wfc_ref68col_d2i.fits renamed to v961506lj_d2i.fits on Sep 6 2011       
+ HISTORY v961506lj_d2i.fits renamed to v971826mj_d2i.fits on Sep 7 2011          
+
+In this case, most of the keywords not required by FITS describe how this file
+was computed while also describing how it should be applied. 
+
+The header keywords for the actual DX array simply needs to provide the information
+necessary to apply the values to the data; namely, 
+
+::
+
+ XTENSION= 'IMAGE   '           / Image extension                                
+ BITPIX  =                  -32 / Bits per pixel                                 
+ NAXIS   =                    1 / Number of axes                                 
+ NAXIS1  =                 4096 / Axis length                                    
+ PCOUNT  =                    0 / No 'random' parameters                         
+ GCOUNT  =                    1 / Only one group                                 
+ EXTNAME = 'DX      '           / Extension name                                 
+ EXTVER  =                   11 / Extension version                              
+ ORIGIN  = 'NOAO-IRAF FITS Image Kernel July 2003' / FITS file originator        
+ INHERIT =                    F / Inherits global header                         
+ DATE    = '2009-03-18T19:28:09' / Date FITS file was generated                  
+ IRAF-TLM= '16:05:02 (18/03/2009)' / Time of last modification                   
+ CRPIX1  =                    0 / Distortion array reference pixel               
+ CDELT1  =                    0 / Grid step size in first coordinate             
+ CRVAL1  =                    0 / Image array pixel coordinate                   
+ CRPIX2  =                    0 / Distortion array reference pixel               
+ CDELT2  =                    0 / Grid step size in second coordinate            
+ CRVAL2  =                    0 / Image array pixel coordinate                   
+
+The fact that these values get applied without interpolation to each pixel in a row,
+in this case, means that no translation terms are needed in the header, making for 
+a very simple header and very simple application to the data.