<!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.0 Transitional//EN"
"http://www.w3.org/TR/xhtml1/DTD/xhtml1-transitional.dtd">
<html xmlns="http://www.w3.org/1999/xhtml">
<head>
<meta http-equiv="Content-Type" content="text/html; charset=utf-8" />
<title>Updating the FITS File — SSB TSR 2012-01 documentation</title>
<link rel="stylesheet" href="_static/stsci_sphinx.css" type="text/css" />
<link rel="stylesheet" href="_static/pygments.css" type="text/css" />
<script type="text/javascript">
var DOCUMENTATION_OPTIONS = {
URL_ROOT: '',
VERSION: 'TSR 2012-01',
COLLAPSE_INDEX: false,
FILE_SUFFIX: '.html',
HAS_SOURCE: true
};
</script>
<script type="text/javascript" src="_static/jquery.js"></script>
<script type="text/javascript" src="_static/underscore.js"></script>
<script type="text/javascript" src="_static/doctools.js"></script>
<link rel="top" title="SSB TSR 2012-01 documentation" href="index.html" />
<link rel="next" title="Summary" href="summary.html" />
<link rel="prev" title="Merging Of The Conventions" href="merging.html" />
</head>
<body>
<div class="related">
<h3>Navigation</h3>
<ul>
<li class="right" style="margin-right: 10px">
<a href="genindex.html" title="General Index"
accesskey="I">index</a></li>
<li class="right" >
<a href="summary.html" title="Summary"
accesskey="N">next</a> |</li>
<li class="right" >
<a href="merging.html" title="Merging Of The Conventions"
accesskey="P">previous</a> |</li>
<li><a href="index.html">SSB TSR 2012-01 documentation</a> »</li>
</ul>
</div>
<div class="sphinxsidebar">
<div class="sphinxsidebarwrapper">
<p class="logo"><a href="index.html">
<img class="logo" src="_static/stsci_logo.png" alt="Logo"/>
</a></p>
<h3><a href="index.html">Table Of Contents</a></h3>
<ul>
<li><a class="reference internal" href="#">Updating the FITS File</a><ul>
<li><a class="reference internal" href="#creating-the-d2imarr-extension">Creating the D2IMARR extension</a></li>
<li><a class="reference internal" href="#creating-the-wcsdvarr-extension">Creating the WCSDVARR Extension</a></li>
</ul>
</li>
</ul>
<h4>Previous topic</h4>
<p class="topless"><a href="merging.html"
title="previous chapter">Merging Of The Conventions</a></p>
<h4>Next topic</h4>
<p class="topless"><a href="summary.html"
title="next chapter">Summary</a></p>
<h3>This Page</h3>
<ul class="this-page-menu">
<li><a href="_sources/updating.txt"
rel="nofollow">Show Source</a></li>
</ul>
<div id="searchbox" style="display: none">
<h3>Quick search</h3>
<form class="search" action="search.html" method="get">
<input type="text" name="q" />
<input type="submit" value="Go" />
<input type="hidden" name="check_keywords" value="yes" />
<input type="hidden" name="area" value="default" />
</form>
<p class="searchtip" style="font-size: 90%">
Enter search terms or a module, class or function name.
</p>
</div>
<script type="text/javascript">$('#searchbox').show(0);</script>
</div>
</div>
<div class="document">
<div class="documentwrapper">
<div class="bodywrapper">
<div class="body">
<div class="section" id="updating-the-fits-file">
<h1>Updating the FITS File<a class="headerlink" href="#updating-the-fits-file" title="Permalink to this headline">¶</a></h1>
<p>Updating each science image with the distortion model using this merged
convention requires integrating these new reference files directly into the FITS file.
This update gets performed using the following steps:</p>
<ul class="simple">
<li>determining what reference files should be applied to the science image</li>
<li>read in distortion coefficients from IDCTAB reference file</li>
<li>[for ACS data only] compute time-dependent (TDD) skew terms from model described in IDCTAB file</li>
<li>read in velocity aberration correction factor (VAFACTOR) keyword</li>
<li>apply velocity aberration, and the TDD terms for ACS data as well, to the distortion coefficients<ul>
<li>write time-corrected distortion coefficients as the SIP keywords</li>
</ul>
</li>
<li>[if d2imfile is to be applied] read in D2IMFILE reference table<ul>
<li>update D2IMEXT with name of reference table and AXISCORR keyword with axis to be corrected</li>
<li>append D2IMFILE array as a new <tt class="docutils literal"><span class="pre">D2IMARR</span></tt> extension</li>
</ul>
</li>
<li>[if NPOLFILE is to be applied] divide the NPOLFILE arrays by the linear distortion coefficients<ul>
<li>write out normalized NPOLFILE arrays as new <tt class="docutils literal"><span class="pre">WCSDVARR</span></tt> extensions</li>
<li>update each SCI extension in the science image with the record-value keywords to point to the 2 <tt class="docutils literal"><span class="pre">WCSDVARR</span></tt> extensions (one for X corrections, one for Y corrections) associated with the SCI extension’s chip</li>
</ul>
</li>
</ul>
<p>The STWCS task <strong>updatewcs</strong> applies these steps to update a science image’s FITS file to
incorporate the distortion model components using this convention. It not only modifies
the input reference file data to apply to each image to account for time-dependent and
velocity-aberration corrections as needed, but also creates the new extensions which get
appended to the science image’s FITS file.</p>
<div class="section" id="creating-the-d2imarr-extension">
<h2>Creating the D2IMARR extension<a class="headerlink" href="#creating-the-d2imarr-extension" title="Permalink to this headline">¶</a></h2>
<p>Converting the D2IMFILE reference table into a new <tt class="docutils literal"><span class="pre">D2IMARR</span></tt> FITS image extension involves only a few simple revisions
to the header from D2IMFILE. The header of the <tt class="docutils literal"><span class="pre">D2IMARR</span></tt> extension consists of the following keywords required in order to
properly interpret and apply the data in the extension to the science array:</p>
<ul class="simple">
<li>AXISCORR : Direction in which the det2im correction is applied</li>
<li>EXTNAME : Set to ‘D2IMARR’</li>
<li>EXTVER : Set to 1</li>
<li>NAXIS : Number of axes</li>
<li><tt class="docutils literal"><span class="pre">NAXISj</span></tt> : Size of each axis</li>
<li><tt class="docutils literal"><span class="pre">CRPIXj</span></tt> : Reference point for each axis, set at axis center</li>
<li><tt class="docutils literal"><span class="pre">CRVALj</span></tt> : computed from input science image array center on chip</li>
<li><tt class="docutils literal"><span class="pre">CDELTj</span></tt> : Binning of axis, computed as <span class="math">1/BINAXIS_i</span> keyword from science image</li>
</ul>
<p>These keywords supplement the standard FITS required keywords for an image extension, including such keywords as PCOUNT, GCOUNT, BITPIX, and XTENSION.</p>
<p>The corrections specified in this extension refer to pixel positions on the detector. Since science images can be taken both as subarrays and in binned modes for some instruments, the subarray offset and binning factor get used to compute the translation from science image pixel position into unbinned full-detector pixel positions. Subarray exposures taken by HST detectors record the position of the detector’s origin, (0,0) pixel, as <tt class="docutils literal"><span class="pre">LTVj</span></tt> keywords to identify what pixels on the physical detector were read out for the exposure. The conversion factor from image pixel position to physical detector pixel position of <tt class="docutils literal"><span class="pre">(NAXISj/2</span> <span class="pre">+</span> <span class="pre">LTVj)*BINAXISj</span></tt> gets recorded as the <tt class="docutils literal"><span class="pre">CRVALj</span></tt> keyword value and gets used to correctly apply this correction to the science image.</p>
<p>In addition to the pixel position transformations encoded as the <tt class="docutils literal"><span class="pre">D2IMARR</span></tt> WCS, keywords reporting how the D2IM correction was created get copied into the new <tt class="docutils literal"><span class="pre">D2IMARR</span></tt> image extension header from the primary header of the D2IMFILE. This maintains as much provenance as possible for this correction.</p>
<p>A full listing of the <tt class="docutils literal"><span class="pre">D2IMARR</span></tt> extension for a sample ACS image can be found in <a class="reference internal" href="appendix1.html#d2imarr-header"><em>D2IMARR Header</em></a> in <a class="reference internal" href="appendix1.html#appendix1"><em>Appendix 1 - Sample ACS/WFC Image</em></a>.</p>
</div>
<div class="section" id="creating-the-wcsdvarr-extension">
<h2>Creating the WCSDVARR Extension<a class="headerlink" href="#creating-the-wcsdvarr-extension" title="Permalink to this headline">¶</a></h2>
<p>The NPOLFILE reference file contains at least 2 image extensions, one for the X correction and one for the Y correction for each chip. All these extensions get converted into their own <tt class="docutils literal"><span class="pre">WCSDVARR</span></tt> extension based on the FITS Distortion Paper convention when the NPOLFILE gets incorporated into the science image as another component of the distortion model. Both the array data for each NPOLFILE extension and the corresponding header needs to be modified before it can be written into the science image FITS file as a new <tt class="docutils literal"><span class="pre">WCSDVARR</span></tt> image extension.</p>
<p>The data from the NPOLFILE arrays represent the residuals after accounting for the distortion model, yet this correction gets applied as part of the distortion correction described in <a class="reference internal" href="merging.html#equation4"><em>Equation 4</em></a>. The linear terms of the distortion model need to be removed from the data in each NPOLFILE array in order to avoid applying the linear terms twice when applying the correction to the science data. This gets performed by reading in the linear distortion coefficients directly from the OCX and OCY keywords written out along with the SIP keywords, the multiplying them into the NPOLFILE data values using matrix dot operator to get the final, image specific NPOL correction to be written out as the <tt class="docutils literal"><span class="pre">WCSDVARR</span></tt> extension.</p>
<p>The header of this new <tt class="docutils literal"><span class="pre">WCSDVARR</span></tt> extension provides the translation from science image pixels to NPOLFILE array pixel positions as well as reporting on the provenance of the calibrations as recorded in the original NPOLFILE. The following keywords get computed based on the values directly from the NPOLFILE header:</p>
<ul class="simple">
<li><tt class="docutils literal"><span class="pre">NAXISj</span></tt> : Length of each axis</li>
<li><tt class="docutils literal"><span class="pre">CDELTj</span></tt> : Step size in detector pixels along each axis for the NPOL array</li>
<li><tt class="docutils literal"><span class="pre">CRPIXj</span></tt> : Reference pixel position of NPOL array</li>
<li><tt class="docutils literal"><span class="pre">CRVALj</span></tt> : Reference pixel position of NPOL array relative to science array</li>
<li>EXTNAME : always set to WCSDVARR</li>
<li>EXTVER : identifier reported in the DP.EXTVER record-value keywords in the science array header</li>
</ul>
<p>These keywords supplement the standard FITS required keywords for an image extension, including such keywords as PCOUNT, GCOUNT, BITPIX, and XTENSION. In addition, all keywords from the NPOLFILE primary header after and including ‘FILENAME’ get copied into the header of each WCSDARR extension to preserve the provenance of the calibration.</p>
<p>The look-up tables are saved as separate FITS image extensions in the science files with <tt class="docutils literal"><span class="pre">EXTNAME</span></tt>
set to <tt class="docutils literal"><span class="pre">WCSDVARR</span></tt>. <tt class="docutils literal"><span class="pre">EXTVER</span></tt> is used when more than one look-up table is present in a single science
file. Software which performs coordinate transformation will use bilinear interpolation to get
the value of the distortion at a certain location in the image array. To fully map the image
array to the distortion array the standard WCS keywords <tt class="docutils literal"><span class="pre">CRPIXj</span></tt>, <tt class="docutils literal"><span class="pre">CRVALj</span></tt> and <tt class="docutils literal"><span class="pre">CDELTj</span></tt> are used. The
mapping follows the transformation</p>
<div class="math" id="equation-Equation 6">
<p><span class="eqno">(1)</span><span class="math">p_{j} = s_{j}(p_{j}-r_{j}) + w_{j}</span></p>
</div><p>where <span class="math">r_{j}</span> is the <tt class="docutils literal"><span class="pre">CRPIXj</span></tt> value in the distortion array which
corresponds to the <span class="math">w_{j}</span> value in the image array, recorded as
<tt class="docutils literal"><span class="pre">CRVALj</span></tt> in the <tt class="docutils literal"><span class="pre">WCSDVARR</span></tt> header. Elements in the distortion array are spaced
by <span class="math">s_j</span> pixels in the image array, where <span class="math">s_j</span> is the <tt class="docutils literal"><span class="pre">CDELTj</span></tt>
value in the distortion array header. In general <span class="math">s_j</span> can have
a non-integer value but cannot be zero. However, if the distortion array
was obtained as a subimage of a larger array having a non-integer step size
can produce undesirable results during interpolation. A full listing of the
<tt class="docutils literal"><span class="pre">WCSDVARR</span></tt> extension for a sample ACS image can be found in <a class="reference internal" href="appendix1.html#wcsdvarr-header"><em>WCSDVARR Header</em></a> in <a class="reference internal" href="appendix1.html#appendix1"><em>Appendix 1 - Sample ACS/WFC Image</em></a>.</p>
</div>
</div>
</div>
</div>
</div>
<div class="clearer"></div>
</div>
<div class="related">
<h3>Navigation</h3>
<ul>
<li class="right" style="margin-right: 10px">
<a href="genindex.html" title="General Index"
>index</a></li>
<li class="right" >
<a href="summary.html" title="Summary"
>next</a> |</li>
<li class="right" >
<a href="merging.html" title="Merging Of The Conventions"
>previous</a> |</li>
<li><a href="index.html">SSB TSR 2012-01 documentation</a> »</li>
</ul>
</div>
<div class="footer">
© Copyright 2012, Nadia Dencheva, Warren Hack.
Created using <a href="http://sphinx.pocoo.org/">Sphinx</a> 1.1.3.
</div>
</body>
</html>
