MUSE Pipeline Reference Manual  2.1.1
muse_utils.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_UTILS_H
23 #define MUSE_UTILS_H
24 
25 /*----------------------------------------------------------------------------*
26  * Includes *
27  *----------------------------------------------------------------------------*/
28 #include <cpl.h>
29 #include <math.h> /* isnormal, isfinite */
30 
31 #include "muse_dfs.h"
32 #include "muse_image.h"
33 #include "muse_pixtable.h"
34 #include "muse_processing.h"
35 
36 /* make compilation fail when FILENAME_MAX is not defined, as that is used *
37  * in various parts of the code to allocated char* for path/filenames */
38 #ifndef FILENAME_MAX
39 # error FILENAME_MAX undefined!
40 #endif
41 
42 /*----------------------------------------------------------------------------*
43  * Defines *
44  *----------------------------------------------------------------------------*/
45 /* Two macros that can be used to work around compiler warnings of the type *
46  * "warning: unused parameter 'arg'" that occur in functions that are not *
47  * yet fully implemented or in test programs that don't really need arguments. *
48  * This trick was taken from SQLite where it was tested on a large variety of *
49  * compilers. */
50 #define UNUSED_ARGUMENT(arg) (void)(arg)
51 #define UNUSED_ARGUMENTS(arg1,arg2) UNUSED_ARGUMENT(arg1),UNUSED_ARGUMENT(arg2);
52 
53 /* work around missing isfinite() */
54 #if !HAVE_ISFINITE
55 #if HAVE_ISNAN && HAVE_ISINF
56 #define isfinite(x) (!isnan(x) && !isinf(x))
57 #else /* last resort, primitive own implementation */
58 #define isfinite(x) ((x != nan) && (x != -nan) && (x != inf) && (x != -inf))
59 #endif
60 #endif
61 
62 /* work around missing isnormal() */
63 #if !HAVE_ISNORMAL
64 #if HAVE_ISNAN && HAVE_ISINF
65 #define isnormal(x) (!isnan(x) && !isinf(x) && (x != 0.))
66 #else /* last resort, primitive own implementation */
67 #define isnormal(x) ((x != nan) && (x != -nan) && (x != inf) && (x != -inf) \
68  && (x != 0.) && (x != -0.))
69 #endif
70 #endif
71 
72 /* work around missing drand48() */
73 #if !HAVE_DRAND48
74 /* make a drand48() replacement using rand() which is already in C89 */
75 #define drand48() ((double)(rand()) / RAND_MAX)
76 #endif
77 
81 /* MUSE specific error codes */
82 /* failures to load any muse_image extension */
83 #define MUSE_ERROR_READ_DATA CPL_ERROR_EOL+1
84 #define MUSE_ERROR_READ_DQ CPL_ERROR_EOL+2
85 #define MUSE_ERROR_READ_STAT CPL_ERROR_EOL+3
86 /* tracing errors */
87 #define MUSE_ERROR_SLICE_LEFT_MISSING CPL_ERROR_EOL+4
88 #define MUSE_ERROR_SLICE_RIGHT_MISSING CPL_ERROR_EOL+5
89 #define MUSE_ERROR_SLICE_EDGE_MISSING CPL_ERROR_EOL+6
90 /* detector aliveness check failed after raw data couldn't be read */
91 #define MUSE_ERROR_CHIP_NOT_LIVE CPL_ERROR_EOL+10
92 
93 /*----------------------------------------------------------------------------*
94  * Data structures *
95  *----------------------------------------------------------------------------*/
96 
97 /*----------------------------------------------------------------------------*/
101 /*----------------------------------------------------------------------------*/
102 typedef enum {
107 
110 /*----------------------------------------------------------------------------*
111  * Function prototypes *
112  *----------------------------------------------------------------------------*/
113 const char *muse_get_license(void);
114 
115 unsigned char muse_utils_get_ifu(const cpl_propertylist *);
116 int muse_utils_get_extension_for_ifu(const char *, unsigned char);
117 
118 cpl_frameset *muse_frameset_find(const cpl_frameset *, const char *, unsigned char, cpl_boolean);
119 cpl_frameset *muse_frameset_find_tags(const cpl_frameset *, const cpl_array *, unsigned char, cpl_boolean);
120 cpl_frameset *muse_frameset_check_raw(const cpl_frameset *, const cpl_array *, unsigned char);
121 cpl_frameset *muse_frameset_sort_raw_other(const cpl_frameset *, int, const char *, cpl_boolean);
122 cpl_frame *muse_frameset_find_master(const cpl_frameset *, const char *, unsigned char);
123 cpl_error_code muse_utils_frameset_merge_frames(cpl_frameset *, cpl_boolean);
124 
126 double muse_utils_filter_fraction(const muse_table *, double, double);
127 cpl_error_code muse_utils_filter_copy_properties(cpl_propertylist *, const muse_table *, double);
128 
129 char *muse_utils_header_get_lamp_names(cpl_propertylist *, char);
130 cpl_array *muse_utils_header_get_lamp_numbers(cpl_propertylist *);
131 cpl_image *muse_utils_image_fit_polynomial(const cpl_image *, unsigned short, unsigned short);
132 cpl_error_code muse_utils_image_get_centroid_window(cpl_image *, int, int, int, int, double *, double *, muse_utils_centroid_type);
133 cpl_error_code muse_utils_get_centroid(const cpl_matrix *, const cpl_vector *, const cpl_vector *, double *, double *, muse_utils_centroid_type);
134 cpl_error_code muse_utils_fit_multigauss_1d(const cpl_vector *, const cpl_bivector *, cpl_vector *, double *, cpl_vector *, cpl_vector *, double *, double *, cpl_matrix **);
135 cpl_error_code muse_utils_fit_moffat_2d(const cpl_matrix *, const cpl_vector *, const cpl_vector *, cpl_array *, cpl_array *, const cpl_array *, double *, double *);
136 cpl_polynomial *muse_utils_iterate_fit_polynomial(cpl_matrix *, cpl_vector *, cpl_vector *, cpl_table *, const unsigned int, const double, double *, double *);
137 double muse_utils_pixtable_fit_line_gaussian(muse_pixtable *, double, double, double, float, float, unsigned char, cpl_array *, cpl_array *);
138 cpl_matrix *muse_matrix_new_gaussian_2d(int, int, double);
139 
140 cpl_error_code muse_utils_copy_modified_header(cpl_propertylist *, cpl_propertylist *, const char *, const char *);
141 cpl_error_code muse_utils_set_hduclass(cpl_propertylist *, const char *, const char *, const char *, const char *);
142 
143 void muse_utils_memory_dump(const char *);
144 
145 muse_image *muse_fov_load(const char *aFilename);
146 cpl_image *muse_convolve_image(const cpl_image *aImage, const cpl_matrix *aKernel);
147 
148 #endif /* MUSE_UTILS_H */
double muse_utils_pixtable_fit_line_gaussian(muse_pixtable *, double, double, double, float, float, unsigned char, cpl_array *, cpl_array *)
Fit a 1D Gaussian to a given wavelength range in a pixel table.
Definition: muse_utils.c:2442
int muse_utils_get_extension_for_ifu(const char *, unsigned char)
Return extension number that corresponds to this IFU/channel number.
Definition: muse_utils.c:118
unsigned char muse_utils_get_ifu(const cpl_propertylist *)
Find out the IFU/channel from which this header originated.
Definition: muse_utils.c:98
muse_utils_centroid_type
Background handling when computing centroids.
Definition: muse_utils.h:102
cpl_error_code muse_utils_filter_copy_properties(cpl_propertylist *, const muse_table *, double)
Add/propagate filter properties to header of collapsed image.
Definition: muse_utils.c:934
void muse_utils_memory_dump(const char *)
Display the current memory usage of the given program.
Definition: muse_utils.c:2702
muse_image * muse_fov_load(const char *aFilename)
Load a FOV image into a MUSE image.
Definition: muse_utils.c:2864
Structure definition of MUSE three extension FITS file.
Definition: muse_image.h:40
cpl_error_code muse_utils_set_hduclass(cpl_propertylist *, const char *, const char *, const char *, const char *)
Set HDU headers for the ESO FITS data format.
Definition: muse_utils.c:2611
const char * muse_get_license(void)
Get the pipeline copyright and license.
Definition: muse_utils.c:83
Structure definition of MUSE pixel table.
cpl_error_code muse_utils_fit_moffat_2d(const cpl_matrix *, const cpl_vector *, const cpl_vector *, cpl_array *, cpl_array *, const cpl_array *, double *, double *)
Fit a 2D Moffat function to a given set of data.
Definition: muse_utils.c:1878
cpl_polynomial * muse_utils_iterate_fit_polynomial(cpl_matrix *, cpl_vector *, cpl_vector *, cpl_table *, const unsigned int, const double, double *, double *)
Iterate a polynomial fit.
Definition: muse_utils.c:2234
cpl_frameset * muse_frameset_sort_raw_other(const cpl_frameset *, int, const char *, cpl_boolean)
Create a new frameset containing all relevant raw frames first then all other frames.
Definition: muse_utils.c:418
muse_table * muse_table_load_filter(muse_processing *, const char *)
Load a table for a given filter name.
Definition: muse_utils.c:799
Structure to store a table together with a property list.
Definition: muse_table.h:43
cpl_error_code muse_utils_fit_multigauss_1d(const cpl_vector *, const cpl_bivector *, cpl_vector *, double *, cpl_vector *, cpl_vector *, double *, double *, cpl_matrix **)
Carry out a multi-Gaussian fit of data in a vector.
Definition: muse_utils.c:1558
char * muse_utils_header_get_lamp_names(cpl_propertylist *, char)
Concatenate names of all active calibration lamps.
Definition: muse_utils.c:989
double muse_utils_filter_fraction(const muse_table *, double, double)
Compute fraction of filter area covered by the data range.
Definition: muse_utils.c:893
cpl_array * muse_utils_header_get_lamp_numbers(cpl_propertylist *)
List numbers of all active calibration lamps.
Definition: muse_utils.c:1056
cpl_image * muse_utils_image_fit_polynomial(const cpl_image *, unsigned short, unsigned short)
Create a smooth version of a 2D image by fitting it with a 2D polynomial.
Definition: muse_utils.c:1147
cpl_image * muse_convolve_image(const cpl_image *aImage, const cpl_matrix *aKernel)
Compute the convolution of an image with a kernel.
Definition: muse_utils.c:2748
cpl_error_code muse_utils_image_get_centroid_window(cpl_image *, int, int, int, int, double *, double *, muse_utils_centroid_type)
Compute centroid over an image window, optionally marginalizing over the background.
Definition: muse_utils.c:1234
cpl_matrix * muse_matrix_new_gaussian_2d(int, int, double)
Create a matrix that contains a normalized 2D Gaussian.
Definition: muse_utils.c:1099
cpl_frameset * muse_frameset_check_raw(const cpl_frameset *, const cpl_array *, unsigned char)
return frameset containing good raw input data
Definition: muse_utils.c:284
cpl_frameset * muse_frameset_find(const cpl_frameset *, const char *, unsigned char, cpl_boolean)
return frameset containing data from an IFU/channel with a certain tag
Definition: muse_utils.c:160
cpl_error_code muse_utils_frameset_merge_frames(cpl_frameset *, cpl_boolean)
Merge IFU-specific files from a frameset to create multi-IFU outputs.
Definition: muse_utils.c:589
cpl_frame * muse_frameset_find_master(const cpl_frameset *, const char *, unsigned char)
find the master frame according to its CCD number and tag
Definition: muse_utils.c:505
cpl_error_code muse_utils_copy_modified_header(cpl_propertylist *, cpl_propertylist *, const char *, const char *)
Copy a modified header keyword from one header to another.
Definition: muse_utils.c:2570
cpl_error_code muse_utils_get_centroid(const cpl_matrix *, const cpl_vector *, const cpl_vector *, double *, double *, muse_utils_centroid_type)
Compute centroid of a two-dimensional dataset.
Definition: muse_utils.c:1328
cpl_frameset * muse_frameset_find_tags(const cpl_frameset *, const cpl_array *, unsigned char, cpl_boolean)
return frameset containing data from an IFU/channel with the given tag(s)
Definition: muse_utils.c:253