<!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/xhtml;charset=UTF-8"/>
<meta http-equiv="X-UA-Compatible" content="IE=9"/>
<meta name="generator" content="Doxygen 1.8.4"/>
<title>WCSLIB 4.18: Example code, testing and verification</title>
<link href="tabs.css" rel="stylesheet" type="text/css"/>
<script type="text/javascript" src="jquery.js"></script>
<script type="text/javascript" src="dynsections.js"></script>
<link href="doxygen.css" rel="stylesheet" type="text/css" />
</head>
<body>
<div id="top"><!-- do not remove this div, it is closed by doxygen! -->
<div id="titlearea">
<table cellspacing="0" cellpadding="0">
<tbody>
<tr style="height: 56px;">
<td style="padding-left: 0.5em;">
<div id="projectname">WCSLIB 4.18
</div>
</td>
</tr>
</tbody>
</table>
</div>
<!-- end header part -->
<!-- Generated by Doxygen 1.8.4 -->
<div id="navrow1" class="tabs">
<ul class="tablist">
<li><a href="index.html"><span>Main Page</span></a></li>
<li class="current"><a href="pages.html"><span>Related Pages</span></a></li>
<li><a href="annotated.html"><span>Data Structures</span></a></li>
<li><a href="files.html"><span>Files</span></a></li>
</ul>
</div>
<div id="nav-path" class="navpath">
<ul>
<li class="navelem"><a class="el" href="index.html">WCSLIB 4.18 and PGSBOX 4.18</a></li> </ul>
</div>
</div><!-- top -->
<div class="header">
<div class="headertitle">
<div class="title">Example code, testing and verification </div> </div>
</div><!--header-->
<div class="contents">
<div class="textblock"><p>WCSLIB has an extensive test suite that also provides programming templates as well as demonstrations. Test programs, with names that indicate the main WCSLIB routine under test, reside in <code></code>./{C,Fortran}/test and each contains a brief description of its purpose.</p>
<p>The high- and middle-level test programs are more instructive for applications programming, while the low-level tests are vital for verifying the integrity of the mathematical routines.</p>
<ul>
<li>High level: <br/>
<em>twcstab</em> provides an example of high-level applications programming using WCSLIB and <a class="el" href="software.html">CFITSIO</a>. It constructs an input FITS test file, specifically for testing TAB coordinates, partly using <code>wcstab.keyrec</code>, and then extracts the coordinate description from it following the steps outlined in <a class="el" href="wcshdr_8h.html">wcshdr.h</a>. <br/>
<br/>
<em>tpih1</em> and <em>tpih2</em> verify <a class="el" href="wcshdr_8h.html#ac75623ee805ab7d43b0bba684c719a60" title="FITS WCS parser routine for image headers. ">wcspih()</a>. The first prints the contents of the structs returned by <a class="el" href="wcshdr_8h.html#ac75623ee805ab7d43b0bba684c719a60" title="FITS WCS parser routine for image headers. ">wcspih()</a> using <a class="el" href="wcs_8h.html#ab9aeb8cf1afb1bfb22e989580d90fca8" title="Print routine for the wcsprm struct. ">wcsprt()</a> and the second uses <em>cpgsbox()</em> to draw coordinate graticules. Input for these comes from a FITS WCS test header implemented as a list of keyrecords, <code>wcs.keyrec</code>, one keyrecord per line, together with a program, <em>tofits</em>, that compiles these into a valid FITS file. <br/>
<br/>
<em>tfitshdr</em> also uses <code>wcs.keyrec</code> to test the generic FITS header parsing routine. <br/>
<br/>
<em>twcsfix</em> sets up a wcsprm struct containing various non-standard constructs and then invokes <a class="el" href="wcsfix_8h.html#a89e1b5b4d2fa89af03f5d1143352b05f" title="Translate a non-standard WCS struct. ">wcsfix()</a> to translate them all to standard usage.</li>
<li>Middle level: <br/>
<em>twcs</em> tests closure of <a class="el" href="wcs_8h.html#a60673d05a3513659ac848a9cb3d0cb07" title="World-to-pixel transformation. ">wcss2p()</a> and <a class="el" href="wcs_8h.html#a27d3dd209db3e76cf4c50f48c01ba986" title="Pixel-to-world transformation. ">wcsp2s()</a> for a number of selected projections. <em>twcsmix</em> verifies <a class="el" href="wcs_8h.html#af3f00b876c8212d43f32a51feeadaa81" title="Hybrid coordinate transformation. ">wcsmix()</a> on the <img class="formulaInl" alt="$1^\circ$" src="form_20.png"/> grid of celestial longitude and latitude for a number of selected projections. It plots a test grid for each projection and indicates the location of successful and failed solutions. <em>twcssub</em> tests the extraction of a coordinate description for a subimage from a wcsprm struct by <a class="el" href="wcs_8h.html#a864c99fef9f3eee29085ce42d0ee0d64" title="Subimage extraction routine for the wcsprm struct. ">wcssub()</a>. <br/>
<br/>
<em>tunits</em> tests <a class="el" href="wcsunits_8h.html#a25ba0f0129e88c6e7c74d4562cf796cd" title="Translation of non-standard unit specifications. ">wcsutrne()</a>, <a class="el" href="wcsunits_8h.html#a47aa4e0a54f11d7ed5146c00906a3984" title="FITS units specification conversion. ">wcsunitse()</a> and <a class="el" href="wcsunits_8h.html#a6c5f3165e687f60176b7f21fdb42fa1c" title="FITS units specification parser. ">wcsulexe()</a>, the units specification translator, converter and parser, either interactively or using a list of units specifications contained in units_test.</li>
<li>Low level: <br/>
<em>tlin</em>, <em>tlog</em>, <em>tprj1</em>, <em>tsph</em>, <em>tspc</em>, <em>tspc</em>, and ttab1 test "closure" of the respective routines. Closure tests apply the forward and reverse transformations in sequence and compare the result with the original value. Ideally, the result should agree exactly, but because of floating point rounding errors there is usually a small discrepancy so it is only required to agree within a "closure tolerance". <br/>
<br/>
<em>tprj1</em> tests for closure separately for longitude and latitude except at the poles where it only tests for closure in latitude. Note that closure in longitude does not deal with angular displacements on the sky. This is appropriate for many projections such as the cylindricals where circumpolar parallels are projected at the same length as the equator. On the other hand, <em>tsph</em> does test for closure in angular displacement. <br/>
<br/>
The tolerance for reporting closure discrepancies is set at <img class="formulaInl" alt="$10^{-10}$" src="form_21.png"/> degree for most projections; this is slightly less than 3 microarcsec. The worst case closure figure is reported for each projection and this is usually better than the reporting tolerance by several orders of magnitude. <em>tprj1</em> and <em>tsph</em> test closure at all points on the <img class="formulaInl" alt="$1^\circ$" src="form_20.png"/> grid of native longitude and latitude and to within <img class="formulaInl" alt="$5^\circ$" src="form_22.png"/> of any latitude of divergence for those projections that cannot represent the full sphere. Closure is also tested at a sequence of points close to the reference point (<em>tprj1</em>) or pole (<em>tsph</em>). <br/>
<br/>
Closure has been verified at all test points for SUN workstations. However, non-closure may be observed for other machines near native latitude <img class="formulaInl" alt="$-90^\circ$" src="form_23.png"/> for the zenithal, cylindrical and conic equal area projections (<code><b>ZEA</b></code>, <code><b>CEA</b></code> and <code><b>COE</b></code>), and near divergent latitudes of projections such as the azimuthal perspective and stereographic projections (<code><b>AZP</b></code> and <code><b>STG</b></code>). Rounding errors may also carry points between faces of the quad-cube projections (<code><b>CSC</b></code>, <code><b>QSC</b></code>, and <code><b>TSC</b></code>). Although such excursions may produce long lists of non-closure points, this is not necessarily indicative of a fundamental problem. <br/>
<br/>
Note that the inverse of the COBE quad-qube projection (<code><b>CSC</b></code>) is a polynomial approximation and its closure tolerance is intrinsically poor. <br/>
<br/>
Although tests for closure help to verify the internal consistency of the routines they do not verify them in an absolute sense. This is partly addressed by <em>tcel1</em>, <em>tcel2</em>, <em>tprj2</em>, <em>ttab2</em> and <em>ttab3</em> which plot graticules for visual inspection of scaling, orientation, and other macroscopic characteristics of the projections. </li>
</ul>
</div></div><!-- contents -->
<!-- start footer part -->
<hr class="footer"/><address class="footer"><small>
Generated on Sat Jul 13 2013 20:00:27 for WCSLIB 4.18 by  <a href="http://www.doxygen.org/index.html">
<img class="footer" src="doxygen.png" alt="doxygen"/>
</a> 1.8.4
</small></address>
</body>
</html>
