1 /*********************************************************************
2 Functions to that only use WCSLIB's functions, not related to FITS.
3 This is part of GNU Astronomy Utilities (Gnuastro) package.
4 
5 Original author:
6      Mohammad Akhlaghi <mohammad@akhlaghi.org>
7 Contributing author(s):
8 Copyright (C) 2015-2021, Free Software Foundation, Inc.
9 
10 Gnuastro is free software: you can redistribute it and/or modify it
11 under the terms of the GNU General Public License as published by the
12 Free Software Foundation, either version 3 of the License, or (at your
13 option) any later version.
14 
15 Gnuastro is distributed in the hope that it will be useful, but
16 WITHOUT ANY WARRANTY; without even the implied warranty of
17 MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the GNU
18 General Public License for more details.
19 
20 You should have received a copy of the GNU General Public License
21 along with Gnuastro. If not, see <http://www.gnu.org/licenses/>.
22 **********************************************************************/
23 #ifndef __GAL_WCS_H__
24 #define __GAL_WCS_H__
25 
26 /* Include other headers if necessary here. Note that other header files
27    must be included before the C++ preparations below */
28 #include <fitsio.h>
29 #include <wcslib/wcs.h>
30 
31 #include <gnuastro/data.h>
32 #include <gnuastro/fits.h>
33 
34 /* Assumed floating point error in the WCS-related functionality. */
35 #define GAL_WCS_FLTERROR 1e-12
36 
37 /* C++ Preparations */
38 #undef __BEGIN_C_DECLS
39 #undef __END_C_DECLS
40 #ifdef __cplusplus
41 # define __BEGIN_C_DECLS extern "C" {
42 # define __END_C_DECLS }
43 #else
44 # define __BEGIN_C_DECLS                /* empty */
45 # define __END_C_DECLS                  /* empty */
46 #endif
47 /* End of C++ preparations */
48 
49 
50 
51 /* Actual header contants (the above were for the Pre-processor). */
52 __BEGIN_C_DECLS  /* From C++ preparations */
53 
54 
55 
56 
57 
58 /*************************************************************
59  **************           Constants            ***************
60  *************************************************************/
61 /* Macros to identify the type of distortion for conversions. */
62 enum gal_wcs_distortions
63 {
64   GAL_WCS_DISTORTION_INVALID,         /* Invalid (=0 by C standard).    */
65 
66   GAL_WCS_DISTORTION_TPD,             /* The TPD polynomial distortion. */
67   GAL_WCS_DISTORTION_SIP,             /* The SIP polynomial distortion. */
68   GAL_WCS_DISTORTION_TPV,             /* The TPV polynomial distortion. */
69   GAL_WCS_DISTORTION_DSS,             /* The DSS polynomial distortion. */
70   GAL_WCS_DISTORTION_WAT,             /* The WAT polynomial distortion. */
71 };
72 
73 /* Macros to identify coordinate system for convesions. */
74 enum gal_wcs_coordsys
75 {
76   GAL_WCS_COORDSYS_INVALID,           /* Invalid (=0 by C standard).    */
77 
78   GAL_WCS_COORDSYS_EQB1950,           /* Equatorial B1950 */
79   GAL_WCS_COORDSYS_EQJ2000,           /* Equatorial J2000 */
80   GAL_WCS_COORDSYS_ECB1950,           /* Ecliptic B1950 */
81   GAL_WCS_COORDSYS_ECJ2000,           /* Ecliptic J2000 */
82   GAL_WCS_COORDSYS_GALACTIC,          /* Galactic */
83   GAL_WCS_COORDSYS_SUPERGALACTIC,     /* Super-galactic */
84 };
85 
86 /* Macros to identify the type of distortion for conversions. */
87 enum gal_wcs_linear_matrix
88 {
89   GAL_WCS_LINEAR_MATRIX_INVALID,      /* Invalid (=0 by C standard).    */
90 
91   GAL_WCS_LINEAR_MATRIX_PC,
92   GAL_WCS_LINEAR_MATRIX_CD,
93 };
94 
95 
96 
97 
98 
99 /*************************************************************
100  ***********               Read WCS                ***********
101  *************************************************************/
102 struct wcsprm *
103 gal_wcs_read_fitsptr(fitsfile *fptr, int linearmatrix, size_t hstartwcs,
104                      size_t hendwcs, int *nwcs);
105 
106 struct wcsprm *
107 gal_wcs_read(char *filename, char *hdu, int linearmatrix, size_t hstartwcs,
108              size_t hendwcs, int *nwcs);
109 
110 struct wcsprm *
111 gal_wcs_create(double *crpix, double *crval, double *cdelt,
112                double *pc, char **cunit, char **ctype, size_t ndim,
113                int linearmatrix);
114 
115 char *
116 gal_wcs_dimension_name(struct wcsprm *wcs, size_t dimension);
117 
118 
119 
120 /*************************************************************
121  ***********               Write WCS               ***********
122  *************************************************************/
123 void
124 gal_wcs_write(struct wcsprm *wcs, char *filename,
125               char *extname, gal_fits_list_key_t *headers,
126               char *program_string);
127 
128 char *
129 gal_wcs_write_wcsstr(struct wcsprm *wcs, int *nkeyrec);
130 
131 void
132 gal_wcs_write_in_fitsptr(fitsfile *fptr, struct wcsprm *wcs);
133 
134 
135 
136 /*************************************************************
137  ***********              Distortions              ***********
138  *************************************************************/
139 int
140 gal_wcs_coordsys_from_string(char *coordsys);
141 
142 int
143 gal_wcs_coordsys_identify(struct wcsprm *inwcs);
144 
145 struct wcsprm *
146 gal_wcs_coordsys_convert(struct wcsprm *inwcs, int coordsysid);
147 
148 
149 
150 /*************************************************************
151  ***********              Distortions              ***********
152  *************************************************************/
153 int
154 gal_wcs_distortion_from_string(char *distortion);
155 
156 char *
157 gal_wcs_distortion_to_string(int distortion);
158 
159 int
160 gal_wcs_distortion_identify(struct wcsprm *wcs);
161 
162 struct wcsprm *
163 gal_wcs_distortion_convert(struct wcsprm *inwcs,
164                            int out_distortion, size_t *fitsize);
165 
166 
167 
168 
169 
170 /**************************************************************/
171 /**********              Utilities                 ************/
172 /**************************************************************/
173 struct wcsprm *
174 gal_wcs_copy(struct wcsprm *wcs);
175 
176 void
177 gal_wcs_remove_dimension(struct wcsprm *wcs, size_t fitsdim);
178 
179 void
180 gal_wcs_on_tile(gal_data_t *tile);
181 
182 double *
183 gal_wcs_warp_matrix(struct wcsprm *wcs);
184 
185 void
186 gal_wcs_clean_errors(struct wcsprm *wcs);
187 
188 void
189 gal_wcs_decompose_pc_cdelt(struct wcsprm *wcs);
190 
191 void
192 gal_wcs_to_cd(struct wcsprm *wcs);
193 
194 double
195 gal_wcs_angular_distance_deg(double r1, double d1, double r2, double d2);
196 
197 double *
198 gal_wcs_pixel_scale(struct wcsprm *wcs);
199 
200 double
201 gal_wcs_pixel_area_arcsec2(struct wcsprm *wcs);
202 
203 int
204 gal_wcs_coverage(char *filename, char *hdu, size_t *ndim,
205                  double **center, double **width, double **min,
206                  double **max);
207 
208 
209 
210 /**************************************************************/
211 /**********              Conversion                ************/
212 /**************************************************************/
213 gal_data_t *
214 gal_wcs_world_to_img(gal_data_t *coords, struct wcsprm *wcs, int inplace);
215 
216 gal_data_t *
217 gal_wcs_img_to_world(gal_data_t *coords, struct wcsprm *wcs, int inplace);
218 
219 
220 
221 
222 
223 __END_C_DECLS    /* From C++ preparations */
224 
225 #endif           /* __GAL_WCS_H__ */
226