<!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: Vector API</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">Vector API </div> </div>
</div><!--header-->
<div class="contents">
<div class="textblock"><p>WCSLIB's API is vector-oriented. At the least, this allows the function call overhead to be amortised by spreading it over multiple coordinate transformations. However, vector computations may provide an opportunity for caching intermediate calculations and this can produce much more significant efficiencies. For example, many of the spherical projection equations are partially or fully separable in the mathematical sense, i.e. <img class="formulaInl" alt="$ (x,y) = f(\phi) g(\theta) $" src="form_17.png"/>, so if <img class="formulaInl" alt="$ \theta $" src="form_18.png"/> was invariant for a set of coordinate transformations then <img class="formulaInl" alt="$ g(\theta) $" src="form_19.png"/> would only need to be computed once. Depending on the circumstances, this may well lead to speedups of a factor of two or more.</p>
<p>WCSLIB has two different categories of vector API:</p>
<ul>
<li>Certain steps in the WCS algorithm chain operate on coordinate vectors as a whole rather than particular elements of it. For example, the linear transformation takes one or more pixel coordinate vectors, multiples by the transformation matrix, and returns whole intermediate world coordinate vectors. <br/>
The routines that implement these steps, <a class="el" href="wcs_8h.html#a27d3dd209db3e76cf4c50f48c01ba986" title="Pixel-to-world transformation. ">wcsp2s()</a>, <a class="el" href="wcs_8h.html#a60673d05a3513659ac848a9cb3d0cb07" title="World-to-pixel transformation. ">wcss2p()</a>, <a class="el" href="lin_8h.html#ae4947608476c198ad27759d1e562d655" title="Pixel-to-world linear transformation. ">linp2x()</a>, <a class="el" href="lin_8h.html#a5490027e9699680dfefe370c28691243" title="World-to-pixel linear transformation. ">linx2p()</a>, <a class="el" href="tab_8h.html#a006d6e8cb373e0dc3e9ccf128adb9411" title="Pixel-to-world transformation. ">tabx2s()</a>, and <a class="el" href="tab_8h.html#aaded7db92aa2758198b33f35f5f18d6e" title="World-to-pixel transformation. ">tabs2x()</a>, accept and return two-dimensional arrays, i.e. a number of coordinate vectors. Because WCSLIB permits these arrays to contain unused elements, three parameters are needed to describe them:<ul>
<li><em>naxis:</em> the number of coordinate elements, as per the FITS <code>NAXIS</code> or <code>WCSAXES</code> keyvalues,</li>
<li><em>ncoord:</em> the number of coordinate vectors,</li>
<li><em>nelem:</em> the total number of elements in each vector, unused as well as used. Clearly, <em>nelem</em> must equal or exceed <em>naxis</em>. (Note that when <em>ncoord</em> is unity, <em>nelem</em> is irrelevant and so is ignored. It may be set to 0.)</li>
</ul>
<em>ncoord</em> and <em>nelem</em> are specified as function arguments while <em>naxis</em> is provided as a member of the wcsprm (or linprm) struct. <br/>
For example, <a class="el" href="wcs_8h.html#a60673d05a3513659ac848a9cb3d0cb07" title="World-to-pixel transformation. ">wcss2p()</a> accepts an array of world coordinate vectors, <em>world[ncoord][nelem]</em>. In the following example, <em>naxis</em> = 4, <em>ncoord</em> = 5, and <em>nelem</em> = 7: <pre class="fragment"> s1 x1 y1 t1 u u u
s2 x2 y2 t2 u u u
s3 x3 y3 t3 u u u
s4 x4 y4 t4 u u u
s5 x5 y5 t5 u u u</pre> where <em>u</em> indicates unused array elements, and the array is laid out in memory as <pre class="fragment"> s1 x1 y1 t1 u u u s2 x2 y2 ...</pre> <b>Note</b> that the <em>stat[]</em> vector returned by routines in this category is of length <em>ncoord</em>, as are the intermediate <em>phi[]</em> and <em>theta[]</em> vectors returned by <a class="el" href="wcs_8h.html#a27d3dd209db3e76cf4c50f48c01ba986" title="Pixel-to-world transformation. ">wcsp2s()</a> and <a class="el" href="wcs_8h.html#a60673d05a3513659ac848a9cb3d0cb07" title="World-to-pixel transformation. ">wcss2p()</a>. <br/>
<b>Note</b> also that the function prototypes for routines in this category have to declare these two-dimensional arrays as one-dimensional vectors in order to avoid warnings from the C compiler about declaration of "incomplete
types". This was considered preferable to declaring them as simple pointers-to-double which gives no indication that storage is associated with them.</li>
<li>Other steps in the WCS algorithm chain typically operate only on a part of the coordinate vector. For example, a spectral transformation operates on only one element of an intermediate world coordinate that may also contain celestial coordinate elements. In the above example, <a class="el" href="spc_8h.html#ae7fe86ae85a1a3bd19c2d78c3dba58f6" title="Transform to spectral coordinates. ">spcx2s()</a> might operate only on the <em>s</em> (spectral) coordinate elements. <br/>
Routines like <a class="el" href="spc_8h.html#ae7fe86ae85a1a3bd19c2d78c3dba58f6" title="Transform to spectral coordinates. ">spcx2s()</a> and <a class="el" href="cel_8h.html#a1fe7f134670262eb54b6049c0275a27b" title="Pixel-to-world celestial transformation. ">celx2s()</a> that implement these steps accept and return one-dimensional vectors in which the coordinate element of interest is specified via a starting address, a length, and a stride. To continue the previous example, the starting address for the spectral elements is <em>s1</em>, the length is 5, and the stride is 7.</li>
</ul>
<h1><a class="anchor" id="lengths"></a>
Vector lengths</h1>
<p>Routines such as <a class="el" href="spc_8h.html#ae7fe86ae85a1a3bd19c2d78c3dba58f6" title="Transform to spectral coordinates. ">spcx2s()</a> and <a class="el" href="cel_8h.html#a1fe7f134670262eb54b6049c0275a27b" title="Pixel-to-world celestial transformation. ">celx2s()</a> accept and return either one coordinate vector, or a pair of coordinate vectors (one-dimensional C arrays). As explained above, the coordinate elements of interest are usually embedded in a two-dimensional array and must be selected by specifying a starting point, length and stride through the array. For routines such as <a class="el" href="spc_8h.html#ae7fe86ae85a1a3bd19c2d78c3dba58f6" title="Transform to spectral coordinates. ">spcx2s()</a> that operate on a single element of each coordinate vector these parameters have a straightforward interpretation.</p>
<p>However, for routines such as <a class="el" href="cel_8h.html#a1fe7f134670262eb54b6049c0275a27b" title="Pixel-to-world celestial transformation. ">celx2s()</a> that operate on a pair of elements in each coordinate vector, WCSLIB allows these parameters to be specified independently for each input vector, thereby providing a much more general interpretation than strictly needed to traverse an array.</p>
<p>This is best described by illustration. The following diagram describes the situation for <a class="el" href="cel_8h.html#a6661c05703158b0808038b7d551f1ea1" title="World-to-pixel celestial transformation. ">cels2x()</a>, as a specific example, with <em>nlng = 5</em>, and <em>nlat = 3:</em></p>
<pre class="fragment"> lng[0] lng[1] lng[2] lng[3] lng[4]
------ ------ ------ ------ ------
lat[0] | x,y[0] x,y[1] x,y[2] x,y[3] x,y[4]
lat[1] | x,y[5] x,y[6] x,y[7] x,y[8] x,y[9]
lat[2] | x,y[10] x,y[11] x,y[12] x,y[13] x,y[14]
</pre><p>In this case, while only 5 longitude elements and 3 latitude elements are specified, the world-to-pixel routine would calculate <em>nlng * nlat = 15 (x,y)</em> coordinate pairs. It is the responsibility of the caller to ensure that sufficient space has been allocated in <em><b>all</b></em> of the output arrays, in this case <em>phi[]</em>, <em>theta[]</em>, <em>x[]</em>, <em>y[]</em> and <em>stat[]</em>.</p>
<p>Vector computation will often be required where neither <em>lng</em> nor <em>lat</em> is constant. This is accomplished by setting <em>nlat</em> = 0 which is interpreted to mean <em>nlat = nlng</em> but only the matrix diagonal is to be computed. Thus, for <em>nlng = 3</em> and <em>nlat = 0</em> only three <em>(x,y)</em> coordinate pairs are computed:</p>
<pre class="fragment"> lng[0] lng[1] lng[2]
------ ------ ------
lat[0] | x,y[0]
lat[1] | x,y[1]
lat[2] | x,y[2]
</pre><p>Note how this differs from <em>nlng = 3, nlat = 1</em>:</p>
<pre class="fragment"> lng[0] lng[1] lng[2]
------ ------ ------
lat[0] | x,y[0] x,y[1] x,y[2]
</pre><p>The situation for <a class="el" href="cel_8h.html#a1fe7f134670262eb54b6049c0275a27b" title="Pixel-to-world celestial transformation. ">celx2s()</a> is similar; the <em>x</em>-coordinate (like <em>lng</em>) varies fastest.</p>
<p>Similar comments can be made for all routines that accept arguments specifying vector length(s) and stride(s). (<a class="el" href="tab_8h.html#a006d6e8cb373e0dc3e9ccf128adb9411" title="Pixel-to-world transformation. ">tabx2s()</a> and <a class="el" href="tab_8h.html#aaded7db92aa2758198b33f35f5f18d6e" title="World-to-pixel transformation. ">tabs2x()</a> do not fall into this category because the <code>-TAB</code> algorithm is fully <em>N</em>-dimensional so there is no way to know in advance how many coordinate elements may be involved.)</p>
<p>The reason that WCSLIB allows this generality is related to the aforementioned opportunities that vector computations may provide for caching intermediate calculations and the significant efficiencies that can result. The high-level routines, <a class="el" href="wcs_8h.html#a27d3dd209db3e76cf4c50f48c01ba986" title="Pixel-to-world transformation. ">wcsp2s()</a> and <a class="el" href="wcs_8h.html#a60673d05a3513659ac848a9cb3d0cb07" title="World-to-pixel transformation. ">wcss2p()</a>, look for opportunities to collapse a set of coordinate transformations where one of the coordinate elements is invariant, and the low-level routines take advantage of such to cache intermediate calculations.</p>
<h1><a class="anchor" id="strides"></a>
Vector strides</h1>
<p>As explained above, the vector stride arguments allow the caller to specify that successive elements of a vector are not contiguous in memory. This applies equally to vectors given to, or returned from a function.</p>
<p>As a further example consider the following two arrangements in memory of the elements of four <em>(x,y)</em> coordinate pairs together with an <em>s</em> coordinate element (e.g. spectral):</p>
<ul>
<li><em>x1 x2 x3 x4 y1 y2 y3 y4 s1 s2 s3 s4</em> <br/>
the address of <em>x[]</em> is <em>x1</em>, its stride is 1, and length 4, <br/>
the address of <em>y[]</em> is <em>y1</em>, its stride is 1, and length 4, <br/>
the address of <em>s[]</em> is <em>s1</em>, its stride is 1, and length 4.</li>
<li><em>x1 y1 s1 x2 y2 s2 x3 y3 s3 x4 y4 s4</em> <br/>
the address of <em>x[]</em> is <em>x1</em>, its stride is 3, and length 4, <br/>
the address of <em>y[]</em> is <em>y1</em>, its stride is 3, and length 4, <br/>
the address of <em>s[]</em> is <em>s1</em>, its stride is 3, and length 4.</li>
</ul>
<p>For routines such as <a class="el" href="cel_8h.html#a6661c05703158b0808038b7d551f1ea1" title="World-to-pixel celestial transformation. ">cels2x()</a>, each of the pair of input vectors is assumed to have the same stride. Each of the output vectors also has the same stride, though it may differ from the input stride. For example, for <a class="el" href="cel_8h.html#a6661c05703158b0808038b7d551f1ea1" title="World-to-pixel celestial transformation. ">cels2x()</a> the input <em>lng[]</em> and <em>lat[]</em> vectors each have vector stride <em>sll</em>, while the <em>x[]</em> and <em>y[]</em> output vectors have stride <em>sxy</em>. However, the intermediate <em>phi[]</em> and <em>theta[]</em> arrays each have unit stride, as does the <em>stat[]</em> vector.</p>
<p>If the vector length is 1 then the stride is irrelevant and so ignored. It may be set to 0. </p>
</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>
