MUSE Pipeline Reference Manual  1.0.2
muse_wcs.h
1 /* -*- Mode: C; tab-width: 2; indent-tabs-mode: nil; c-basic-offset: 2 -*- */
2 /* vim:set sw=2 sts=2 et cin: */
3 /*
4  * This file is part of the MUSE Instrument Pipeline
5  * Copyright (C) 2005-2014 European Southern Observatory
6  *
7  * This program is free software; you can redistribute it and/or modify
8  * it under the terms of the GNU General Public License as published by
9  * the Free Software Foundation; either version 2 of the License, or
10  * (at your option) any later version.
11  *
12  * This program is distributed in the hope that it will be useful,
13  * but WITHOUT ANY WARRANTY; without even the implied warranty of
14  * MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the
15  * GNU General Public License for more details.
16  *
17  * You should have received a copy of the GNU General Public License
18  * along with this program; if not, write to the Free Software
19  * Foundation, Inc., 51 Franklin Street, Fifth Floor, Boston, MA 02110-1301, USA.
20  */
21 
22 #ifndef MUSE_WCS_H
23 #define MUSE_WCS_H
24 
25 /*----------------------------------------------------------------------------*
26  * Includes *
27  *----------------------------------------------------------------------------*/
28 #include <cpl.h>
29 #include <math.h>
30 
31 #include "muse_cplwrappers.h"
32 #include "muse_datacube.h"
33 #include "muse_pixtable.h"
34 #include "muse_resampling.h"
35 
36 /*----------------------------------------------------------------------------*
37  * Defines *
38  *----------------------------------------------------------------------------*/
39 /* regular expression to copy/erase all keywords relevant to world coordinates *
40  * this list is mostly taken from the FITS Standard v3.0 (Tab. 8.2, p. 77) */
41 #define MUSE_WCS_KEYS "^C(TYPE|UNIT|RPIX|RVAL|DELT|SYER)|^CD[0-9]+_[0-9]+|" \
42  "^WCSAXES$|^L[OA][NT]POLE$"
43 
44 /*----------------------------------------------------------------------------*
45  * Special variable types *
46  *----------------------------------------------------------------------------*/
48 
52 /*----------------------------------------------------------------------------*/
57 /*----------------------------------------------------------------------------*/
58 typedef struct {
59  /* the datacube created for the exposure of the astrometric field */
60  muse_datacube *cube;
61  /* spatial center of the data in the pixel table */
62  double xcenter, ycenter;
63  /* right ascension and declination corresponding to the center of the data */
64  double ra, dec;
65  /* pixel values of the center of rotation */
66  double crpix1, crpix2;
67  /* table of detected sources */
68  cpl_table *detected;
69  /* the astrometric solution in the form of a FITS header */
70  cpl_propertylist *wcs;
72 
73 /*----------------------------------------------------------------------------*/
77 /*----------------------------------------------------------------------------*/
78 typedef enum {
83 
84 /*----------------------------------------------------------------------------*/
92 /*----------------------------------------------------------------------------*/
93 typedef struct {
94  double crpix1, crpix2;
95  double crval1, crval2;
96  double cd11, cd12, cd21, cd22;
97  double cddet;
100  cpl_boolean iscelsph;
101 } muse_wcs;
102 
103 /*----------------------------------------------------------------------------*
104  * Inline functions *
105  *----------------------------------------------------------------------------*/
106 
107 /*---------------------------------------------------------------------------*/
124 /*---------------------------------------------------------------------------*/
125 static inline void
126 muse_wcs_celestial_from_pixel_fast(muse_wcs *aWCS, double aX, double aY,
127  double *aRA, double *aDEC)
128 {
129  /* linear transformation */
130  double x = aWCS->cd11 * (aX - aWCS->crpix1) + aWCS->cd12 * (aY - aWCS->crpix2),
131  y = aWCS->cd22 * (aY - aWCS->crpix2) + aWCS->cd21 * (aX - aWCS->crpix1);
132  /* spherical projection */
133  double phi = atan2(x, -y),
134  theta = atan(CPL_MATH_DEG_RAD / sqrt(x*x + y*y));
135  /* spherical coordinate shift/translation */
136  /* dec is delta_p in Paper II (in radians), aWCS->crval1 is alpha_p (in degrees) */
137  double dec = aWCS->crval2 / CPL_MATH_DEG_RAD; /* DEC in radians */
138  *aRA = aWCS->crval1 + atan2(cos(theta) * sin(phi),
139  sin(theta) * cos(dec) + cos(theta) * sin(dec) * cos(phi))
140  * CPL_MATH_DEG_RAD;
141  *aDEC = asin(sin(theta) * sin(dec) - cos(theta) * cos(dec) * cos(phi))
142  * CPL_MATH_DEG_RAD;
143 } /* muse_wcs_celestial_from_pixel_fast() */
144 
145 /*---------------------------------------------------------------------------*/
162 /*---------------------------------------------------------------------------*/
163 static inline void
164 muse_wcs_pixel_from_celestial_fast(muse_wcs *aWCS, double aRA, double aDEC,
165  double *aX, double *aY)
166 {
167  /* spherical coordinate shift/translation */
168  /* aRA is alpha in Paper II, aDEC is delta, aWCS->crval1 is alpha_p, *
169  * aWCS->crval2 is delta_p, all of them in units of radians */
170  double phi = atan2(-cos(aDEC) * sin(aRA - aWCS->crval1),
171  sin(aDEC) * cos(aWCS->crval2)
172  - cos(aDEC) * sin(aWCS->crval2) * cos(aRA - aWCS->crval1))
173  + 180 / CPL_MATH_DEG_RAD,
174  theta = asin(sin(aDEC) * sin(aWCS->crval2)
175  + cos(aDEC) * cos(aWCS->crval2) * cos(aRA - aWCS->crval1)),
176  R_theta = CPL_MATH_DEG_RAD / tan(theta);
177  /* spherical deprojection */
178  double x = R_theta * sin(phi),
179  y = -R_theta * cos(phi);
180  /* inverse linear transformation */
181  *aX = (aWCS->cd22 * x - aWCS->cd12 * y) / aWCS->cddet + aWCS->crpix1;
182  *aY = (aWCS->cd11 * y - aWCS->cd21 * x) / aWCS->cddet + aWCS->crpix2;
183 } /* muse_wcs_pixel_from_celestial_fast() */
184 
185 /*---------------------------------------------------------------------------*/
202 /*---------------------------------------------------------------------------*/
203 static inline void
204 muse_wcs_projplane_from_pixel_fast(muse_wcs *aWCS, double aX, double aY,
205  double *aXOut, double *aYOut)
206 {
207  /* linear transformation */
208  *aXOut = aWCS->cd11 * (aX - aWCS->crpix1) + aWCS->cd12 * (aY - aWCS->crpix2)
209  + aWCS->crval1;
210  *aYOut = aWCS->cd22 * (aY - aWCS->crpix2) + aWCS->cd21 * (aX - aWCS->crpix1)
211  + aWCS->crval2;
212 } /* muse_wcs_projplane_from_pixel_fast() */
213 
214 /*---------------------------------------------------------------------------*/
231 /*---------------------------------------------------------------------------*/
232 static inline void
233 muse_wcs_pixel_from_projplane_fast(muse_wcs *aWCS, double aX, double aY,
234  double *aXOut, double *aYOut)
235 {
236  /* inverse linear transformation */
237  *aXOut = (aWCS->cd22 * (aX - aWCS->crval1) - aWCS->cd12 * (aY - aWCS->crval2))
238  / aWCS->cddet + aWCS->crpix1;
239  *aYOut = (aWCS->cd11 * (aY - aWCS->crval2) - aWCS->cd21 * (aX - aWCS->crval1))
240  / aWCS->cddet + aWCS->crpix2;
241 } /* muse_wcs_pixel_from_projplane_fast() */
242 
245 /*----------------------------------------------------------------------------*
246  * Function prototypes *
247  *----------------------------------------------------------------------------*/
250 
252 cpl_error_code muse_wcs_solve(muse_wcs_object *, cpl_table *, float, float, int, float);
253 cpl_propertylist *muse_wcs_create_default(void);
254 cpl_propertylist *muse_wcs_apply_cd(const cpl_propertylist *, const cpl_propertylist *);
255 cpl_error_code muse_wcs_project_tan(muse_pixtable *, const cpl_propertylist *);
256 cpl_error_code muse_wcs_position_celestial(muse_pixtable *, double, double);
257 
258 cpl_error_code muse_wcs_celestial_from_pixel(cpl_propertylist *, double, double, double *, double *);
259 cpl_error_code muse_wcs_pixel_from_celestial(cpl_propertylist *, double, double, double *, double *);
260 cpl_error_code muse_wcs_projplane_from_celestial(cpl_propertylist *, double, double, double *, double *);
261 cpl_error_code muse_wcs_projplane_from_pixel(cpl_propertylist *, double, double, double *, double *);
262 cpl_error_code muse_wcs_pixel_from_projplane(cpl_propertylist *, double, double, double *, double *);
263 
264 cpl_error_code muse_wcs_get_angles(cpl_propertylist *, double *, double *);
265 cpl_error_code muse_wcs_get_scales(cpl_propertylist *, double *, double *);
266 
267 muse_wcs *muse_wcs_new(cpl_propertylist *);
268 
269 #endif /* MUSE_WCS_H */
double crpix2
Definition: muse_wcs.h:94
Structure definition of a MUSE datacube.
Definition: muse_datacube.h:47
cpl_error_code muse_wcs_get_scales(cpl_propertylist *, double *, double *)
Compute the spatial scales (in degrees) from the FITS header WCS.
Definition: muse_wcs.c:1492
cpl_error_code muse_wcs_pixel_from_projplane(cpl_propertylist *, double, double, double *, double *)
Convert from projection plane coordinates to pixel coordinates.
Definition: muse_wcs.c:1406
A structure containing a spatial two-axis WCS.
Definition: muse_wcs.h:93
double cd22
Definition: muse_wcs.h:96
static void muse_wcs_pixel_from_projplane_fast(muse_wcs *aWCS, double aX, double aY, double *aXOut, double *aYOut)
Convert from projection plane coordinates to pixel coordinates.
Definition: muse_wcs.h:233
cpl_error_code muse_wcs_projplane_from_celestial(cpl_propertylist *, double, double, double *, double *)
Convert from celestial spherical coordinates to projection plane coordinates.
Definition: muse_wcs.c:1325
WCS object to store data needed while computing the astrometric solution.
Definition: muse_wcs.h:58
cpl_error_code muse_wcs_project_tan(muse_pixtable *, const cpl_propertylist *)
Carry out a gnomonic projection of a pixel table into native spherical coordinates.
Definition: muse_wcs.c:993
const muse_cpltable_def muse_wcs_reference_def[]
Definition of the table structure for the astrometric reference sources.
Definition: muse_wcs.c:141
muse_wcs * muse_wcs_new(cpl_propertylist *)
Create a new WCS structure from a given FITS header.
Definition: muse_wcs.c:1537
muse_wcs_centroid_type
Type of centroiding algorithm to use.
Definition: muse_wcs.h:78
Structure definition of MUSE pixel table.
cpl_error_code muse_wcs_celestial_from_pixel(cpl_propertylist *, double, double, double *, double *)
Convert from pixel coordinates to celestial spherical coordinates.
Definition: muse_wcs.c:1226
static void muse_wcs_pixel_from_celestial_fast(muse_wcs *aWCS, double aRA, double aDEC, double *aX, double *aY)
Convert from celestial spherical coordinates to pixel coordinates.
Definition: muse_wcs.h:164
static void muse_wcs_celestial_from_pixel_fast(muse_wcs *aWCS, double aX, double aY, double *aRA, double *aDEC)
Convert from pixel coordinates to celestial spherical coordinates.
Definition: muse_wcs.h:126
double cddet
Definition: muse_wcs.h:97
cpl_error_code muse_wcs_solve(muse_wcs_object *, cpl_table *, float, float, int, float)
Find the world coordinate solution for a given field using coordinates of detected sources and coordi...
Definition: muse_wcs.c:580
muse_wcs_object * muse_wcs_object_new(void)
Allocate memory for a new muse_wcs_object object.
Definition: muse_wcs.c:71
cpl_error_code muse_wcs_projplane_from_pixel(cpl_propertylist *, double, double, double *, double *)
Convert from pixel coordinates to projection plane coordinates.
Definition: muse_wcs.c:1373
cpl_error_code muse_wcs_pixel_from_celestial(cpl_propertylist *, double, double, double *, double *)
Convert from celestial spherical coordinates to pixel coordinates.
Definition: muse_wcs.c:1270
static void muse_wcs_projplane_from_pixel_fast(muse_wcs *aWCS, double aX, double aY, double *aXOut, double *aYOut)
Convert from pixel coordinates to projection plane coordinates.
Definition: muse_wcs.h:204
cpl_boolean iscelsph
Definition: muse_wcs.h:100
cpl_propertylist * muse_wcs_apply_cd(const cpl_propertylist *, const cpl_propertylist *)
Apply the CDi_j matrix of an astrometric solution to an observation.
Definition: muse_wcs.c:904
Definition of a cpl table structure.
cpl_error_code muse_wcs_get_angles(cpl_propertylist *, double *, double *)
Compute the rotation angles (in degrees) from the FITS header WCS.
Definition: muse_wcs.c:1445
void muse_wcs_object_delete(muse_wcs_object *)
Deallocate memory associated to a muse_wcs_object.
Definition: muse_wcs.c:89
cpl_error_code muse_wcs_position_celestial(muse_pixtable *, double, double)
Convert native to celestial spherical coordinates in a pixel table.
Definition: muse_wcs.c:1133
double crval2
Definition: muse_wcs.h:95
cpl_error_code muse_wcs_locate_sources(muse_pixtable *, float, muse_wcs_centroid_type, muse_wcs_object *)
Determine the centers of stars on an astrometric exposure.
Definition: muse_wcs.c:198
cpl_propertylist * muse_wcs_create_default(void)
Create FITS headers containing a default (relative) WCS.
Definition: muse_wcs.c:839