Add more documentation

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

4 files changed, 67 insertions, 11 deletions

diff --git a/doc/source/altwcs.rst b/doc/source/altwcs.rst
index 3670a75..0b44bfb 100644
--- a/doc/source/altwcs.rst
+++ b/doc/source/altwcs.rst
@@ -3,7 +3,8 @@
 **************************************
 User Interface: altwcs
 **************************************
- 
+The functions in this module manage alternate WCS's in a header.
+
 .. currentmodule:: stwcs.wcsutil.altwcs
 
 .. automodule:: stwcs.wcsutil.altwcs
diff --git a/doc/source/hstwcs.rst b/doc/source/hstwcs.rst
index dd858d5..08af8a4 100644
--- a/doc/source/hstwcs.rst
+++ b/doc/source/hstwcs.rst
@@ -3,11 +3,11 @@
 **************************************
 HSTWCS API
 **************************************
-    
+
 .. currentmodule:: stwcs.wcsutil.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
index 7a09af4..ae5331d 100644
--- a/doc/source/hstwcs_ui.rst
+++ b/doc/source/hstwcs_ui.rst
@@ -1,26 +1,81 @@
 .. _hstwcs_ui:
 
 **************************************
-HSTWCS UI Examples
+HSTWCS Examples
 **************************************
+
+--------------------------
+Create an HSTWCS Object
+--------------------------
 - Create an HSTWCS object using a pyfits HDUList and an extension number 
 
-  fobj = pyfits.open('some_file.fits')
+  ``fobj = pyfits.open('some_file.fits')``
 
-  w = wcsutil.HSTWCS(fobj, 3)
+  ``w = wcsutil.HSTWCS(fobj, 3)``
 
 - Create an HSTWCS object using a qualified file name. 
 
-  w = wcsutil.HSTWCS('j9irw4b1q_flt.fits[sci,1]')
+  ``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)
+  ``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')
+  ``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
+  ``w = wcsutil.HSTWCS(instrument='DEFAULT')``
+  
+----------------------------------
+Coordinate Transformation Examples
+----------------------------------
+All coordinate transformation functions accept input coordinates 
+as 2D numpy arrays or 2 sequences of X and Y coordinates. 
+
+``inpix = np.array([[1., 2.], [1,3], [1,4], [1,5]])``
+
+or
+
+``X = [1.,1.,1.,1.]``
+
+``Y = np.array([2.,3.,4.,5.])``
+
+In addition all transformation functions require an `origin` parameter 
+which specifies if the coordinates are 0 or 1 based. For example in FITS 
+and Fortran, coordinates start from 1, while in Python and C, the index 
+of the first image pixel is (0,0).
+
+- Apply the entire detector to sky transformation at once:
+
+ ``outpix=w1.all_pix2sky(inpix,1)``
+
+ ``outpix=w1.all_pix2sky(X, Y,1)``
+
+- The same transformation can be done in separate steps:
+
+1. Apply the detector to image correction
+
+ ``dpx = w.det2im(inpix,1)``
+
+2. Aply the SIP polynomial distortion
+
+ ``spx = w.sip_pix2foc(dpx, 1)``
+ 
+3. Apply the non-polynomial distortion from the lookup table
+
+ ``lutpx = w.p4_pix2foc(dpx,1)``
+ 
+4. The undistorted coordinates are the sum of the input coordinates with 
+   the deltas for the distortion corrections.
+
+ ``fpix = dpx + (spx-dpx) +(lutpx-dpx)``
+ 
+5. Finally the transformation from undistorted to world coordinates is done 
+   by applying the linear WCS.
+ 
+ ``wpix = w.wcs_pix2sky(fpix, 1)``
+ 
+ 
\ No newline at end of file
diff --git a/doc/source/wcsutil.rst b/doc/source/wcsutil.rst
index 8a8be24..eef4ce8 100644
--- a/doc/source/wcsutil.rst
+++ b/doc/source/wcsutil.rst
@@ -12,8 +12,8 @@ transformations and a module for managing alternate WCS's.
    :maxdepth: 2
    
    
-   hstwcs_ui
    hstwcs
+   hstwcs_ui
    altwcs