/*-------------------------------------------------------------------------*/
/**
   @file    spectro_wave.h
   @author  N.Devillard
   @date    October 1999
   @version $Revision: 1.11 $
   @brief   spectroscopy routines
*/
/*--------------------------------------------------------------------------*/

/*
    $Id: spectro_wave.h,v 1.11 2001/11/07 16:14:40 yjung Exp $
    $Author: yjung $
    $Date: 2001/11/07 16:14:40 $
    $Revision: 1.11 $
*/

#ifndef _SPECTRO_WAVE_H_
#define _SPECTRO_WAVE_H_

/*---------------------------------------------------------------------------
   								Includes
 ---------------------------------------------------------------------------*/

#include <stdio.h>
#include <stdlib.h>

#include "eclipse.h"

/*---------------------------------------------------------------------------
   								Defines
 ---------------------------------------------------------------------------*/
/* Tolerated wavelength range in angstroms: targetted for infrared */

#define MIN_WAVELENGTH		0.0
#define MAX_WAVELENGTH		(1000000) /* 100 microns */

/*---------------------------------------------------------------------------
   							Function prototypes
 ---------------------------------------------------------------------------*/


/*-------------------------------------------------------------------------*/
/**
  @brief    compute a dispersion relation
  @param  inimage     Allocated spectroscopic image
  @param  discard_lo  number of pixels to discard at the bottom
  @param  discard_hi  (at the top)
  @param  discard_le  Number of pixels to discard on the left
  @param  discard_ri  Number of pixels to discard on the left
  @param  remove_thermal  Flag to force thermal background removal.
  @param  table_name  spectral table name (see below)
  @param  wl_min      wavelength range as [wl_min..wl_max] in angstroms
  @param  wl_max
  @return two linear coefficients such as wave = c[0] + c[1]*pix

  Compute a dispersion relation from a spectroscopic image showing some
  strong emission lines. A vital assumption is that strong emission lines
  can be seen in the image.
  
  The spectral table name is a character string. Possible values are:
  
  \begin{tabular}{ll}
  "oh"            &   OH lines \\
  "Xe"            &   Xenon lines \\
  "Ar"            &   Argon lines \\
  "Xe+Ar"         &   Xenon and Argon lines \\
  "/path/file"    &   Full pathname of an ASCII table
  \end{tabular}
  
  The latter specifies an ASCII table containing the lines you want to
  use for spectral calibration. Notice that this table must respect the
  format described in spectral_lines.c.
  
  Algorithm:
  \begin{itemize}
  \item Spectrum extraction along the spectrum direction (horizontal).
  For each column the lower and higher
  pixels are discarded, then a median value of the remaining pixels in
  the column is returned. This forms a 1d signal of same size as the
  image in the spectrum direction.
  \item If a thermal background should be removed, this is done at this
  point.
  \item If some values must be discarded (set to zero) in the input
  spectrum, they are zeroed at that point.
  \item Spectral lines are retrieved from a catalog (internal).
  \item Cross-correlation of the extracted signal and the spectral lines
  catalog at various scales. The best scale (highest cross-correlation
  factor) is kept, and the displacement giving the best cross-correlation
  factor is computed.
  \item The offset and scale are converted to wavelengths, using the
  catalog.
  \item A linear relation is computed and returned.
  \end{itemize}

  Setting parts of the input spectrum to zero enables a correct
  wavelength calibration in the thermal regime. You should provide -1 and
  -1 if you want to let this function decide for you about a correct
  zeroing interval, (0,0) if you do not want to zero the spectrum at all,
  and any other values depending on which interval you want to set to
  zero on each side of the spectrum.
  Notice that setting these values to (10,20) will set to zero the 10
  left pixels and 20 rightmost pixels of the input spectrum before
  throwing it into the cross-correlation procedure.
*/
/*---------------------------------------------------------------------------*/
/* <python> */
double * spectro_compute_disprel_from_table(
        image_t *   in,
        int         discard_lo,
        int         discard_hi,
        int         discard_le,
        int         discard_ri,
        int         remove_thermal,
        char    *   table_name,
        double      wl_min,
        double      wl_max) ;
/* </python> */

#endif