wcslib (8.2.2)
<!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.0 Transitional//EN" "https://www.w3.org/TR/xhtml1/DTD/xhtml1-transitional.dtd">
<html xmlns="http://www.w3.org/1999/xhtml" lang="en-US">
<head>
<meta http-equiv="Content-Type" content="text/xhtml;charset=UTF-8"/>
<meta http-equiv="X-UA-Compatible" content="IE=11"/>
<meta name="generator" content="Doxygen 1.9.8"/>
<meta name="viewport" content="width=device-width, initial-scale=1"/>
<title>WCSLIB: dis.h File Reference</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="search/search.css" rel="stylesheet" type="text/css"/>
<script type="text/javascript" src="search/searchdata.js"></script>
<script type="text/javascript" src="search/search.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 id="projectrow">
<td id="projectalign">
<div id="projectname">WCSLIB<span id="projectnumber"> 8.2.2</span>
</div>
</td>
</tr>
</tbody>
</table>
</div>
<!-- end header part -->
<!-- Generated by Doxygen 1.9.8 -->
<script type="text/javascript">
/* @license magnet:?xt=urn:btih:d3d9a9a6595521f9666a5e94cc830dab83b65699&dn=expat.txt MIT */
var searchBox = new SearchBox("searchBox", "search/",'.html');
/* @license-end */
</script>
<script type="text/javascript" src="menudata.js"></script>
<script type="text/javascript" src="menu.js"></script>
<script type="text/javascript">
/* @license magnet:?xt=urn:btih:d3d9a9a6595521f9666a5e94cc830dab83b65699&dn=expat.txt MIT */
$(function() {
initMenu('',true,false,'search.php','Search');
$(document).ready(function() { init_search(); });
});
/* @license-end */
</script>
<div id="main-nav"></div>
<!-- window showing the filter options -->
<div id="MSearchSelectWindow"
onmouseover="return searchBox.OnSearchSelectShow()"
onmouseout="return searchBox.OnSearchSelectHide()"
onkeydown="return searchBox.OnSearchSelectKey(event)">
</div>
<!-- iframe showing the search results (closed by default) -->
<div id="MSearchResultsWindow">
<div id="MSearchResults">
<div class="SRPage">
<div id="SRIndex">
<div id="SRResults"></div>
<div class="SRStatus" id="Loading">Loading...</div>
<div class="SRStatus" id="Searching">Searching...</div>
<div class="SRStatus" id="NoMatches">No Matches</div>
</div>
</div>
</div>
</div>
<div id="nav-path" class="navpath">
<ul>
<li class="navelem"><a class="el" href="dir_af99bb3c152a306abd27951285ad1127.html">C</a></li> </ul>
</div>
</div><!-- top -->
<div class="header">
<div class="summary">
<a href="#nested-classes">Data Structures</a> |
<a href="#define-members">Macros</a> |
<a href="#enum-members">Enumerations</a> |
<a href="#func-members">Functions</a> |
<a href="#var-members">Variables</a> </div>
<div class="headertitle"><div class="title">dis.h File Reference</div></div>
</div><!--header-->
<div class="contents">
<p><a href="dis_8h_source.html">Go to the source code of this file.</a></p>
<table class="memberdecls">
<tr class="heading"><td colspan="2"><h2 class="groupheader"><a id="nested-classes" name="nested-classes"></a>
Data Structures</h2></td></tr>
<tr class="memitem:"><td class="memItemLeft" align="right" valign="top">struct  </td><td class="memItemRight" valign="bottom"><a class="el" href="structdpkey.html">dpkey</a></td></tr>
<tr class="memdesc:"><td class="mdescLeft"> </td><td class="mdescRight">Store for <code><b>DP</b>ja</code> and <code><b>DQ</b>ia</code> keyvalues. <a href="structdpkey.html#details">More...</a><br /></td></tr>
<tr class="separator:"><td class="memSeparator" colspan="2"> </td></tr>
<tr class="memitem:"><td class="memItemLeft" align="right" valign="top">struct  </td><td class="memItemRight" valign="bottom"><a class="el" href="structdisprm.html">disprm</a></td></tr>
<tr class="memdesc:"><td class="mdescLeft"> </td><td class="mdescRight">Distortion parameters. <a href="structdisprm.html#details">More...</a><br /></td></tr>
<tr class="separator:"><td class="memSeparator" colspan="2"> </td></tr>
</table><table class="memberdecls">
<tr class="heading"><td colspan="2"><h2 class="groupheader"><a id="define-members" name="define-members"></a>
Macros</h2></td></tr>
<tr class="memitem:a23068602f42552a4257462b2875d8c51" id="r_a23068602f42552a4257462b2875d8c51"><td class="memItemLeft" align="right" valign="top">#define </td><td class="memItemRight" valign="bottom"><a class="el" href="dis_8h.html#a23068602f42552a4257462b2875d8c51">DISP2X_ARGS</a></td></tr>
<tr class="separator:a23068602f42552a4257462b2875d8c51"><td class="memSeparator" colspan="2"> </td></tr>
<tr class="memitem:ac593cd79fb7f89b1c7395d0ecf2f7876" id="r_ac593cd79fb7f89b1c7395d0ecf2f7876"><td class="memItemLeft" align="right" valign="top">#define </td><td class="memItemRight" valign="bottom"><a class="el" href="dis_8h.html#ac593cd79fb7f89b1c7395d0ecf2f7876">DISX2P_ARGS</a></td></tr>
<tr class="separator:ac593cd79fb7f89b1c7395d0ecf2f7876"><td class="memSeparator" colspan="2"> </td></tr>
<tr class="memitem:a10a6a35bdc567bcbedf1ec10c4aa94c3" id="r_a10a6a35bdc567bcbedf1ec10c4aa94c3"><td class="memItemLeft" align="right" valign="top">#define </td><td class="memItemRight" valign="bottom"><a class="el" href="dis_8h.html#a10a6a35bdc567bcbedf1ec10c4aa94c3">DPLEN</a>   (sizeof(struct <a class="el" href="structdpkey.html">dpkey</a>)/sizeof(int))</td></tr>
<tr class="separator:a10a6a35bdc567bcbedf1ec10c4aa94c3"><td class="memSeparator" colspan="2"> </td></tr>
<tr class="memitem:a5df41117cb392fc0c5d051002b441aa9" id="r_a5df41117cb392fc0c5d051002b441aa9"><td class="memItemLeft" align="right" valign="top">#define </td><td class="memItemRight" valign="bottom"><a class="el" href="dis_8h.html#a5df41117cb392fc0c5d051002b441aa9">DISLEN</a>   (sizeof(struct <a class="el" href="structdisprm.html">disprm</a>)/sizeof(int))</td></tr>
<tr class="separator:a5df41117cb392fc0c5d051002b441aa9"><td class="memSeparator" colspan="2"> </td></tr>
</table><table class="memberdecls">
<tr class="heading"><td colspan="2"><h2 class="groupheader"><a id="enum-members" name="enum-members"></a>
Enumerations</h2></td></tr>
<tr class="memitem:a27ab258e601dcfa4d184a35edbc590fd" id="r_a27ab258e601dcfa4d184a35edbc590fd"><td class="memItemLeft" align="right" valign="top">enum  </td><td class="memItemRight" valign="bottom"><a class="el" href="dis_8h.html#a27ab258e601dcfa4d184a35edbc590fd">dis_errmsg_enum</a> { <br />
  <a class="el" href="dis_8h.html#a27ab258e601dcfa4d184a35edbc590fdaeaef8bb1725ea601f43900897ee144a8">DISERR_SUCCESS</a> = 0
, <a class="el" href="dis_8h.html#a27ab258e601dcfa4d184a35edbc590fda8c5a7d847d62520f972e51435d4d0d46">DISERR_NULL_POINTER</a> = 1
, <a class="el" href="dis_8h.html#a27ab258e601dcfa4d184a35edbc590fda7298d8c404456ac8c3a5365f2f266d80">DISERR_MEMORY</a> = 2
, <a class="el" href="dis_8h.html#a27ab258e601dcfa4d184a35edbc590fdace3a5f769a3b8966f980f1279e2f08b0">DISERR_BAD_PARAM</a> = 3
, <br />
  <a class="el" href="dis_8h.html#a27ab258e601dcfa4d184a35edbc590fdadbabbc4a9fe6441177efcd050b4cc579">DISERR_DISTORT</a> = 4
, <a class="el" href="dis_8h.html#a27ab258e601dcfa4d184a35edbc590fdabe0645cb8d4bfc0f496aa84336ca492a">DISERR_DEDISTORT</a> = 5
<br />
}</td></tr>
<tr class="separator:a27ab258e601dcfa4d184a35edbc590fd"><td class="memSeparator" colspan="2"> </td></tr>
</table><table class="memberdecls">
<tr class="heading"><td colspan="2"><h2 class="groupheader"><a id="func-members" name="func-members"></a>
Functions</h2></td></tr>
<tr class="memitem:aa5486b870327544f7423ad2751fb4120" id="r_aa5486b870327544f7423ad2751fb4120"><td class="memItemLeft" align="right" valign="top">int </td><td class="memItemRight" valign="bottom"><a class="el" href="dis_8h.html#aa5486b870327544f7423ad2751fb4120">disndp</a> (int n)</td></tr>
<tr class="memdesc:aa5486b870327544f7423ad2751fb4120"><td class="mdescLeft"> </td><td class="mdescRight">Memory allocation for <code><b>DP</b>ja</code> and <code><b>DQ</b>ia</code>. <br /></td></tr>
<tr class="separator:aa5486b870327544f7423ad2751fb4120"><td class="memSeparator" colspan="2"> </td></tr>
<tr class="memitem:a44e73dd6831a2eb25f09d316d175875f" id="r_a44e73dd6831a2eb25f09d316d175875f"><td class="memItemLeft" align="right" valign="top">int </td><td class="memItemRight" valign="bottom"><a class="el" href="dis_8h.html#a44e73dd6831a2eb25f09d316d175875f">dpfill</a> (struct <a class="el" href="structdpkey.html">dpkey</a> *dp, const char *keyword, const char *field, int j, int type, int i, double f)</td></tr>
<tr class="memdesc:a44e73dd6831a2eb25f09d316d175875f"><td class="mdescLeft"> </td><td class="mdescRight">Fill the contents of a dpkey struct. <br /></td></tr>
<tr class="separator:a44e73dd6831a2eb25f09d316d175875f"><td class="memSeparator" colspan="2"> </td></tr>
<tr class="memitem:a5fab5cff95ef5e505314a6fb67325074" id="r_a5fab5cff95ef5e505314a6fb67325074"><td class="memItemLeft" align="right" valign="top">int </td><td class="memItemRight" valign="bottom"><a class="el" href="dis_8h.html#a5fab5cff95ef5e505314a6fb67325074">dpkeyi</a> (const struct <a class="el" href="structdpkey.html">dpkey</a> *dp)</td></tr>
<tr class="memdesc:a5fab5cff95ef5e505314a6fb67325074"><td class="mdescLeft"> </td><td class="mdescRight">Get the data value in a dpkey struct as int. <br /></td></tr>
<tr class="separator:a5fab5cff95ef5e505314a6fb67325074"><td class="memSeparator" colspan="2"> </td></tr>
<tr class="memitem:a2181881844241449382477a5c2723082" id="r_a2181881844241449382477a5c2723082"><td class="memItemLeft" align="right" valign="top">double </td><td class="memItemRight" valign="bottom"><a class="el" href="dis_8h.html#a2181881844241449382477a5c2723082">dpkeyd</a> (const struct <a class="el" href="structdpkey.html">dpkey</a> *dp)</td></tr>
<tr class="memdesc:a2181881844241449382477a5c2723082"><td class="mdescLeft"> </td><td class="mdescRight">Get the data value in a dpkey struct as double. <br /></td></tr>
<tr class="separator:a2181881844241449382477a5c2723082"><td class="memSeparator" colspan="2"> </td></tr>
<tr class="memitem:a8896e2a5330e55cd85da4a28ed6ee463" id="r_a8896e2a5330e55cd85da4a28ed6ee463"><td class="memItemLeft" align="right" valign="top">int </td><td class="memItemRight" valign="bottom"><a class="el" href="dis_8h.html#a8896e2a5330e55cd85da4a28ed6ee463">disini</a> (int alloc, int naxis, struct <a class="el" href="structdisprm.html">disprm</a> *dis)</td></tr>
<tr class="memdesc:a8896e2a5330e55cd85da4a28ed6ee463"><td class="mdescLeft"> </td><td class="mdescRight">Default constructor for the <a class="el" href="structdisprm.html" title="Distortion parameters.">disprm</a> struct. <br /></td></tr>
<tr class="separator:a8896e2a5330e55cd85da4a28ed6ee463"><td class="memSeparator" colspan="2"> </td></tr>
<tr class="memitem:a3e0e67bdd01c86eede779de63249c703" id="r_a3e0e67bdd01c86eede779de63249c703"><td class="memItemLeft" align="right" valign="top">int </td><td class="memItemRight" valign="bottom"><a class="el" href="dis_8h.html#a3e0e67bdd01c86eede779de63249c703">disinit</a> (int alloc, int naxis, struct <a class="el" href="structdisprm.html">disprm</a> *dis, int ndpmax)</td></tr>
<tr class="memdesc:a3e0e67bdd01c86eede779de63249c703"><td class="mdescLeft"> </td><td class="mdescRight">Default constructor for the <a class="el" href="structdisprm.html" title="Distortion parameters.">disprm</a> struct. <br /></td></tr>
<tr class="separator:a3e0e67bdd01c86eede779de63249c703"><td class="memSeparator" colspan="2"> </td></tr>
<tr class="memitem:a42e03676a3def43ef6b936cd7beb4dd5" id="r_a42e03676a3def43ef6b936cd7beb4dd5"><td class="memItemLeft" align="right" valign="top">int </td><td class="memItemRight" valign="bottom"><a class="el" href="dis_8h.html#a42e03676a3def43ef6b936cd7beb4dd5">discpy</a> (int alloc, const struct <a class="el" href="structdisprm.html">disprm</a> *dissrc, struct <a class="el" href="structdisprm.html">disprm</a> *disdst)</td></tr>
<tr class="memdesc:a42e03676a3def43ef6b936cd7beb4dd5"><td class="mdescLeft"> </td><td class="mdescRight">Copy routine for the <a class="el" href="structdisprm.html" title="Distortion parameters.">disprm</a> struct. <br /></td></tr>
<tr class="separator:a42e03676a3def43ef6b936cd7beb4dd5"><td class="memSeparator" colspan="2"> </td></tr>
<tr class="memitem:a83b98d0f6429f4f19024675645026187" id="r_a83b98d0f6429f4f19024675645026187"><td class="memItemLeft" align="right" valign="top">int </td><td class="memItemRight" valign="bottom"><a class="el" href="dis_8h.html#a83b98d0f6429f4f19024675645026187">disfree</a> (struct <a class="el" href="structdisprm.html">disprm</a> *dis)</td></tr>
<tr class="memdesc:a83b98d0f6429f4f19024675645026187"><td class="mdescLeft"> </td><td class="mdescRight">Destructor for the <a class="el" href="structdisprm.html" title="Distortion parameters.">disprm</a> struct. <br /></td></tr>
<tr class="separator:a83b98d0f6429f4f19024675645026187"><td class="memSeparator" colspan="2"> </td></tr>
<tr class="memitem:a6f07892abc6d9d73ee9017750dc7bd8d" id="r_a6f07892abc6d9d73ee9017750dc7bd8d"><td class="memItemLeft" align="right" valign="top">int </td><td class="memItemRight" valign="bottom"><a class="el" href="dis_8h.html#a6f07892abc6d9d73ee9017750dc7bd8d">dissize</a> (const struct <a class="el" href="structdisprm.html">disprm</a> *dis, int sizes[2])</td></tr>
<tr class="memdesc:a6f07892abc6d9d73ee9017750dc7bd8d"><td class="mdescLeft"> </td><td class="mdescRight">Compute the size of a <a class="el" href="structdisprm.html" title="Distortion parameters.">disprm</a> struct. <br /></td></tr>
<tr class="separator:a6f07892abc6d9d73ee9017750dc7bd8d"><td class="memSeparator" colspan="2"> </td></tr>
<tr class="memitem:aeee35e0d5183e74f20c64526d908886b" id="r_aeee35e0d5183e74f20c64526d908886b"><td class="memItemLeft" align="right" valign="top">int </td><td class="memItemRight" valign="bottom"><a class="el" href="dis_8h.html#aeee35e0d5183e74f20c64526d908886b">disprt</a> (const struct <a class="el" href="structdisprm.html">disprm</a> *dis)</td></tr>
<tr class="memdesc:aeee35e0d5183e74f20c64526d908886b"><td class="mdescLeft"> </td><td class="mdescRight">Print routine for the <a class="el" href="structdisprm.html" title="Distortion parameters.">disprm</a> struct. <br /></td></tr>
<tr class="separator:aeee35e0d5183e74f20c64526d908886b"><td class="memSeparator" colspan="2"> </td></tr>
<tr class="memitem:acc9e98282026d5a249c450f2d2c0f2f4" id="r_acc9e98282026d5a249c450f2d2c0f2f4"><td class="memItemLeft" align="right" valign="top">int </td><td class="memItemRight" valign="bottom"><a class="el" href="dis_8h.html#acc9e98282026d5a249c450f2d2c0f2f4">disperr</a> (const struct <a class="el" href="structdisprm.html">disprm</a> *dis, const char *prefix)</td></tr>
<tr class="memdesc:acc9e98282026d5a249c450f2d2c0f2f4"><td class="mdescLeft"> </td><td class="mdescRight">Print error messages from a <a class="el" href="structdisprm.html" title="Distortion parameters.">disprm</a> struct. <br /></td></tr>
<tr class="separator:acc9e98282026d5a249c450f2d2c0f2f4"><td class="memSeparator" colspan="2"> </td></tr>
<tr class="memitem:ab69a8e21c3a3b7409458f681bd6ac888" id="r_ab69a8e21c3a3b7409458f681bd6ac888"><td class="memItemLeft" align="right" valign="top">int </td><td class="memItemRight" valign="bottom"><a class="el" href="dis_8h.html#ab69a8e21c3a3b7409458f681bd6ac888">dishdo</a> (struct <a class="el" href="structdisprm.html">disprm</a> *dis)</td></tr>
<tr class="memdesc:ab69a8e21c3a3b7409458f681bd6ac888"><td class="mdescLeft"> </td><td class="mdescRight">write FITS headers using <code><b>TPD</b></code>. <br /></td></tr>
<tr class="separator:ab69a8e21c3a3b7409458f681bd6ac888"><td class="memSeparator" colspan="2"> </td></tr>
<tr class="memitem:ad1bdf4497eb4513ca8431e1baa419041" id="r_ad1bdf4497eb4513ca8431e1baa419041"><td class="memItemLeft" align="right" valign="top">int </td><td class="memItemRight" valign="bottom"><a class="el" href="dis_8h.html#ad1bdf4497eb4513ca8431e1baa419041">disset</a> (struct <a class="el" href="structdisprm.html">disprm</a> *dis)</td></tr>
<tr class="memdesc:ad1bdf4497eb4513ca8431e1baa419041"><td class="mdescLeft"> </td><td class="mdescRight">Setup routine for the <a class="el" href="structdisprm.html" title="Distortion parameters.">disprm</a> struct. <br /></td></tr>
<tr class="separator:ad1bdf4497eb4513ca8431e1baa419041"><td class="memSeparator" colspan="2"> </td></tr>
<tr class="memitem:a135726e4c4c5bc00e2eba865ab202201" id="r_a135726e4c4c5bc00e2eba865ab202201"><td class="memItemLeft" align="right" valign="top">int </td><td class="memItemRight" valign="bottom"><a class="el" href="dis_8h.html#a135726e4c4c5bc00e2eba865ab202201">disp2x</a> (struct <a class="el" href="structdisprm.html">disprm</a> *dis, const double rawcrd[], double discrd[])</td></tr>
<tr class="memdesc:a135726e4c4c5bc00e2eba865ab202201"><td class="mdescLeft"> </td><td class="mdescRight">Apply distortion function. <br /></td></tr>
<tr class="separator:a135726e4c4c5bc00e2eba865ab202201"><td class="memSeparator" colspan="2"> </td></tr>
<tr class="memitem:ac589d5e85afe3d775cba4c06734ce653" id="r_ac589d5e85afe3d775cba4c06734ce653"><td class="memItemLeft" align="right" valign="top">int </td><td class="memItemRight" valign="bottom"><a class="el" href="dis_8h.html#ac589d5e85afe3d775cba4c06734ce653">disx2p</a> (struct <a class="el" href="structdisprm.html">disprm</a> *dis, const double discrd[], double rawcrd[])</td></tr>
<tr class="memdesc:ac589d5e85afe3d775cba4c06734ce653"><td class="mdescLeft"> </td><td class="mdescRight">Apply de-distortion function. <br /></td></tr>
<tr class="separator:ac589d5e85afe3d775cba4c06734ce653"><td class="memSeparator" colspan="2"> </td></tr>
<tr class="memitem:a91fa2d34c30be042516a0246d393b116" id="r_a91fa2d34c30be042516a0246d393b116"><td class="memItemLeft" align="right" valign="top">int </td><td class="memItemRight" valign="bottom"><a class="el" href="dis_8h.html#a91fa2d34c30be042516a0246d393b116">diswarp</a> (struct <a class="el" href="structdisprm.html">disprm</a> *dis, const double pixblc[], const double pixtrc[], const double pixsamp[], int *nsamp, double maxdis[], double *maxtot, double avgdis[], double *avgtot, double rmsdis[], double *rmstot)</td></tr>
<tr class="memdesc:a91fa2d34c30be042516a0246d393b116"><td class="mdescLeft"> </td><td class="mdescRight">Compute measures of distortion. <br /></td></tr>
<tr class="separator:a91fa2d34c30be042516a0246d393b116"><td class="memSeparator" colspan="2"> </td></tr>
</table><table class="memberdecls">
<tr class="heading"><td colspan="2"><h2 class="groupheader"><a id="var-members" name="var-members"></a>
Variables</h2></td></tr>
<tr class="memitem:a6f125a402553f5dab46435299f0742a3" id="r_a6f125a402553f5dab46435299f0742a3"><td class="memItemLeft" align="right" valign="top">const char * </td><td class="memItemRight" valign="bottom"><a class="el" href="dis_8h.html#a6f125a402553f5dab46435299f0742a3">dis_errmsg</a> []</td></tr>
<tr class="memdesc:a6f125a402553f5dab46435299f0742a3"><td class="mdescLeft"> </td><td class="mdescRight">Status return messages. <br /></td></tr>
<tr class="separator:a6f125a402553f5dab46435299f0742a3"><td class="memSeparator" colspan="2"> </td></tr>
</table>
<a name="details" id="details"></a><h2 class="groupheader">Detailed Description</h2>
<div class="textblock"><p>Routines in this suite implement extensions to the FITS World Coordinate System (WCS) standard proposed by </p><div class="fragment"><div class="line"><span class="stringliteral">"Representations of distortions in FITS world coordinate systems"</span>,</div>
<div class="line">Calabretta, M.R. et al. (WCS Paper IV, draft dated 2004/04/22),</div>
<div class="line">available from http:<span class="comment">//www.atnf.csiro.au/people/Mark.Calabretta</span></div>
</div><!-- fragment --><p>In brief, a distortion function may occupy one of two positions in the WCS algorithm chain. Prior distortions precede the linear transformation matrix, whether it be <code><b>PC</b>i<b>_</b>ja</code> or <code><b>CD</b>i<b>_</b>ja</code>, and sequent distortions follow it. WCS Paper IV defines FITS keywords used to specify parameters for predefined distortion functions. The following are used for prior distortions: </p><div class="fragment"><div class="line">CPDISja ...(string-valued, identifies the distortion function)</div>
<div class="line">DPja ...(record-valued, parameters)</div>
<div class="line">CPERRja ...(floating-valued, maximum value)</div>
</div><!-- fragment --><p>Their counterparts for sequent distortions are <code><b>CQDIS</b>ia</code>, <code><b>DQ</b>ia</code>, and <code><b>CQERR</b>ia</code>. An additional floating-valued keyword, <code><b>DVERR</b>a</code>, records the maximum value of the combined distortions.</p>
<p><code><b>DP</b>ja</code> and <code><b>DQ</b>ia</code> are "record-valued". Syntactically, the keyvalues are standard FITS strings, but they are to be interpreted in a special way. The general form is </p><div class="fragment"><div class="line">DPja = <span class="stringliteral">'<field-specifier>: <float>'</span></div>
</div><!-- fragment --><p>where the field-specifier consists of a sequence of fields separated by periods, and the ': ' between the field-specifier and the floating-point value is part of the record syntax. For example: </p><div class="fragment"><div class="line">DP1 = <span class="stringliteral">'AXIS.1: 1'</span></div>
</div><!-- fragment --><p>Certain field-specifiers are defined for all distortion functions, while others are defined only for particular distortions. Refer to WCS Paper IV for further details. <a class="el" href="wcshdr_8h.html#ac75623ee805ab7d43b0bba684c719a60" title="FITS WCS parser routine for image headers.">wcspih()</a> parses all distortion keywords and loads them into a <a class="el" href="structdisprm.html" title="Distortion parameters.">disprm</a> struct for analysis by <a class="el" href="dis_8h.html#ad1bdf4497eb4513ca8431e1baa419041" title="Setup routine for the disprm struct.">disset()</a> which knows (or possibly does not know) how to interpret them. Of the Paper IV distortion functions, only the general Polynomial distortion is currently implemented here.</p>
<p><b><code><b>TPV</b></code> - the <code><b>TPV</b></code> "projection":</b> <br />
The distortion function component of the <code><b>TPV</b></code> celestial "projection" is also supported. The <code><b>TPV</b></code> projection, originally proposed in a draft of WCS Paper II, consists of a <code><b>TAN</b></code> projection with sequent polynomial distortion, the coefficients of which are encoded in <code><b>PV</b>i<b>_</b>ma</code> keyrecords. Full details may be found at the registry of FITS conventions: </p><div class="fragment"><div class="line">http:<span class="comment">//fits.gsfc.nasa.gov/registry/tpvwcs/tpv.html</span></div>
</div><!-- fragment --><p>Internally, <a class="el" href="wcs_8h.html#ae5cc3f5d249755583403cdf54d2ebb91" title="Setup routine for the wcsprm struct.">wcsset()</a> changes <code><b>TPV</b></code> to a <code><b>TAN</b></code> projection, translates the <code><b>PV</b>i<b>_</b>ma</code> keywords to <code><b>DQ</b>ia</code> and loads them into a <a class="el" href="structdisprm.html" title="Distortion parameters.">disprm</a> struct. These <code><b>DQ</b>ia</code> keyrecords have the form </p><div class="fragment"><div class="line">DQia = <span class="stringliteral">'TPV.m: <value>'</span></div>
</div><!-- fragment --><p>where i, a, m, and the value for each <code><b>DQ</b>ia</code> match each <code><b>PV</b>i<b>_</b>ma</code>. Consequently, WCSLIB would handle a FITS header containing these keywords, along with <code><b>CQDIS</b>ia</code> = '<code><b>TPV</b></code>' and the required <code><b>DQ</b>ia</code><code><b>.NAXES</b></code> and <code><b>DQ</b>ia</code><code><b>.AXIS.</b></code>ihat keywords.</p>
<p>Note that, as defined, <code><b>TPV</b></code> assumes that <code><b>CD</b>i<b>_</b>ja</code> is used to define the linear transformation. The section on historical idiosyncrasies (below) cautions about translating <code><b>CD</b>i<b>_</b>ja</code> to <code><b>PC</b>i<b>_</b>ja</code> plus <code><b>CDELT</b>ia</code> in this case.</p>
<p><b><code><b>SIP</b></code> - Simple Imaging Polynomial:</b> <br />
These routines also support the Simple Imaging Polynomial (<code><b>SIP</b></code>), whose design was influenced by early drafts of WCS Paper IV. It is described in detail in </p><div class="fragment"><div class="line">http:<span class="comment">//fits.gsfc.nasa.gov/registry/sip.html</span></div>
</div><!-- fragment --><p><code><b>SIP</b></code>, which is defined only as a prior distortion for 2-D celestial images, has the interesting feature that it records an approximation to the inverse polynomial distortion function. This is used by <a class="el" href="dis_8h.html#ac589d5e85afe3d775cba4c06734ce653" title="Apply de-distortion function.">disx2p()</a> to provide an initial estimate for its more precise iterative inversion. The special-purpose keywords used by <code><b>SIP</b></code> are parsed and translated by <a class="el" href="wcshdr_8h.html#ac75623ee805ab7d43b0bba684c719a60" title="FITS WCS parser routine for image headers.">wcspih()</a> as follows: </p><div class="fragment"><div class="line"> A_p_q = <value> -> DP1 = <span class="stringliteral">'SIP.FWD.p_q: <value>'</span></div>
<div class="line">AP_p_q = <value> -> DP1 = <span class="stringliteral">'SIP.REV.p_q: <value>'</span></div>
<div class="line"> B_p_q = <value> -> DP2 = <span class="stringliteral">'SIP.FWD.p_q: <value>'</span></div>
<div class="line">BP_p_q = <value> -> DP2 = <span class="stringliteral">'SIP.REV.p_q: <value>'</span></div>
<div class="line">A_DMAX = <value> -> DPERR1 = <value></div>
<div class="line">B_DMAX = <value> -> DPERR2 = <value></div>
</div><!-- fragment --><p><code><b>SIP</b></code>'s <code><b>A_ORDER</b></code> and <code><b>B_ORDER</b></code> keywords are not used. WCSLIB would recognise a FITS header containing the above keywords, along with <code><b>CPDIS</b>ja</code> = '<code><b>SIP</b></code>' and the required <code><b>DP</b>ja</code><code><b>.NAXES</b></code> keywords.</p>
<p><b><code><b>DSS</b></code> - Digitized Sky Survey:</b> <br />
The Digitized Sky Survey resulted from the production of the Guide Star Catalogue for the Hubble Space Telescope. Plate solutions based on a polynomial distortion function were encoded in FITS using non-standard keywords. Sect. 5.2 of WCS Paper IV describes how <code><b>DSS</b></code> coordinates may be translated to a sequent Polynomial distortion using two auxiliary variables. That translation is based on optimising the non-distortion component of the plate solution.</p>
<p>Following Paper IV, <a class="el" href="wcshdr_8h.html#ac75623ee805ab7d43b0bba684c719a60" title="FITS WCS parser routine for image headers.">wcspih()</a> translates the non-distortion component of <code><b>DSS</b></code> coordinates to standard WCS keywords (<code><b>CRPIX</b>ja</code>, <code><b>PC</b>i<b>_</b>ja</code>, <code><b>CRVAL</b>ia</code>, etc), and fills a wcsprm struct with their values. It encodes the <code><b>DSS</b></code> polynomial coefficients as </p><div class="fragment"><div class="line">AMDXm = <value> -> DQ1 = <span class="stringliteral">'AMD.m: <value>'</span></div>
<div class="line">AMDYm = <value> -> DQ2 = <span class="stringliteral">'AMD.m: <value>'</span></div>
</div><!-- fragment --><p>WCSLIB would recognise a FITS header containing the above keywords, along with <code><b>CQDIS</b>ia</code> = '<code><b>DSS</b></code>' and the required <code><b>DQ</b>ia</code><code><b>.NAXES</b></code> keywords.</p>
<p><b><code><b>WAT</b></code> - the <code><b>TNX</b></code> and <code><b>ZPX</b></code> "projections":</b> <br />
The <code><b>TNX</b></code> and <code><b>ZPX</b></code> "projections" add a polynomial distortion function to the standard <code><b>TAN</b></code> and <code><b>ZPN</b></code> projections respectively. Unusually, the polynomial may be expressed as the sum of Chebyshev or Legendre polynomials, or as a simple sum of monomials, as described in </p><div class="fragment"><div class="line">http:<span class="comment">//fits.gsfc.nasa.gov/registry/tnx/tnx-doc.html</span></div>
<div class="line">http:<span class="comment">//fits.gsfc.nasa.gov/registry/zpxwcs/zpx.html</span></div>
</div><!-- fragment --><p>The polynomial coefficients are encoded in special-purpose <code><b>WAT</b></code>i_n keywords as a set of continued strings, thus providing the name for this distortion type. <code><b>WAT</b></code>i_n are parsed and translated by <a class="el" href="wcshdr_8h.html#ac75623ee805ab7d43b0bba684c719a60" title="FITS WCS parser routine for image headers.">wcspih()</a> into the following set: </p><div class="fragment"><div class="line">DQi = <span class="stringliteral">'WAT.POLY: <value>'</span></div>
<div class="line">DQi = <span class="stringliteral">'WAT.XMIN: <value>'</span></div>
<div class="line">DQi = <span class="stringliteral">'WAT.XMAX: <value>'</span></div>
<div class="line">DQi = <span class="stringliteral">'WAT.YMIN: <value>'</span></div>
<div class="line">DQi = <span class="stringliteral">'WAT.YMAX: <value>'</span></div>
<div class="line">DQi = <span class="stringliteral">'WAT.CHBY.m_n: <value>'</span> or</div>
<div class="line">DQi = <span class="stringliteral">'WAT.LEGR.m_n: <value>'</span> or</div>
<div class="line">DQi = <span class="stringliteral">'WAT.MONO.m_n: <value>'</span></div>
</div><!-- fragment --><p>along with <code><b>CQDIS</b>ia</code> = '<code><b>WAT</b></code>' and the required <code><b>DP</b>ja</code><code><b>.NAXES</b></code> keywords. For <code><b>ZPX</b></code>, the <code><b>ZPN</b></code> projection parameters are also encoded in <code><b>WAT</b></code>i_n, and <a class="el" href="wcshdr_8h.html#ac75623ee805ab7d43b0bba684c719a60" title="FITS WCS parser routine for image headers.">wcspih()</a> translates these to standard <code><b>PV</b>i<b>_</b>ma</code>.</p>
<p>Note that, as defined, <code><b>TNX</b></code> and <code><b>ZPX</b></code> assume that <code><b>CD</b>i<b>_</b>ja</code> is used to define the linear transformation. The section on historical idiosyncrasies (below) cautions about translating <code><b>CD</b>i<b>_</b>ja</code> to <code><b>PC</b>i<b>_</b>ja</code> plus <code><b>CDELT</b>ia</code> in this case.</p>
<p><b><code><b>TPD</b></code> - Template Polynomial Distortion:</b> <br />
The "Template Polynomial Distortion" (<code><b>TPD</b></code>) is a superset of the <code><b>TPV</b></code>, <code><b>SIP</b></code>, <code><b>DSS</b></code>, and <code><b>WAT</b></code> (<code><b>TNX</b></code> & <code><b>ZPX</b></code>) polynomial distortions that also supports 1-D usage and inversions. Like <code><b>TPV</b></code>, <code><b>SIP</b></code>, and <code><b>DSS</b></code>, the form of the polynomial is fixed (the "template") and only the coefficients for the required terms are set non-zero. <code><b>TPD</b></code> generalizes <code><b>TPV</b></code> in going to 9th degree, <code><b>SIP</b></code> by accomodating <code><b>TPV</b></code>'s linear and radial terms, and <code><b>DSS</b></code> in both respects. While in theory the degree of the <code><b>WAT</b></code> polynomial distortion in unconstrained, in practice it is limited to values that can be handled by <code><b>TPD</b></code>.</p>
<p>Within WCSLIB, <code><b>TPV</b></code>, <code><b>SIP</b></code>, <code><b>DSS</b></code>, and <code><b>WAT</b></code> are all implemented as special cases of <code><b>TPD</b></code>. Indeed, <code><b>TPD</b></code> was developed precisely for that purpose. <code><b>WAT</b></code> distortions expressed as the sum of Chebyshev or Legendre polynomials are expanded for <code><b>TPD</b></code> as a simple sum of monomials. Moreover, the general Polynomial distortion is translated and implemented internally as <code><b>TPD</b></code> whenever possible.</p>
<p>However, WCSLIB also recognizes '<code><b>TPD</b></code>' as a distortion function in its own right (i.e. a recognized value of <code><b>CPDIS</b>ja</code> or <code><b>CQDIS</b>ia</code>), for use as both prior and sequent distortions. Its <code><b>DP</b>ja</code> and <code><b>DQ</b>ia</code> keyrecords have the form </p><div class="fragment"><div class="line">DPja = <span class="stringliteral">'TPD.FWD.m: <value>'</span></div>
<div class="line">DPja = <span class="stringliteral">'TPD.REV.m: <value>'</span></div>
</div><!-- fragment --><p>for the forward and reverse distortion functions. Moreover, like the general Polynomial distortion, <code><b>TPD</b></code> supports auxiliary variables, though only as a linear transformation of pixel coordinates (p1,p2): </p><div class="fragment"><div class="line">x = a0 + a1*p1 + a2*p2</div>
<div class="line">y = b0 + b1*p1 + b2*p2</div>
</div><!-- fragment --><p>where the coefficients of the auxiliary variables (x,y) are recorded as </p><div class="fragment"><div class="line">DPja = <span class="stringliteral">'AUX.1.COEFF.0: a0'</span> ...default 0.0</div>
<div class="line">DPja = <span class="stringliteral">'AUX.1.COEFF.1: a1'</span> ...default 1.0</div>
<div class="line">DPja = <span class="stringliteral">'AUX.1.COEFF.2: a2'</span> ...default 0.0</div>
<div class="line">DPja = <span class="stringliteral">'AUX.2.COEFF.0: b0'</span> ...default 0.0</div>
<div class="line">DPja = <span class="stringliteral">'AUX.2.COEFF.1: b1'</span> ...default 0.0</div>
<div class="line">DPja = <span class="stringliteral">'AUX.2.COEFF.2: b2'</span> ...default 1.0</div>
</div><!-- fragment --><p>Though nowhere near as powerful, in typical applications <code><b>TPD</b></code> is considerably faster than the general Polynomial distortion. As <code><b>TPD</b></code> has a finite and not too large number of possible terms (60), the coefficients for each can be stored (by <a class="el" href="dis_8h.html#ad1bdf4497eb4513ca8431e1baa419041" title="Setup routine for the disprm struct.">disset()</a>) in a fixed location in the <a class="el" href="structdisprm.html#a9775ace81c64bf04c0fbe5b750bc2a79">disprm::dparm</a>[] array. A large part of the speedup then arises from evaluating the polynomial using Horner's scheme.</p>
<p>Separate implementations for polynomials of each degree, and conditionals for 1-D polynomials and 2-D polynomials with and without the radial variable, ensure that unused terms mostly do not impose a significant computational overhead.</p>
<p>The <code><b>TPD</b></code> terms are as follows </p><div class="fragment"><div class="line">0: 1 4: xx 12: xxxx 24: xxxxxx 40: xxxxxxxx</div>
<div class="line"> 5: xy 13: xxxy 25: xxxxxy 41: xxxxxxxy</div>
<div class="line">1: x 6: yy 14: xxyy 26: xxxxyy 42: xxxxxxyy</div>
<div class="line">2: y 15: xyyy 27: xxxyyy 43: xxxxxyyy</div>
<div class="line">3: r 7: xxx 16: yyyy 28: xxyyyy 44: xxxxyyyy</div>
<div class="line"> 8: xxy 29: xyyyyy 45: xxxyyyyy</div>
<div class="line"> 9: xyy 17: xxxxx 30: yyyyyy 46: xxyyyyyy</div>
<div class="line"> 10: yyy 18: xxxxy 47: xyyyyyyy</div>
<div class="line"> 11: rrr 19: xxxyy 31: xxxxxxx 48: yyyyyyyy</div>
<div class="line"> 20: xxyyy 32: xxxxxxy</div>
<div class="line"> 21: xyyyy 33: xxxxxyy 49: xxxxxxxxx</div>
<div class="line"> 22: yyyyy 34: xxxxyyy 50: xxxxxxxxy</div>
<div class="line"> 23: rrrrr 35: xxxyyyy 51: xxxxxxxyy</div>
<div class="line"> 36: xxyyyyy 52: xxxxxxyyy</div>
<div class="line"> 37: xyyyyyy 53: xxxxxyyyy</div>
<div class="line"> 38: yyyyyyy 54: xxxxyyyyy</div>
<div class="line"> 39: rrrrrrr 55: xxxyyyyyy</div>
<div class="line"> 56: xxyyyyyyy</div>
<div class="line"> 57: xyyyyyyyy</div>
<div class="line"> 58: yyyyyyyyy</div>
<div class="line"> 59: rrrrrrrrr</div>
</div><!-- fragment --><p>where r = <picture><source srcset="form_12_dark.png" media="(prefers-color-scheme: dark)"/><img class="formulaInl" alt="$\sqrt(x^2 + y^2)$" src="form_12.png" width="61" height="16"/></picture>. Note that even powers of r are excluded since they can be accomodated by powers of <picture><source srcset="form_13_dark.png" media="(prefers-color-scheme: dark)"/><img class="formulaInl" alt="$(x^2 + y^2)$" src="form_13.png" width="49" height="15"/></picture>.</p>
<p>Note here that "x" refers to the axis to which the distortion function is attached, with "y" being the complementary axis. So, for example, with longitude on axis 1 and latitude on axis 2, for <code><b>TPD</b></code> attached to axis 1, "x" refers to axis 1 and "y" to axis 2. For <code><b>TPD</b></code> attached to axis 2, "x" refers to axis 2, and "y" to axis 1.</p>
<p><code><b>TPV</b></code> uses all terms up to 39. The m in its <code><b>PV</b>i<b>_</b>ma</code> keywords translates directly to the <code><b>TPD</b></code> coefficient number.</p>
<p><code><b>SIP</b></code> uses all terms except for 0, 3, 11, 23, 39, and 59, with terms 1 and 2 only used for the inverse. Its <code><b>A_</b>p<b>_</b>q</code>, etc. keywords must be translated using a map.</p>
<p><code><b>DSS</b></code> uses terms 0, 1, 2, 4, 5, 6, 7, 8, 9, 10, 17, 19, and 21. The presence of a non-zero constant term arises through the use of auxiliary variables with origin offset from the reference point of the <code><b>TAN</b></code> projection. However, in the translation given by WCS Paper IV, the distortion polynomial is zero, or very close to zero, at the reference pixel itself. The mapping between <code><b>DSS</b></code>'s <code><b>AMDX</b></code>m (or <code><b>AMDY</b></code>m) keyvalues and <code><b>TPD</b></code> coefficients, while still simple, is not quite as straightforward as for <code><b>TPV</b></code> and <code><b>SIP</b></code>.</p>
<p><code><b>WAT</b></code> uses all but the radial terms, namely 3, 11, 23, 39, and 59. While the mapping between <code><b>WAT</b></code>'s monomial coefficients and <code><b>TPD</b></code> is fairly simple, for its expression in terms of a sum of Chebyshev or Legendre polynomials it is much less so.</p>
<p><b>Historical idiosyncrasies:</b> <br />
In addition to the above, some historical distortion functions have further idiosyncrasies that must be taken into account when translating them to <code><b>TPD</b></code>.</p>
<p>WCS Paper IV specifies that a distortion function returns a correction to be added to pixel coordinates (prior distortion) or intermediate pixel coordinates (sequent distortion). The correction is meant to be small so that ignoring the distortion function, i.e. setting the correction to zero, produces a commensurately small error.</p>
<p>However, rather than an additive correction, some historical distortion functions (<code><b>TPV</b></code>, <code><b>DSS</b></code>) define a polynomial that returns the corrected coordinates directly.</p>
<p>The difference between the two approaches is readily accounted for simply by adding or subtracting 1 from the coefficient of the first degree term of the polynomial. However, it opens the way for considerable confusion.</p>
<p>Additional to the formalism of WCS Paper IV, both the Polynomial and <code><b>TPD</b></code> distortion functions recognise a keyword </p><div class="fragment"><div class="line">DPja = <span class="stringliteral">'DOCORR: 0'</span></div>
</div><!-- fragment --><p>which is meant to apply generally to indicate that the distortion function returns the corrected coordinates directly. Any other value for <code><b>DOCORR</b></code> (or its absence) indicates that the distortion function returns an additive correction.</p>
<p>WCS Paper IV also specifies that the independent variables of a distortion function are pixel coordinates (prior distortion) or intermediate pixel coordinates (sequent distortion).</p>
<p>On the contrary, the independent variables of the <code><b>SIP</b></code> polynomial are pixel coordinate offsets from the reference pixel. This is readily handled via the renormalisation parameters </p><div class="fragment"><div class="line">DPja = <span class="stringliteral">'OFFSET.jhat: <value>'</span></div>
</div><!-- fragment --><p>where the value corresponds to <code><b>CRPIX</b>ja</code>.</p>
<p>Likewise, because <code><b>TPV</b></code>, <code><b>TNX</b></code>, and <code><b>ZPX</b></code> are defined in terms of <code><b>CD</b>i<b>_</b>ja</code>, the independent variables of the polynomial are intermediate world coordinates rather than intermediate pixel coordinates. Because sequent distortions are always applied before <code><b>CDELT</b>ia</code>, if <code><b>CD</b>i<b>_</b>ja</code> is translated to <code><b>PC</b>i<b>_</b>ja</code> plus <code><b>CDELT</b>ia</code>, then either <code><b>CDELT</b>ia</code> must be unity, or the distortion polynomial coefficients must be adjusted to account for the change of scale.</p>
<p><b>Summary of the dis routines:</b> <br />
These routines apply the distortion functions defined by the extension to the FITS WCS standard proposed in Paper IV. They are based on the <a class="el" href="structdisprm.html" title="Distortion parameters.">disprm</a> struct which contains all information needed for the computations. The struct contains some members that must be set by the user, and others that are maintained by these routines, somewhat like a C++ class but with no encapsulation.</p>
<p><a class="el" href="dis_8h.html#a44e73dd6831a2eb25f09d316d175875f" title="Fill the contents of a dpkey struct.">dpfill()</a>, <a class="el" href="dis_8h.html#a5fab5cff95ef5e505314a6fb67325074" title="Get the data value in a dpkey struct as int.">dpkeyi()</a>, and <a class="el" href="dis_8h.html#a2181881844241449382477a5c2723082" title="Get the data value in a dpkey struct as double.">dpkeyd()</a> are provided to manage the dpkey struct.</p>
<p><a class="el" href="dis_8h.html#aa5486b870327544f7423ad2751fb4120" title="Memory allocation for DPja and DQia.">disndp()</a>, <a class="el" href="dis_8h.html#a8896e2a5330e55cd85da4a28ed6ee463" title="Default constructor for the disprm struct.">disini()</a>, <a class="el" href="dis_8h.html#a3e0e67bdd01c86eede779de63249c703" title="Default constructor for the disprm struct.">disinit()</a>, <a class="el" href="dis_8h.html#a42e03676a3def43ef6b936cd7beb4dd5" title="Copy routine for the disprm struct.">discpy()</a>, and <a class="el" href="dis_8h.html#a83b98d0f6429f4f19024675645026187" title="Destructor for the disprm struct.">disfree()</a> are provided to manage the <a class="el" href="structdisprm.html" title="Distortion parameters.">disprm</a> struct, <a class="el" href="dis_8h.html#a6f07892abc6d9d73ee9017750dc7bd8d" title="Compute the size of a disprm struct.">dissize()</a> computes its total size including allocated memory, and <a class="el" href="dis_8h.html#aeee35e0d5183e74f20c64526d908886b" title="Print routine for the disprm struct.">disprt()</a> prints its contents.</p>
<p><a class="el" href="dis_8h.html#acc9e98282026d5a249c450f2d2c0f2f4" title="Print error messages from a disprm struct.">disperr()</a> prints the error message(s) (if any) stored in a <a class="el" href="structdisprm.html" title="Distortion parameters.">disprm</a> struct.</p>
<p><a class="el" href="wcshdr_8h.html#ace387e4a5f6c519ad2a0e1fdebe62381" title="Write out a wcsprm struct as a FITS header.">wcshdo()</a> normally writes <code><b>SIP</b></code> and <code><b>TPV</b></code> headers in their native form if at all possible. However, <a class="el" href="dis_8h.html#ab69a8e21c3a3b7409458f681bd6ac888" title="write FITS headers using TPD.">dishdo()</a> may be used to set a flag that tells it to write the header in the form of the <code><b>TPD</b></code> translation used internally.</p>
<p>A setup routine, <a class="el" href="dis_8h.html#ad1bdf4497eb4513ca8431e1baa419041" title="Setup routine for the disprm struct.">disset()</a>, computes intermediate values in the <a class="el" href="structdisprm.html" title="Distortion parameters.">disprm</a> struct from parameters in it that were supplied by the user. The struct always needs to be set up by <a class="el" href="dis_8h.html#ad1bdf4497eb4513ca8431e1baa419041" title="Setup routine for the disprm struct.">disset()</a>, though <a class="el" href="dis_8h.html#ad1bdf4497eb4513ca8431e1baa419041" title="Setup routine for the disprm struct.">disset()</a> need not be called explicitly - refer to the explanation of <a class="el" href="structdisprm.html#a4d6ba28bee2fc636f4b2b9ca4b50b0a4">disprm::flag</a>.</p>
<p><a class="el" href="dis_8h.html#a135726e4c4c5bc00e2eba865ab202201" title="Apply distortion function.">disp2x()</a> and <a class="el" href="dis_8h.html#ac589d5e85afe3d775cba4c06734ce653" title="Apply de-distortion function.">disx2p()</a> implement the WCS distortion functions, <a class="el" href="dis_8h.html#a135726e4c4c5bc00e2eba865ab202201" title="Apply distortion function.">disp2x()</a> using separate functions, such as dispoly() and tpd7(), to do the computation.</p>
<p>An auxiliary routine, <a class="el" href="dis_8h.html#a91fa2d34c30be042516a0246d393b116" title="Compute measures of distortion.">diswarp()</a>, computes various measures of the distortion over a specified range of coordinates.</p>
<p><b><b>PLEASE NOTE:</b></b> <br />
</p>
</div><h2 class="groupheader">Macro Definition Documentation</h2>
<a id="a23068602f42552a4257462b2875d8c51" name="a23068602f42552a4257462b2875d8c51"></a>
<h2 class="memtitle"><span class="permalink"><a href="#a23068602f42552a4257462b2875d8c51">◆ </a></span>DISP2X_ARGS</h2>
<div class="memitem">
<div class="memproto">
<table class="memname">
<tr>
<td class="memname">#define DISP2X_ARGS</td>
</tr>
</table>
</div><div class="memdoc">
<b>Value:</b><div class="fragment"><div class="line"><span class="keywordtype">int</span> inverse, <span class="keyword">const</span> <span class="keywordtype">int</span> iparm[], <span class="keyword">const</span> <span class="keywordtype">double</span> dparm[], \</div>
<div class="line"><span class="keywordtype">int</span> ncrd, <span class="keyword">const</span> <span class="keywordtype">double</span> rawcrd[], <span class="keywordtype">double</span> *discrd</div>
</div><!-- fragment -->
</div>
</div>
<a id="ac593cd79fb7f89b1c7395d0ecf2f7876" name="ac593cd79fb7f89b1c7395d0ecf2f7876"></a>
<h2 class="memtitle"><span class="permalink"><a href="#ac593cd79fb7f89b1c7395d0ecf2f7876">◆ </a></span>DISX2P_ARGS</h2>
<div class="memitem">
<div class="memproto">
<table class="memname">
<tr>
<td class="memname">#define DISX2P_ARGS</td>
</tr>
</table>
</div><div class="memdoc">
<b>Value:</b><div class="fragment"><div class="line"><span class="keywordtype">int</span> inverse, <span class="keyword">const</span> <span class="keywordtype">int</span> iparm[], <span class="keyword">const</span> <span class="keywordtype">double</span> dparm[], \</div>
<div class="line"><span class="keywordtype">int</span> ncrd, <span class="keyword">const</span> <span class="keywordtype">double</span> discrd[], <span class="keywordtype">double</span> *rawcrd</div>
</div><!-- fragment -->
</div>
</div>
<a id="a10a6a35bdc567bcbedf1ec10c4aa94c3" name="a10a6a35bdc567bcbedf1ec10c4aa94c3"></a>
<h2 class="memtitle"><span class="permalink"><a href="#a10a6a35bdc567bcbedf1ec10c4aa94c3">◆ </a></span>DPLEN</h2>
<div class="memitem">
<div class="memproto">
<table class="memname">
<tr>
<td class="memname">#define DPLEN   (sizeof(struct <a class="el" href="structdpkey.html">dpkey</a>)/sizeof(int))</td>
</tr>
</table>
</div><div class="memdoc">
</div>
</div>
<a id="a5df41117cb392fc0c5d051002b441aa9" name="a5df41117cb392fc0c5d051002b441aa9"></a>
<h2 class="memtitle"><span class="permalink"><a href="#a5df41117cb392fc0c5d051002b441aa9">◆ </a></span>DISLEN</h2>
<div class="memitem">
<div class="memproto">
<table class="memname">
<tr>
<td class="memname">#define DISLEN   (sizeof(struct <a class="el" href="structdisprm.html">disprm</a>)/sizeof(int))</td>
</tr>
</table>
</div><div class="memdoc">
</div>
</div>
<h2 class="groupheader">Enumeration Type Documentation</h2>
<a id="a27ab258e601dcfa4d184a35edbc590fd" name="a27ab258e601dcfa4d184a35edbc590fd"></a>
<h2 class="memtitle"><span class="permalink"><a href="#a27ab258e601dcfa4d184a35edbc590fd">◆ </a></span>dis_errmsg_enum</h2>
<div class="memitem">
<div class="memproto">
<table class="memname">
<tr>
<td class="memname">enum <a class="el" href="dis_8h.html#a27ab258e601dcfa4d184a35edbc590fd">dis_errmsg_enum</a></td>
</tr>
</table>
</div><div class="memdoc">
<table class="fieldtable">
<tr><th colspan="2">Enumerator</th></tr><tr><td class="fieldname"><a id="a27ab258e601dcfa4d184a35edbc590fdaeaef8bb1725ea601f43900897ee144a8" name="a27ab258e601dcfa4d184a35edbc590fdaeaef8bb1725ea601f43900897ee144a8"></a>DISERR_SUCCESS </td><td class="fielddoc"></td></tr>
<tr><td class="fieldname"><a id="a27ab258e601dcfa4d184a35edbc590fda8c5a7d847d62520f972e51435d4d0d46" name="a27ab258e601dcfa4d184a35edbc590fda8c5a7d847d62520f972e51435d4d0d46"></a>DISERR_NULL_POINTER </td><td class="fielddoc"></td></tr>
<tr><td class="fieldname"><a id="a27ab258e601dcfa4d184a35edbc590fda7298d8c404456ac8c3a5365f2f266d80" name="a27ab258e601dcfa4d184a35edbc590fda7298d8c404456ac8c3a5365f2f266d80"></a>DISERR_MEMORY </td><td class="fielddoc"></td></tr>
<tr><td class="fieldname"><a id="a27ab258e601dcfa4d184a35edbc590fdace3a5f769a3b8966f980f1279e2f08b0" name="a27ab258e601dcfa4d184a35edbc590fdace3a5f769a3b8966f980f1279e2f08b0"></a>DISERR_BAD_PARAM </td><td class="fielddoc"></td></tr>
<tr><td class="fieldname"><a id="a27ab258e601dcfa4d184a35edbc590fdadbabbc4a9fe6441177efcd050b4cc579" name="a27ab258e601dcfa4d184a35edbc590fdadbabbc4a9fe6441177efcd050b4cc579"></a>DISERR_DISTORT </td><td class="fielddoc"></td></tr>
<tr><td class="fieldname"><a id="a27ab258e601dcfa4d184a35edbc590fdabe0645cb8d4bfc0f496aa84336ca492a" name="a27ab258e601dcfa4d184a35edbc590fdabe0645cb8d4bfc0f496aa84336ca492a"></a>DISERR_DEDISTORT </td><td class="fielddoc"></td></tr>
</table>
</div>
</div>
<h2 class="groupheader">Function Documentation</h2>
<a id="aa5486b870327544f7423ad2751fb4120" name="aa5486b870327544f7423ad2751fb4120"></a>
<h2 class="memtitle"><span class="permalink"><a href="#aa5486b870327544f7423ad2751fb4120">◆ </a></span>disndp()</h2>
<div class="memitem">
<div class="memproto">
<table class="memname">
<tr>
<td class="memname">int disndp </td>
<td>(</td>
<td class="paramtype">int </td>
<td class="paramname"><em>n</em></td><td>)</td>
<td></td>
</tr>
</table>
</div><div class="memdoc">
<p>Memory allocation for <code><b>DP</b>ja</code> and <code><b>DQ</b>ia</code>. </p>
<p><b>disndp</b>() sets or gets the value of NDPMAX (default 256). This global variable controls the maximum number of dpkey structs, for holding <code><b>DP</b>ja</code> or <code><b>DQ</b>ia</code> keyvalues, that <a class="el" href="dis_8h.html#a8896e2a5330e55cd85da4a28ed6ee463" title="Default constructor for the disprm struct.">disini()</a> should allocate space for. It is also used by <a class="el" href="dis_8h.html#a3e0e67bdd01c86eede779de63249c703" title="Default constructor for the disprm struct.">disinit()</a> as the default value of ndpmax.</p>
<p><b>PLEASE NOTE:</b> This function is not thread-safe.</p>
<dl class="params"><dt>Parameters</dt><dd>
<table class="params">
<tr><td class="paramdir">[in]</td><td class="paramname">n</td><td>Value of NDPMAX; ignored if < 0. Use a value less than zero to get the current value.</td></tr>
</table>
</dd>
</dl>
<dl class="section return"><dt>Returns</dt><dd>Current value of NDPMAX. </dd></dl>
</div>
</div>
<a id="a44e73dd6831a2eb25f09d316d175875f" name="a44e73dd6831a2eb25f09d316d175875f"></a>
<h2 class="memtitle"><span class="permalink"><a href="#a44e73dd6831a2eb25f09d316d175875f">◆ </a></span>dpfill()</h2>
<div class="memitem">
<div class="memproto">
<table class="memname">
<tr>
<td class="memname">int dpfill </td>
<td>(</td>
<td class="paramtype">struct <a class="el" href="structdpkey.html">dpkey</a> * </td>
<td class="paramname"><em>dp</em>, </td>
</tr>
<tr>
<td class="paramkey"></td>
<td></td>
<td class="paramtype">const char * </td>
<td class="paramname"><em>keyword</em>, </td>
</tr>
<tr>
<td class="paramkey"></td>
<td></td>
<td class="paramtype">const char * </td>
<td class="paramname"><em>field</em>, </td>
</tr>
<tr>
<td class="paramkey"></td>
<td></td>
<td class="paramtype">int </td>
<td class="paramname"><em>j</em>, </td>
</tr>
<tr>
<td class="paramkey"></td>
<td></td>
<td class="paramtype">int </td>
<td class="paramname"><em>type</em>, </td>
</tr>
<tr>
<td class="paramkey"></td>
<td></td>
<td class="paramtype">int </td>
<td class="paramname"><em>i</em>, </td>
</tr>
<tr>
<td class="paramkey"></td>
<td></td>
<td class="paramtype">double </td>
<td class="paramname"><em>f</em> </td>
</tr>
<tr>
<td></td>
<td>)</td>
<td></td><td></td>
</tr>
</table>
</div><div class="memdoc">
<p>Fill the contents of a dpkey struct. </p>
<p><b>dpfill</b>() is a utility routine to aid in filling the contents of the dpkey struct. No checks are done on the validity of the inputs.</p>
<p>WCS Paper IV specifies the syntax of a record-valued keyword as </p><div class="fragment"><div class="line">keyword = <span class="stringliteral">'<field-specifier>: <float>'</span></div>
</div><!-- fragment --><p>However, some <code><b>DP</b>ja</code> and <code><b>DQ</b>ia</code> record values, such as those of <code><b>DP</b>ja</code><code><b>.NAXES</b></code> and <code><b>DP</b>ja</code><code><b>.AXIS.</b></code>j, are intrinsically integer-valued. While FITS header parsers are not expected to know in advance which of <code><b>DP</b>ja</code> and <code><b>DQ</b>ia</code> are integral and which are floating point, if the record's value parses as an integer (i.e. without decimal point or exponent), then preferably enter it into the dpkey struct as an integer. Either way, it doesn't matter as <a class="el" href="dis_8h.html#ad1bdf4497eb4513ca8431e1baa419041" title="Setup routine for the disprm struct.">disset()</a> accepts either data type for all record values.</p>
<dl class="params"><dt>Parameters</dt><dd>
<table class="params">
<tr><td class="paramdir">[in,out]</td><td class="paramname">dp</td><td>Store for <code><b>DP</b>ja</code> and <code><b>DQ</b>ia</code> keyvalues.</td></tr>
<tr><td class="paramdir">[in]</td><td class="paramname">keyword</td><td></td></tr>
<tr><td class="paramdir">[in]</td><td class="paramname">field</td><td>These arguments are concatenated with an intervening "." to construct the full record field name, i.e. including the keyword name, <code><b>DP</b>ja</code> or <code><b>DQ</b>ia</code> (but excluding the colon delimiter which is NOT part of the name). Either may be given as a NULL pointer. Set both NULL to omit setting this component of the struct. </td></tr>
<tr><td class="paramdir">[in]</td><td class="paramname">j</td><td>Axis number (1-relative), i.e. the j in <code><b>DP</b>ja</code> or i in <code><b>DQ</b>ia</code>. Can be given as 0, in which case the axis number will be obtained from the keyword component of the field name which must either have been given or preset. <br />
If j is non-zero, and keyword was given, then the value of j will be used to fill in the axis number. </td></tr>
<tr><td class="paramdir">[in]</td><td class="paramname">type</td><td>Data type of the record's value<ul>
<li>0: Integer,</li>
<li>1: Floating point. </li>
</ul>
</td></tr>
<tr><td class="paramdir">[in]</td><td class="paramname">i</td><td>For type == 0, the integer value of the record. </td></tr>
<tr><td class="paramdir">[in]</td><td class="paramname">f</td><td>For type == 1, the floating point value of the record.</td></tr>
</table>
</dd>
</dl>
<dl class="section return"><dt>Returns</dt><dd>Status return value:<ul>
<li>0: Success. </li>
</ul>
</dd></dl>
</div>
</div>
<a id="a5fab5cff95ef5e505314a6fb67325074" name="a5fab5cff95ef5e505314a6fb67325074"></a>
<h2 class="memtitle"><span class="permalink"><a href="#a5fab5cff95ef5e505314a6fb67325074">◆ </a></span>dpkeyi()</h2>
<div class="memitem">
<div class="memproto">
<table class="memname">
<tr>
<td class="memname">int dpkeyi </td>
<td>(</td>
<td class="paramtype">const struct <a class="el" href="structdpkey.html">dpkey</a> * </td>
<td class="paramname"><em>dp</em></td><td>)</td>
<td></td>
</tr>
</table>
</div><div class="memdoc">
<p>Get the data value in a dpkey struct as int. </p>
<p><b>dpkeyi</b>() returns the data value in a dpkey struct as an integer value.</p>
<dl class="params"><dt>Parameters</dt><dd>
<table class="params">
<tr><td class="paramdir">[in,out]</td><td class="paramname">dp</td><td>Parsed contents of a <code><b>DP</b>ja</code> or <code><b>DQ</b>ia</code> keyrecord.</td></tr>
</table>
</dd>
</dl>
<dl class="section return"><dt>Returns</dt><dd>The record's value as int. </dd></dl>
</div>
</div>
<a id="a2181881844241449382477a5c2723082" name="a2181881844241449382477a5c2723082"></a>
<h2 class="memtitle"><span class="permalink"><a href="#a2181881844241449382477a5c2723082">◆ </a></span>dpkeyd()</h2>
<div class="memitem">
<div class="memproto">
<table class="memname">
<tr>
<td class="memname">double dpkeyd </td>
<td>(</td>
<td class="paramtype">const struct <a class="el" href="structdpkey.html">dpkey</a> * </td>
<td class="paramname"><em>dp</em></td><td>)</td>
<td></td>
</tr>
</table>
</div><div class="memdoc">
<p>Get the data value in a dpkey struct as double. </p>
<p><b>dpkeyd</b>() returns the data value in a dpkey struct as a floating point value.</p>
<dl class="params"><dt>Parameters</dt><dd>
<table class="params">
<tr><td class="paramdir">[in,out]</td><td class="paramname">dp</td><td>Parsed contents of a <code><b>DP</b>ja</code> or <code><b>DQ</b>ia</code> keyrecord.</td></tr>
</table>
</dd>
</dl>
<dl class="section return"><dt>Returns</dt><dd>The record's value as double. </dd></dl>
</div>
</div>
<a id="a8896e2a5330e55cd85da4a28ed6ee463" name="a8896e2a5330e55cd85da4a28ed6ee463"></a>
<h2 class="memtitle"><span class="permalink"><a href="#a8896e2a5330e55cd85da4a28ed6ee463">◆ </a></span>disini()</h2>
<div class="memitem">
<div class="memproto">
<table class="memname">
<tr>
<td class="memname">int disini </td>
<td>(</td>
<td class="paramtype">int </td>
<td class="paramname"><em>alloc</em>, </td>
</tr>
<tr>
<td class="paramkey"></td>
<td></td>
<td class="paramtype">int </td>
<td class="paramname"><em>naxis</em>, </td>
</tr>
<tr>
<td class="paramkey"></td>
<td></td>
<td class="paramtype">struct <a class="el" href="structdisprm.html">disprm</a> * </td>
<td class="paramname"><em>dis</em> </td>
</tr>
<tr>
<td></td>
<td>)</td>
<td></td><td></td>
</tr>
</table>
</div><div class="memdoc">
<p>Default constructor for the <a class="el" href="structdisprm.html" title="Distortion parameters.">disprm</a> struct. </p>
<p><b>disini</b>() is a thin wrapper on <b>disinit</b>(). It invokes it with ndpmax set to -1 which causes it to use the value of the global variable NDPMAX. It is thereby potentially thread-unsafe if NDPMAX is altered dynamically via <a class="el" href="dis_8h.html#aa5486b870327544f7423ad2751fb4120" title="Memory allocation for DPja and DQia.">disndp()</a>. Use <b>disinit</b>() for a thread-safe alternative in this case. </p>
</div>
</div>
<a id="a3e0e67bdd01c86eede779de63249c703" name="a3e0e67bdd01c86eede779de63249c703"></a>
<h2 class="memtitle"><span class="permalink"><a href="#a3e0e67bdd01c86eede779de63249c703">◆ </a></span>disinit()</h2>
<div class="memitem">
<div class="memproto">
<table class="memname">
<tr>
<td class="memname">int disinit </td>
<td>(</td>
<td class="paramtype">int </td>
<td class="paramname"><em>alloc</em>, </td>
</tr>
<tr>
<td class="paramkey"></td>
<td></td>
<td class="paramtype">int </td>
<td class="paramname"><em>naxis</em>, </td>
</tr>
<tr>
<td class="paramkey"></td>
<td></td>
<td class="paramtype">struct <a class="el" href="structdisprm.html">disprm</a> * </td>
<td class="paramname"><em>dis</em>, </td>
</tr>
<tr>
<td class="paramkey"></td>
<td></td>
<td class="paramtype">int </td>
<td class="paramname"><em>ndpmax</em> </td>
</tr>
<tr>
<td></td>
<td>)</td>
<td></td><td></td>
</tr>
</table>
</div><div class="memdoc">
<p>Default constructor for the <a class="el" href="structdisprm.html" title="Distortion parameters.">disprm</a> struct. </p>
<p><b>disinit</b>() allocates memory for arrays in a <a class="el" href="structdisprm.html" title="Distortion parameters.">disprm</a> struct and sets all members of the struct to default values.</p>
<p><b>PLEASE NOTE:</b> every <a class="el" href="structdisprm.html" title="Distortion parameters.">disprm</a> struct must be initialized by <b>disinit</b>(), possibly repeatedly. On the first invokation, and only the first invokation, <a class="el" href="structdisprm.html#a4d6ba28bee2fc636f4b2b9ca4b50b0a4">disprm::flag</a> must be set to -1 to initialize memory management, regardless of whether <b>disinit</b>() will actually be used to allocate memory.</p>
<dl class="params"><dt>Parameters</dt><dd>
<table class="params">
<tr><td class="paramdir">[in]</td><td class="paramname">alloc</td><td>If true, allocate memory unconditionally for arrays in the <a class="el" href="structdisprm.html" title="Distortion parameters.">disprm</a> struct. <br />
If false, it is assumed that pointers to these arrays have been set by the user except if they are null pointers in which case memory will be allocated for them regardless. (In other words, setting alloc true saves having to initalize these pointers to zero.) </td></tr>
<tr><td class="paramdir">[in]</td><td class="paramname">naxis</td><td>The number of world coordinate axes, used to determine array sizes.</td></tr>
<tr><td class="paramdir">[in,out]</td><td class="paramname">dis</td><td>Distortion function parameters. Note that, in order to initialize memory management <a class="el" href="structdisprm.html#a4d6ba28bee2fc636f4b2b9ca4b50b0a4">disprm::flag</a> must be set to -1 when dis is initialized for the first time (memory leaks may result if it had already been initialized).</td></tr>
<tr><td class="paramdir">[in]</td><td class="paramname">ndpmax</td><td>The number of <code><b>DP</b>ja</code> or <code><b>DQ</b>ia</code> keywords to allocate space for. If set to -1, the value of the global variable NDPMAX will be used. This is potentially thread-unsafe if <a class="el" href="dis_8h.html#aa5486b870327544f7423ad2751fb4120" title="Memory allocation for DPja and DQia.">disndp()</a> is being used dynamically to alter its value.</td></tr>
</table>
</dd>
</dl>
<dl class="section return"><dt>Returns</dt><dd>Status return value:<ul>
<li>0: Success.</li>
<li>1: Null <a class="el" href="structdisprm.html" title="Distortion parameters.">disprm</a> pointer passed.</li>
<li>2: Memory allocation failed.</li>
</ul>
For returns > 1, a detailed error message is set in <a class="el" href="structdisprm.html#a40a81085335f9d9aa617eb9605ae9421">disprm::err</a> if enabled, see <a class="el" href="wcserr_8h.html#a1691b8bd184d40ca6fda255be078fa53" title="Enable/disable error messaging.">wcserr_enable()</a>. </dd></dl>
</div>
</div>
<a id="a42e03676a3def43ef6b936cd7beb4dd5" name="a42e03676a3def43ef6b936cd7beb4dd5"></a>
<h2 class="memtitle"><span class="permalink"><a href="#a42e03676a3def43ef6b936cd7beb4dd5">◆ </a></span>discpy()</h2>
<div class="memitem">
<div class="memproto">
<table class="memname">
<tr>
<td class="memname">int discpy </td>
<td>(</td>
<td class="paramtype">int </td>
<td class="paramname"><em>alloc</em>, </td>
</tr>
<tr>
<td class="paramkey"></td>
<td></td>
<td class="paramtype">const struct <a class="el" href="structdisprm.html">disprm</a> * </td>
<td class="paramname"><em>dissrc</em>, </td>
</tr>
<tr>
<td class="paramkey"></td>
<td></td>
<td class="paramtype">struct <a class="el" href="structdisprm.html">disprm</a> * </td>
<td class="paramname"><em>disdst</em> </td>
</tr>
<tr>
<td></td>
<td>)</td>
<td></td><td></td>
</tr>
</table>
</div><div class="memdoc">
<p>Copy routine for the <a class="el" href="structdisprm.html" title="Distortion parameters.">disprm</a> struct. </p>
<p><b>discpy</b>() does a deep copy of one <a class="el" href="structdisprm.html" title="Distortion parameters.">disprm</a> struct to another, using <a class="el" href="dis_8h.html#a3e0e67bdd01c86eede779de63249c703" title="Default constructor for the disprm struct.">disinit()</a> to allocate memory unconditionally for its arrays if required. Only the "information to be provided" part of the struct is copied; a call to <a class="el" href="dis_8h.html#ad1bdf4497eb4513ca8431e1baa419041" title="Setup routine for the disprm struct.">disset()</a> is required to initialize the remainder.</p>
<dl class="params"><dt>Parameters</dt><dd>
<table class="params">
<tr><td class="paramdir">[in]</td><td class="paramname">alloc</td><td>If true, allocate memory unconditionally for arrays in the destination. Otherwise, it is assumed that pointers to these arrays have been set by the user except if they are null pointers in which case memory will be allocated for them regardless. </td></tr>
<tr><td class="paramdir">[in]</td><td class="paramname">dissrc</td><td>Struct to copy from.</td></tr>
<tr><td class="paramdir">[in,out]</td><td class="paramname">disdst</td><td>Struct to copy to. <a class="el" href="structdisprm.html#a4d6ba28bee2fc636f4b2b9ca4b50b0a4">disprm::flag</a> should be set to -1 if disdst was not previously initialized (memory leaks may result if it was previously initialized).</td></tr>
</table>
</dd>
</dl>
<dl class="section return"><dt>Returns</dt><dd>Status return value:<ul>
<li>0: Success.</li>
<li>1: Null <a class="el" href="structdisprm.html" title="Distortion parameters.">disprm</a> pointer passed.</li>
<li>2: Memory allocation failed.</li>
</ul>
For returns > 1, a detailed error message is set in <a class="el" href="structdisprm.html#a40a81085335f9d9aa617eb9605ae9421">disprm::err</a> if enabled, see <a class="el" href="wcserr_8h.html#a1691b8bd184d40ca6fda255be078fa53" title="Enable/disable error messaging.">wcserr_enable()</a>. </dd></dl>
</div>
</div>
<a id="a83b98d0f6429f4f19024675645026187" name="a83b98d0f6429f4f19024675645026187"></a>
<h2 class="memtitle"><span class="permalink"><a href="#a83b98d0f6429f4f19024675645026187">◆ </a></span>disfree()</h2>
<div class="memitem">
<div class="memproto">
<table class="memname">
<tr>
<td class="memname">int disfree </td>
<td>(</td>
<td class="paramtype">struct <a class="el" href="structdisprm.html">disprm</a> * </td>
<td class="paramname"><em>dis</em></td><td>)</td>
<td></td>
</tr>
</table>
</div><div class="memdoc">
<p>Destructor for the <a class="el" href="structdisprm.html" title="Distortion parameters.">disprm</a> struct. </p>
<p><b>disfree</b>() frees memory allocated for the <a class="el" href="structdisprm.html" title="Distortion parameters.">disprm</a> arrays by <a class="el" href="dis_8h.html#a3e0e67bdd01c86eede779de63249c703" title="Default constructor for the disprm struct.">disinit()</a>. <a class="el" href="dis_8h.html#a3e0e67bdd01c86eede779de63249c703" title="Default constructor for the disprm struct.">disinit()</a> keeps a record of the memory it allocates and <b>disfree</b>() will only attempt to free this.</p>
<p><b>PLEASE NOTE:</b> <b>disfree</b>() must not be invoked on a <a class="el" href="structdisprm.html" title="Distortion parameters.">disprm</a> struct that was not initialized by <a class="el" href="dis_8h.html#a3e0e67bdd01c86eede779de63249c703" title="Default constructor for the disprm struct.">disinit()</a>.</p>
<dl class="params"><dt>Parameters</dt><dd>
<table class="params">
<tr><td class="paramdir">[in]</td><td class="paramname">dis</td><td>Distortion function parameters.</td></tr>
</table>
</dd>
</dl>
<dl class="section return"><dt>Returns</dt><dd>Status return value:<ul>
<li>0: Success.</li>
<li>1: Null <a class="el" href="structdisprm.html" title="Distortion parameters.">disprm</a> pointer passed. </li>
</ul>
</dd></dl>
</div>
</div>
<a id="a6f07892abc6d9d73ee9017750dc7bd8d" name="a6f07892abc6d9d73ee9017750dc7bd8d"></a>
<h2 class="memtitle"><span class="permalink"><a href="#a6f07892abc6d9d73ee9017750dc7bd8d">◆ </a></span>dissize()</h2>
<div class="memitem">
<div class="memproto">
<table class="memname">
<tr>
<td class="memname">int dissize </td>
<td>(</td>
<td class="paramtype">const struct <a class="el" href="structdisprm.html">disprm</a> * </td>
<td class="paramname"><em>dis</em>, </td>
</tr>
<tr>
<td class="paramkey"></td>
<td></td>
<td class="paramtype">int </td>
<td class="paramname"><em>sizes</em>[2] </td>
</tr>
<tr>
<td></td>
<td>)</td>
<td></td><td></td>
</tr>
</table>
</div><div class="memdoc">
<p>Compute the size of a <a class="el" href="structdisprm.html" title="Distortion parameters.">disprm</a> struct. </p>
<p><b>dissize</b>() computes the full size of a <a class="el" href="structdisprm.html" title="Distortion parameters.">disprm</a> struct, including allocated memory.</p>
<dl class="params"><dt>Parameters</dt><dd>
<table class="params">
<tr><td class="paramdir">[in]</td><td class="paramname">dis</td><td>Distortion function parameters. <br />
If NULL, the base size of the struct and the allocated size are both set to zero.</td></tr>
<tr><td class="paramdir">[out]</td><td class="paramname">sizes</td><td>The first element is the base size of the struct as returned by sizeof(struct <a class="el" href="structdisprm.html" title="Distortion parameters.">disprm</a>). The second element is the total allocated size, in bytes, assuming that the allocation was done by <a class="el" href="dis_8h.html#a8896e2a5330e55cd85da4a28ed6ee463" title="Default constructor for the disprm struct.">disini()</a>. This figure includes memory allocated for members of constituent structs, such as <a class="el" href="structdisprm.html#a71567452603ef3effc07877e7366a5b2">disprm::dp</a>. <br />
It is not an error for the struct not to have been set up via <a class="el" href="tab_8h.html#a519e8e4503f7c41c0f99e8597171c97f" title="Setup routine for the tabprm struct.">tabset()</a>, which normally results in additional memory allocation.</td></tr>
</table>
</dd>
</dl>
<dl class="section return"><dt>Returns</dt><dd>Status return value:<ul>
<li>0: Success. </li>
</ul>
</dd></dl>
</div>
</div>
<a id="aeee35e0d5183e74f20c64526d908886b" name="aeee35e0d5183e74f20c64526d908886b"></a>
<h2 class="memtitle"><span class="permalink"><a href="#aeee35e0d5183e74f20c64526d908886b">◆ </a></span>disprt()</h2>
<div class="memitem">
<div class="memproto">
<table class="memname">
<tr>
<td class="memname">int disprt </td>
<td>(</td>
<td class="paramtype">const struct <a class="el" href="structdisprm.html">disprm</a> * </td>
<td class="paramname"><em>dis</em></td><td>)</td>
<td></td>
</tr>
</table>
</div><div class="memdoc">
<p>Print routine for the <a class="el" href="structdisprm.html" title="Distortion parameters.">disprm</a> struct. </p>
<p><b>disprt</b>() prints the contents of a <a class="el" href="structdisprm.html" title="Distortion parameters.">disprm</a> struct using <a class="el" href="wcsprintf_8h.html#a46950abaf5a27347da8160741f98f973" title="Print function used by WCSLIB diagnostic routines.">wcsprintf()</a>. Mainly intended for diagnostic purposes.</p>
<dl class="params"><dt>Parameters</dt><dd>
<table class="params">
<tr><td class="paramdir">[in]</td><td class="paramname">dis</td><td>Distortion function parameters.</td></tr>
</table>
</dd>
</dl>
<dl class="section return"><dt>Returns</dt><dd>Status return value:<ul>
<li>0: Success.</li>
<li>1: Null <a class="el" href="structdisprm.html" title="Distortion parameters.">disprm</a> pointer passed. </li>
</ul>
</dd></dl>
</div>
</div>
<a id="acc9e98282026d5a249c450f2d2c0f2f4" name="acc9e98282026d5a249c450f2d2c0f2f4"></a>
<h2 class="memtitle"><span class="permalink"><a href="#acc9e98282026d5a249c450f2d2c0f2f4">◆ </a></span>disperr()</h2>
<div class="memitem">
<div class="memproto">
<table class="memname">
<tr>
<td class="memname">int disperr </td>
<td>(</td>
<td class="paramtype">const struct <a class="el" href="structdisprm.html">disprm</a> * </td>
<td class="paramname"><em>dis</em>, </td>
</tr>
<tr>
<td class="paramkey"></td>
<td></td>
<td class="paramtype">const char * </td>
<td class="paramname"><em>prefix</em> </td>
</tr>
<tr>
<td></td>
<td>)</td>
<td></td><td></td>
</tr>
</table>
</div><div class="memdoc">
<p>Print error messages from a <a class="el" href="structdisprm.html" title="Distortion parameters.">disprm</a> struct. </p>
<p><b>disperr</b>() prints the error message(s) (if any) stored in a <a class="el" href="structdisprm.html" title="Distortion parameters.">disprm</a> struct. If there are no errors then nothing is printed. It uses <a class="el" href="wcserr_8h.html#a6585b9fc3a59b369e3336f3133dd1ca9" title="Print a wcserr struct.">wcserr_prt()</a>, q.v.</p>
<dl class="params"><dt>Parameters</dt><dd>
<table class="params">
<tr><td class="paramdir">[in]</td><td class="paramname">dis</td><td>Distortion function parameters. </td></tr>
<tr><td class="paramdir">[in]</td><td class="paramname">prefix</td><td>If non-NULL, each output line will be prefixed with this string.</td></tr>
</table>
</dd>
</dl>
<dl class="section return"><dt>Returns</dt><dd>Status return value:<ul>
<li>0: Success.</li>
<li>1: Null <a class="el" href="structdisprm.html" title="Distortion parameters.">disprm</a> pointer passed. </li>
</ul>
</dd></dl>
</div>
</div>
<a id="ab69a8e21c3a3b7409458f681bd6ac888" name="ab69a8e21c3a3b7409458f681bd6ac888"></a>
<h2 class="memtitle"><span class="permalink"><a href="#ab69a8e21c3a3b7409458f681bd6ac888">◆ </a></span>dishdo()</h2>
<div class="memitem">
<div class="memproto">
<table class="memname">
<tr>
<td class="memname">int dishdo </td>
<td>(</td>
<td class="paramtype">struct <a class="el" href="structdisprm.html">disprm</a> * </td>
<td class="paramname"><em>dis</em></td><td>)</td>
<td></td>
</tr>
</table>
</div><div class="memdoc">
<p>write FITS headers using <code><b>TPD</b></code>. </p>
<p><b>dishdo</b>() sets a flag that tells <a class="el" href="wcshdr_8h.html#ace387e4a5f6c519ad2a0e1fdebe62381" title="Write out a wcsprm struct as a FITS header.">wcshdo()</a> to write FITS headers in the form of the <code><b>TPD</b></code> translation used internally. Normally <code><b>SIP</b></code> and <code><b>TPV</b></code> would be written in their native form if at all possible.</p>
<dl class="params"><dt>Parameters</dt><dd>
<table class="params">
<tr><td class="paramdir">[in,out]</td><td class="paramname">dis</td><td>Distortion function parameters.</td></tr>
</table>
</dd>
</dl>
<dl class="section return"><dt>Returns</dt><dd>Status return value:<ul>
<li>0: Success.</li>
<li>1: Null <a class="el" href="structdisprm.html" title="Distortion parameters.">disprm</a> pointer passed.</li>
<li>3: No <code><b>TPD</b></code> translation. </li>
</ul>
</dd></dl>
</div>
</div>
<a id="ad1bdf4497eb4513ca8431e1baa419041" name="ad1bdf4497eb4513ca8431e1baa419041"></a>
<h2 class="memtitle"><span class="permalink"><a href="#ad1bdf4497eb4513ca8431e1baa419041">◆ </a></span>disset()</h2>
<div class="memitem">
<div class="memproto">
<table class="memname">
<tr>
<td class="memname">int disset </td>
<td>(</td>
<td class="paramtype">struct <a class="el" href="structdisprm.html">disprm</a> * </td>
<td class="paramname"><em>dis</em></td><td>)</td>
<td></td>
</tr>
</table>
</div><div class="memdoc">
<p>Setup routine for the <a class="el" href="structdisprm.html" title="Distortion parameters.">disprm</a> struct. </p>
<p><b>disset</b>(), sets up the <a class="el" href="structdisprm.html" title="Distortion parameters.">disprm</a> struct according to information supplied within it - refer to the explanation of <a class="el" href="structdisprm.html#a4d6ba28bee2fc636f4b2b9ca4b50b0a4">disprm::flag</a>.</p>
<p>Note that this routine need not be called directly; it will be invoked by <a class="el" href="dis_8h.html#a135726e4c4c5bc00e2eba865ab202201" title="Apply distortion function.">disp2x()</a> and <a class="el" href="dis_8h.html#ac589d5e85afe3d775cba4c06734ce653" title="Apply de-distortion function.">disx2p()</a> if the <a class="el" href="structdisprm.html#a4d6ba28bee2fc636f4b2b9ca4b50b0a4">disprm::flag</a> is anything other than a predefined magic value.</p>
<dl class="params"><dt>Parameters</dt><dd>
<table class="params">
<tr><td class="paramdir">[in,out]</td><td class="paramname">dis</td><td>Distortion function parameters.</td></tr>
</table>
</dd>
</dl>
<dl class="section return"><dt>Returns</dt><dd>Status return value:<ul>
<li>0: Success.</li>
<li>1: Null <a class="el" href="structdisprm.html" title="Distortion parameters.">disprm</a> pointer passed.</li>
<li>2: Memory allocation failed.</li>
<li>3: Invalid parameter.</li>
</ul>
For returns > 1, a detailed error message is set in <a class="el" href="structdisprm.html#a40a81085335f9d9aa617eb9605ae9421">disprm::err</a> if enabled, see <a class="el" href="wcserr_8h.html#a1691b8bd184d40ca6fda255be078fa53" title="Enable/disable error messaging.">wcserr_enable()</a>. </dd></dl>
</div>
</div>
<a id="a135726e4c4c5bc00e2eba865ab202201" name="a135726e4c4c5bc00e2eba865ab202201"></a>
<h2 class="memtitle"><span class="permalink"><a href="#a135726e4c4c5bc00e2eba865ab202201">◆ </a></span>disp2x()</h2>
<div class="memitem">
<div class="memproto">
<table class="memname">
<tr>
<td class="memname">int disp2x </td>
<td>(</td>
<td class="paramtype">struct <a class="el" href="structdisprm.html">disprm</a> * </td>
<td class="paramname"><em>dis</em>, </td>
</tr>
<tr>
<td class="paramkey"></td>
<td></td>
<td class="paramtype">const double </td>
<td class="paramname"><em>rawcrd</em>[], </td>
</tr>
<tr>
<td class="paramkey"></td>
<td></td>
<td class="paramtype">double </td>
<td class="paramname"><em>discrd</em>[] </td>
</tr>
<tr>
<td></td>
<td>)</td>
<td></td><td></td>
</tr>
</table>
</div><div class="memdoc">
<p>Apply distortion function. </p>
<p><b>disp2x</b>() applies the distortion functions. By definition, the distortion is in the pixel-to-world direction.</p>
<p>Depending on the point in the algorithm chain at which it is invoked, <b>disp2x</b>() may transform pixel coordinates to corrected pixel coordinates, or intermediate pixel coordinates to corrected intermediate pixel coordinates, or image coordinates to corrected image coordinates. </p>
</div>
</div>
<a id="ac589d5e85afe3d775cba4c06734ce653" name="ac589d5e85afe3d775cba4c06734ce653"></a>
<h2 class="memtitle"><span class="permalink"><a href="#ac589d5e85afe3d775cba4c06734ce653">◆ </a></span>disx2p()</h2>
<div class="memitem">
<div class="memproto">
<table class="memname">
<tr>
<td class="memname">int disx2p </td>
<td>(</td>
<td class="paramtype">struct <a class="el" href="structdisprm.html">disprm</a> * </td>
<td class="paramname"><em>dis</em>, </td>
</tr>
<tr>
<td class="paramkey"></td>
<td></td>
<td class="paramtype">const double </td>
<td class="paramname"><em>discrd</em>[], </td>
</tr>
<tr>
<td class="paramkey"></td>
<td></td>
<td class="paramtype">double </td>
<td class="paramname"><em>rawcrd</em>[] </td>
</tr>
<tr>
<td></td>
<td>)</td>
<td></td><td></td>
</tr>
</table>
</div><div class="memdoc">
<p>Apply de-distortion function. </p>
<p><b>disx2p</b>() applies the inverse of the distortion functions. By definition, the de-distortion is in the world-to-pixel direction.</p>
<p>Depending on the point in the algorithm chain at which it is invoked, <b>disx2p</b>() may transform corrected pixel coordinates to pixel coordinates, or corrected intermediate pixel coordinates to intermediate pixel coordinates, or corrected image coordinates to image coordinates.</p>
<p><b>disx2p</b>() iteratively solves for the inverse using <a class="el" href="dis_8h.html#a135726e4c4c5bc00e2eba865ab202201" title="Apply distortion function.">disp2x()</a>. It assumes that the distortion is small and the functions are well-behaved, being continuous and with continuous derivatives. Also that, to first order in the neighbourhood of the solution, discrd[j] ~= a + b*rawcrd[j], i.e. independent of rawcrd[i], where i != j. This is effectively equivalent to assuming that the distortion functions are separable to first order. Furthermore, a is assumed to be small, and b close to unity.</p>
<p>If <a class="el" href="structdisprm.html" title="Distortion parameters.">disprm</a>::<b>disx2p</b>() is defined, then <b>disx2p</b>() uses it to provide an initial estimate for its more precise iterative inversion.</p>
<dl class="params"><dt>Parameters</dt><dd>
<table class="params">
<tr><td class="paramdir">[in,out]</td><td class="paramname">dis</td><td>Distortion function parameters.</td></tr>
<tr><td class="paramdir">[in]</td><td class="paramname">discrd</td><td>Array of coordinates.</td></tr>
<tr><td class="paramdir">[out]</td><td class="paramname">rawcrd</td><td>Array of coordinates to which the inverse distortion functions have been applied.</td></tr>
</table>
</dd>
</dl>
<dl class="section return"><dt>Returns</dt><dd>Status return value:<ul>
<li>0: Success.</li>
<li>1: Null <a class="el" href="structdisprm.html" title="Distortion parameters.">disprm</a> pointer passed.</li>
<li>2: Memory allocation failed.</li>
<li>3: Invalid parameter.</li>
<li>5: De-distort error.</li>
</ul>
For returns > 1, a detailed error message is set in <a class="el" href="structdisprm.html#a40a81085335f9d9aa617eb9605ae9421">disprm::err</a> if enabled, see <a class="el" href="wcserr_8h.html#a1691b8bd184d40ca6fda255be078fa53" title="Enable/disable error messaging.">wcserr_enable()</a>. </dd></dl>
</div>
</div>
<a id="a91fa2d34c30be042516a0246d393b116" name="a91fa2d34c30be042516a0246d393b116"></a>
<h2 class="memtitle"><span class="permalink"><a href="#a91fa2d34c30be042516a0246d393b116">◆ </a></span>diswarp()</h2>
<div class="memitem">
<div class="memproto">
<table class="memname">
<tr>
<td class="memname">int diswarp </td>
<td>(</td>
<td class="paramtype">struct <a class="el" href="structdisprm.html">disprm</a> * </td>
<td class="paramname"><em>dis</em>, </td>
</tr>
<tr>
<td class="paramkey"></td>
<td></td>
<td class="paramtype">const double </td>
<td class="paramname"><em>pixblc</em>[], </td>
</tr>
<tr>
<td class="paramkey"></td>
<td></td>
<td class="paramtype">const double </td>
<td class="paramname"><em>pixtrc</em>[], </td>
</tr>
<tr>
<td class="paramkey"></td>
<td></td>
<td class="paramtype">const double </td>
<td class="paramname"><em>pixsamp</em>[], </td>
</tr>
<tr>
<td class="paramkey"></td>
<td></td>
<td class="paramtype">int * </td>
<td class="paramname"><em>nsamp</em>, </td>
</tr>
<tr>
<td class="paramkey"></td>
<td></td>
<td class="paramtype">double </td>
<td class="paramname"><em>maxdis</em>[], </td>
</tr>
<tr>
<td class="paramkey"></td>
<td></td>
<td class="paramtype">double * </td>
<td class="paramname"><em>maxtot</em>, </td>
</tr>
<tr>
<td class="paramkey"></td>
<td></td>
<td class="paramtype">double </td>
<td class="paramname"><em>avgdis</em>[], </td>
</tr>
<tr>
<td class="paramkey"></td>
<td></td>
<td class="paramtype">double * </td>
<td class="paramname"><em>avgtot</em>, </td>
</tr>
<tr>
<td class="paramkey"></td>
<td></td>
<td class="paramtype">double </td>
<td class="paramname"><em>rmsdis</em>[], </td>
</tr>
<tr>
<td class="paramkey"></td>
<td></td>
<td class="paramtype">double * </td>
<td class="paramname"><em>rmstot</em> </td>
</tr>
<tr>
<td></td>
<td>)</td>
<td></td><td></td>
</tr>
</table>
</div><div class="memdoc">
<p>Compute measures of distortion. </p>
<p><b>diswarp</b>() computes various measures of the distortion over a specified range of coordinates.</p>
<p>For prior distortions, the measures may be interpreted simply as an offset in pixel coordinates. For sequent distortions, the interpretation depends on the nature of the linear transformation matrix (<code><b>PC</b>i<b>_</b>ja</code> or <code><b>CD</b>i<b>_</b>ja</code>). If the latter introduces a scaling, then the measures will also be scaled. Note also that the image domain, which is rectangular in pixel coordinates, may be rotated, skewed, and/or stretched in intermediate pixel coordinates, and in general cannot be defined using pixblc[] and pixtrc[].</p>
<p><b>PLEASE NOTE:</b> the measures of total distortion may be essentially meaningless if there are multiple sequent distortions with different scaling.</p>
<p>See also <a class="el" href="lin_8h.html#a27a7a4a2cc3183bb1cd639efaade2265" title="Compute measures of distortion.">linwarp()</a>.</p>
<dl class="params"><dt>Parameters</dt><dd>
<table class="params">
<tr><td class="paramdir">[in,out]</td><td class="paramname">dis</td><td>Distortion function parameters.</td></tr>
<tr><td class="paramdir">[in]</td><td class="paramname">pixblc</td><td>Start of the range of pixel coordinates (for prior distortions), or intermediate pixel coordinates (for sequent distortions). May be specified as a NULL pointer which is interpreted as (1,1,...). </td></tr>
<tr><td class="paramdir">[in]</td><td class="paramname">pixtrc</td><td>End of the range of pixel coordinates (prior) or intermediate pixel coordinates (sequent). </td></tr>
<tr><td class="paramdir">[in]</td><td class="paramname">pixsamp</td><td>If positive or zero, the increment on the particular axis, starting at pixblc[]. Zero is interpreted as a unit increment. pixsamp may also be specified as a NULL pointer which is interpreted as all zeroes, i.e. unit increments on all axes. <br />
If negative, the grid size on the particular axis (the absolute value being rounded to the nearest integer). For example, if pixsamp is (-128.0,-128.0,...) then each axis will be sampled at 128 points between pixblc[] and pixtrc[] inclusive. Use caution when using this option on non-square images.</td></tr>
<tr><td class="paramdir">[out]</td><td class="paramname">nsamp</td><td>The number of pixel coordinates sampled. <br />
Can be specified as a NULL pointer if not required. </td></tr>
<tr><td class="paramdir">[out]</td><td class="paramname">maxdis</td><td>For each individual distortion function, the maximum absolute value of the distortion. <br />
Can be specified as a NULL pointer if not required. </td></tr>
<tr><td class="paramdir">[out]</td><td class="paramname">maxtot</td><td>For the combination of all distortion functions, the maximum absolute value of the distortion. <br />
Can be specified as a NULL pointer if not required. </td></tr>
<tr><td class="paramdir">[out]</td><td class="paramname">avgdis</td><td>For each individual distortion function, the mean value of the distortion. <br />
Can be specified as a NULL pointer if not required. </td></tr>
<tr><td class="paramdir">[out]</td><td class="paramname">avgtot</td><td>For the combination of all distortion functions, the mean value of the distortion. <br />
Can be specified as a NULL pointer if not required. </td></tr>
<tr><td class="paramdir">[out]</td><td class="paramname">rmsdis</td><td>For each individual distortion function, the root mean square deviation of the distortion. <br />
Can be specified as a NULL pointer if not required. </td></tr>
<tr><td class="paramdir">[out]</td><td class="paramname">rmstot</td><td>For the combination of all distortion functions, the root mean square deviation of the distortion. <br />
Can be specified as a NULL pointer if not required.</td></tr>
</table>
</dd>
</dl>
<dl class="section return"><dt>Returns</dt><dd>Status return value:<ul>
<li>0: Success.</li>
<li>1: Null <a class="el" href="structdisprm.html" title="Distortion parameters.">disprm</a> pointer passed.</li>
<li>2: Memory allocation failed.</li>
<li>3: Invalid parameter.</li>
<li>4: Distort error. </li>
</ul>
</dd></dl>
</div>
</div>
<h2 class="groupheader">Variable Documentation</h2>
<a id="a6f125a402553f5dab46435299f0742a3" name="a6f125a402553f5dab46435299f0742a3"></a>
<h2 class="memtitle"><span class="permalink"><a href="#a6f125a402553f5dab46435299f0742a3">◆ </a></span>dis_errmsg</h2>
<div class="memitem">
<div class="memproto">
<table class="mlabels">
<tr>
<td class="mlabels-left">
<table class="memname">
<tr>
<td class="memname">const char * dis_errmsg[]</td>
</tr>
</table>
</td>
<td class="mlabels-right">
<span class="mlabels"><span class="mlabel">extern</span></span> </td>
</tr>
</table>
</div><div class="memdoc">
<p>Status return messages. </p>
<p>Error messages to match the status value returned from each function. </p>
</div>
</div>
</div><!-- contents -->
<!-- start footer part -->
<hr class="footer"/><address class="footer"><small>
Generated on Wed Nov 29 2023 19:09:57 for WCSLIB by <a href="https://www.doxygen.org/index.html"><img class="footer" src="doxygen.svg" width="104" height="31" alt="doxygen"/></a> 1.9.8
</small></address>
</body>
</html>
Browse
Usage
Versions