Generalized WCS

generalized_wcs/coordinate_systems_api.md

@@ -0,0 +1,140 @@
+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 very high level description of coordinate system classes.
+
+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
+        ----------
+        system : string
+            type of the frame
+        num_axes : int
+        axes_names : list of strings
+        units : list of units
+        """
+        def __init__(self, system, num_axes, axes_names=None, units=None):
+            """ Initialize a frame"""
+
+        def transform_to(self, other):
+            """
+            Transform from the current reference system to other if
+            the system attribute of the two matches
+            """
+
+Four basic frames are defined as subclasses of `CoordinateFrame`:
+
+    class TimeFrame(CoordinateFrame):
+        """
+        Time Frame
+
+        Parameters
+        ----------
+        time_scale : time scale
+
+        reference_position :an instance of ReferencePosition
+
+        reference_direction : (optional)
+        """
+
+        standard_time_scale = ["TT", "TDT", "ET", "TAI", "IAT",
+                               "UTC", "GPS", "TDB", "TEB", "TCG",
+                               "TCB", "LST"]
+
+        def __init__(self, time_scale, reference_position, reference_direction=None, units="s"):
+            assert time_scale in standard_time_scale, "Unrecognized time scale"
+
+            super("Time", numaxes=1, axes_names=['time'], units=[units])
+            self._time_scale =time_scale
+            self._reference_position = reference_position
+
+    class SkyFrame(CoordinateFrame):
+        """
+        Space Frame Representation
+        """
+        standart_ref_frame = ["FK4", "FK5", "ICRS", '...']
+
+        def __init__(self, reference_frame, reference_position, obstime, equinox=None,
+                     projection="", axes_names=["", ""], units=["",""], offset_center=None):
+
+            super(SkyFrame, self).__init__('Space', num_axes=2, axes_names=axes_names, units=units)
+            self._equinox = equinox
+            self._projection = projection
+            self._offset_center = offset_center
+            self._reference_frame = reference_frame
+            self._reference_position = reference_position
+
+    class SpectralFrame(CoordinateFrame):
+        """
+        Represents Spectral Frame
+
+        Parameters
+        ----------
+        reference_frame : string
+            one of spectral_ref_frame
+        reference_position : an instance of ReferencePosition
+
+        """
+        spectral_ref_frame = ["WAVE", "FREQ", "ENER", "WAVEN",  "AWAV", "VRAD",
+                            "VOPT", "ZOPT", "VELO", "BETA"]
+        def __init__(self, reference_frame, reference_pos, date_obs, rest_freq=None, rest_wave=None,
+                              units=""):
+
+            super(SpectralFrame, self).__init__('Spec', num_axes=1, axes_names=[reference_frame], units=[""])
+            self._reference_frame = reference_frame
+            self._reference_position = reference_position
+            self.rest_freq = rest_freq
+            self.rest_wave = rest_wave
+            self.dateobs = dateobs
+
+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
+
+        def _validate_ref_pos(self, frame):
+            """
+            validates that the reference position is allowed for the frame
+            """
+            return True

generalized_wcs/region_api.md

@@ -0,0 +1,163 @@
+Regions
+-------
+
+This file describes the region api.
+
+Regions are necessary to describe multiple WCSs in an observation,
+for example IFUs. This proposal follows the Region definitions in the
+[STC document](http://www.ivoa.net/documents/PR/STC/STC-20050315.html).
+
+* Note : This has some overlap with the aperture definitions in photutils.
+Should we consider merging this work?
+
+A Region is defined in the context of a coordinate system. Subclasses should
+define `__contains__` method and a `scan` method.
+
+    class Region(object):
+        """
+        Base class for regions.
+
+        Parameters
+        -------------
+        rid : int or string
+            region ID
+        coordinate_system : astropy.wcs.CoordinateSystem instance or a string
+            in the context of WCS this would be an instance of wcs.CoordinateSysem
+        """
+        def __init__(self, rid, coordinate_system):
+            self._coordinate_system = coordinate_system
+            self._rid = rid
+
+        def __contains__(self, x, y):
+            """
+            Determines if a pixel is within a region.
+
+            Parameters
+            ----------
+            x,y : float
+                x , y values of a pixel
+
+            Returns
+            -------
+                True or False
+
+            Subclasses must define this method.
+            """
+
+        def scan(self, mask):
+            """
+            Sets mask values to region id for all pixels within the region.
+            Subclasses must define this method.
+
+            Parameters
+            ----------
+            mask : ndarray
+                a byte array with the shape of the observation to be used as a mask
+
+            Returns
+            -------
+            mask : array where the value of the elements is the region ID or 0 (for
+                pixels which are not included in any region).
+            """
+
+An example of a Polygon region class
+
+    class Polygon(Region):
+        """
+        Represents a 2D polygon region with multiple vertices
+
+        Parameters
+        ----------
+        rid : string
+             polygon id
+        vertices : list of (x,y) tuples or lists
+             The list is ordered in such a way that when traversed in a
+             counterclockwise direction, the enclosed area is the polygon.
+             The last vertex must coincide with the first vertex, minimum
+             4 vertices are needed to define a triangle
+        coord_system : string
+            coordinate system
+
+        """
+        def __init__(self, rid, vertices, coord_system="Cartesian"):
+            self._rid = rid
+            self._vertices = vertices
+            self.coord_system = coord_system
+
+        def __contains__(self, x, y):
+
+        def scan(mask):
+
+
+
+
+`create_regions_mask` is a function which creates a byte array with regions labels
+
+    def create_regions_mask(mask_shape, regions_def, regions_schema=None):
+        """
+        Given a JSON file with regions definitions and a schema, this function
+
+        - creates a byte array of shape mask_shape
+        - reads in and validates the regions definitions
+        - scans each region and marks each pixel in the output array with the region ID
+        - returns the mask
+
+        Given 2 regions on a detector of size 10x10 px, the mask may look like this:
+
+        0 0 0 0 0 0 0 0 0 0
+        1 1 1 1 1 1 1 1 1 1
+        1 1 1 1 1 1 1 1 1 1
+        1 1 1 1 1 1 1 1 1 1
+        0 0 0 0 0 0 0 0 0 0
+        0 0 0 0 0 0 0 0 2 2
+        2 2 2 2 2 2 2 2 2 2
+        2 2 2 2 2 2 2 2 2 2
+        2 2 0 0 0 0 2 2 2 2
+        2 0 0 0 0 0 0 0 2 2
+
+        """
+
+JSON is used for regions definitions. The schema for a Set of Regions and a Polygon region is
+defined below. It will be expanded with other kinds of regions.
+
+    {"$schema": "http://json-schema.org/draft-03/schema#",
+    "title": "A set of Regions",
+    "type": "array",
+    "items":{
+    "type": "object",
+    "title": "Polygon Region",
+    "description": "A representation of a rectangular region on a detector",
+    "properties": {
+        "id": {
+            "type": ["integer", "string"],
+            "required": true,
+            "unique": true
+        },
+        "coordinate_system": {
+            "type": "object",
+            "properties":{
+                "name": {
+                    "type": "string",
+                    "enum": ["Cartesian", "Sky"]
+                }
+            },
+            "required": true
+        },
+        "vertices": {
+            "type": "array",
+            "description": "Array of vertices describing the Polygon",
+            "items": {
+                "type": "array",
+                "description": "Pairs of (x, y) coordinates, representing a vertex",
+                "items": {
+                    "type": "integer"
+                },
+                "minItems": 2,
+                "maxItems": 2
+            },
+            "minItems": 4,
+            "required": true
+        }
+       }
+      }
+    }

generalized_wcs/selector.md

@@ -0,0 +1,43 @@
+SelectorModel
+-------------
+
+The `SelectorModel` provides mappings between a transform and some other quantity.
+The obvious case is an IFU detector where each region maps to a different transform.
+However, the goal is for this to be general and allow for other use cases, for example
+multiple orders, slitless spectroscopy.
+
+For this reason the base class defines only the mapping and additional functionality
+is left for specific classes.
+
+The `__call__` method is defined by subclasses and implements the real work of
+figuring out how to match input coordinates with a transform.
+
+    class SelectorModel(object):
+        """
+        Parameters
+        ----------
+        labels : a list of strings or objects
+        transforms : a list of transforms
+            transforms match labels
+        """
+        def __init__(self, labels, transforms):
+            self._selector = dict(labels, transforms)
+
+        def __call__(self, label):
+           raise NotImplementedError
+
+An example of a selector of regions of an IFU is below. It has an additional attribute
+`regions_map` which is a byte array with region labels. The actual definitions of the
+regions are read in from a JSON file, see the [Region API](https://github.com/nden/astropy-api/blob/generalized_wcs/generalized_wcs/region_api.md)
+
+    class RegionsSelector(SelectorModel):
+        def __init__(self, labels, transforms, regions):
+            super(RegionsSelector, self).__init__(labels, transforms)
+            #create_regions_mask_from_json is defined in the regions API.
+            self.regions_map = regions.create_regions_map_from_json(mask_shape, regions, schema)
+
+        def __call__(self, x, y):
+            """
+            Transforms x and y using self._selector and self.regions_map
+
+            """