1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
|
<!DOCTYPE HTML PUBLIC "-//W3C//DTD HTML 4.01 Transitional//EN">
<html><head><meta http-equiv="Content-Type" content="text/html;charset=UTF-8">
<title>WCSLIB 4.8.2: WCSLIB Fortran wrappers</title>
<link href="doxygen.css" rel="stylesheet" type="text/css">
<link href="tabs.css" rel="stylesheet" type="text/css">
</head><body>
<!-- Generated by Doxygen 1.5.6 -->
<div class="navigation" id="top">
<div class="tabs">
<ul>
<li><a href="index.html"><span>Main Page</span></a></li>
<li><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 class="navpath"><a class="el" href="index.html">WCSLIB 4.8.2 and PGSBOX 4.8.2</a>
</div>
</div>
<div class="contents">
<h1><a class="anchor" name="fortran">WCSLIB Fortran wrappers </a></h1>The Fortran subdirectory contains wrappers, written in C, that allow Fortran programs to use WCSLIB.<p>
A prerequisite for using the wrappers is an understanding of the usage of the associated C routines, in particular the data structures they are based on. The principle difficulty in creating the wrappers was the need to manage these C structs from within Fortran, particularly as they contain pointers to allocated memory, pointers to C functions, and other structs that themselves contain similar entities.<p>
To this end, routines have been provided to set and retrieve values of the various structs, for example <code>WCSPUT</code> and <code>WCSGET</code> for the <a class="el" href="structwcsprm.html" title="Coordinate transformation parameters.">wcsprm</a> struct, and <code>CELPUT</code> and <code>CELGET</code> for the <a class="el" href="structcelprm.html" title="Celestial transformation parameters.">celprm</a> struct. These must be used in conjunction with wrappers on the routines provided to manage the structs in C, for example <code>WCSINI</code>, <code>WCSSUB</code>, <code>WCSCOPY</code>, <code>WCSFREE</code>, and <code>WCSPRT</code> which wrap <a class="el" href="wcs_8h.html#2afc8255fde0965dddaa374463666d45" title="Default constructor for the wcsprm struct.">wcsini()</a>, <a class="el" href="wcs_8h.html#864c99fef9f3eee29085ce42d0ee0d64" title="Subimage extraction routine for the wcsprm struct.">wcssub()</a>, <a class="el" href="wcs_8h.html#c55946dadc53ac592cb686275902ae7b" title="Copy routine for the wcsprm struct.">wcscopy()</a>, <a class="el" href="wcs_8h.html#4ab38bc642c4656f62c43acf84a849f1" title="Destructor for the wcsprm struct.">wcsfree()</a>, and <a class="el" href="wcs_8h.html#b9aeb8cf1afb1bfb22e989580d90fca8" title="Print routine for the wcsprm struct.">wcsprt()</a>.<p>
The various <code>*PUT</code> and <code>*GET</code> routines are based on codes defined in Fortran include files (*.inc), if your Fortran compiler does not support the <code>INCLUDE</code> statement then you will need to include these manually wherever necessary. Codes are defined as parameters with names like <code>WCS_CRPIX</code> which refers to <a class="el" href="structwcsprm.html#adad828f07e3affd1511e533b00da19f">wcsprm::crpix</a> (if your Fortran compiler does not support long symbolic names then you will need to rename these).<p>
The include files also contain parameters, such as <code>WCSLEN</code>, that define the length of an <code>INTEGER</code> array that must be declared to hold the struct. This length may differ for different platforms depending on how the C compiler aligns data within the structs. A test program for the C library, <em>twcs</em>, prints the size of the struct in <em>sizeof(int)</em> units and the values in the Fortran include files must equal or exceed these. On some platforms, such as Suns, it is important that the start of the <code>INTEGER</code> array be <em><b>aligned on a <code>DOUBLE</code> <code>PRECISION</code> boundary</b></em>, otherwise a <code>BUS</code> error may result. This may be achieved via an <code>EQUIVALENCE</code> with a <code>DOUBLE</code> <code>PRECISION</code> variable, or by sequencing variables in a <code>COMMON</code> block so that the <code>INTEGER</code> array follows immediately after a <code>DOUBLE</code> <code>PRECISION</code> variable.<p>
The <code>*PUT</code> routines set only one element of an array at a time; the final one or two integer arguments of these routines specify 1-relative array indices (N.B. not 0-relative as in C). The one exception is the <a class="el" href="structprjprm.html#46d6928a9026e7b3376dcf0d3f91db64">prjprm::pv</a> array.<p>
The <code>*PUT</code> routines also reset the <em>flag</em> element to signal that the struct needs to be reinitialized. Therefore, if you wanted to set <a class="el" href="structwcsprm.html#35bff8de85e5a8892e1b68db69ca7a68">wcsprm::flag</a> itself to -1 prior to the first call to <code>WCSINI</code>, for example, then that <code>WCSPUT</code> must be the last one before the call.<p>
The <code>*GET</code> routines retrieve whole arrays at a time and expect array arguments of the appropriate length where necessary. Note that they do not initialize the structs.<p>
A basic coding fragment is<p>
<div class="fragment"><pre class="fragment">
INTEGER LNGIDX, STATUS
CHARACTER CTYPE1*72
INCLUDE 'wcs.inc'
* WCSLEN is defined as a parameter in wcs.inc.
INTEGER WCS(WCSLEN)
DOUBLE PRECISION DUMMY
EQUIVALENCE (WCS, DUMMY)
* Allocate memory and set default values for 2 axes.
STATUS = WCSPUT (WCS, WCS_FLAG, -1, 0, 0)
STATUS = WCSINI (2, WCS)
* Set CRPIX1, and CRPIX2; WCS_CRPIX is defined in wcs.inc.
STATUS = WCSPUT (WCS, WCS_CRPIX, 512D0, 1, 0)
STATUS = WCSPUT (WCS, WCS_CRPIX, 512D0, 2, 0)
* Set PC1_2 to 5.0 (I = 1, J = 2).
STATUS = WCSPUT (WCS, WCS_PC, 5D0, 1, 2)
* Set CTYPE1 to 'RA---SIN'; N.B. must be given as CHARACTER*72.
CTYPE1 = 'RA---SIN'
STATUS = WCSPUT (WCS, WCS_CTYPE, CTYPE1, 1, 0)
* Set PV1_3 to -1.0 (I = 1, M = 3).
STATUS = WCSPUT (WCS, WCS_PV, -1D0, 1, 3)
etc.
* Initialize.
STATUS = WCSSET (WCS)
IF (STATUS.NE.0) THEN
CALL FLUSH(6)
STATUS = WCSPERR(WCS, CHAR(0))
ENDIF
* Find the "longitude" axis.
STATUS = WCSGET (WCS, WCS_LNG, LNGIDX)
* Free memory.
STATUS = WCSFREE (WCS)
</pre></div><p>
Refer to the various Fortran test programs for further programming examples. In particular, <em>twcs</em> and <em>twcsmix</em> show how to retrieve elements of the <a class="el" href="structcelprm.html" title="Celestial transformation parameters.">celprm</a> and <a class="el" href="structprjprm.html" title="Projection parameters.">prjprm</a> structs contained within the <a class="el" href="structwcsprm.html" title="Coordinate transformation parameters.">wcsprm</a> struct.<p>
Note that the data type of the third argument to the <code>*PUT</code> and <code>*GET</code> routines differs depending on the data type of the corresponding C struct member, be it <em>int</em>, <em>double</em>, or <em>char</em>[]. It is essential that the Fortran data type match that of the C struct for <em>int</em> and <em>double</em> types, and be a <code>CHARACTER</code> variable of the correct length for <em>char</em>[] types. Compilers (e.g. g77) may warn of inconsistent usage of this argument but this can (usually) be safely ignored. If these warnings become annoying, type-specific variants are provided for each of the <code>*PUT</code> routines, <code>*PTI</code>, <code>*PTD</code>, and <code>*PTC</code> for <em>int</em>, <em>double</em>, or <em>char</em>[] and likewise <code>*GTI</code>, <code>*GTD</code>, and <code>*GTC</code> for the <code>*GET</code> routines.<p>
When calling wrappers for C functions that print to <em>stdout</em>, such as <code>WCSPRT</code>, and <code>WCSPERR</code>, or that may print to <em>stderr</em>, such as <code>WCSPIH</code>, <code>WCSBTH</code>, <code>WCSULEXE</code>, or <code>WCSUTRNE</code>, it may be necessary to flush the Fortran I/O buffers beforehand so that the output appears in the correct order. The wrappers for these functions do call <code>fflush(NULL)</code>, but depending on the particular system, this may not succeed in flushing the Fortran I/O buffers. Most Fortran compilers provide the non-standard intrinsic <code>FLUSH()</code>, which is called with unit number 6 to flush <em>stdout</em> (as in the example above), and unit 0 for <em>stderr</em>.<p>
A basic assumption made by the wrappers is that an <code>INTEGER</code> variable is no less than half the size of a <code>DOUBLE</code> <code>PRECISION</code>. </div>
<hr size="1"><address style="text-align: right;"><small>Generated on Tue Oct 4 19:02:31 2011 for WCSLIB 4.8.2 by
<a href="http://www.doxygen.org/index.html">
<img src="doxygen.png" alt="doxygen" align="middle" border="0"></a> 1.5.6 </small></address>
</body>
</html>
|
