Adding documentation

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

9 files changed, 214 insertions, 0 deletions

diff --git a/doc/source/altwcs.rst b/doc/source/altwcs.rst
new file mode 100644
index 0000000..3670a75
--- /dev/null
+++ b/doc/source/altwcs.rst
@@ -0,0 +1,18 @@
+.. _altwcs:
+
+**************************************
+User Interface: altwcs
+**************************************
+ 
+.. currentmodule:: stwcs.wcsutil.altwcs
+
+.. automodule:: stwcs.wcsutil.altwcs
+
+.. autofunction:: stwcs.wcsutil.altwcs.archiveWCS
+.. autofunction:: stwcs.wcsutil.altwcs.restoreWCS
+.. autofunction:: stwcs.wcsutil.altwcs.deleteWCS
+.. autofunction:: stwcs.wcsutil.altwcs.wcsnames
+.. autofunction:: stwcs.wcsutil.altwcs.wcskeys
+.. autofunction:: stwcs.wcsutil.altwcs.available_wcskeys
+.. autofunction:: stwcs.wcsutil.altwcs.next_wcskey
+.. autofunction:: stwcs.wcsutil.altwcs.getKeyFromName
\ No newline at end of file
diff --git a/doc/source/apply_corrections.rst b/doc/source/apply_corrections.rst
new file mode 100644
index 0000000..3efe122
--- /dev/null
+++ b/doc/source/apply_corrections.rst
@@ -0,0 +1,5 @@
+.. _apply_corrections:
+
+**************************************
+Decision Tree For Applying Corrections
+**************************************
\ No newline at end of file
diff --git a/doc/source/hstwcs.rst b/doc/source/hstwcs.rst
new file mode 100644
index 0000000..ec69944
--- /dev/null
+++ b/doc/source/hstwcs.rst
@@ -0,0 +1,16 @@
+.. _hstwcs:
+
+**************************************
+HSTWCS API
+**************************************
+    
+.. currentmodule:: stwcs.wcsutil.hstwcs
+
+--------------------------
+HSTWCS
+--------------------------
+.. autoclass:: HSTWCS
+   :members:
+   :undoc-members:
+   :show-inheritance:
+   
\ No newline at end of file
diff --git a/doc/source/hstwcs_ui.rst b/doc/source/hstwcs_ui.rst
new file mode 100644
index 0000000..7a09af4
--- /dev/null
+++ b/doc/source/hstwcs_ui.rst
@@ -0,0 +1,26 @@
+.. _hstwcs_ui:
+
+**************************************
+HSTWCS UI Examples
+**************************************
+- Create an HSTWCS object using a pyfits HDUList and an extension number 
+
+  fobj = pyfits.open('some_file.fits')
+
+  w = wcsutil.HSTWCS(fobj, 3)
+
+- Create an HSTWCS object using a qualified file name. 
+
+  w = wcsutil.HSTWCS('j9irw4b1q_flt.fits[sci,1]')
+
+- Create an HSTWCS object using a file name and an extension number. 
+
+  w = wcsutil.HSTWCS('j9irw4b1q_flt.fits', ext=2)
+  
+- Create an HSTWCS object from WCS with key 'O'.
+
+  w = wcsutil.HSTWCS('j9irw4b1q_flt.fits', ext=2, wcskey='O')
+
+- Create a template HSTWCS object for a DEFAULT object.
+
+  w = wcsutil.HSTWCS(instrument='DEFAULT')
\ No newline at end of file
diff --git a/doc/source/index.rst b/doc/source/index.rst
index a7bacd1..f108683 100644
--- a/doc/source/index.rst
+++ b/doc/source/index.rst
@@ -6,10 +6,22 @@
 Welcome to STWCS's documentation!
 =================================
 
+This package provides support for WCS based distortion models and coordinate 
+transformation. It relies on PyWCS (based on WCSLIB). It consists of two subpackages:
+UPDATEWCS and WCSUTIL. UPDATEWCS performs corrections to the basic WCS and includes 
+other distortion infomation in the science files as header keywords or file extensions.
+WCSUTIL provides an HSTWCS object which extends pywcs.WCS object and provides HST instrument
+specific information as well as methods for coordinate tarnsformaiton. WCSUTIL also provides 
+functions for manipulating alternate WCS descriptions in the headers.
+
 Contents:
 
 .. toctree::
    :maxdepth: 2
+   
+   wcsutil
+   updatewcs
+   
 
 Indices and tables
 ==================
diff --git a/doc/source/updatewcs.rst b/doc/source/updatewcs.rst
new file mode 100644
index 0000000..73b3840
--- /dev/null
+++ b/doc/source/updatewcs.rst
@@ -0,0 +1,68 @@
+.. _updatewcs:
+
+**************************************
+UPDATEWCS
+**************************************
+UPDATEWCS applies corrections to the WCS of a science file
+and adds reference information as header keywords and fits 
+file extensions so that a science file contains all necessary 
+information to represent astrometrically precise positions.
+The order in which the corrections are applied is important 
+and is as follows:
+
+- Detector to Image Correction
+
+- Apply Time dependent distortion (if applciable)
+
+- Recomputing the basic WCS
+
+- Apply Velocity Aberration Correction
+
+- Apply polynomial distortion through the SIP coefficients
+
+- Apply non-polynomial distortion
+
+Mathematicall the entire transformation from detector to sky 
+coordinates is described by:
+
+.. math:: (x',y') &= DET2IM(x,y) 
+
+.. math:: \binom{u'}{v'} &= \binom{x' - CRPIX1}{y' - CRPIX2}
+
+.. math:: \left( \begin{array}{ll}
+         \alpha \\
+         \delta \\
+         \end{array} \right) &=
+      \left( \begin{array}{ll}
+      CRVAL1 \\
+      CRVAL2\\
+      \end{array} \right) + 
+      \left( \begin{array}{cc}
+      CD11 & CD12 \\ 
+      CD21 & CD22\\
+      \end{array} \right) 
+      \left( \begin{array}{ll}
+      u' + f(u',v') + LT_x(x',y') \\ 
+      v' + g(u',v') + LT_y(x',y') \\ 
+      \end{array} \right)
+    
+where f(u',v') and g(u',v') represent the polynomial distortion correction specified as
+
+.. math:: f(u',v') = \sum_{p+q=2}^{AORDER} A_{pq} {u'}^{p} {v'}^{q}
+          \\
+          g(u',v')  = \sum_{p+q=2}^{BORDER} B_{pq} {u'}^{p} {v'}^{q}
+
+
+where
+
+* x', y' are the initial coordinates x,y with the 68th column correction applied through the DET2IM convention
+* u',v' are the DET2IM-corrected coordinates relative to CRPIX1,CRPIX2
+* LT<sub>x</sub>, LT<sub>y</sub> is the residual distortion in the lookup tables written to the header using the Paper IV lookup table convention
+* A, B are the SIP coefficients specified using the SIP convention
+
+.. toctree::
+   :maxdepth: 2
+   
+   updatewcs_ui
+   apply_corrections
+   wcs_corrections
\ No newline at end of file
diff --git a/doc/source/updatewcs_ui.rst b/doc/source/updatewcs_ui.rst
new file mode 100644
index 0000000..9e113c9
--- /dev/null
+++ b/doc/source/updatewcs_ui.rst
@@ -0,0 +1,9 @@
+.. _updatewcsUi:
+
+**************************************
+UPDATEWCS - User Interface
+**************************************
+
+.. currentmodule:: stwcs.updatewcs.__init__
+
+.. autofunction:: stwcs.updatewcs.updatewcs
\ No newline at end of file
diff --git a/doc/source/wcs_corrections.rst b/doc/source/wcs_corrections.rst
new file mode 100644
index 0000000..80d8686
--- /dev/null
+++ b/doc/source/wcs_corrections.rst
@@ -0,0 +1,41 @@
+.. _wcs_corrections:
+
+**************************************
+WCS Corrections
+**************************************
+
+.. currentmodule:: stwcs.updatewcs.corrections
+
+---------------------------------------
+Time Dependent Distortion
+---------------------------------------
+
+.. autoclass:: stwcs.updatewcs.corrections.TDDCorr
+
+-----------------------------------------
+Velocity Aberration Correction
+-----------------------------------------
+
+.. autoclass:: stwcs.updatewcs.corrections.VACorr
+
+-----------------------------------------
+Simple Imaging Polynomial Coefficients
+-----------------------------------------
+
+.. autoclass:: stwcs.updatewcs.corrections.CompSIP
+
+-----------------------------------------
+Non-Polynomial Distortion Correction
+-----------------------------------------
+
+.. module:: stwcs.updatewcs.corrections
+
+.. autoclass:: stwcs.updatewcs.dgeo.DGEOCorr
+
+-----------------------------------------
+Detector to Image Correction
+-----------------------------------------
+
+.. module:: stwcs.updatewcs.det2im
+
+.. autoclass:: stwcs.updatewcs.det2im.DET2IMCorr
\ No newline at end of file
diff --git a/doc/source/wcsutil.rst b/doc/source/wcsutil.rst
new file mode 100644
index 0000000..8a8be24
--- /dev/null
+++ b/doc/source/wcsutil.rst
@@ -0,0 +1,19 @@
+.. _wcsutil:
+
+**************************************
+WCSUTIL 
+**************************************
+This package provides an HSTWCS class which performs WCS based coordinate 
+transformations and a module for managing alternate WCS's.
+
+.. currentmodule:: stwcs.wcsutil.__init__
+
+.. toctree::
+   :maxdepth: 2
+   
+   
+   hstwcs_ui
+   hstwcs
+   altwcs
+   
+