Merge pull request #65 from nden/docs

tests

docs/gwcs/selector_model.rst

@@ -4,7 +4,7 @@ Discontinuous WCS - An IFU Example
 There are a couple of models in GWCS which help with managing discontinuous WCSs.
 Given (x, y) pixel indices, `~gwcs.selector.LabelMapperArray` returns a label (int or str)
 which uniquely identifies a location in a frame. `~gwcs.selector.RegionsSelector`
-maps different transforms to different locations in the frame of `~gwcs.selector.RegionsSelector.label_mapper`.
+maps different transforms to different locations in the frame of `~gwcs.selector._LabelMapper`.
 
 An example use case is an IFU observation. The locations on the detector where slices are
 projected are labeled with integer numbers. Given an (x, y) pixel, the `~gwcs.selector.LabelMapperArray`
@@ -71,7 +71,7 @@ Create the pixel to world transform for the entire IFU:
 The WCS object now can evaluate simultaneously the transforms of all slices
 
   >>> wifu = wcs.WCS(forward_transform=regions_transform, output_frame=cframe, input_frame=det)
-  >>> x, y = mask.data.shape
+  >>> x, y = mask.mapper.shape
   >>> x, y = np.mgrid[:x, :y]
   >>> r, d, l = wifu(x, y)
 
@@ -91,19 +91,15 @@ is functionally equivalent to the above commands bu returns coordinate objects:
   >>> wifu.available_frames
       ['detector', 'world']
 
-  >>> wifu.world.coordinates(10, 200)
+  >>> wifu.output_frame.coordinates(10, 200)
       (<SkyCoord (ICRS): (ra, dec) in deg
           (10.3, 60.0)>, <Quantity 10.6 micron>)
 
 Frames provide additional information:
 
-  >>> print output_frame.axes_type
+  >>> print(wifu.output_frame.axes_type)
       [u'SPATIAL', u'SPECTRAL', u'SPATIAL']
-  >>> print output_frame.axes_names
+  >>> print(wifu.output_frame.axes_names)
       [u'ra', 'lambda', u'dec']
-  >>> output_frame.unit
+  >>> print(wifu.output_frame.unit)
       [Unit("deg"), Unit("micron"), Unit("deg")]
-
-
-
-

docs/gwcs/using_wcs.rst

@@ -0,0 +1,82 @@
+Using the WCS object
+====================
+
+Let's expand the WCS created in :ref:`getting-started` by adding a distortion.
+
+First create polynomial transform to represent distortion:
+
+  >>> polyx = Polynomial2D(4)
+  >>> polyx.parameters = np.random.randn(15)
+  >>> polyy = Polynomial2D(4)
+  >>> polyy.parameters = np.random.randn(15)
+  >>> distortion = (Mapping((0, 1, 0, 1)) | polyx & polyy).rename("distortion")
+
+Create an intermediate frame. The distortion transforms positions on the
+detector into this frame.
+
+  >>> focal_frame = cf.Frame2D(name="focal_frame", unit=(u.arcsec, u.arcsec))
+
+Create the WCS pipeline and initialize the WCS:
+
+  >>> pipeline = [(detector_frame, distortion),
+                  (focal_frame, det2sky),
+                  (sky_frame, None)
+                  ]
+  >>> wcsobj = wcs.WCS(pipeline)
+  >>> print(wcsobj)
+      From        Transform
+      ----------- ----------
+      detector     distortion
+      focal_frame  focal2sky
+      icrs         None
+
+To see what frames are defined:
+
+   >>> print(wcsobj.available_frames)
+       ['detector', 'focal_frame', 'icrs']
+   >>> wcsobj.input_frame
+       <Frame2D(name="detector", unit=(Unit("pix"), Unit("pix")), axes_names=('x', 'y'),
+       axes_order=(0, 1))>
+   >>> wcsobj.output_frame
+       <CelestialFrame(name="icrs", unit=(Unit("deg"), Unit("deg")), axes_names=('lon', 'lat'),
+       axes_order=(0, 1), reference_frame=<ICRS Frame>)>
+
+Because the ``output_frame`` is a `~gwcs.coordinate_frames.CoordinateFrame` object we can get
+the result of the WCS transform as an `astropy.coordinates.SkyCoord` object and transform
+them to other standard coordinate frames supported by `astropy.coordinates`.
+
+  >>> skycoord = wcsobj(1, 2, output="numericals_plus")
+  >>> print(skycoord)
+      <SkyCoord (ICRS): (ra, dec) in deg
+          ( 4.97563356, -72.54530634)>
+  >>> print(skycoord.transform_to("galactic"))
+      <SkyCoord (Galactic): (l, b) in deg
+          ( 306.23201951, -44.38032023)>
+
+Some methods allow managing the transforms in a more detailed manner.
+
+Transforms between frames can be retrieved and evaluated separately.
+
+  >>> distortion = wcsobj.get_transform('detector', 'focal')
+  >>> distortion(1, 2)
+      (4.807433286098964, 4.924746607074259)
+
+Transforms in the pipeline can be replaced by new transforms.
+
+  >>> new_transform = Shift(1) & Shift(1.5) | distortion
+  >>> wcsobj.set_transform('detector', 'focal_frame', new_transform)
+  >>> wcsobj(1, 2)
+      (7.641677379945592, -71.18890415491595)
+
+A transform can be inserted before or after a frame in the pipeline.
+
+  >>> scale = Scale(2) & Scale(1)
+  >>> wcsobj.insert_transform('icrs', scale, after=False)
+  >>> wcsobj(1, 2)
+      (15.283354759891184, -71.18890415491595)
+
+The WCS object has an attribute ``domain`` which describes the range of
+acceptable values for each input axis.
+
+  >>> wcsobj.domain = [{'lower': 0, 'upper': 2048, 'includes_lower': True, 'includes_upper': False},
+                       {'lower': 0, 'upper': 1000, 'includes_lower': True, 'includes_upper': False}]

docs/index.rst

@@ -1,7 +1,7 @@
 GWCS Documentation
-====================
+==================
 
-`GWCS <https://github.com/spacetelescope/gwcs>`__ is a package for constructing and managing
+`GWCS <https://github.com/spacetelescope/gwcs>`__ is a package for managing
 the World Coordinate System (WCS) of astronomical data.
 
 Introduction
@@ -16,78 +16,93 @@ using the flexible framework of compound models in `~astropy.modeling`.
 In the case of a celestial output frame `~astropy.coordinates` provides
 further transformations between standard coordinate frames.
 Spectral output coordinates are instances of `~astropy.units.Quantity`  and are
-transformed to other units with the tools in that package.
-The goal is to provide a flexible toolkit which is easily extendable by adding new
-transforms and frames.
+transformed to other units with the tools in that package. The goal is to provide
+a flexible toolkit which is easily extendable by adding new transforms and frames.
 
 
 Installation
 ------------
 
 `gwcs <https://github.com/spacetelescope/gwcs>`__ requires:
 
-- `numpy <http://www.numpy.org/>`__ 1.6 or later
+- `numpy <http://www.numpy.org/>`__ 1.7 or later
 
-- `astropy <http://www.astropy.org/>`__ 1.1 or later
+- `astropy <http://www.astropy.org/>`__ 1.2 or later
 
 - `asdf <http://pyasdf.readthedocs.org/en/latest/>`__
 
+To install from source::
+
+    git clone https://github.com/spacetelescope/gwcs.git
+    cd gwcs
+    python setup.py install
+
+To install the latest release::
+
+    pip install gwcs
+
+GWCS is also available as part of astroconda.
+
+.. _getting-started:
 
 Getting Started
----------------
+===============
+
+The WCS data model represents a pipeline of transformations from some
+initial coordinate frame to a standard coordinate frame.
+It is implemented as a list of steps executed in order. Each step defines a
+starting coordinate frame and the transform to the next frame in the pipeline.
+The last step has no transform, only a frame which is the output frame of
+the total transform. As a minimum a WCS object has an ``input_frame`` (defaults to "detector"),
+an ``output_frame`` and the transform between them.
+
+As an example, consider a typical WCS of an image without distortion.
 
-The simplest way to initialize a WCS object is to pass a `forward_transform` and an `output_frame`
-to `~gwcs.wcs.WCS`. As an example, consider a typical basic FITS WCS of an image.
 The following imports are generally useful:
 
+  >>> import numpy as np
   >>> from astropy.modeling.models import (Shift, Scale, Rotation2D,
       Pix2Sky_TAN, RotateNative2Celestial, Mapping, Polynomial2D)
   >>> from astropy import coordinates as coord
   >>> from astropy import units as u
   >>> from gwcs import wcs
-  >>> from gwcs import coordinate_frames
-
-The `forward_transform` is constructed as a combined model using `astropy.modeling`. The frames
-can be strings or subclasses of `~gwcs.coordinate_frames.CoordinateFrame`.
-
-  >>> transform = Shift(-10.5) & Shift(-13.2) | Rotation2D(0.0023) | \
-      Scale(.01) & Scale(.04) | Pix2Sky_TAN() | RotateNative2Celestial(5.6, -72.05, 180)
-  >>> sky_frame = coordinate_frames.CelestialFrame(reference_frame=coord.ICRS(), name='icrs')
-  >>> w = wcs.WCS(forward_transform=transform, output_frame=sky_frame)
+  >>> from gwcs import coordinate_frames as cf
 
-To convert a pixel (x, y) = (1, 2) to sky coordinates, call the WCS object as a function:
+The ``forward_transform`` is constructed as a combined model using `astropy.modeling`.
+The frames are subclasses of `~gwcs.coordinate_frames.CoordinateFrame` (although strings are
+acceptable too).
 
-  >>> sky = w(1, 2)
-  >>> print(sky)
-      (5.284139265842845, -72.49775640633503)
+Create a transform to convert detector coordinates to ICRS.
 
-The :meth:`~gwcs.wcs.WCS.invert` method evaluates the :meth:`~gwcs.wcs.WCS.backward_transform`
-if available, otherwise applies an iterative method to calculate the reverse coordinates.
+  >>> det2sky = (Shift(-10.5) & Shift(-13.2) | Rotation2D(0.0023) | \
+      Scale(.01) & Scale(.04) | Pix2Sky_TAN() | \
+      RotateNative2Celestial(5.6, -72.05, 180)).rename("detector2sky")
 
-  >>> w.invert(*sky)
-      (1.000000000009388, 2.0000000000112728)
+Create a coordinate frame associated with the detector and a celestial frame.
 
-Some methods allow managing the transforms in a more detailed manner.
+  >>> detector_frame = cf.Frame2D(name="detector", axes_names=("x", "y"), unit=(u.pix, u.pix))
+  >>> sky_frame = cf.CelestialFrame(reference_frame=coord.ICRS(), name='icrs')
 
-Transforms between frames can be retrieved and evaluated separately.
+Initialize the WCS:
 
-  >>> dist = w.get_transform('detector', 'focal')
-  >>> dist(1, 2)
-      (0.16, 0.8)
+  >>> wcsobj = wcs.WCS(forward_transform=det2sky, input_frame=detector_frame, output_frame=sky_frame)
+  >>> print(wcsobj)
+      From        Transform
+      ----------- ----------
+      detector     detector2sky
+      icrs         None
 
-Transforms in the pipeline can be replaced by new transforms.
+To convert a pixel (x, y) = (1, 2) to sky coordinates, call the WCS object as a function:
 
-  >>> new_transform = Shift(1) & Shift(1.5) | distortion
-  >>> w.set_transform('detector', 'focal', new_transform)
-  >>> w(1, 2)
-      (5.257230028926096, -72.53171157138964)
+  >>> sky = wcsobj(1, 2)
+  >>> print(sky)
+      (5.284139265842838, -72.49775640633504)
 
-A transform can be inserted before or after a frame in the pipeline.
+The :meth:`~gwcs.wcs.WCS.invert` method evaluates the :meth:`~gwcs.wcs.WCS.backward_transform`
+if available, otherwise applies an iterative method to calculate the reverse coordinates.
 
-  >>> scale = Scale(2) & Scale(1)
-  >>> w.insert_transform('icrs', scale, after=False)
-  >>> w(1, 2)
-      (10.514460057852192, -72.53171157138964)
+  >>> wcsobj.invert(*sky)
+      (1.000, 2.000)
 
 
 Using `gwcs`
@@ -97,11 +112,12 @@ Using `gwcs`
 .. toctree::
   :maxdepth: 2
 
-  gwcs/create_wcs
+  gwcs/using_wcs.rst
   gwcs/selector_model.rst
   gwcs/wcstools.rst
 
 
+
 See also
 --------