MUSE Pipeline Reference Manual  1.0.2
muse_pixtable.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_PIXTABLE_H
23 #define MUSE_PIXTABLE_H
24 
25 /*----------------------------------------------------------------------------*
26  * Includes *
27  *----------------------------------------------------------------------------*/
28 #include <cpl.h>
29 #include <stdint.h>
30 
31 #include "muse_dfs.h"
32 #include "muse_image.h"
33 #include "muse_imagelist.h"
34 #include "muse_mask.h"
35 #include "muse_cplwrappers.h"
36 
37 /*----------------------------------------------------------------------------*
38  * Defines *
39  *----------------------------------------------------------------------------*/
40 #if !HAVE_UINT32_T /* is common but C99 only requires uint_least32_t... */
41 typedef unsigned int uint32_t;
42 #endif
43 
44 /* Table column names of the pixel table, see muse_pixtable_def for comments */
45 #define MUSE_PIXTABLE_DATA "data"
46 #define MUSE_PIXTABLE_DQ "dq"
47 #define MUSE_PIXTABLE_STAT "stat"
48 #define MUSE_PIXTABLE_XPOS "xpos"
49 #define MUSE_PIXTABLE_YPOS "ypos"
50 #define MUSE_PIXTABLE_LAMBDA "lambda"
51 #define MUSE_PIXTABLE_ORIGIN "origin"
52 /* relative weight of a pixel (used for combining exposures) */
53 #define MUSE_PIXTABLE_WEIGHT "weight"
54 
56 
68 #define MUSE_HDR_PT_IFU_SLICE_OFFSET "ESO DRS MUSE PIXTABLE EXP%u IFU%02hu SLICE%02hu XOFFSET"
69 #define MUSE_HDR_PT_IFU_SLICE_OFFSET_COMMENT "x-offset of given slice in given IFU of given exposure"
70 
77 #define MUSE_HDR_PT_TYPE "ESO DRS MUSE PIXTABLE TYPE"
78 #define MUSE_PIXTABLE_STRING_SIMPLE "SIMPLE"
79 #define MUSE_PIXTABLE_STRING_FULL "GEOFULL"
80 #define MUSE_PIXTABLE_COMMENT_SIMPLE "pixel table without y coordinates"
81 #define MUSE_PIXTABLE_COMMENT_FULL "pixel table with full geometry information"
82 
87 #define MUSE_HDR_PT_EXP_FST "ESO DRS MUSE PIXTABLE EXP%u FIRST"
88 
92 #define MUSE_HDR_PT_EXP_LST "ESO DRS MUSE PIXTABLE EXP%u LAST"
93 #define MUSE_HDR_PT_EXP_FST_COMMENT "Exposure %u first row index"
94 #define MUSE_HDR_PT_EXP_LST_COMMENT "Exposure %u last row index"
95 #define MUSE_HDR_PT_EXP_REGEXP "ESO DRS MUSE PIXTABLE EXP[0-9]+ (FIRST|LAST)"
96 
98 #define MUSE_HDR_PT_ILLUMi "ESO DRS MUSE PIXTABLE ILLUM%hu"
99 
100 #define MUSE_HDR_PT_ILLUM_MEAN "ESO DRS MUSE PIXTABLE ILLUM MEAN"
101 
102 #define MUSE_HDR_PT_ILLUM_STDEV "ESO DRS MUSE PIXTABLE ILLUM STDEV"
103 
104 #define MUSE_HDR_PT_ILLUM_REGEXP "^ESO DRS MUSE PIXTABLE ILLUM"
105 
106 /* properties of the pixel table stored in the FITS header */
111 #define MUSE_HDR_PT_XLO "ESO DRS MUSE PIXTABLE LIMITS X LOW"
112 
116 #define MUSE_HDR_PT_XHI "ESO DRS MUSE PIXTABLE LIMITS X HIGH"
117 
121 #define MUSE_HDR_PT_YLO "ESO DRS MUSE PIXTABLE LIMITS Y LOW"
122 
126 #define MUSE_HDR_PT_YHI "ESO DRS MUSE PIXTABLE LIMITS Y HIGH"
127 
131 #define MUSE_HDR_PT_LLO "ESO DRS MUSE PIXTABLE LIMITS LAMBDA LOW"
132 
136 #define MUSE_HDR_PT_LHI "ESO DRS MUSE PIXTABLE LIMITS LAMBDA HIGH"
137 
141 #define MUSE_HDR_PT_ILO "ESO DRS MUSE PIXTABLE LIMITS IFU LOW"
142 
146 #define MUSE_HDR_PT_IHI "ESO DRS MUSE PIXTABLE LIMITS IFU HIGH"
147 
151 #define MUSE_HDR_PT_SLO "ESO DRS MUSE PIXTABLE LIMITS SLICE LOW"
152 
156 #define MUSE_HDR_PT_SHI "ESO DRS MUSE PIXTABLE LIMITS SLICE HIGH"
157 /* regexp to delete all pixtable limits */
158 #define MUSE_HDR_PT_LIMITS_REGEXP "^ESO DRS MUSE PIXTABLE LIMITS "
159 
160 /* limits in spatial direction before applying DAR correction */
162 #define MUSE_HDR_PT_PREDAR_XLO "ESO DRS MUSE PIXTABLE PREDAR LIMITS XLO"
163 
164 #define MUSE_HDR_PT_PREDAR_XHI "ESO DRS MUSE PIXTABLE PREDAR LIMITS XHI"
165 
166 #define MUSE_HDR_PT_PREDAR_YLO "ESO DRS MUSE PIXTABLE PREDAR LIMITS YLO"
167 
168 #define MUSE_HDR_PT_PREDAR_YHI "ESO DRS MUSE PIXTABLE PREDAR LIMITS YHI"
169 
170 /* headers and comments to describe the status of the pixel table */
172 #define MUSE_HDR_PT_MERGED "ESO DRS MUSE PIXTABLE MERGED" /* int */
173 #define MUSE_HDR_PT_MERGED_COMMENT "Merged IFUs that went into this pixel table"
174 
175 #define MUSE_HDR_PT_SKYSUB "ESO DRS MUSE PIXTABLE SKYSUB" /* bool */
176 #define MUSE_HDR_PT_SKYSUB_COMMENT "Pixel table was sky-subtracted"
177 /* headers and comments to describe the DAR status */
179 #define MUSE_HDR_PT_DAR_NAME "ESO DRS MUSE PIXTABLE DAR CORRECT"
180 #define MUSE_HDR_PT_DAR_COMMENT "[Angstrom] ref. lambda for DAR correction"
181 #define MUSE_HDR_PT_DAR_C_SKIP "skipped DAR correction!"
182 
183 #define MUSE_HDR_PT_DAR_CHECK "ESO DRS MUSE PIXTABLE DAR CHECK"
184 #define MUSE_HDR_PT_DAR_CHECK_C "[arcsec] maximum residual DAR offsets found"
185 
186 #define MUSE_HDR_PT_DAR_CORR "ESO DRS MUSE PIXTABLE DAR CORRECT RESIDUAL"
187 #define MUSE_HDR_PT_DAR_CORR_C "[Angstrom] ref. lambda for residual DAR correction"
188 
189 #define MUSE_HDR_PT_RVCORR "ESO DRS MUSE PIXTABLE RVCORR"
190 #define MUSE_HDR_PT_RVCORR_C "[km/s] %scentric correction was applied"
191 
192 #define MUSE_HDR_PT_FLUXCAL "ESO DRS MUSE PIXTABLE FLUXCAL" /* bool */
193 #define MUSE_HDR_PT_FLUXCAL_COMMENT "Pixel table was flux-calibrated"
194 
195 #define MUSE_HDR_PT_WCS "ESO DRS MUSE PIXTABLE WCS" /* string */
196 
197 #define MUSE_HDR_PT_WCS_PROJ "projected (intermediate)"
198 #define MUSE_HDR_PT_WCS_COMMENT_PROJ "Gnomonic projection applied to this pixel table"
199 
200 #define MUSE_HDR_PT_WCS_POSI "positioned (final)"
201 #define MUSE_HDR_PT_WCS_COMMENT_POSI "Positioned this pixel table to sky coordinates"
202 
203 #define MUSE_HDR_PT_WEIGHTED "ESO DRS MUSE PIXTABLE WEIGHTED" /* bool */
204 #define MUSE_HDR_PT_WEIGHTED_COMMENT "Pixel table was weighted relative to other exposures"
205 
206 #define MUSE_HDR_PT_COMBINED "ESO DRS MUSE PIXTABLE COMBINED" /* int */
207 #define MUSE_HDR_PT_COMBINED_COMMENT "Combined exposures that went into this pixel table"
208 
209 /* regular expression to remove all pixtable-related keyword, *
210  * e.g. when transforming to 2D image or 3D cube */
211 #define MUSE_HDR_PT_REGEXP "^ESO DRS MUSE PIXTABLE "
212 
213 /*----------------------------------------------------------------------------*
214  * Special variable types *
215  *----------------------------------------------------------------------------*/
216 
217 /*----------------------------------------------------------------------------*/
224 /*----------------------------------------------------------------------------*/
225 typedef struct {
231  cpl_table *table;
232 
239  cpl_propertylist *header;
240 } muse_pixtable;
241 
242 /*----------------------------------------------------------------------------*/
246 /*----------------------------------------------------------------------------*/
254 };
255 
256 /*----------------------------------------------------------------------------*/
260 /*----------------------------------------------------------------------------*/
261 typedef enum {
271 
274 /*----------------------------------------------------------------------------*
275  * Function prototypes *
276  *----------------------------------------------------------------------------*/
277 /* utility functions dealing with the origin column */
278 uint32_t muse_pixtable_origin_encode(unsigned int, unsigned int, unsigned short, unsigned short, unsigned int);
279 unsigned int muse_pixtable_origin_get_x(uint32_t, muse_pixtable *, cpl_size);
280 unsigned int muse_pixtable_origin_get_y(uint32_t);
281 unsigned short muse_pixtable_origin_get_ifu(uint32_t);
282 unsigned short muse_pixtable_origin_get_slice(uint32_t);
283 unsigned int muse_pixtable_origin_set_offset(muse_pixtable *, cpl_polynomial *, unsigned short, unsigned short);
284 unsigned int muse_pixtable_origin_get_offset(muse_pixtable *, unsigned int, unsigned short, unsigned short);
285 cpl_error_code muse_pixtable_origin_copy_offsets(muse_pixtable *, muse_pixtable *, unsigned int);
286 unsigned int muse_pixtable_get_expnum(muse_pixtable *, cpl_size);
287 
288 /* the four main functions */
289 muse_pixtable *muse_pixtable_create(muse_image *, cpl_table *, cpl_table *, cpl_table *);
292 cpl_error_code muse_pixtable_save(muse_pixtable *, const char *);
293 muse_pixtable *muse_pixtable_load_window(const char *, cpl_size, cpl_size);
294 muse_pixtable *muse_pixtable_load(const char *);
295 muse_pixtable *muse_pixtable_load_restricted_wavelength(const char *, double, double);
296 muse_pixtable *muse_pixtable_load_merge_channels(cpl_table *, double, double);
297 
298 /* other utility functions for MUSE pixel tables */
300 cpl_size muse_pixtable_get_nrow(const muse_pixtable *);
302 
303 cpl_error_code muse_pixtable_restrict_wavelength(muse_pixtable *, double, double);
304 cpl_error_code muse_pixtable_restrict_xpos(muse_pixtable *, double, double);
305 cpl_error_code muse_pixtable_restrict_ypos(muse_pixtable *, double, double);
306 cpl_error_code muse_pixtable_erase_ifu_slice(muse_pixtable *, unsigned char, unsigned short);
308 
309 cpl_error_code muse_pixtable_dump(muse_pixtable *, cpl_size, cpl_size, unsigned char);
314 
315 cpl_error_code muse_pixtable_reset_dq(muse_pixtable *, unsigned int);
316 
319 
323 
324 #endif /* MUSE_PIXTABLE_H */
muse_pixtable_wcs
State of the astrometric calibration of a MUSE pixel table.
unsigned int muse_pixtable_get_expnum(muse_pixtable *, cpl_size)
Get the exposure number of a given row in a pixel table.
Structure definition for a collection of muse_images.
void muse_pixtable_extracted_delete(muse_pixtable **)
Delete a pixel table array.
muse_pixtable * muse_pixtable_load(const char *)
Load the table itself and the FITS headers of a MUSE pixel table from a file.
unsigned short muse_pixtable_origin_get_slice(uint32_t)
Get the slice number from the encoded 32bit origin number.
muse_pixtable * muse_pixtable_duplicate(muse_pixtable *)
Make a copy of the pixtanle.
cpl_size muse_pixtable_extracted_get_size(muse_pixtable **)
Get the size of an array of extracted pixel tables.
unsigned int muse_pixtable_origin_set_offset(muse_pixtable *, cpl_polynomial *, unsigned short, unsigned short)
Set the slice offset from the pixel table header.
muse_pixtable ** muse_pixtable_extracted_get_slices(muse_pixtable *)
Extract one pixel table per IFU and slice.
cpl_size muse_pixtable_get_nrow(const muse_pixtable *)
get the number of rows within the pixel table
int muse_pixtable_get_type(muse_pixtable *)
Determine the type of pixel table.
cpl_error_code muse_pixtable_and_selected_mask(muse_pixtable *, muse_mask *)
Select all pixels where the (x,y) positions are enabled in the given mask.
cpl_error_code muse_pixtable_erase_ifu_slice(muse_pixtable *, unsigned char, unsigned short)
Erase pixel table rows related to one slice of one IFU.
cpl_error_code muse_pixtable_dump(muse_pixtable *, cpl_size, cpl_size, unsigned char)
Dump a MUSE pixel table to the screen, resolving the origin column.
Structure definition of MUSE three extension FITS file.
Definition: muse_image.h:40
cpl_table * table
The pixel table.
cpl_error_code muse_pixtable_origin_copy_offsets(muse_pixtable *, muse_pixtable *, unsigned int)
Copy MUSE_HDR_PT_IFU_SLICE_OFFSET keywords between pixel tables.
cpl_error_code muse_pixtable_reset_dq(muse_pixtable *, unsigned int)
Reset a given bad pixel status (DQ flag) for all pixels in the table.
muse_imagelist * muse_pixtable_to_imagelist(muse_pixtable *)
Project a pixel table with data from one IFU back onto its image.
cpl_error_code muse_pixtable_restrict_wavelength(muse_pixtable *, double, double)
Restrict a pixel table to a certain wavelength range.
cpl_boolean muse_pixtable_is_skysub(muse_pixtable *)
Determine whether the pixel table is sky subtracted.
unsigned int muse_pixtable_origin_get_x(uint32_t, muse_pixtable *, cpl_size)
Get the horizontal coordinate from the encoded 32bit origin number.
Structure definition of MUSE pixel table.
muse_pixtable_wcs muse_pixtable_wcs_check(muse_pixtable *)
Check the state of the world coordinate system of a pixel table.
cpl_boolean muse_pixtable_is_fluxcal(muse_pixtable *)
Determine whether the pixel table is flux calibrated.
muse_pixtable_type
Type of a MUSE pixel table.
unsigned int muse_pixtable_origin_get_offset(muse_pixtable *, unsigned int, unsigned short, unsigned short)
Get the slice offset from the pixel table header.
uint32_t muse_pixtable_origin_encode(unsigned int, unsigned int, unsigned short, unsigned short, unsigned int)
Encode the three CCD coordinates defining the origin of one MUSE pixel into a 32bit integer...
muse_pixtable * muse_pixtable_load_window(const char *, cpl_size, cpl_size)
Load a range of rows from the table and all the FITS headers of a MUSE pixel table from a file...
muse_pixtable * muse_pixtable_create(muse_image *, cpl_table *, cpl_table *, cpl_table *)
Create the pixel table for one CCD.
muse_pixtable * muse_pixtable_load_restricted_wavelength(const char *, double, double)
Load a pixel table from file and cut down the wavelength range.
cpl_error_code muse_pixtable_save(muse_pixtable *, const char *)
Save a MUSE pixel table to a file on disk.
unsigned short muse_pixtable_origin_get_ifu(uint32_t)
Get the IFU number from the encoded 32bit origin number.
muse_pixtable * muse_pixtable_load_merge_channels(cpl_table *, double, double)
Load and merge the pixel tables of the 24 MUSE sub-fields.
cpl_error_code muse_pixtable_restrict_xpos(muse_pixtable *, double, double)
Restrict a pixel table to a certain x coordinate range.
cpl_error_code muse_pixtable_from_imagelist(muse_pixtable *, muse_imagelist *)
Get pixel table values back from a per-IFU imagelist.
Handling of "mask" files.
Definition: muse_mask.h:42
const muse_cpltable_def muse_pixtable_def[]
MUSE pixel table definition.
Definition of a cpl table structure.
unsigned int muse_pixtable_origin_get_y(uint32_t)
Get the vertical coordinate from the encoded 32bit origin number.
void muse_pixtable_delete(muse_pixtable *)
Deallocate memory associated to a pixel table object.
cpl_error_code muse_pixtable_restrict_ypos(muse_pixtable *, double, double)
Restrict a pixel table to a certain y coordinate range.
cpl_error_code muse_pixtable_compute_limits(muse_pixtable *)
(Re-)Compute the limits of the coordinate columns of a pixel table.
cpl_propertylist * header
The FITS header.
cpl_boolean muse_pixtable_is_rvcorr(muse_pixtable *)
Determine whether the pixel table is radial-velocity corrected.