Merge pull request #48 from spacetelescope/gwcs-improvements

Gwcs improvements

schemas/stsci.edu/asdf/0.1.0/transform/compose.yaml

@@ -0,0 +1,42 @@
+%YAML 1.1
+---
+$schema: "http://stsci.edu/schemas/yaml-schema/draft-01"
+id: "http://stsci.edu/schemas/asdf/0.1.0/transform/compose"
+tag: "tag:stsci.edu:asdf/0.1.0/transform/compose"
+title: >
+  Perform a list of subtransforms in series.
+
+description: |
+  The output of each subtransform is fed into the input of the next
+  subtransform.
+
+  The number of output dimensions of each subtransform must be equal
+  to the number of input dimensions of the next subtransform in list.
+  To reorder or add/drop axes, insert ``remap_axes`` transforms in the
+  subtransform list.
+
+  Invertability: All ASDF tools are required to be able to compute the
+  analytic inverse of this transform, by reversing the list of
+  transforms and applying the inverse of each.
+
+examples:
+  -
+    - A series of transforms
+    - |
+      !transform/compose
+        forward:
+          - !transform/generic
+            n_inputs: 1
+            n_outputs: 2
+          - !transform/generic
+            n_inputs: 2
+            n_outputs: 1
+
+allOf:
+  - $ref: transform
+  - properties:
+      forward:
+        type: array
+        items:
+          $ref: transform
+    required: [forward]

schemas/stsci.edu/asdf/0.1.0/transform/concatenate.yaml

@@ -4,27 +4,51 @@ $schema: "http://stsci.edu/schemas/yaml-schema/draft-01"
 id: "http://stsci.edu/schemas/asdf/0.1.0/transform/concatenate"
 tag: "tag:stsci.edu:asdf/0.1.0/transform/concatenate"
 title: >
-  Perform a list of subtransforms in series.
+  Send axes to different subtransforms.
 
 description: |
-  The output of each subtransform is fed into the input of the next
-  subtransform.
+  Transforms a set of separable inputs by splitting the axes apart,
+  sending them through the given subtransforms in parallel, and
+  finally concatenating the subtransform output axes back together.
 
-  The number of output dimensions of each subtransform must be equal
-  to the number of input dimensions of the next subtransform in list.
-  To reorder or add/drop axes, insert ``remap_axes`` transforms in the
-  subtransform list.
+  The input axes are assigned to each subtransform in order.  If the
+  number of input axes is unequal to the sum of the number of input
+  axes of all of the subtransforms, that is considered an error case.
 
-  Invertability: All ASDF tools are required to be able to compute the
-  analytic inverse of this transform, by reversing the list of
-  transforms and applying the inverse of each.
+  The output axes from each subtransform are appended together to make
+  up the resulting output axes.
+
+  For example, given 5 input axes, and 3 subtransforms with the
+  following orders:
+
+  - transform A: 2 in -> 2 out
+  - transform B: 1 in -> 2 out
+  - transform C: 2 in -> 1 out
+
+  The transform is performed as follows::
+
+    :    i0    i1       i2       i3    i4
+    :    |     |        |        |     |
+    :  +---------+ +---------+ +----------+
+    :  |    A    | |    B    | |    C     |
+    :  +---------+ +---------+ +----------+
+    :    |     |     |     |        |
+    :    o0    o1    o2    o3       o4
 
+  If reordering of the input or output axes is required, use in series
+  with the ``remap_axes`` transform.
+
+  Invertability: All ASDF tools are required to be able to compute the
+  analytic inverse of this transform.
 examples:
   -
-    - A series of transforms
+    - The example in the description
     - |
       !transform/concatenate
         forward:
+          - !transform/generic
+            n_inputs: 2
+            n_outputs: 2
           - !transform/generic
             n_inputs: 1
             n_outputs: 2

schemas/stsci.edu/asdf/0.1.0/transform/constant.yaml

@@ -0,0 +1,18 @@
+%YAML 1.1
+---
+$schema: "http://stsci.edu/schemas/yaml-schema/draft-01"
+id: "http://stsci.edu/schemas/asdf/0.1.0/transform/constant"
+tag: "tag:stsci.edu:asdf/0.1.0/transform/constant"
+title: >
+  A transform that takes no inputs and always outputs a constant
+  value.
+description: |
+  Invertability: All ASDF tools are required to be able to compute the
+  analytic inverse of this transform, which always outputs zero values.
+allOf:
+  - $ref: transform
+  - type: object
+    properties:
+      value:
+        type: number
+    required: [value]

schemas/stsci.edu/asdf/0.1.0/transform/remap_axes.yaml

@@ -49,6 +49,20 @@ examples:
         !transform/remap_axes
           mapping: [0, 1, !core/constant 42]
 
+  -
+    - |
+        The above example is equivalent to the following, and ASDF
+        implementations are free to normalize it thusly:
+    - |
+        !transform/concatenate
+          forward:
+            - !transform/remap_axes
+              mapping: [0]
+            - !transform/remap_axes
+              mapping: [1]
+            - !transform/constant
+              value: 42
+
   -
     - Here we have 3 input axes, but we are explicitly dropping the last one
     - |

schemas/stsci.edu/asdf/0.1.0/transform/transform.yaml

@@ -12,6 +12,10 @@ description: >
 anyOf:
   - type: object
     properties:
+      name:
+        description: |
+          A user-friendly name for the transform, to give it extra
+          meaning.
       inverse:
         description: |
           Explicitly sets the inverse transform of this transform.

source/schemas/transform.rst

@@ -25,9 +25,9 @@ Compound transformations
 .. toctree::
    :maxdepth: 1
 
-   stsci.edu/asdf/0.1.0/transform/remap_axes.rst
-   stsci.edu/asdf/0.1.0/transform/join.rst
+   stsci.edu/asdf/0.1.0/transform/compose.rst
    stsci.edu/asdf/0.1.0/transform/concatenate.rst
+   stsci.edu/asdf/0.1.0/transform/remap_axes.rst
 
 Arithmetic operations
 ---------------------