MUSE Pipeline Reference Manual  2.1.1
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  *----------------------------------------------------------------------------*/
48 #define MUSE_WCS_KEYS "^C(TYPE|UNIT|RPIX|RVAL|DELT|SYER|RDER)|^CD[0-9]+_[0-9]+|" \
49  "^WCSAXES$|^L[OA][NT]POLE$"
50 
56 #define MUSE_WCS_DETIMAGE_EXTNAME "ASTROMETRY_DETECTION"
57 
58 /*----------------------------------------------------------------------------*
59  * Special variable types *
60  *----------------------------------------------------------------------------*/
62 
63 
64 /*----------------------------------------------------------------------------*/
69 /*----------------------------------------------------------------------------*/
70 typedef struct {
71  /* the datacube created for the exposure of the astrometric field */
72  muse_datacube *cube;
73  /* spatial center of the data in the pixel table */
74  double xcenter, ycenter;
75  /* right ascension and declination corresponding to the center of the data */
76  double ra, dec;
77  /* pixel values of the center of rotation */
78  double crpix1, crpix2;
79  /* table of detected sources */
80  cpl_table *detected;
81  /* the astrometric solution in the form of a FITS header */
82  cpl_propertylist *wcs;
84 
85 /*----------------------------------------------------------------------------*/
89 /*----------------------------------------------------------------------------*/
90 typedef enum {
95 
96 /*----------------------------------------------------------------------------*/
104 /*----------------------------------------------------------------------------*/
105 typedef struct {
106  double crpix1, crpix2;
107  double crval1, crval2;
108  double cd11, cd12, cd21, cd22;
109  double cddet;
112  cpl_boolean iscelsph;
113 } muse_wcs;
114 
115 /*----------------------------------------------------------------------------*
116  * Inline functions *
117  *----------------------------------------------------------------------------*/
118 
119 /*---------------------------------------------------------------------------*/
136 /*---------------------------------------------------------------------------*/
137 static inline void
138 muse_wcs_celestial_from_pixel_fast(muse_wcs *aWCS, double aX, double aY,
139  double *aRA, double *aDEC)
140 {
141  /* linear transformation */
142  double x = aWCS->cd11 * (aX - aWCS->crpix1) + aWCS->cd12 * (aY - aWCS->crpix2),
143  y = aWCS->cd22 * (aY - aWCS->crpix2) + aWCS->cd21 * (aX - aWCS->crpix1);
144  /* spherical projection */
145  double phi = atan2(x, -y),
146  theta = atan(CPL_MATH_DEG_RAD / sqrt(x*x + y*y));
147  /* spherical coordinate shift/translation */
148  /* dec is delta_p in Paper II (in radians), aWCS->crval1 is alpha_p (in degrees) */
149  double dec = aWCS->crval2 / CPL_MATH_DEG_RAD; /* DEC in radians */
150  *aRA = aWCS->crval1 + atan2(cos(theta) * sin(phi),
151  sin(theta) * cos(dec) + cos(theta) * sin(dec) * cos(phi))
152  * CPL_MATH_DEG_RAD;
153  *aDEC = asin(sin(theta) * sin(dec) - cos(theta) * cos(dec) * cos(phi))
154  * CPL_MATH_DEG_RAD;
155 } /* muse_wcs_celestial_from_pixel_fast() */
156 
157 /*---------------------------------------------------------------------------*/
174 /*---------------------------------------------------------------------------*/
175 static inline void
176 muse_wcs_pixel_from_celestial_fast(muse_wcs *aWCS, double aRA, double aDEC,
177  double *aX, double *aY)
178 {
179  /* spherical coordinate shift/translation */
180  /* aRA is alpha in Paper II, aDEC is delta, aWCS->crval1 is alpha_p, *
181  * aWCS->crval2 is delta_p, all of them in units of radians */
182  double phi = atan2(-cos(aDEC) * sin(aRA - aWCS->crval1),
183  sin(aDEC) * cos(aWCS->crval2)
184  - cos(aDEC) * sin(aWCS->crval2) * cos(aRA - aWCS->crval1))
185  + 180 / CPL_MATH_DEG_RAD,
186  theta = asin(sin(aDEC) * sin(aWCS->crval2)
187  + cos(aDEC) * cos(aWCS->crval2) * cos(aRA - aWCS->crval1)),
188  R_theta = CPL_MATH_DEG_RAD / tan(theta);
189  /* spherical deprojection */
190  double x = R_theta * sin(phi),
191  y = -R_theta * cos(phi);
192  /* inverse linear transformation */
193  *aX = (aWCS->cd22 * x - aWCS->cd12 * y) / aWCS->cddet + aWCS->crpix1;
194  *aY = (aWCS->cd11 * y - aWCS->cd21 * x) / aWCS->cddet + aWCS->crpix2;
195 } /* muse_wcs_pixel_from_celestial_fast() */
196 
197 /*---------------------------------------------------------------------------*/
214 /*---------------------------------------------------------------------------*/
215 static inline void
216 muse_wcs_projplane_from_pixel_fast(muse_wcs *aWCS, double aX, double aY,
217  double *aXOut, double *aYOut)
218 {
219  /* linear transformation */
220  *aXOut = aWCS->cd11 * (aX - aWCS->crpix1) + aWCS->cd12 * (aY - aWCS->crpix2)
221  + aWCS->crval1;
222  *aYOut = aWCS->cd22 * (aY - aWCS->crpix2) + aWCS->cd21 * (aX - aWCS->crpix1)
223  + aWCS->crval2;
224 } /* muse_wcs_projplane_from_pixel_fast() */
225 
226 /*---------------------------------------------------------------------------*/
243 /*---------------------------------------------------------------------------*/
244 static inline void
245 muse_wcs_pixel_from_projplane_fast(muse_wcs *aWCS, double aX, double aY,
246  double *aXOut, double *aYOut)
247 {
248  /* inverse linear transformation */
249  *aXOut = (aWCS->cd22 * (aX - aWCS->crval1) - aWCS->cd12 * (aY - aWCS->crval2))
250  / aWCS->cddet + aWCS->crpix1;
251  *aYOut = (aWCS->cd11 * (aY - aWCS->crval2) - aWCS->cd21 * (aX - aWCS->crval1))
252  / aWCS->cddet + aWCS->crpix2;
253 } /* muse_wcs_pixel_from_projplane_fast() */
254 
257 /*----------------------------------------------------------------------------*
258  * Function prototypes *
259  *----------------------------------------------------------------------------*/
262 
265 cpl_error_code muse_wcs_solve(muse_wcs_object *, cpl_table *, float, float, int, float);
266 cpl_error_code muse_wcs_optimize_solution(muse_wcs_object *, float, muse_wcs_centroid_type, cpl_table *, float, float, int, float);
267 cpl_propertylist *muse_wcs_create_default(void);
268 cpl_propertylist *muse_wcs_apply_cd(const cpl_propertylist *, const cpl_propertylist *);
269 cpl_error_code muse_wcs_project_tan(muse_pixtable *, const cpl_propertylist *);
270 cpl_error_code muse_wcs_position_celestial(muse_pixtable *, double, double);
271 
272 cpl_error_code muse_wcs_celestial_from_pixel(cpl_propertylist *, double, double, double *, double *);
273 cpl_error_code muse_wcs_pixel_from_celestial(cpl_propertylist *, double, double, double *, double *);
274 cpl_error_code muse_wcs_projplane_from_celestial(cpl_propertylist *, double, double, double *, double *);
275 cpl_error_code muse_wcs_projplane_from_pixel(cpl_propertylist *, double, double, double *, double *);
276 cpl_error_code muse_wcs_pixel_from_projplane(cpl_propertylist *, double, double, double *, double *);
277 
278 cpl_error_code muse_wcs_get_angles(cpl_propertylist *, double *, double *);
279 cpl_error_code muse_wcs_get_scales(cpl_propertylist *, double *, double *);
280 
281 muse_wcs *muse_wcs_new(cpl_propertylist *);
282 
283 #endif /* MUSE_WCS_H */
double crpix2
Definition: muse_wcs.h:106
Structure definition of a MUSE datacube.
Definition: muse_datacube.h:48
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:1825
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:1739
A structure containing a spatial two-axis WCS.
Definition: muse_wcs.h:105
double cd22
Definition: muse_wcs.h:108
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:245
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:1658
WCS object to store data needed while computing the astrometric solution.
Definition: muse_wcs.h:70
Structure definition of MUSE three extension FITS file.
Definition: muse_image.h:40
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:1326
cpl_table * muse_wcs_centroid_stars(muse_image *, float, muse_wcs_centroid_type)
Detect and centroid stars on an image of an astrometric exposure.
Definition: muse_wcs.c:178
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:1870
muse_wcs_centroid_type
Type of centroiding algorithm to use.
Definition: muse_wcs.h:90
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:1559
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:176
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:138
double cddet
Definition: muse_wcs.h:109
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:671
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:1706
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:1603
cpl_error_code muse_wcs_optimize_solution(muse_wcs_object *, float, muse_wcs_centroid_type, cpl_table *, float, float, int, float)
Find an optimal astrometry solution given a detection image.
Definition: muse_wcs.c:988
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:216
cpl_boolean iscelsph
Definition: muse_wcs.h:112
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:1237
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:1778
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:1466
double crval2
Definition: muse_wcs.h:107
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:496
cpl_propertylist * muse_wcs_create_default(void)
Create FITS headers containing a default (relative) WCS.
Definition: muse_wcs.c:1174