MUSE Pipeline Reference Manual  2.1.1
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-2016 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 
47 /* Table columns of a MUSE pixel table. See muse_pixtable_def for comments. */
48 #define MUSE_PIXTABLE_DATA "data"
49 #define MUSE_PIXTABLE_DQ "dq"
50 #define MUSE_PIXTABLE_STAT "stat"
51 #define MUSE_PIXTABLE_XPOS "xpos"
52 #define MUSE_PIXTABLE_YPOS "ypos"
53 #define MUSE_PIXTABLE_LAMBDA "lambda"
54 #define MUSE_PIXTABLE_ORIGIN "origin"
55 /* relative weight of a pixel (used for combining exposures) */
56 #define MUSE_PIXTABLE_WEIGHT "weight"
58 /* Table columns of the flat-field spectrum of a MUSE pixel table. */
59 #define MUSE_PIXTABLE_FF_EXT "PIXTABLE_FLAT_FIELD"
60 #define MUSE_PIXTABLE_FFLAMBDA MUSE_PIXTABLE_LAMBDA
61 #define MUSE_PIXTABLE_FFDATA MUSE_PIXTABLE_DATA
63 extern const muse_cpltable_def muse_pixtable_def[];
64 
74 #define MUSE_HDR_PT_IFU_SLICE_OFFSET "ESO DRS MUSE PIXTABLE EXP%u IFU%02hu SLICE%02hu XOFFSET"
75 #define MUSE_HDR_PT_IFU_SLICE_OFFSET_COMMENT "x-offset of given slice in given IFU of given exposure"
76 
83 #define MUSE_HDR_PT_TYPE "ESO DRS MUSE PIXTABLE TYPE"
84 #define MUSE_PIXTABLE_STRING_SIMPLE "SIMPLE"
85 #define MUSE_PIXTABLE_STRING_FULL "GEOFULL"
86 #define MUSE_PIXTABLE_COMMENT_SIMPLE "pixel table without y coordinates"
87 #define MUSE_PIXTABLE_COMMENT_FULL "pixel table with full geometry information"
88 
93 #define MUSE_HDR_PT_EXP_FST "ESO DRS MUSE PIXTABLE EXP%u FIRST"
94 
98 #define MUSE_HDR_PT_EXP_LST "ESO DRS MUSE PIXTABLE EXP%u LAST"
99 #define MUSE_HDR_PT_EXP_FST_COMMENT "Exposure %u first row index"
100 #define MUSE_HDR_PT_EXP_LST_COMMENT "Exposure %u last row index"
101 #define MUSE_HDR_PT_EXP_REGEXP "ESO DRS MUSE PIXTABLE EXP[0-9]+ (FIRST|LAST)"
102 
104 #define MUSE_HDR_PT_ILLUMi "ESO DRS MUSE PIXTABLE ILLUM%hu"
105 
106 #define MUSE_HDR_PT_ILLUM_MEAN "ESO DRS MUSE PIXTABLE ILLUM MEAN"
107 
108 #define MUSE_HDR_PT_ILLUM_STDEV "ESO DRS MUSE PIXTABLE ILLUM STDEV"
109 
110 #define MUSE_HDR_PT_ILLUM_REGEXP "^ESO DRS MUSE PIXTABLE ILLUM"
111 
112 /* properties of the pixel table stored in the FITS header */
117 #define MUSE_HDR_PT_XLO "ESO DRS MUSE PIXTABLE LIMITS X LOW"
118 
122 #define MUSE_HDR_PT_XHI "ESO DRS MUSE PIXTABLE LIMITS X HIGH"
123 
127 #define MUSE_HDR_PT_YLO "ESO DRS MUSE PIXTABLE LIMITS Y LOW"
128 
132 #define MUSE_HDR_PT_YHI "ESO DRS MUSE PIXTABLE LIMITS Y HIGH"
133 
137 #define MUSE_HDR_PT_LLO "ESO DRS MUSE PIXTABLE LIMITS LAMBDA LOW"
138 
142 #define MUSE_HDR_PT_LHI "ESO DRS MUSE PIXTABLE LIMITS LAMBDA HIGH"
143 
147 #define MUSE_HDR_PT_ILO "ESO DRS MUSE PIXTABLE LIMITS IFU LOW"
148 
152 #define MUSE_HDR_PT_IHI "ESO DRS MUSE PIXTABLE LIMITS IFU HIGH"
153 
157 #define MUSE_HDR_PT_SLO "ESO DRS MUSE PIXTABLE LIMITS SLICE LOW"
158 
162 #define MUSE_HDR_PT_SHI "ESO DRS MUSE PIXTABLE LIMITS SLICE HIGH"
163 /* regexp to delete all pixtable limits */
164 #define MUSE_HDR_PT_LIMITS_REGEXP "^ESO DRS MUSE PIXTABLE LIMITS "
165 
166 /* limits in spatial direction before applying DAR correction */
168 #define MUSE_HDR_PT_PREDAR_XLO "ESO DRS MUSE PIXTABLE PREDAR LIMITS XLO"
169 
170 #define MUSE_HDR_PT_PREDAR_XHI "ESO DRS MUSE PIXTABLE PREDAR LIMITS XHI"
171 
172 #define MUSE_HDR_PT_PREDAR_YLO "ESO DRS MUSE PIXTABLE PREDAR LIMITS YLO"
173 
174 #define MUSE_HDR_PT_PREDAR_YHI "ESO DRS MUSE PIXTABLE PREDAR LIMITS YHI"
175 
176 /* headers and comments to describe the status of the pixel table */
178 #define MUSE_HDR_PT_FFCORR "ESO DRS MUSE PIXTABLE FFCORR" /* int */
179 #define MUSE_HDR_PT_FFCORR_COMMENT "Pixel table corrected for flat-field spectrum"
180 
181 #define MUSE_HDR_PT_MERGED "ESO DRS MUSE PIXTABLE MERGED" /* int */
182 #define MUSE_HDR_PT_MERGED_COMMENT "Merged IFUs that went into this pixel table"
183 
184 #define MUSE_HDR_PT_SKYSUB "ESO DRS MUSE PIXTABLE SKYSUB" /* bool */
185 #define MUSE_HDR_PT_SKYSUB_COMMENT "Pixel table was sky-subtracted"
186 /* headers and comments to describe the DAR status */
188 #define MUSE_HDR_PT_DAR_NAME "ESO DRS MUSE PIXTABLE DAR CORRECT"
189 #define MUSE_HDR_PT_DAR_COMMENT "[Angstrom] ref. lambda for DAR correction"
190 #define MUSE_HDR_PT_DAR_C_SKIP "skipped DAR correction!"
191 
192 #define MUSE_HDR_PT_DAR_CHECK "ESO DRS MUSE PIXTABLE DAR CHECK"
193 #define MUSE_HDR_PT_DAR_CHECK_C "[arcsec] maximum residual DAR offsets found"
194 
195 #define MUSE_HDR_PT_DAR_CORR "ESO DRS MUSE PIXTABLE DAR CORRECT RESIDUAL"
196 #define MUSE_HDR_PT_DAR_CORR_C "[Angstrom] ref. lambda for residual DAR correction"
197 
198 #define MUSE_HDR_PT_RVCORR "ESO DRS MUSE PIXTABLE RVCORR"
199 #define MUSE_HDR_PT_RVCORR_C "[km/s] %scentric correction was applied"
200 
201 #define MUSE_HDR_PT_FLUXCAL "ESO DRS MUSE PIXTABLE FLUXCAL" /* bool */
202 #define MUSE_HDR_PT_FLUXCAL_COMMENT "Pixel table was flux-calibrated"
203 
204 #define MUSE_HDR_PT_WCS "ESO DRS MUSE PIXTABLE WCS" /* string */
205 
206 #define MUSE_HDR_PT_WCS_PROJ "projected (intermediate)"
207 #define MUSE_HDR_PT_WCS_COMMENT_PROJ "Gnomonic projection applied to this pixel table"
208 
209 #define MUSE_HDR_PT_WCS_POSI "positioned (final)"
210 #define MUSE_HDR_PT_WCS_COMMENT_POSI "Positioned this pixel table to sky coordinates"
211 
212 #define MUSE_HDR_PT_WEIGHTED "ESO DRS MUSE PIXTABLE WEIGHTED" /* bool */
213 #define MUSE_HDR_PT_WEIGHTED_COMMENT "Pixel table was weighted relative to other exposures"
214 
215 #define MUSE_HDR_PT_COMBINED "ESO DRS MUSE PIXTABLE COMBINED" /* int */
216 #define MUSE_HDR_PT_COMBINED_COMMENT "Combined exposures that went into this pixel table"
217 
218 #define MUSE_HDR_PT_SPEC_TYPE "ESO DRS MUSE PIXTABLE SPECTYPE" /* string */
219 #define MUSE_HDR_PT_SPEC_TYPE_COMMENT "FITS spectral type code of wavelength"
220 
221 /* regular expression to remove all pixtable-related keyword, *
222  * e.g. when transforming to 2D image or 3D cube */
223 #define MUSE_HDR_PT_REGEXP "^ESO DRS MUSE PIXTABLE "
224 
225 /*----------------------------------------------------------------------------*
226  * Special variable types *
227  *----------------------------------------------------------------------------*/
228 
229 /*----------------------------------------------------------------------------*/
236 /*----------------------------------------------------------------------------*/
237 typedef struct {
243  cpl_table *table;
244 
251  cpl_propertylist *header;
252 
260  cpl_table *ffspec;
261 } muse_pixtable;
262 
263 /*----------------------------------------------------------------------------*/
267 /*----------------------------------------------------------------------------*/
275 };
276 
277 /*----------------------------------------------------------------------------*/
281 /*----------------------------------------------------------------------------*/
282 typedef enum {
283  MUSE_PIXTABLE_OPERATION_SUBTRACT = 0,
284  MUSE_PIXTABLE_OPERATION_MULTIPLY,
285  MUSE_PIXTABLE_OPERATION_DIVIDE
287 
288 /*----------------------------------------------------------------------------*/
292 /*----------------------------------------------------------------------------*/
293 typedef enum {
303 
306 /*----------------------------------------------------------------------------*
307  * Function prototypes *
308  *----------------------------------------------------------------------------*/
309 /* utility functions dealing with the origin column */
310 uint32_t muse_pixtable_origin_encode(unsigned int, unsigned int, unsigned short, unsigned short, unsigned int);
311 unsigned int muse_pixtable_origin_get_x(uint32_t, muse_pixtable *, cpl_size);
312 unsigned int muse_pixtable_origin_get_y(uint32_t);
313 unsigned short muse_pixtable_origin_get_ifu(uint32_t);
314 unsigned short muse_pixtable_origin_get_slice(uint32_t);
315 unsigned int muse_pixtable_origin_set_offset(muse_pixtable *, cpl_polynomial *, unsigned short, unsigned short);
316 unsigned int muse_pixtable_origin_get_offset(muse_pixtable *, unsigned int, unsigned short, unsigned short);
317 cpl_error_code muse_pixtable_origin_copy_offsets(muse_pixtable *, muse_pixtable *, unsigned int);
318 unsigned int muse_pixtable_get_expnum(muse_pixtable *, cpl_size);
319 
320 /* the four main functions */
321 muse_pixtable *muse_pixtable_create(muse_image *, cpl_table *, cpl_table *, cpl_table *);
324 cpl_error_code muse_pixtable_append_ff(muse_pixtable *, muse_image *, cpl_table *, cpl_table *, float);
325 cpl_error_code muse_pixtable_save(muse_pixtable *, const char *);
326 muse_pixtable *muse_pixtable_load_window(const char *, cpl_size, cpl_size);
327 muse_pixtable *muse_pixtable_load(const char *);
328 muse_pixtable *muse_pixtable_load_restricted_wavelength(const char *, double, double);
329 muse_pixtable *muse_pixtable_load_merge_channels(cpl_table *, double, double);
330 
331 /* other utility functions for MUSE pixel tables */
333 cpl_size muse_pixtable_get_nrow(const muse_pixtable *);
335 cpl_error_code muse_pixtable_flux_multiply(muse_pixtable *, double);
336 cpl_error_code muse_pixtable_spectrum_apply(muse_pixtable *, const cpl_array *, const cpl_array *, muse_pixtable_operation);
337 
338 cpl_error_code muse_pixtable_restrict_wavelength(muse_pixtable *, double, double);
339 cpl_error_code muse_pixtable_restrict_xpos(muse_pixtable *, double, double);
340 cpl_error_code muse_pixtable_restrict_ypos(muse_pixtable *, double, double);
341 cpl_error_code muse_pixtable_erase_ifu_slice(muse_pixtable *, unsigned char, unsigned short);
343 
344 cpl_error_code muse_pixtable_dump(muse_pixtable *, cpl_size, cpl_size, unsigned char);
349 
350 cpl_error_code muse_pixtable_reset_dq(muse_pixtable *, unsigned int);
351 
354 
358 
359 #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_append_ff(muse_pixtable *, muse_image *, cpl_table *, cpl_table *, float)
Create flat-field spectrum and append to pixel table.
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.
cpl_table * ffspec
A flat-field spectrum.
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_operation
Type of operation to apply to a MUSE pixel table.
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:43
cpl_error_code muse_pixtable_spectrum_apply(muse_pixtable *, const cpl_array *, const cpl_array *, muse_pixtable_operation)
Apply a spectrum given by two arrays with an operation to a pixel table.
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_error_code muse_pixtable_flux_multiply(muse_pixtable *, double)
Scale the flux of a pixel table with correct treatment of variance.
cpl_boolean muse_pixtable_is_rvcorr(muse_pixtable *)
Determine whether the pixel table is radial-velocity corrected.