Generalized WCS

generalized_wcs/README.md

@@ -0,0 +1,11 @@
+Proposal for a WCS package
+
+*wcs_api.md* contains the main class.
+
+*coordinate_systems.md* defines the coordinate systems.
+
+*selector.md* contains a definition of a SelectorModel (a subclass of `astropy.modeling.Model`, to be used when a WCS requires more than one transform based on a selection criteria, e.g. for IFUs.
+
+*region_api.md* explains the role of regions in WCS.
+
+*example.md* shows how an instrument scientist would use the API.

generalized_wcs/coordinate_systems_api.md

@@ -0,0 +1,207 @@
+Coordinate Systems
+------------------
+
+The proposed API for coordinate systems is based on the
+[STC document](http://www.ivoa.net/documents/PR/STC/STC-20050315.html)
+and [WCS Paper III](http://fits.gsfc.nasa.gov/fits_wcs.html)
+and is a high level description of coordinate system classes.
+
+[Prototype implementation (incomplete)] ( https://github.com/nden/code-experiments/blob/master/generalized_wcs_api/prototype/coordinate_systems.py)
+
+Note: Some of this may be replaced (or merged) with the high level coordinate class
+being worked on although it may be that it is only a space coordinate class.
+
+A coordinate system consists of one or more coordinate frames which
+describe a reference position and a reference frame.
+
+The base class of all frames is `CoordinateFrame`. It is kept intentionally
+very simple so that it can be easily extended.
+
+    class CoordinateFrame(object):
+        """
+        Base class for CoordinateFrames
+
+        Parameters
+        ----------
+        num_axes : int
+            number of axes
+        ref_system : str
+            reference system (see subclasses)
+        ref_pos : str or ``ReferencePosition``
+            reference position or standard of rest
+        units : list of units
+            unit for each axis
+        axes_names : list of str
+            names of the axes in this frame
+        name : str
+            name (alias) for this frame
+        """
+        def __init__(self, num_axes, ref_system=None, ref_pos=None, units=None, axes_names=None, name=None):
+            """ Initialize a frame"""
+
+        def transform_to(self, other):
+            """
+            Transform from the current reference system to other
+            """
+
+The following basic frames are defined as subclasses of `CoordinateFrame`:
+
+    class TimeFrame(CoordinateFrame):
+        """
+        Time Frame
+
+        Parameters
+        ----------
+        scale : str
+            time scale, one of ``standard_time_scale``
+        format : str
+            time representation
+        obslat : float or ``astropy.coordinates.Latitude``
+            observer's latitude
+        obslon : float or ``astropy.coordinates.Longitude``
+            observer's longitude
+        units : str or ``astropy.units.Unit``
+            unit for each axis
+        axes_names : list of str
+            names of the axes in this frame 
+        """
+
+        standard_time_scale = time.Time.SCALES
+
+        time_format = time.Time.FORMATS
+
+        def __init__(self, scale, format, obslat=0., obslon=0., units="s", axes_names="Time", name="Time"):
+
+
+        def transform_to(self, val, tosys, val2=None, precision=None, in_subfmt=None,
+                         out_subfmt=None, copy=False):
+            """Transforms to a different scale/representation"""
+
+    class SkyFrame(CoordinateFrame):
+        """
+        Sky Frame Representation
+
+        Parameters
+        ----------
+        reference_system : str
+            one of standard_ref_frame
+        reference_position : str, ReferencePosition instance
+        obstime : time.Time instance
+            observation time
+        equinox : time.Time
+            equinox
+        ##TODO? List of supported projections per frame
+        projection : str
+            projection type
+        axes_names : iterable or str
+            axes labels
+        units : str or units.Unit instance or iterable of those
+            units on axes
+        distance : Quantity
+            distance from origin
+            see ``~astropy.coordinates.distance`
+        obslat : float or ~astropy.coordinates.Latitute`
+            observer's latitude
+        obslon : float or ~astropy.coordinates.Longitude
+            observer's longitude
+        """
+        standart_ref_frame = ["FK4", "FK5", "ICRS", '...']
+
+        def __init__(self, reference_system, reference_position, obstime, equinox=None,
+                 projection="", axes_names=["", ""], units=["",""], distance=None,
+                 obslat=None, obslon=None, name=None):
+
+        def transform_to(self, lat, lon, other, distance=None):
+            """
+            Transform from the current reference system to other.
+            """
+
+
+    class SpectralFrame(CoordinateFrame):
+        """
+        Represents Spectral Frame
+
+        Parameters
+        ----------
+        reference_frame : str
+            one of spectral_ref_frame
+        reference_position : ``ReferencePosition``
+        obstime : time.Time instance
+        units : str or units.Unit instance
+            units for the spectral frame
+        axes_names : str
+            spectral axis name
+            If None, reference_system is used
+        rest_freq : float or Quantity (default None)
+            rest frequency
+        obslat : float or instance of `~astropy.coordinates.Latitude`
+            observer's latitude
+        obslon : float or instanceof `~astropy.coordinates.Longitude`
+            observer's longitude
+        """
+
+        spectral_ref_frame = ["WAVE", "FREQ", "ENER", "WAVEN", "AWAV", "VRAD",
+                          "VOPT", "ZOPT", "VELO", "BETA"]
+
+        standard_reference_position = ["GEOCENTER", "BARYCENTER", "HELIOCENTER",
+                                       "TOPOCENTER", "LSR", "LSRK", "LSRD",
+                                       "GALACTIC_CENTER", "MOON", "LOCAL_GROUP_CENTER"]
+
+    def __init__(self, reference_system, reference_position, units, axes_names=None,
+                 obstime=None, rest_freq=None, obslat=None, obslon=None, name=None):
+
+    def transform_to(self, coord, other):
+        """ Transforms to other spectral coordinate system"""
+
+    class CartesianFrame(CoordinateFrame):
+        def __init__(self, num_axes, reference_position, units, projection=None, name=None, axes_names=None):
+            ##TODO: reference position
+            super(CartesianFrame, self).__init__(num_axes, ref_pos=reference_position, units=units,
+                                                 axes_names=axes_names, name=name)
+
+        def transform_to(self, other, *args):
+            #use affine transform
+
+
+    class DetectorFrame(CartesianFrame):
+        def __init__(self, reference_pixel, units=[u.pixel, u.pixel], name=None, reference_position="Local",
+                     axes_names=None):
+            super(DetectorFrame, self).__init__(2, reference_position=reference_position, units=units, name=name, axes_names=axes_names)
+            self._reference_pixel = 
+
+
+A `CoordinateSystem` has one or more `CoordinateFrame` objects:
+
+    class CoordinateSystem(object):
+        """
+        A coordinate system has one or more frames.
+
+        Parameters
+        ----------
+        name : string
+            a user defined name
+        frames : list
+            list of frames [Time, Sky, Spectral]
+        """
+        def __init__(self, frames, name="CompositeSystem"):
+            self.frames = frames
+
+
+    class ReferencePosition(object):
+        """
+        Encapsulates a reference position for a CoordFrame
+
+        Table 1 in the STC document.
+
+        """
+        standart_reference_positions = ["GEOCENTER", "BARYCENTER", "HELIOCENTER",
+                                        "TOPOCENTER", "LSR", "LSRK", "LSRD",
+                                        "GALACTIC_CENTER", "MOON", "LOCAL_GROUP_CENTER",
+                                        "EMBARYCENTER", "RELOCATABLE", "UNKNOWNRefPos"]
+
+        def __init__(self, frame, name):
+            if self._validate(frame, name):
+                self._name = name
+            else:
+                raise ReferencePositionError
+

generalized_wcs/design.md

@@ -0,0 +1,7 @@
+The goal is to provide a framework for WCS transformations which is general and flexible enough that it is easy to extend by adding new transformations or coordinate classes.
+
+The WCS class is represented as a directed graph whose nodes are coordinate systems and edges are transformations
+between them. This allows one to specify multiple coordinate systems and the transformations between them. 
+(The [prototype](https://github.com/nden/code-experiments/blob/master/generalized_wcs_api/prototype/wcs.py) uses [networkx](http://networkx.github.io).)
+
+Further advantage of this approach is that this can be extended by the transformations in the celestial coordinates package `astropy.coordinates` which is also represented by a graph and thus providing access to its claasses and transformations.

generalized_wcs/examples.md

@@ -0,0 +1,99 @@
+These are examples of how an instrument scientist can use the package to construct a WCS for an instrument. All examples assume the WCS information was already read in from somewhere (either a FITS header or a JSON file). This does not deal with WCS serialization issues.
+
+
+JSON files used in the examples:
+
+[dist_info](https://github.com/nden/code-experiments/blob/master/generalized_wcs_api/prototype/jwst_example/reference_files/spec_regions.json) - coonstains models for distortion corrections
+
+
+[spec_info](https://github.com/nden/code-experiments/blob/master/generalized_wcs_api/prototype/jwst_example/reference_files/spec_wcs.json) - contsains spectral models
+
+
+[regions_def](https://github.com/nden/code-experiments/blob/master/generalized_wcs_api/prototype/jwst_example/reference_files/regions_miri.json) - constains definitions of IFU regions as polygon vertices in pixel space
+
+[wcs_regions](https://github.com/nden/code-experiments/blob/master/generalized_wcs_api/prototype/jwst_example/reference_files/wcs_regions.json) - contains basic WCS for each IFU region as offsets from a primary region. The WCS for the primary region is in the FITS header
+
+[spec_regions](https://github.com/nden/code-experiments/blob/master/generalized_wcs_api/prototype/jwst_example/reference_files/spec_regions.json) - contains spectral models for all regions
+
+
+
+    class ImagingWCS(WCS):
+         """
+         wcs_info is a dict of basic FITS WCS keywords from the FITS header
+
+         """
+        def __init__(wcs_info, distortion_info):
+              dist = self.create_distortion_transformstion(distortion_info)
+              linear_trans = self.create_linear_wcs_transformation(wcs_info)
+              coord_sys = self.create_coordinate_system(wcs_info)
+              foc2sky = self.create_foc2sky(wcs_info)
+              trans = modeling.SerialCompositeModel([dist, linear_trans, foc2sky_trans])
+              super(ImagingWCS, self).__init__(trans, coord_sys)
+
+        def create_linear_wcs_transformation(self, wcs_info):
+             """Creates a composite transformation of a shift, rotation and scaling"""
+             return linear_trans
+
+        def create_distortion_transformation(self, dist_info):
+            """
+            Creates a distortion transformation.
+
+            An example of a JSON representation.
+            """
+            return dist_trans
+
+
+        def create_foc2sky(self, wcs_info):
+            """ Create a transformation from focal plane to sky - deprojection + celestial rotation"""
+            return foc2sky
+
+       def create_coordinate_system(self, wcs_info):
+           """Construts an instance of wsc.CoordinateSystem"""
+           return coord_sys            
+
+
+Spectral WCS:
+
+    class SpectralWCS(WCS):
+
+        def __init__(self, spec_info):
+            trans = self.create_spectral_transform(spec_info)
+            coord_sys = self.create_coordinate_system(wcs_info)
+            super(SpectralWCS, self).__init__(trans, coord_sys)
+
+         def create_coordinate_system(self, wcs_info):
+           """Construts an instance of wsc.CoordinateSystem"""
+           return coord_sys
+
+         def create_spectral_transform(spec_info):
+             """ Constructs a transform from teh model(s) in sepc_info"""
+             return spec_model
+
+An examplel of a composite spectral transform
+
+    class CompositeSpectralTransform(object):
+
+    def __init__(self, wcs_info, spec_info, dist_info=None):
+        self.spatial_transform = ImagingTransform(wcs_info, dist_info)
+        self.spectral_transform = SpectralTransform(spec_info)
+
+    def __call__(self, x, y):
+        alpha, delta = self.spatial_transform(x, y)
+        wave = self.spectral_transform(x)
+        return alpha, delta, wave
+
+
+IFU Example:
+
+    class IFUWCS(WCS):
+
+        def __init__(self, regions_def, wcs_info, wcs_regions, spec_regions, dist_info):
+             trans = selector.RegionsSelector(mask_shape, regions_def, wcs_info, wcs_regions, spec_regions, dist_info )
+             coord_sys = self.create_coordinate_system(wcs_info)
+             super(IFUWCS, self).__init__(trans, coord_sys)
+
+         def create_coordinate_system(self, wcs_info):
+           """
+           Construts an instance of wcs.CoordinateSystem which in this case is a composite systems of a SkyFrame and SpectralFrame.
+           """
+           return coord_sys