Updating fits_conventions TSR with figures, along with some minor corrections to other TSRs.

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

6 files changed, 36 insertions, 12 deletions

diff --git a/doc/source/fits_conventions.rst b/doc/source/fits_conventions.rst
index d67add4..6f3ed44 100644
--- a/doc/source/fits_conventions.rst
+++ b/doc/source/fits_conventions.rst
@@ -148,7 +148,17 @@ as the original DGEOFILE as used by ACS and WFPC2 as that large of a reference
 file would more than double the size of each input image since the reference 
 file gets folded into each file. Instead, a sub-sampled array of corrections will 
 be stored in the new reference file, with ACS using a 65 x 33 array for each ACS/WFC 
-chip. This new reference file will be called an NPOLFILE in the FITS image header, 
+chip. 
+
+.. figure:: /images/npol_vector_text.png
+   :width: 95 %
+   :alt: ACS/WFC F475W NPOLFILE corrections
+   :align: center
+   
+   This figure illustrates the corrections included in the ACS/WFC F475W NPOLFILE.
+
+
+This new reference file will be called an NPOLFILE in the FITS image header, 
 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
@@ -178,8 +188,8 @@ For ACS the correction is stored as an image extension with one row. Each elemen
 the row specifies the correction in pixels for every pixel in the column (or row) in 
 the science extension as predetermined by the calibration teams who would be responsible 
 for creating the reference files. For ACS the correction is in the X direction and for 
-WFPC2 - in the Y direction. The following new keywords are added to the primary header 
-of a science file: 
+WFPC2 - in the Y direction. The following new keywords are added to the header of each 
+science extension of a science file: 
 
 ::
 
@@ -215,6 +225,14 @@ small enough to easily be added to an input image without significant change in
 initial D2IMFILE for ACS has been generated for testing with a sample header provided in 
 the Appendix. 
 
+.. figure:: /images/d2im_bar.png
+   :width: 95 %
+   :alt: ACS/WFC F475W D2IMFILE corrections
+   :align: center
+   
+   This figure illustrates the corrections included in the first 246 columns of 
+   the ACS/WFC F475W D21IMFILE.
+
 The WCS for this correction describes the extension as a 1-D image, even though it will 
 be applied to a 2-D image. This keeps it clear that the same correction gets applied to 
 all rows(columns) without interpolation. The header specifies which axis this correction 
@@ -285,4 +303,4 @@ the CTYPE keyword.
 
    Coordinate Transformation Pipeline
    
-   
\ No newline at end of file
+   
diff --git a/doc/source/fits_conventions_tsr.rst b/doc/source/fits_conventions_tsr.rst
index 99b9d81..091cf78 100644
--- a/doc/source/fits_conventions_tsr.rst
+++ b/doc/source/fits_conventions_tsr.rst
@@ -1,3 +1,8 @@
+.. _fits_conventions_tsr:
+
+FITS Conventions Report
+-----------------------
+
 .. toctree::
    :maxdepth: 3
    
diff --git a/doc/source/headerlet_def.rst b/doc/source/headerlet_def.rst
index b5c6944..9d4afd0 100644
--- a/doc/source/headerlet_def.rst
+++ b/doc/source/headerlet_def.rst
@@ -29,13 +29,13 @@ Source Image
 ============
 All users get their copy of an image from the HST Archive (OTFR) after being processed with the latest image calibrations, including applying the latest available distortion models. The calibrated image gets passed to the user with the ``_flt.fits`` suffix and is referred to as the ``FLT`` image.  These FLT images serve as the inputs to MultiDrizzle in order to apply the distortion models and combine the images into a single ``DRZ`` product.  
 
-The WCS information in the FLT images has been updated to include the full distortion model, including the full polynomial solution from the IDCTAB and all the corrections formerly combined into the DGEOFILE. The FITSConventions_ report by Dencheva (currently available online) contains the full description of the conventions used to describe all these components in a FITS file. The header now contains the following set of keywords and extensions to fully describe the WCS with distortion:
+The WCS information in the FLT images has been updated to include the full distortion model, including the full polynomial solution from the IDCTAB and all the corrections formerly combined into the DGEOFILE. The :ref:`FITS Conventions Report <fits_conventions_tsr>` report by Dencheva contains the full description of the conventions used to describe all these components in a FITS file. The header now contains the following set of keywords and extensions to fully describe the WCS with distortion:
 
   * **Linear WCS keywords**: specifically, CRPIX, CRVAL, CTYPE, CD matrix keywords
   * **SIP coefficients**: A_*_* and B_*_*, A_ORDER, B_ORDER, 
     OCX10, OCX11, OCY10, and OCY11 keywords
   * **NPOL file**: if an NPOLFILE has been specified for the image, 
-    CPDIS and DP keywords to point to WCSDVARR extensions (Paper IV convention)
+    CPDIS and DP record-value keywords to point to WCSDVARR extensions (Paper IV convention)
   * **Column correction file**: if a D2IMFILE has been specified for use with the image, 
     the D2IMEXT and D2IMERR keywords signify the use of a D2IM file extension
   * **WCSDVARR extensions**: 2 extensions for each chip with lookup tables containing 
@@ -45,9 +45,9 @@ The WCS information in the FLT images has been updated to include the full disto
     column-correction for that chip from the D2IMFILE.
  
 
-Each science header will have its own set of these keywords and extensions that will be kept together as part of the headerlet definition.  This avoids any ambiguity as to what solution was used for any given WCS. A summary of all the WCS solutions for all the chips can be written out to the WCSCORR table, a `binary FITS table extension <http://mediawiki.stsci.edu/mediawiki/index.php/Telescopedia:WCSTableDefinition>`__ described online.
+Each science header will have its own set of these keywords and extensions that will be kept together as part of the headerlet definition.  This avoids any ambiguity as to what solution was used for any given WCS. 
 
-An ACS/WFC exposure would end up with the following set of extensions::
+An HST ACS/WFC exposure would end up with the following set of extensions::
 
     EXT#  FITSNAME      FILENAME              EXTVE DIMENS       BITPI OBJECT       
 
@@ -63,13 +63,14 @@ An ACS/WFC exposure would end up with the following set of extensions::
     9       IMAGE       WCSDVARR              2     64x32        -32                
     10      IMAGE       WCSDVARR              3     64x32        -32                
     11      IMAGE       WCSDVARR              4     64x32        -32                
-    12      BINTABLE    WCSCORR                     18Fx10R
 
 There may be a lot of extensions appended to this FITS file, but the sum total of all these new extensions comes to approximately 100kB for ACS/WFC images (our sample only requires 86400 bytes), making them a space efficient means of managing all the distortion and WCS information. 
 
 Headerlet Definition
 ====================
-The `headerlet` needs to be a self-consistent, fully described definition of a WCS and its distortion.  The WCS and SIP coefficients get derived from the SCI header directly, along with the keywords which refer to the extensions with the NPOLFILE and D2IMFILE corrections.  The science observation will be stripped from the original WCS which will be saved to a headerlet so that the user can always revert back to the original WCS solution at any time. 
+The `headerlet` needs to be a self-consistent, fully described definition of a WCS and its distortion for all chips/detectors of a single exposure.  The WCS and SIP coefficients get derived from the SCI header directly, along with the all keywords which refer to the extensions with the optional NPOLFILE and D2IMFILE corrections.  The full 'headerlet' will be stored as a multi-extension FITS object that includes a primary header, an extension for each chip which only contains the WCS and distortion keywords, and any additional extensions for optional distortion correction information.  This object can be written out to a file and/or attached to an existing image's FITS file as a new extension.
+
+The science observation's original WCS will be saved to a headerlet so that the user can always revert back to the original WCS solution at any time. 
 There will be an option to permanently delete the original WCS and not save it to a headerlet.  
 
 New WCS Extension
diff --git a/doc/source/images/d2im_bar.png b/doc/source/images/d2im_bar.png
new file mode 100644
index 0000000..99c2832
--- /dev/null
+++ b/doc/source/images/d2im_bar.png
diff --git a/doc/source/images/npol_vector_text.png b/doc/source/images/npol_vector_text.png
new file mode 100644
index 0000000..78c85e9
--- /dev/null
+++ b/doc/source/images/npol_vector_text.png
diff --git a/doc/source/wcs_corrections.rst b/doc/source/wcs_corrections.rst
index d1f7b62..086d0a1 100644
--- a/doc/source/wcs_corrections.rst
+++ b/doc/source/wcs_corrections.rst
@@ -30,7 +30,7 @@ Non-Polynomial Distortion Correction
 
 .. py:module:: stwcs.updatewcs.corrections
 
-.. autoclass:: stwcs.updatewcs.dgeo.DGEOCorr
+.. autoclass:: stwcs.updatewcs.npol.NPOLCorr
 
 -----------------------------------------
 Detector to Image Correction
@@ -38,4 +38,4 @@ Detector to Image Correction
 
 .. py:module:: stwcs.updatewcs.det2im
 
-.. autoclass:: stwcs.updatewcs.det2im.DET2IMCorr
\ No newline at end of file
+.. autoclass:: stwcs.updatewcs.det2im.DET2IMCorr