MUSE Pipeline Reference Manual  2.1.1
muse_qi_mask.c
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 #ifdef HAVE_CONFIG_H
23 #include <config.h>
24 #endif
25 
26 /*---------------------------------------------------------------------------*
27  * Includes *
28  *---------------------------------------------------------------------------*/
29 #include <string.h>
30 
31 #include <muse.h>
32 #include "muse_qi_mask_z.h"
33 
34 /*---------------------------------------------------------------------------*
35  * Functions code *
36  *---------------------------------------------------------------------------*/
37 
38 /*----------------------------------------------------------------------------*/
48 /*----------------------------------------------------------------------------*/
49 static void
50 muse_qi_mask_wavecal_polys(cpl_propertylist *aHeader, cpl_table *aWC,
51  cpl_table *aTT)
52 {
53  if (!aHeader || !aWC || !aTT) {
54  cpl_error_set_message(__func__, CPL_ERROR_NULL_INPUT, "Could not create per"
55  "-slice wavelength polynomials in the FITS header!");
56  return;
57  }
58 
59  /* number of evaluation steps for the wavelength calibration solution */
60  const unsigned int kSteps = 50;
61 
62  /* create matrix and vector for the fitting process */
63  cpl_matrix *pos = cpl_matrix_new(1, kMuseSlicesPerCCD * kSteps);
64  cpl_vector *val = cpl_vector_new(kMuseSlicesPerCCD * kSteps),
65  *ycenters = cpl_vector_new(kMuseSlicesPerCCD);
66  cpl_size ipos = 0;
67  unsigned short nslice;
68  for (nslice = 1; nslice <= kMuseSlicesPerCCD; nslice++) {
69  cpl_polynomial *pw = muse_wave_table_get_poly_for_slice(aWC, nslice),
70  **pt = muse_trace_table_get_polys_for_slice(aTT, nslice);
71  /* evaluate central trace at vertical center of the CCD */
72  double x = cpl_polynomial_eval_1d(pt[MUSE_TRACE_CENTER], kMuseOutputYTop/2,
73  NULL);
75 
76  cpl_polynomial *pconst = cpl_polynomial_new(1);
77  cpl_size pows = 0;
78  cpl_polynomial_set_coeff(pconst, &pows, x);
79  /* reduce the polynomial to 1D at the center of the slice */
80  cpl_polynomial *pwcen = cpl_polynomial_extract(pw, 0, pconst);
81  double ycen = cpl_polynomial_eval_1d(pwcen, kMuseOutputYTop/2, NULL);
82  cpl_vector_set(ycenters, nslice - 1, ycen);
83  cpl_polynomial_delete(pconst);
84  cpl_polynomial_delete(pw);
85 
86  /* shift the polynomial to a common center */
87  pows = 0;
88  double c0 = cpl_polynomial_get_coeff(pwcen, &pows);
89  cpl_polynomial_set_coeff(pwcen, &pows, c0 - ycen);
90 
91  unsigned int iy;
92  for (iy = 1;
93  iy <= (unsigned)kMuseOutputYTop;
94  iy += ((unsigned)kMuseOutputYTop) / (kSteps - 1)) {
95  cpl_matrix_set(pos, 0, ipos, iy);
96  cpl_vector_set(val, ipos++, cpl_polynomial_eval_1d(pwcen, iy, NULL));
97  }
98  } /* for nslice */
99 
100  /* now try to fit the common 2nd-order polynomial */
101  cpl_polynomial *fit = cpl_polynomial_new(1);
102  cpl_size maxdeg = 2;
103  cpl_polynomial_fit(fit, pos, NULL, val, NULL, CPL_TRUE, NULL, &maxdeg);
104 #if 0 /* DEBUG */
105  cpl_vector *res = cpl_vector_duplicate(val);
106  double chisq;
107  cpl_vector_fill_polynomial_fit_residual(res, val, NULL, fit, pos, &chisq);
108  const double mse = cpl_vector_product(res, res)
109  / cpl_vector_get_size(res);
110  cpl_vector_delete(res);
111  cpl_msg_debug(__func__, "MSE=%g ChiSq=%g", mse, chisq);
112 #endif
113  cpl_vector_delete(val);
114  cpl_matrix_delete(pos);
115 
116  /* now finally add the relevant keywords to the header for this IFU */
117  char keyword[KEYWORD_LENGTH];
118  cpl_size j = 0; /* accessor to polynomial coefficients */
119  for (nslice = 1; nslice <= kMuseSlicesPerCCD; nslice++) {
120  snprintf(keyword, KEYWORD_LENGTH, "ESO DET WLEN SLICE%hu POLY0", nslice);
121  /* add the vertical shift back again */
122  double zeropoint = cpl_polynomial_get_coeff(fit, &j)
123  + cpl_vector_get(ycenters, nslice - 1);
124  cpl_propertylist_append_float(aHeader, keyword, zeropoint);
125  cpl_propertylist_set_comment(aHeader, keyword,
126  "[Angstrom] Slice-specific zero-point");
127  } /* for nslice */
128  cpl_vector_delete(ycenters);
129 
130  /* also add the common coefficients for 1st and 2nd order */
131  for (j = 1; j <= 2; j++) {
132  snprintf(keyword, KEYWORD_LENGTH, "ESO DET WLEN POLY%d", (int)j);
133  cpl_propertylist_append_float(aHeader, keyword,
134  cpl_polynomial_get_coeff(fit, &j));
135  char comment[100];
136  snprintf(comment, 99, "[Angstrom] Common %s-order polynomial coefficient",
137  j == 1 ? "1st" : "2nd");
138  cpl_propertylist_set_comment(aHeader, keyword, comment);
139  } /* for j (polynomial orders) */
140  cpl_polynomial_delete(fit);
141 } /* muse_qi_mask_wavecal_polys() */
142 
143 /*----------------------------------------------------------------------------*/
154 /*----------------------------------------------------------------------------*/
155 int
156 muse_qi_mask_compute(muse_processing *aProcessing,
157  muse_qi_mask_params_t *aParams)
158 {
159  /* check for wrange and/or wmin/wmax parameters */
160  double wmin = 4650.,
161  wmax = 9300.;
162 
163  cpl_msg_info(__func__, "Creating mask for full MUSE wavelength range "
164  "(%.1f...%.1f)", wmin, wmax);
165 
166  /* if we find a BIAS input, add it to usedframes to get it *
167  * to be used for creation of the DFS-compliant header */
168  cpl_frame *frame = cpl_frameset_find(aProcessing->inframes, MUSE_TAG_BIAS);
169  if (frame) {
170  muse_processing_append_used(aProcessing, frame, CPL_FRAME_GROUP_RAW, 1);
171  }
172 
173  /* create at least minimal header and save it */
174  cpl_propertylist *header = cpl_propertylist_new();
175  cpl_propertylist_append_string(header, "OBJECT", "Mask full MUSE range");
176  cpl_propertylist_append_float(header, "ESO DET FRS WMIN", wmin);
177  cpl_propertylist_set_comment(header, "ESO DET FRS WMIN", "[Angstrom] Minimum wavelength");
178  cpl_propertylist_append_float(header, "ESO DET FRS WMAX", wmax);
179  cpl_propertylist_set_comment(header, "ESO DET FRS WMAX", "[Angstrom] Maximum wavelength");
180  muse_processing_save_header(aProcessing, aParams->nifu ? aParams->nifu : -1,
181  header, MUSE_TAG_MASK_IMAGE);
182  cpl_propertylist_delete(header);
183 
184  /* get output filename from output frameset */
185  frame = cpl_frameset_find(aProcessing->outframes, MUSE_TAG_MASK_IMAGE);
186  const char *fn = cpl_frame_get_filename(frame);
187 
188  /* loop over all 24 IFUs */
189  int n1 = aParams->nifu ? aParams->nifu : 1,
190  n2 = aParams->nifu ? aParams->nifu : kMuseNumIFUs,
191  nifu;
192  for (nifu = n1; nifu <= n2; nifu++) {
193  /* load raw (bias) image and trim it or create minimal default image */
194  cpl_errorstate prestate = cpl_errorstate_get();
195  muse_imagelist *images = muse_basicproc_load(aProcessing, nifu, NULL);
196  muse_image *image = NULL;
197  if (images) {
198  cpl_msg_debug(__func__, "succeeded to load %u raw images, using first one",
199  muse_imagelist_get_size(images));
200  image = muse_imagelist_get(images, 0);
201  } else {
202  cpl_msg_warning(__func__, "failed to load raw image, assuming 1x1 binning");
203  cpl_errorstate_dump(prestate, CPL_FALSE, muse_cplerrorstate_dump_some);
204  image = muse_image_new();
205  /* use typical 1x1 binned trimmed MUSE image size */
206  image->data = cpl_image_new(kMuseOutputXRight, kMuseOutputYTop,
207  CPL_TYPE_FLOAT);
208  image->header = cpl_propertylist_new();
209  cpl_propertylist_append_int(image->header, "ESO DET BINX", 1);
210  cpl_propertylist_append_int(image->header, "ESO DET BINY", 1);
211  images = muse_imagelist_new();
212  muse_imagelist_set(images, image, 0); /* to easily delete it below */
213  }
214 
215  /* load wavecaltable and tracetable */
216  cpl_table *wavecaltable = muse_processing_load_ctable(aProcessing,
217  MUSE_TAG_WAVECAL_TABLE,
218  nifu),
219  *tracetable = muse_processing_load_ctable(aProcessing,
220  MUSE_TAG_TRACE_TABLE, nifu);
221 
222  /* create the wavelength map, first always unbinned */
223  int binx = muse_pfits_get_binx(image->header),
224  biny = muse_pfits_get_biny(image->header);
225  muse_image *imunbinned = image;
226  if (binx != 1 || biny != 1) { /* need unbinned image for wavemep to work */
227  imunbinned = muse_image_new();
228  imunbinned->data = cpl_image_new(kMuseOutputXRight, kMuseOutputYTop,
229  CPL_TYPE_FLOAT);
230  }
231  cpl_image *wavemap = muse_wave_map(imunbinned, wavecaltable, tracetable);
232 
233  /* now take into account the binning */
234  if (binx != 1 || biny != 1) {
235  muse_image_delete(imunbinned);
236  cpl_msg_info(__func__, "Rebinning wavelength map %dx%d", binx, biny);
237  cpl_image *binned = cpl_image_rebin(wavemap, 1, 1, binx, biny);
238  cpl_image_delete(wavemap);
239  /* cpl_image_rebin() creates summed image, we need averaged */
240  wavemap = cpl_image_divide_scalar_create(binned, binx * biny);
241  cpl_image_delete(binned);
242  }
243 
244  /* apply the threshold in wavelengths */
245  cpl_mask *mask = cpl_mask_threshold_image_create(wavemap, wmin, wmax);
246 
247  /* create the output FITS header, for properties in this extension */
248  header = cpl_propertylist_new();
249  if (binx == 1 && biny == 1) {
250  muse_qi_mask_wavecal_polys(header, wavecaltable, tracetable);
251  }
252 
253  /* Analyze mask to determine slice positions and store them in the *
254  * header. Use the trimmed mask, so that cpl_apertures_get_size() *
255  * finds 48 connected regions instead of 96 with the overscan gap. *
256  * Also make up for the pre- and overscans by adding n*32/bin. */
257  int nx = cpl_mask_get_size_x(mask),
258  ny = cpl_mask_get_size_y(mask);
259  cpl_size ndet;
260  cpl_image *labeled = cpl_image_labelise_mask_create(mask, &ndet);
261  /* it is simplest to use apertures to get the coordinates that we want */
262  cpl_apertures *apertures = cpl_apertures_new_from_image(labeled, labeled);
263  int napertures = cpl_apertures_get_size(apertures);
264  /* the apertures are not sorted by x position and we cannot *
265  * sort apertures externally to CPL, so use an x-sorted object *
266  * to access slice numbers directly */
267  cpl_matrix *mlabels = cpl_matrix_new(2, napertures);
268  int n; /* aperture number = label number */
269  for (n = 1; n <= napertures; n++) {
270  cpl_matrix_set(mlabels, 0, n - 1,
271  cpl_apertures_get_left(apertures, n)); /* x-position in row. 0 */
272  cpl_matrix_set(mlabels, 1, n - 1, n); /* aperture number in row. 1 */
273  } /* for n (all apertures) */
274  cpl_matrix_sort_columns(mlabels, 1); /* sort by x-position value */
275 #if 0
276  cpl_matrix_dump(mlabels, stdout);
277 #endif
278  int m, /* index entry in matrix */
279  nslice = 1; /* real slice number */
280  for (m = 1; m <= ndet; m++) {
281  n = cpl_matrix_get(mlabels, 1, m - 1); /* get aperture number from sorted matrix */
282  /* aperture extremes, with prescan added */
283  int x1 = cpl_apertures_get_left(apertures, n),
284  x2 = cpl_apertures_get_right(apertures, n),
285  y1 = cpl_apertures_get_bottom(apertures, n),
286  y2 = cpl_apertures_get_top(apertures, n);
287  if (x1 == x2 || y1 == y2) {
288  /* need to exclude single-pixel apertures, created by rebinning; *
289  * also replace them with zeros in the mask */
290  int i;
291  for (i = x1; i <= x2; i++) {
292  int j;
293  for (j = y1; j <= y2; j++) {
294  cpl_mask_set(mask, i, j, CPL_BINARY_0);
295  } /* for j (all y pixels of detection) */
296  } /* for i (all x pixels of detection) */
297  cpl_msg_debug(__func__, "Excluding aperture [%d:%d,%d:%d]", x1, x2, y1, y2);
298  continue;
299  }
300  /* add prescan to aperture extremes */
301  x1 += 32 / binx;
302  x2 += 32 / binx;
303  y1 += 32 / biny;
304  y2 += 32 / biny;
305  /* add overscan gaps */
306  if (x1 > nx/2+32/binx) x1 += 64 / binx;
307  if (x2 > nx/2+32/binx) x2 += 64 / binx;
308  if (y1 > ny/2+32/biny) y1 += 64 / biny;
309  if (y2 > ny/2+32/biny) y2 += 64 / biny;
310 #if 0
311  int xc = (x1 + x2) / 2,
312  yc = (y1 + y2) / 2,
313  w = x2 - x1 + 1,
314  h = y2 - y1 + 1;
315  cpl_msg_debug(__func__, "Aperture %2d Slice %2d: [%d:%d,%d:%d] center %d,%d size %dx%d",
316  n, m, x1, x2, y1, y2, xc, yc, w, h);
317 #endif
318  char keyword[KEYWORD_LENGTH];
319  snprintf(keyword, KEYWORD_LENGTH, "ESO DET SLICE%d XSTART", nslice);
320  cpl_propertylist_append_int(header, keyword, x1);
321  cpl_propertylist_set_comment(header, keyword, "[pix] Start position of the slice along X");
322  snprintf(keyword, KEYWORD_LENGTH, "ESO DET SLICE%d YSTART", nslice);
323  cpl_propertylist_append_int(header, keyword, y1);
324  cpl_propertylist_set_comment(header, keyword, "[pix] Start position of the slice along Y");
325  snprintf(keyword, KEYWORD_LENGTH, "ESO DET SLICE%d XEND", nslice);
326  cpl_propertylist_append_int(header, keyword, x2);
327  cpl_propertylist_set_comment(header, keyword, "[pix] End position of the slice along X");
328  snprintf(keyword, KEYWORD_LENGTH, "ESO DET SLICE%d YEND", nslice);
329  cpl_propertylist_append_int(header, keyword, y2);
330  cpl_propertylist_set_comment(header, keyword, "[pix] End position of the slice along Y");
331  nslice++;
332  } /* for m (all matrix entries) */
333  cpl_image_delete(labeled);
334  cpl_apertures_delete(apertures);
335  cpl_matrix_delete(mlabels);
336  if (nslice - 1 != kMuseSlicesPerCCD) {
337  cpl_msg_warning(__func__, "Found %d slices (%d apertures) instead of %d",
338  nslice - 1, napertures, kMuseSlicesPerCCD);
339  }
340 
341  /* re-add pre- and overscans, assuming 32/bin pixels on all sides */
342  cpl_mask *untrimmed = cpl_mask_new(nx + 4*32/binx, ny + 4*32/biny);
343  cpl_mask *m1 = cpl_mask_extract(mask, 1, 1, nx/2-1, ny/2-1),
344  *m2 = cpl_mask_extract(mask, 1, ny/2, nx/2-1, ny),
345  *m3 = cpl_mask_extract(mask, nx/2, 1, nx, ny/2-1),
346  *m4 = cpl_mask_extract(mask, nx/2, ny/2, nx, ny);
347  cpl_mask_copy(untrimmed, m1, 32/binx+1, 32/biny+1);
348  cpl_mask_copy(untrimmed, m2, 32/binx+1, ny/2+3*32/biny);
349  cpl_mask_copy(untrimmed, m3, nx/2+3*32/binx, 32/biny+1);
350  cpl_mask_copy(untrimmed, m4, nx/2+3*32/binx, ny/2+3*32/biny);
351  cpl_mask_delete(m1);
352  cpl_mask_delete(m2);
353  cpl_mask_delete(m3);
354  cpl_mask_delete(m4);
355  cpl_mask_delete(mask);
356  mask = untrimmed;
357 
358  /* save the image to extension CHAN%02d, as 8bit mask image */
359  if (image->header) {
360  /* copy relevant detector properties from input image */
361  cpl_propertylist_copy_property_regexp(header, image->header,
362  "ESO DET (CHIP |OUT)|EXTNAME", 0);
363  } else {
364  /* create minimal header with only EXTNAME */
365  char *extname = cpl_sprintf("CHAN%02d", nifu);
366  cpl_propertylist_append_string(header, "EXTNAME", extname);
367  cpl_free(extname);
368  }
369  cpl_mask_save(mask, fn, header, CPL_IO_EXTEND);
370  cpl_propertylist_delete(header);
371  cpl_image_delete(wavemap);
372  cpl_mask_delete(mask);
373  cpl_table_delete(tracetable);
374  cpl_table_delete(wavecaltable);
375  muse_imagelist_delete(images);
376  } /* for nifu */
377 
378  return 0;
379 } /* muse_qi_mask_compute() */
muse_imagelist * muse_basicproc_load(muse_processing *aProcessing, unsigned char aIFU, muse_basicproc_params *aBPars)
Load the raw input files from disk and do basic processing.
cpl_polynomial ** muse_trace_table_get_polys_for_slice(const cpl_table *aTable, const unsigned short aSlice)
construct polynomial from the trace table entry for the given slice
Structure definition for a collection of muse_images.
void muse_image_delete(muse_image *aImage)
Deallocate memory associated to a muse_image object.
Definition: muse_image.c:85
cpl_polynomial * muse_wave_table_get_poly_for_slice(const cpl_table *aTable, const unsigned short aSlice)
Construct polynomial from the wavelength calibration table entry for the given slice.
cpl_image * data
the data extension
Definition: muse_image.h:46
void muse_imagelist_delete(muse_imagelist *aList)
Free the memory of the MUSE image list.
Structure definition of MUSE three extension FITS file.
Definition: muse_image.h:40
cpl_propertylist * header
the FITS header
Definition: muse_image.h:72
unsigned int muse_imagelist_get_size(muse_imagelist *aList)
Return the number of stored images.
void muse_trace_polys_delete(cpl_polynomial *aPolys[])
Delete the multi-polynomial array created in relation to tracing.
cpl_error_code muse_processing_save_header(muse_processing *aProcessing, int aIFU, cpl_propertylist *aHeader, const char *aTag)
Save a FITS header to disk.
int muse_pfits_get_biny(const cpl_propertylist *aHeaders)
find out the binning factor in y direction
Definition: muse_pfits.c:566
muse_image * muse_imagelist_get(muse_imagelist *aList, unsigned int aIdx)
Get the muse_image of given list index.
cpl_frameset * outframes
void muse_cplerrorstate_dump_some(unsigned aCurrent, unsigned aFirst, unsigned aLast)
Dump some CPL errors.
cpl_image * muse_wave_map(muse_image *aImage, const cpl_table *aWave, const cpl_table *aTrace)
Write out a wavelength map for visual checks.
void muse_processing_append_used(muse_processing *aProcessing, cpl_frame *aFrame, cpl_frame_group aGroup, int aDuplicate)
Add a frame to the set of used frames.
Structure to hold the parameters of the muse_qi_mask recipe.
int muse_pfits_get_binx(const cpl_propertylist *aHeaders)
find out the binning factor in x direction
Definition: muse_pfits.c:548
cpl_table * muse_processing_load_ctable(muse_processing *aProcessing, const char *aTag, unsigned char aIFU)
Load a CPL table according to its tag and IFU/channel number.
muse_imagelist * muse_imagelist_new(void)
Create a new (empty) MUSE image list.
cpl_frameset * inframes
muse_image * muse_image_new(void)
Allocate memory for a new muse_image object.
Definition: muse_image.c:66
cpl_error_code muse_imagelist_set(muse_imagelist *aList, muse_image *aImage, unsigned int aIdx)
Set the muse_image of given list index.
int nifu
IFU to handle. If set to 0, all IFUs are processed serially, which is the recommendation for this rec...