wave_calibration.h

00001 #ifndef WAVE_CALIBRATION_H
00002 #define WAVE_CALIBRATION_H
00003 /*******************************************************************************
00004 * E.S.O. - VLT project
00005 *
00006 * "@(#) $Id: wave_calibration.h,v 1.9 2005/05/23 07:03:34 amodigli Exp $"
00007 *
00008 * who       when      what
00009 * --------  --------  ----------------------------------------------
00010 * schreib  13/07/00  created
00011 */
00012 
00013 /************************************************************************
00014  * wave_calibration.h
00015  * routines needed for wavelength calibration
00016  *----------------------------------------------------------------------
00017  */
00018 
00019 /*
00020  * header files
00021  */
00022 
00023 /*
00024 #include <stdio.h>
00025 #include <inttypes.h> 
00026 #include <string.h>
00027 */
00028 
00029 /*
00030 #include "recipes.h"
00031 #include "svd.h"
00032 #include "eclipse.h"
00033 #include "spectrum_ops.h"
00034 #include <math.h>
00035 */
00036 #include <qfits.h>
00037 #include <cpl.h>
00038 #include "wavecal.h"
00039 
00040 
00041 /*
00042  * function prototypes
00043  */
00044 
00045 /*----------------------------------------------------------------------------
00046    Function     :       newFitParams()
00047    In           :       number of parameters that will be fitted
00048    Out          :       allocated vector of FitParams data structures
00049    Job          :       allocates memory for a new vector of 
00050                         FitParams data structures
00051  ---------------------------------------------------------------------------*/
00052 /*<python>*/
00053 FitParams ** newFitParams( int n_params ) ;
00054 /*</python>*/
00055 
00056 /*----------------------------------------------------------------------------
00057    Function     :       destroyFitParams()
00058    In           :       fit params to destroy
00059    Out          :       nothing
00060    Job          :       frees memory of a vector of FitParams data structures
00061  ---------------------------------------------------------------------------*/
00062 
00063 /*<python>*/
00064 void destroyFitParams ( FitParams ** params ) ;
00065 /*</python>*/
00066 
00067 /*----------------------------------------------------------------------------
00068    Function     :       dumpFitParamsToAscii()
00069    In           :       params: fit params to dump
00070                         filename
00071    Out          :       filled ASCII file
00072    Job          :       dumps the fit parameters to an ASCII file
00073  ---------------------------------------------------------------------------*/
00074 
00075 /*<python>*/
00076 void dumpFitParamsToAscii ( FitParams ** params, char * filename ) ;
00077 /*</python>*/
00078 
00079 /*----------------------------------------------------------------------------
00080    Function     :       dumpAsciiToFitParams()
00081    In           :       allocated dummy for the fit params
00082                         filename
00083    Out          :       params: filled FitParams object
00084    Job          :       dumps ASCII information to an allocated FitParams data structure
00085  ---------------------------------------------------------------------------*/
00086 
00087 /*<python>*/
00088 void dumpAsciiToFitParams ( FitParams ** params, char * filename ) ;
00089 /*</python>*/
00090 
00091 /*----------------------------------------------------------------------------
00092    Function     :       findLines()
00093    In           :       lineImage: merged emission line image,
00094                         wave_position: wavelength list in Angstroems
00095                         wave_intensity: corresponding intensity list
00096                         n_lines: number of lines in list
00097                         row_clean: resulting list of the row indices but without the
00098                                    lines that are too close to each other for the fit
00099                         wavelength_clean: corrected wavelength list corresponding to
00100                                           the row_clean array
00101                         beginWave: beginning wavelength on detector in microns
00102                         dispersion: dispersion of the grating on the detector
00103                                     (microns per pixel, attention: merged image).
00104                         mindiff: minimal difference of mean and median column
00105                                  intensity to do the correlation.
00106                                  This is done to avoid correlations in columns
00107                                  without emission line intensity.
00108                         halfWidth:   half width of the box where the line must sit,
00109                         n_found_lines: number of found and correlated
00110                                        emission lines in a column.
00111                         sigma: sigma of Gaussian that is convolved with the artificial spectrum
00112    Out          :       0 if all went o.k.
00113                         row: resulting list of the row indices of the line positions
00114                         row_clean: resulting list of the row indices but without the
00115                                    lines that are too close to each other for the fit
00116                         wavelength: wavelength from the list corresponding to the
00117                                     found row positions
00118                         wavelength_clean: corrected wavelength list corresponding to
00119                                           the row_clean array
00120                         n_found_lines: number of found and correlated
00121                                        emission lines in a column.
00122                         sum_lines: total sum of found and correlated emission lines
00123                         INT32_MAX = 2^32/2 if something has gone wrong
00124    Job          :       determines the pixel shift between the line list
00125                         and the real image by using the beginning wavelength
00126                         on the detector and the dispersion estimate.
00127  ---------------------------------------------------------------------------*/
00128 
00129 /*<python>*/
00130 int findLines( OneImage * lineImage,
00131                float    * wave_position,
00132                float    * wave_intensity,
00133                int        n_lines,
00134                int     ** row_clean,
00135                float   ** wavelength_clean,
00136                float      beginWave,
00137                float      dispersion1,
00138                float      dispersion2,
00139                float      mindiff,
00140                int        halfWidth,
00141                int      * n_found_lines,
00142                float      sigma,
00143                int      * sum_lines ) ;
00144 /*</python>*/
00145 
00146 /*----------------------------------------------------------------------------
00147    Function     :       readList()
00148    In           :       name of the list file, arrays to store the wavelength
00149                         and the intensities of the emission lines
00150    Out          :       number of lines in file
00151    Job          :       reads the line data  of the calibration lamps
00152  ---------------------------------------------------------------------------*/
00153 
00154 /*<python>*/
00155 int readList( char * listname, float * lineCenter, float * lineIntensity ) ;
00156 /*</python>*/
00157 
00158 /*----------------------------------------------------------------------------
00159    Function     :       linefit()
00160    In           :       mergedImage: image of a calibration emission lamp,
00161                         par:         dummys for the resulting fitting parameters,
00162                         fwhm:        guess for full width of half maximum of gaussian
00163                         lineInd:     index of the emission line,
00164                         column:      present index of the image column,
00165                         halfWidth:   half width of the box where the line must sit,
00166                         lineRow:     row index where the line is expected,
00167                         min_amplitude: minimum amplitude of the Gaussian with
00168                                        respect to the background to do the fit
00169    Out          :       the fitting parameter data structure containing the
00170                         resulting parameters.
00171                         integers:
00172                         number of iterations if all was ok,
00173                         -8   if no input image was given,
00174                         -9   if no dummy for the fit parameters is given,
00175                         -10  if the wrong column index was given,
00176                         -11  if the wrong box width was given,
00177                         -12  if the wrong row index was given,
00178                         -13  if a wrong minimum amplitude factor was given
00179                         -14  if the spectral vector data structure memory
00180                              could not be allocated
00181                         -15  wrong row index or box width was given,
00182                         -16  negative peak or signal too low to fit
00183                         -17 least squares fit failed
00184    Job          :       fits a gaussian to a 1-dimensional slice of an image,
00185                         this routine uses the routine lsqfit_c as a non-linear
00186                         least square fit method (Levenberg-Marquardt).
00187  ---------------------------------------------------------------------------*/
00188 
00189 int linefit ( OneImage  * mergedImage,
00190               FitParams * par,
00191               float       fwhm,
00192               int         lineInd,
00193               int         column,
00194               int         halfWidth,
00195               int         lineRow,
00196               float       min_amplitude,
00197           Vector    *  line,
00198           int       *  mpar,
00199           float     *  xdat,
00200           float     *  wdat ) ;
00201 
00202 /*----------------------------------------------------------------------------
00203    Function     :       fitLines
00204    In           :       line_image: merged image of a calibration lamp ,
00205                         allParams:  allocated vector of FitParams data structures,
00206                         fwhm:       guess for full width of half maximum of gaussian,
00207                         n_lines:    number of neon lines that will be fitted in one column ,
00208                         row:        list of the rows of the fitted lines
00209                         wavelength: list of wavelength corresponding to the found line rows
00210                         width:      list of the half widths
00211                                     around the corresponding rows to find line
00212                         min_amplitude: minimal amplitude of the Gaussian beyond which 
00213                        the fit is carried through.
00214    Out          :       filled FitParams data structure vector,
00215                         number of successfully fitted lines,
00216                         errors: negative integers resulting from the linefit
00217                                 routine and:
00218                         -18: no image given,
00219                         -19: number of emission lines or number of slitlets is wrong,
00220                         -20: vector of the slitlet boundaries or of the line rows or
00221                              of the half width are empty.
00222                         -21: no wavelength array given.
00223    Job          :       calculates and stores the fit parameters of the neon
00224                         emission lines of a neon frame by using the linefit
00225                         routine.
00226  ---------------------------------------------------------------------------*/
00227 
00228 int fitLines ( OneImage  *  line_image,
00229                FitParams ** allParams,
00230                float        fwhm,
00231                int       *  n_lines,
00232                int       ** row,
00233                float     ** wavelength,
00234                int          width,
00235                float        min_amplitude ) ;
00236 
00237 /*----------------------------------------------------------------------------
00238    Function     :       polyfit()
00239    In           :       par:          filled array of fit parameter structure
00240                         column:       image column index
00241                         n_lines:      number of lines found in column
00242                         n_rows:       number of image rows
00243                         dispersion:   microns per pixel
00244                         max_residual: maximum residual value, beyond that value
00245                                       the fit is rejected.
00246                         acoefs:       array of the 3 coefficients of the fitted
00247                                       parabola
00248                         n_reject:     rejected number of fits due to high residuals
00249                         n_fitcoefs:   number of polynomial coefficients to fit
00250    Out          :       chisq, the three fit coefficients acoefs[i] and their
00251                         variances dacoefs[i], the rejected number of fits
00252                         due to too high residuals: n_reject
00253    Job          :       fits a second order polynom
00254                         lambda[i] = a1 + a2*pos[i] + a3*pos[i]^2
00255                         to determine the connection between the listed wave-
00256                         length values and the gauss-fitted positions for each
00257                         image column using the singular value decomposition
00258                         method.
00259  ---------------------------------------------------------------------------*/
00260 
00261 float polyfit( FitParams ** par,
00262                int          column,
00263                int          n_lines,
00264                int          n_rows,
00265                float        dispersion,
00266                float        max_residual,
00267                float *      acoefs,
00268                float *      dacoefs,
00269                int   *      n_reject,
00270                int          n_fitcoefs ) ;
00271 
00272 /*----------------------------------------------------------------------------
00273    Function     :       coefsCrossFit()
00274    In           :       n_columns:    number of image columns
00275                         acoefs:       coeffs fitted in polyfit
00276                                       note: this is a vector of coefficients with
00277                                             the same index for all columns
00278                         dacoefs:      fit errors of the corresponding acoefs
00279                         bcoefs:       the fitted coefs
00280                         n_fitcoefs:   number of fit coefficients
00281                         sigma_factor: factor of sigma beyond which the
00282                                       column coefficients are discarded for the fit
00283 
00284    Out          :       chisq, the found fit coefficients
00285    Job          :       Fits the each single parameter of the three fit parameters
00286                         acoefs from polyfit through the image columns
00287  ---------------------------------------------------------------------------*/
00288 
00289 float coefsCrossFit ( int      n_columns,
00290                       float *  acoefs,
00291                       float *  dacoefs,
00292                       float *  bcoefs,
00293                       int      n_fitcoefs,
00294                       float    sigma_factor ) ;
00295 
00296 /*----------------------------------------------------------------------------
00297    Function     :       waveMap()
00298    In           :       lineImage:    image from a calibration emission lamp,
00299                         bcoefs:       transformed fit coefficients
00300                         n_a_fitcoefs: number of fit coefficients for the single
00301                                       column fits lambda-position
00302                         n_b_fitcoefs: number of fit coefficients for the fits of
00303                                       the single a coefficients across the columns
00304                         wavelength:   wavelength list from lamp file
00305                         intensity:    corresponding line intensity from line list
00306                         n_lines:      number of lines in the list
00307                         magFactor:    magnifying factor of the image for FFT
00308    Out          :       wavelength calibration map image.
00309    Job          :       this routine determines a wavelength calibration map
00310                         frame associating a wavelength value to each pixel
00311                         by using the fit coefficients determined before.
00312  ---------------------------------------------------------------------------*/
00313 
00314 /*<python>*/
00315 OneImage * waveMap( OneImage * lineImage,
00316                     float   ** bcoefs,
00317                     int        n_a_fitcoefs,
00318                     int        n_b_fitcoefs,
00319                     float    * wavelength,
00320                     float    * intensity,
00321                     int        n_lines,
00322                     int        magFactor) ;
00323 /*</python>*/
00324 
00325 /*----------------------------------------------------------------------------
00326    Function     :       wavelengthCalibration()
00327    In           :       image:        merged image from a calibration emission lamp,
00328                         wave:         wavelength array read from the wavelength list
00329                         n_lines:      number of lines in the wavelength list
00330                         row_clean: resulting list of the row indices but without the
00331                                    lines that are too close to each other for the fit
00332                                    output of findLines()
00333                         wavelength_clean: corrected wavelength list corresponding to
00334                                           the row_clean array
00335                                           output of findLines()
00336                         n_found_lines: output of findLines(): total number of found emission lines
00337                         dispersion:   dispersion of spectrum: micron per pixel
00338                         halfWidth:    half width of the box where the line must sit
00339                         minAmplitude: minimum amplitude of the Gaussian beyond which
00340                                       the fit is carried out
00341                         max_residual: maximum residual value, beyond that value
00342                                       the polynomial lambda-position fit is rejected.
00343                         fwhm:         first guess for the full width of half maximum
00344                                       of the gaussian line fit
00345                         n_a_fitcoefs: number of fit coefficients for the single
00346                                       column fits: lambda-position
00347                         n_b_fitcoefs: number of fit coefficients for the fits of
00348                                       the single a coefficients across the columns
00349                         sigmaFactor:  factor of the standard deviation of the determined
00350                                       polynomial coefficients of the columns beyond
00351                                       which these coefficients are not used to carry out
00352                                       the polynomial fit across the columns.
00353                         pixel_tolerance: maximum tolerated difference between estimated
00354                                          and fitted line positions.
00355    Out          :       0 if all went o.k., -1 if something went wrong.
00356                         bcoefs: array of cooefficients of the polynomial fit across the columns.
00357                         par: array of the resulting FitParams data structure
00358    Job          :       this routine takes an image from a calibration
00359                         emission lamp and delivers the fit coefficients of
00360                         a polynomial fit across the columns
00361                         of the coefficients of the polynomial line position
00362                         fits as output. Furthermore it delivers an array of the fit parameters
00363                         as output. This routine expects Nyquist sampled spectra
00364                         (either an interleaved image or an image convolved with an
00365                          appropriate function in spectral direction)
00366  ---------------------------------------------------------------------------*/
00367 
00368 /*<python>*/
00369 int wavelengthCalibration( OneImage   * image,
00370                            FitParams ** par ,
00371                            float     ** bcoefs,
00372                            float      * wave,
00373                            int          n_lines,
00374                            int       ** row_clean,
00375                            float     ** wavelength_clean,
00376                            int        * n_found_lines,
00377                            float        dispersion,
00378                            int          halfWidth,
00379                            float        minAmplitude,
00380                            float        max_residual,
00381                            float        fwhm,
00382                            int          n_a_fitcoefs,
00383                            int          n_b_fitcoefs,
00384                            float        sigmaFactor,
00385                float        pixel_tolerance ) ;
00386 /*</python>*/
00387 
00388 /*----------------------------------------------------------------------------
00389    Function     :       convolveImageByGauss()
00390    In           :       lineImage:  emission line image
00391                         hw:         kernel half width of the gaussian
00392                                     response function
00393    Out          :       emission line image convolved with a gaussian
00394    Job          :       convolves an emission line image with a gaussian
00395                         with user given integer half width by using the eclipse
00396                         routine function1d_filter_lowpass().
00397  ---------------------------------------------------------------------------*/
00398 
00399 /*<python>*/
00400 OneImage * convolveImageByGauss( OneImage * lineImage,
00401                                  int        hw ) ;
00402 /*</python>*/
00403 
00404 /*----------------------------------------------------------------------------
00405    Function     :       definedResampling()
00406    In           :       image:      source image to be calibrated
00407                         calimage:   wavelength map image
00408                         n_params:   number of fit parameters for polynomial interpolation
00409                                     standard should be 3
00410                                     that means order of polynom + 1
00411                         n_rows:     desired number of rows for the final image,
00412                                     this will be the final number of spectral pixels
00413                                     in the final data cube.
00414                         dispersion: dummy for the resulting dispersion
00415                         minval:     dummy for minimal wavelength value,
00416                         maxval:     dummy for maximal wavelength value
00417                         centralLambda: dummy for the final central wavelength
00418    Out          :       wavelength calibrated source image,
00419                         dispersion: resulting spectral dispersion (microns/pixel)
00420                                     is chosen as the minimum dispersion found in
00421                                     the wavelength map - 2% of this value
00422                         minval:     minimal wavelength value,
00423                         maxval:     maximal wavelength value
00424                         centralLambda: final central wavelength value
00425                         centralpix:    row of central wavelength
00426                                        (in image coordinates!)
00427    Job          :       Given a source image and a corresponding wavelength
00428                         calibration file this routine produces an image
00429                         in which elements in a given row are associated
00430                         with a single wavelength. It thus corrects for
00431                         the wavelength shifts between adjacent elements
00432                         in the rows of the input image. The output image
00433                         is larger in the wavelength domain than the input
00434                         image with pixels in each column corresponding to
00435                         undefined (blank, ZERO) values. The distribution
00436                         of these undefined values varies from column to
00437                         column. The input image is resampled at discrete
00438                         wavelength intervals using the polynomial interpolation
00439                         routine.
00440                         The wavelength intervals (dispersion) and the
00441                         central wavelength are defined and stable for each
00442                         used grating. Thus, each row has a defined wavelength
00443                         for each grating. Only the number of rows can be
00444                         changed by the user.
00445  ---------------------------------------------------------------------------*/
00446 
00447 /*<python>*/
00448 OneImage * definedResampling( OneImage * image,
00449                               OneImage * calimage,
00450                               int        n_params,
00451                               int*        n_rows,
00452                               double   * dispersion,
00453                               float    * minval,
00454                               float    * maxval,
00455                               double   * centralLambda,
00456                               int    * centralpix ) ;
00457 /*</python>*/
00458 
00459 
00460 #endif 

Generated on Wed Oct 26 13:08:56 2005 for SINFONI Pipeline Reference Manual by doxygen1.2.13.1 written by Dimitri van Heesch, © 1997-2001