RCAL-318: Update the reference file document for reftype "distortion"

CHANGES.rst

@@ -16,6 +16,8 @@ Documentation
 - Updated documentation for the photom step and removed the area reference
   documentation. [#488]
 
+- Added documentation for Distortion reference files. [#493]
+
 
 linearity
 ---------

docs/roman/references_general/distortion_reffile.rst

@@ -0,0 +1,43 @@
+:orphan:
+
+.. _distortion_reffile:
+
+DISTORTION Reference File
+-------------------------
+
+:REFTYPE: DISTORTION
+:Data model: `~roman_datamodels.datamodels.DistortionRefModel`
+
+The distortion reference file contains a combination of astropy models,
+representing the transform from detector to the telescope V2, V3 system.
+The following convention was adopted:
+
+- The output in the V2, V3 system.
+- The input x and y are 0-based coordinates in the DMS system.
+- The center of the first pixel is (0, 0), so the first pixel goes from -0.5 to 0.5.
+- The origin of the transform is taken to be (0, 0).
+  Note, that while a different origin can be used for some transforms the relevant
+  offset should first be prepended to the distortion transform to account for the change
+  in origin of the coordinate frame.  
+
+Internally the WCS pipeline works with 0-based coordinates.
+
+.. include:: ../references_general/distortion_selection.inc
+
+.. include:: ../includes/standard_keywords.inc
+
+Reference File Format
++++++++++++++++++++++
+DISTORTION reference files are ASDF format, and contain an astropy model object.
+The format and content of the file is as follows
+(see `~roman_datamodels.datamodels.DistortionRefModel`):
+
+==================================  ========================
+Data                                 Data type
+==================================  ========================
+coordinate_distortion_transform      astropy.modeling.Model   
+==================================  ========================
+
+The ASDF file contains a single astropy model object.
+
+:model: Transform from detector to an intermediate frame (instrument dependent).

docs/roman/references_general/distortion_selection.inc

@@ -0,0 +1,13 @@
+.. _distortion_selectors:
+
+Reference Selection Keyword Attributes for DISTORTION
++++++++++++++++++++++++++++++++++++++++++++++++++++++
+CRDS selects appropriate DISTORTION reference files based on the following keyword attributes.
+DISTORTION is not applicable for instruments not in the table.
+
+========== ===================================================
+Instrument  Keyword Attributes                                                                                           
+========== ===================================================
+WFI	    instrument, detector, optical_element, date, time
+========== ===================================================
+

docs/roman/references_general/references_general.rst

@@ -43,6 +43,7 @@ documentation on each reference file.
 +---------------------------------------------+--------------------------------------------------+
 | Pipeline Step                               | Reference File Type (reftype)                    |
 +=============================================+==================================================+
+| :ref:`assign_wcs <assign_wcs_step>`         | :ref:`DISTORTION <distortion_reffile>`           |
 +---------------------------------------------+--------------------------------------------------+
 | :ref:`dark_current <dark_current_step>`     | :ref:`DARK <dark_reffile>`                       |
 +---------------------------------------------+--------------------------------------------------+
@@ -71,6 +72,8 @@ documentation on each reference file.
 +==================================================+=============================================+
 | :ref:`DARK <dark_reffile>`                       | :ref:`dark_current <dark_current_step>`     |
 +--------------------------------------------------+---------------------------------------------+
+| :ref:`DISTORTION <distortion_reffile>`           | :ref:`assign_wcs <assign_wcs_step>`         |
++--------------------------------------------------+---------------------------------------------+
 | :ref:`FLAT <flat_reffile>`                       | :ref:`flatfield <flatfield_step>`           |
 +--------------------------------------------------+---------------------------------------------+
 | :ref:`GAIN <gain_reffile>`                       | :ref:`jump_detection <jump_step>`           |