WCSLIB 4.18
wcslib.h
Go to the documentation of this file.
1 /*============================================================================
2 
3  WCSLIB 4.18 - an implementation of the FITS WCS standard.
4  Copyright (C) 1995-2013, Mark Calabretta
5 
6  This file is part of WCSLIB.
7 
8  WCSLIB is free software: you can redistribute it and/or modify it under the
9  terms of the GNU Lesser General Public License as published by the Free
10  Software Foundation, either version 3 of the License, or (at your option)
11  any later version.
12 
13  WCSLIB is distributed in the hope that it will be useful, but WITHOUT ANY
14  WARRANTY; without even the implied warranty of MERCHANTABILITY or FITNESS
15  FOR A PARTICULAR PURPOSE. See the GNU Lesser General Public License for
16  more details.
17 
18  You should have received a copy of the GNU Lesser General Public License
19  along with WCSLIB. If not, see http://www.gnu.org/licenses.
20 
21  Direct correspondence concerning WCSLIB to mark@calabretta.id.au
22 
23  Author: Mark Calabretta, Australia Telescope National Facility, CSIRO.
24  http://www.atnf.csiro.au/people/Mark.Calabretta
25  $Id: wcslib.h,v 4.18 2013/07/13 10:00:04 mcalabre Exp $
26 *=============================================================================
27 *
28 * WCSLIB 4.18 - C routines that implement the FITS World Coordinate System
29 * (WCS) standard.
30 *
31 * Summary of wcslib.h
32 * -------------------
33 * This header file is provided purely for convenience. Use it to include all
34 * of the separate WCSLIB headers.
35 *
36 *===========================================================================*/
37 
38 #ifndef WCSLIB_WCSLIB
39 #define WCSLIB_WCSLIB
40 
41 #include "cel.h"
42 #include "fitshdr.h"
43 #include "lin.h"
44 #include "log.h"
45 #include "prj.h"
46 #include "spc.h"
47 #include "sph.h"
48 #include "spx.h"
49 #include "tab.h"
50 #include "wcs.h"
51 #include "wcserr.h"
52 #include "wcsfix.h"
53 #include "wcshdr.h"
54 #include "wcsmath.h"
55 #include "wcsprintf.h"
56 #include "wcstrig.h"
57 #include "wcsunits.h"
58 #include "wcsutil.h"
59 
60 #endif /* WCSLIB_WCSLIB */
61 
1934  wcserr_enable(1);
1935  wcsprintf_set(stderr);
1936 
1937  ...
1938 
1939  if (wcsset(&wcs) {
1940  wcsperr(&wcs);
1941  return wcs.err->status;
1942  }
1943 @endverbatim
1944 In this example, if an error was generated in one of the prjset() functions,
1945 wcsperr() would print an error traceback starting with wcsset(), then
1946 celset(), and finally the particular projection-setting function that
1947 generated the error. For each of them it would print the status return value,
1948 function name, source file, line number, and an error message which may be
1949 more specific and informative than the general error messages reported in the
1950 first example. For example, in response to a deliberately generated error,
1951 the @c twcs test program, which tests wcserr among other things, produces a
1952 traceback similar to this:
1953 @verbatim
1954 ERROR 5 in wcsset() at line 1564 of file wcs.c:
1955  Invalid parameter value.
1956 ERROR 2 in celset() at line 196 of file cel.c:
1957  Invalid projection parameters.
1958 ERROR 2 in bonset() at line 5727 of file prj.c:
1959  Invalid parameters for Bonne's projection.
1960 @endverbatim
1961 
1962 Each of the @ref structs "structs" in @ref overview "WCSLIB" includes a
1963 pointer, called @a err, to a wcserr struct. When an error occurs, a struct is
1964 allocated and error information stored in it. The wcserr pointers and the
1965 @ref memory "memory" allocated for them are managed by the routines that
1966 manage the various structs such as wcsini() and wcsfree().
1967 
1968 wcserr messaging is an opt-in system enabled via wcserr_enable(), as in the
1969 example above. If enabled, when an error occurs it is the user's
1970 responsibility to free the memory allocated for the error message using
1971 wcsfree(), celfree(), prjfree(), etc. Failure to do so before the struct goes
1972 out of scope will result in memory leaks (if execution continues beyond the
1973 error).
1974 */
1975 
1976