WCSLIB 8.6
Loading...
Searching...
No Matches
wcslib.h
Go to the documentation of this file.
1/*============================================================================
2 WCSLIB 8.6 - an implementation of the FITS WCS standard.
3 Copyright (C) 1995-2026, Mark Calabretta
4
5 This file is part of WCSLIB.
6
7 WCSLIB is free software: you can redistribute it and/or modify it under the
8 terms of the GNU Lesser General Public License as published by the Free
9 Software Foundation, either version 3 of the License, or (at your option)
10 any later version.
11
12 WCSLIB is distributed in the hope that it will be useful, but WITHOUT ANY
13 WARRANTY; without even the implied warranty of MERCHANTABILITY or FITNESS
14 FOR A PARTICULAR PURPOSE. See the GNU Lesser General Public License for
15 more details.
16
17 You should have received a copy of the GNU Lesser General Public License
18 along with WCSLIB. If not, see http://www.gnu.org/licenses.
19
20 Author: Mark Calabretta, Australia Telescope National Facility, CSIRO.
21 http://www.atnf.csiro.au/computing/software/wcs
22 $Id: wcslib.h,v 8.6 2026/03/29 13:53:56 mcalabre Exp $
23*=============================================================================
24*
25* WCSLIB 8.6 - C routines that implement the FITS World Coordinate System
26* (WCS) standard. Refer to the README file provided with WCSLIB for an
27* overview of the library.
28*
29* Summary of wcslib.h
30* -------------------
31* This header file is provided purely for convenience. Use it to include all
32* of the separate WCSLIB headers.
33*
34*===========================================================================*/
35
36#ifndef WCSLIB_WCSLIB
37#define WCSLIB_WCSLIB
38
39#include "cel.h"
40#include "dis.h"
41#include "fitshdr.h"
42#include "lin.h"
43#include "log.h"
44#include "prj.h"
45#include "spc.h"
46#include "sph.h"
47#include "spx.h"
48#include "tab.h"
49#include "wcs.h"
50#include "wcserr.h"
51#include "wcsfix.h"
52#include "wcshdr.h"
53#include "wcsmath.h"
54#include "wcsprintf.h"
55#include "wcstrig.h"
56#include "wcsunits.h"
57#include "wcsutil.h"
58#include "wtbarr.h"
59
60#endif // WCSLIB_WCSLIB
100
120
135
161
180
195
214
247
287
327
340
365
372
377
386
426
432
440
452
461
467
472
484
490
496
502
508
856
873
924
936
949
959
1004
1035
1054
1082
1107
1122
1140
1157
1188
1201
1245
1333
1345
1367
1376
1382
1387
1395
1407
1417
1427
1438
1445
1467
1478
1489
1496
1503
1508
1513
1519
1524
1529
1534
1539
1544
1549
1554
1565
1579
1584
1593
1604
1618
1626
1634
1641
1649
1657
1665
1673
1681
1689
1697
1705
1713
1721
1729
1747
1881
1891
1898
1903
1916
1925
1932
1938
1955
1973
2045
2050
2067
2073
2079
2085
2091
2097
2103
2110
2122
2135
2142
2149
2156
2163
2170
2205
2314
2324
2369
2380
2421
2452
2471
2501
2526
2541
2560
2593
2632
2670
2755
2765
2788
2797
2806
2839
2845
2894
2902
2908
2914
2920
2925
2930
2935
2941
2946
2951
2956
2961
2966
2971
2976
2981
2993
2999
3005
3011
3017
3023
3029
3035
3088
3113
3141
3194
3248
3249
3394
3395
3547
3548
3602
3603
3661
3662
3694 wcserr_enable(1);
3695 wcsprintf_set(stderr);
3696
3697 ...
3698
3699 if (wcsset(&wcs) {
3700 wcsperr(&wcs);
3701 return wcs.err->status;
3702 }
3703@endverbatim
3704In this example, if an error was generated in one of the prjset() functions,
3705wcsperr() would print an error traceback starting with wcsset(), then
3706celset(), and finally the particular projection-setting function that
3707generated the error. For each of them it would print the status return value,
3708function name, source file, line number, and an error message which may be
3709more specific and informative than the general error messages reported in the
3710first example. For example, in response to a deliberately generated error,
3711the @c twcs test program, which tests wcserr among other things, produces a
3712traceback similar to this:
3713@verbatim
3714ERROR 5 in wcsset() at line 1564 of file wcs.c:
3715 Invalid parameter value.
3716ERROR 2 in celset() at line 196 of file cel.c:
3717 Invalid projection parameters.
3718ERROR 2 in bonset() at line 5727 of file prj.c:
3719 Invalid parameters for Bonne's projection.
3720@endverbatim
3721
3722Each of the @ref structs "structs" in @ref overview "WCSLIB" includes a
3723pointer, called @a err, to a wcserr struct. When an error occurs, a struct is
3724allocated and error information stored in it. The wcserr pointers and the
3725@ref memory "memory" allocated for them are managed by the routines that
3726manage the various structs such as wcsinit() and wcsfree().
3727
3728wcserr messaging is an opt-in system enabled via wcserr_enable(), as in the
3729example above. If enabled, when an error occurs it is the user's
3730responsibility to free the memory allocated for the error message using
3731wcsfree(), celfree(), prjfree(), etc. Failure to do so before the struct goes
3732out of scope will result in memory leaks (if execution continues beyond the
3733error).
3734*/
3735
3736
3917
3918
3979
3980
4001
4002
4003
4114
4115
4304
4305
4344
4563
4583
4598
4624
4643
4658
4676
4710
4747
4781
4816
4827
4847
4852
4859
4871
4876
4884
4903
4910
4937
4946
4954
4961
4968
4976
4983
4988
4994
5000
5005
5014
5021
5026
5031
5050
5063
5077
5090
5103
5117
5130
5143
5157
5170
5183
5197
5210
5223
5237
5250
5264
5278
5291
5304
5318
5331
5344
5358
5371
5384
5398
5411
5424
5438
5451
5464
5478
5491
5504
5518
5531
5544
5558
5571
5584
5598
5611
5624
5638
5651
5664
5678
5691
5704
5718
5731
5744
5758
5771
5784
5798
5811
5824
5838
5851
5864
5878
5891
5904
5918
5931
5944
5958
5971
5984
5998
6011
6024
6038
6051
6064
6078
6091
6104
6118
6124
6130
6136
6142
6148
6154
6160
6166
6174
6181
6188
6194
6200
6206
6212
6218
6224
6230
6236
6398
6417
6432
6458
6483
6498
6516
6546
6578
6611
6682
6735
6791
6859
6922
6933
6952
6958
6964
6969
6974
6982
6999
7011
7021
7026
7032
7037
7042
7050
7055
7063
7075
7081
7087
7093
7099
7126
7158
7188
7252
7409
7452
7470
7495
7520
7545
7557
7562
7567
7572
7585
7590
7595
7600
7605
7610
7615
7620
7625
7630
7635
7640
7646
7651
7657
7663
7669
7674
7680
7685
7691
7696
7702
7707
7713
7718
7724
7729
7735
7740
7746
7751
7757
7762
7768
7773
7780
7785
7791
7796
7810
7818
7826
7834
7842
7850
7858
7866
7874
7882
7890
7898
7906
7914
7922
7930
7938
7946
7954
7962
7970
7978
7986
7993
8042
8097
8116
8151
8178
8197
8225
8250
8265
8283
8313
8348
8382
8393
8417
8426
8437
8459
8466
8484
8496
8502
8507
8514
8521
8528
8542
8548
8553
8558
8563
8568
8573
8578
8583
8588
8593
8598
8610
8616
8622
8628
8634
8640
8646
8748
8765
8782
8794
8853
8880
9017
9056
9065
9084
9122
9150
9171
9200
9215
9234
9264
9313
9377
9443
9549
9692
9734
9764
9792
9832
9841
9847
9880
9886
9892
9921
9937
9944
9957
9962
9968
9973
9981
9996
10001
10009
10020
10027
10034
10103
10111
10125
10137
10149
10162
10171
10180
10189
10198
10209
10220
10229
10238
10247
10258
10267
10277
10287
10297
10306
10315
10324
10333
10342
10351
10360
10369
10378
10387
10396
10405
10414
10423
10432
10441
10450
10462
10471
10480
10490
10499
10509
10519
10527
10536
10545
10556
10561
10566
10582
10592
10597
10605
10610
10615
10620
10629
10636
10644
10693
10699
10705
10711
10717
10722
10727
10732
10737
10742
10747
10752
10757
10762
10767
10772
10777
10782
10787
10792
10797
10802
10807
10812
10817
10827
10833
10838
10843
10853
10858
10863
10868
10879
10885
10891
10897
10903
10909
10915
10921
10927
10933
10939
10944
10957
10964
10971
10979
10986
10993
10999
11005
11011
11017
11023
11029
11035
11041
11047
11077
11086
11093
11106
11111
11128
11150
11168
11182
11228
11247
11357
11364
11405
11427
11475
11568
11595
11638
11684
11721
11810
11823
11830
11837
11844
11851
11858
11864
11951
12072
12947
12994
13029
13072
13090
13340
13356
13365
13374
13384
13393
13402
13412
13422
13431
13440
13449
13458
13468
13482
13493
13506
13513
13521
13528
13537
13546
13555
13565
13576
13591
13615
13633
13657
13663
13667
13671
13678
13693
13709
13726
13746
13760
13806
13817
13828
13842
13853
13864
13875
13886
13942
13993
14085
14177
14184
14209
14234
14242
14250
14258
14266
14274
14282
14290
14298
14306
14314
14322
14330
14338
14346
14354
14362
14379
14399
14437
14454
14478
14497
14516
14536
14567
14591
14610
14629
14658
14687
14707
14728
14751
14765
14787
14803
14808
14813
14822
14827
14832
14837
14843
14848
14853
14859
int celfree(struct celprm *cel)
Destructor for the celprm struct.
int celset(struct celprm *cel)
Setup routine for the celprm struct.
int prjfree(struct prjprm *prj)
Destructor for the prjprm struct.
int bonset(struct prjprm *prj)
Set up a prjprm struct for Bonne's (BON) projection.
int prjset(struct prjprm *prj)
Generic setup routine for the prjprm struct.
Error message handling.
Definition wcserr.h:243
int wcsfree(struct wcsprm *wcs)
Destructor for the wcsprm struct.
int wcsperr(const struct wcsprm *wcs, const char *prefix)
Print error messages from a wcsprm struct.
int wcsinit(int alloc, int naxis, struct wcsprm *wcs, int npvmax, int npsmax, int ndpmax)
Default constructor for the wcsprm struct.
int wcsset(struct wcsprm *wcs)
Setup routine for the wcsprm struct.
int wcserr_enable(int enable)
Enable/disable error messaging.
int wcsprintf_set(FILE *wcsout)
Set output disposition for wcsprintf() and wcsfprintf().