Loading...
Searching...
No Matches
Wavelength calibration

## Functions

cpl_error_code | cpl_wlcalib_fill_line_spectrum (cpl_vector *self, void *model, const cpl_polynomial *disp)
| Generate a 1D spectrum from a model and a dispersion relation.
cpl_error_code | cpl_wlcalib_fill_line_spectrum_fast (cpl_vector *self, void *model, const cpl_polynomial *disp)
| Generate a 1D spectrum from a model and a dispersion relation.
cpl_error_code | cpl_wlcalib_fill_logline_spectrum (cpl_vector *self, void *model, const cpl_polynomial *disp)
| Generate a 1D spectrum from a model and a dispersion relation.
cpl_error_code | cpl_wlcalib_fill_logline_spectrum_fast (cpl_vector *self, void *model, const cpl_polynomial *disp)
| Generate a 1D spectrum from a model and a dispersion relation.
cpl_error_code | cpl_wlcalib_find_best_1d (cpl_polynomial *self, const cpl_polynomial *guess, const cpl_vector *spectrum, void *model, cpl_error_code(*filler)(cpl_vector *, void *, const cpl_polynomial *), const cpl_vector *wl_search, cpl_size nsamples, cpl_size hsize, double *xcmax, cpl_vector *xcorrs)
| Find the best 1D dispersion polynomial in a given search space.
void | cpl_wlcalib_slitmodel_delete (cpl_wlcalib_slitmodel *self)
| Free memory associated with a cpl_wlcalib_slitmodel object.
cpl_wlcalib_slitmodel * | cpl_wlcalib_slitmodel_new (void)
| Create a new line model to be initialized.
cpl_error_code | cpl_wlcalib_slitmodel_set_catalog (cpl_wlcalib_slitmodel *self, cpl_bivector *catalog)
| Set the catalog of lines to be used by the spectrum filler.
cpl_error_code | cpl_wlcalib_slitmodel_set_threshold (cpl_wlcalib_slitmodel *self, double value)
| The (positive) threshold for truncating the transfer function.
cpl_error_code | cpl_wlcalib_slitmodel_set_wfwhm (cpl_wlcalib_slitmodel *self, double value)
| Set the FWHM of the transfer function to be used by the spectrum filler.
cpl_error_code | cpl_wlcalib_slitmodel_set_wslit (cpl_wlcalib_slitmodel *self, double value)
| Set the slit width to be used by the spectrum filler.

## Detailed Description

This module contains functions to perform 1D-wavelength calibration, typically of long-slit spectroscopy data.

Synopsis:
  #include "cpl_wlcalib.h"

## Function Documentation

## cpl_wlcalib_fill_line_spectrum()

cpl_error_code cpl_wlcalib_fill_line_spectrum | ( | cpl_vector * | self,
|  | void * | model,
|  | const cpl_polynomial * | disp )

Generate a 1D spectrum from a model and a dispersion relation.

Parameters

  self | Vector to fill with spectrum
  model | Pointer to cpl_wlcalib_slitmodel object
  disp | 1D-Dispersion relation, at least of degree 1

Returns
  CPL_ERROR_NONE or the relevant _cpl_error_code_ on error

Note
  The model is passed as a void pointer so the function can be used with cpl_wlcalib_find_best_1d().

See also
  cpl_wlcalib_find_best_1d()

The fill a vector with a spectrum, one must first initialize the parameters of the model (error checks omitted for brevity):

cpl_vector * spectrum = cpl_vector_new(nresolution);
cpl_wlcalib_slitmodel * model = cpl_wlcalib_slitmodel_new();
cpl_bivector * lines = my_load_lines_catalog(filename);
cpl_polynomial * dispersion = my_1d_dispersion();
cpl_wlcalib_slitmodel_set_wslit(model, 3.0);
cpl_wlcalib_slitmodel_set_wfwhm(model, 4.0);
cpl_wlcalib_slitmodel_set_threshold(model, 5.0);
cpl_wlcalib_slitmodel_set_catalog(model, lines);
cpl_vector_new
cpl_vector * cpl_vector_new(cpl_size n)
Create a new cpl_vector.
Definition cpl_vector.c:137
cpl_wlcalib_slitmodel_set_wfwhm
cpl_error_code cpl_wlcalib_slitmodel_set_wfwhm(cpl_wlcalib_slitmodel *self, double value)
Set the FWHM of the transfer function to be used by the spectrum filler.
Definition cpl_wlcalib.c:293
cpl_wlcalib_slitmodel_new
cpl_wlcalib_slitmodel * cpl_wlcalib_slitmodel_new(void)
Create a new line model to be initialized.
Definition cpl_wlcalib.c:147
cpl_wlcalib_slitmodel_set_wslit
cpl_error_code cpl_wlcalib_slitmodel_set_wslit(cpl_wlcalib_slitmodel *self, double value)
Set the slit width to be used by the spectrum filler.
Definition cpl_wlcalib.c:268
cpl_wlcalib_slitmodel_set_catalog
cpl_error_code cpl_wlcalib_slitmodel_set_catalog(cpl_wlcalib_slitmodel *self, cpl_bivector *catalog)
Set the catalog of lines to be used by the spectrum filler.
Definition cpl_wlcalib.c:352
cpl_wlcalib_slitmodel_set_threshold
cpl_error_code cpl_wlcalib_slitmodel_set_threshold(cpl_wlcalib_slitmodel *self, double value)
The (positive) threshold for truncating the transfer function.
Definition cpl_wlcalib.c:326

With that the spectrum can be filled:

cpl_wlcalib_fill_line_spectrum(spectrum, model, dispersion);
cpl_wlcalib_fill_line_spectrum
cpl_error_code cpl_wlcalib_fill_line_spectrum(cpl_vector *self, void *model, const cpl_polynomial *disp)
Generate a 1D spectrum from a model and a dispersion relation.
Definition cpl_wlcalib.c:619

Clean-up when no more spectra are needed (lines are deleted with the model):

cpl_wlcalib_slitmodel_delete(model);
cpl_polynomial_delete(dispersion);
cpl_vector_delete(spectrum);
cpl_polynomial_delete
void cpl_polynomial_delete(cpl_polynomial *self)
Delete a cpl_polynomial.
Definition cpl_polynomial.c:550
cpl_vector_delete
void cpl_vector_delete(cpl_vector *v)
Delete a cpl_vector.
Definition cpl_vector.c:240
cpl_wlcalib_slitmodel_delete
void cpl_wlcalib_slitmodel_delete(cpl_wlcalib_slitmodel *self)
Free memory associated with a cpl_wlcalib_slitmodel object.
Definition cpl_wlcalib.c:165

Each line profile is given by the convolution of the Dirac delta function with a Gaussian with and a top-hat with the slit width as width. This continuous line profile is then integrated over each pixel, wherever the intensity is above the threshold set by the given model. For a given line the value on a given pixel requires the evaluation of two calls to erf().

Possible _cpl_error_code_ set by this function:

- CPL_ERROR_NULL_INPUT if an input pointer is NULL
- CPL_ERROR_INVALID_TYPE If the input polynomial is not 1D
- CPL_ERROR_ILLEGAL_INPUT If the input polynomial is non-increasing over the given input (pixel) range, or if a model parameter is non-physical (e.g. non-positive slit width).
- CPL_ERROR_DATA_NOT_FOUND If no catalog lines are available in the range of the dispersion relation
- CPL_ERROR_INCOMPATIBLE_INPUT If the wavelengths of two catalog lines are found to be in non-increasing order.

References cpl_ensure_code, CPL_ERROR_NONE, and CPL_ERROR_NULL_INPUT.

## cpl_wlcalib_fill_line_spectrum_fast()

cpl_error_code cpl_wlcalib_fill_line_spectrum_fast | ( | cpl_vector * | self,
|  | void * | model,
|  | const cpl_polynomial * | disp )

Generate a 1D spectrum from a model and a dispersion relation.

Parameters

  self | Vector to fill with spectrum
  model | Pointer to cpl_wlcalib_slitmodel object
  disp | 1D-Dispersion relation, at least of degree 1

Returns
  CPL_ERROR_NONE or the relevant _cpl_error_code_ on error

Note
  The generated spectrum will use an approximate line profile for speed

See also
  cpl_wlcalib_fill_line_spectrum()

The approximation preserves the position of the maximum, the symmetry and the flux of the line profile.

The use of a given line in a spectrum requires the evaluation of four calls to erf().

The fast spectrum generation can be useful when the model spectrum includes many catalog lines.

References cpl_ensure_code, CPL_ERROR_NONE, and CPL_ERROR_NULL_INPUT.

## cpl_wlcalib_fill_logline_spectrum()

cpl_error_code cpl_wlcalib_fill_logline_spectrum | ( | cpl_vector * | self,
|  | void * | model,
|  | const cpl_polynomial * | disp )

Generate a 1D spectrum from a model and a dispersion relation.

Parameters

  self | Vector to fill with spectrum
  model | Pointer to cpl_wlcalib_slitmodel object
  disp | 1D-Dispersion relation, at least of degree 1

Returns
  CPL_ERROR_NONE or the relevant _cpl_error_code_ on error

Note
  The spectrum is generated from 1 + the logarithm of the line intensities

See also
  cpl_wlcalib_fill_line_spectrum()

References cpl_ensure_code, CPL_ERROR_NONE, and CPL_ERROR_NULL_INPUT.

## cpl_wlcalib_fill_logline_spectrum_fast()

cpl_error_code cpl_wlcalib_fill_logline_spectrum_fast | ( | cpl_vector * | self,
|  | void * | model,
|  | const cpl_polynomial * | disp )

Generate a 1D spectrum from a model and a dispersion relation.

Parameters

  self | Vector to fill with spectrum
  model | Pointer to cpl_wlcalib_slitmodel object
  disp | 1D-Dispersion relation, at least of degree 1

Returns
  CPL_ERROR_NONE or the relevant _cpl_error_code_ on error

Note
  The spectrum is generated from 1 + the logarithm of the line intensities and an approximate line profile for speed

See also
  cpl_wlcalib_fill_line_spectrum_fast()

References cpl_ensure_code, CPL_ERROR_NONE, and CPL_ERROR_NULL_INPUT.

## cpl_wlcalib_find_best_1d()

cpl_error_code cpl_wlcalib_find_best_1d | ( | cpl_polynomial * | self,
|  | const cpl_polynomial * | guess,
|  | const cpl_vector * | spectrum,
|  | void * | model,
|  | cpl_error_code(* | filler )(cpl_vector *, void *, const cpl_polynomial *),
|  | const cpl_vector * | wl_search,
|  | cpl_size | nsamples,
|  | cpl_size | hsize,
|  | double * | xcmax,
|  | cpl_vector * | xcorrs )

Find the best 1D dispersion polynomial in a given search space.

Parameters

  self | Pre-created 1D-polynomial for the result
  guess | 1D-polynomial with the guess, may equal self
  spectrum | The vector with the observed 1D-spectrum
  model | The spectrum model
  filler | The function used to make the spectrum
  wl_search | Search range around the anchor points, same unit as guess
  nsamples | Number of samples around the anchor points
  hsize | Maximum (pixel) displacement of the polynomial guess
  xcmax | On success, the maximum cross-correlation
  xcorrs | The vector to fill with the correlation values or NULL

Returns
  CPL_ERROR_NONE or the relevant _cpl_error_code_ on error

See also
  cpl_wlcalib_fill_line_spectrum() for the model and filler.

Find the polynomial that maximizes the cross-correlation between an observed 1D-spectrum and a model spectrum based on the polynomial dispersion relation.

Each element in the vector of wavelength search ranges is in the same unit as the corresponding Y-value of the dispersion relation. Each value in the vector is the width of a search window centered on the corresponding value in the guess polynomial. The length D of the search vector thus determines the dimensionality of the search space for the dispersion polynomial. If for example the search vector consists of three elements, then the three lowest order coefficients of the dispersion relation may be modified by the search.

For each candidate polynomial P(x), the polynomial P(x+u), -hsize <= u <= hsize is also evaluated. The half-size hsize may be zero. When it is non-zero, an additional 2 * hsize cross-correlations are performed for each candidate polynomial, one for each possible shift. The maximizing polynomial among those shifted polynomials is kept. A well-chosen half-size can allow for the use of fewer number of samples around the anchor points, leading to a reduction of polynomials to be evaluated.

The complexity in terms of model spectra creation is O(N^D) and in terms of cross-correlations O(hsize * N^D), where N is nsamples and D is the length of wl_search.

xcorrs must be NULL or have a size of (at least) N^D*(1 + 2 * hsize).

Possible _cpl_error_code_ set by this function:

- CPL_ERROR_NULL_INPUT if an input pointer is NULL
- CPL_ERROR_INVALID_TYPE If an input polynomial is not 1D
- CPL_ERROR_ILLEGAL_INPUT If nfree is less than 2, or nsamples is less than 1, hsize negative or if wl_search contains a zero search bound, or if xcorrs is non-NULL and too short.
- CPL_ERROR_DATA_NOT_FOUND If no model spectra can be created using the supplied model and filler

References cpl_ensure_code, CPL_ERROR_DATA_NOT_FOUND, CPL_ERROR_ILLEGAL_INPUT, CPL_ERROR_INVALID_TYPE, CPL_ERROR_NONE, CPL_ERROR_NULL_INPUT, cpl_errorstate_dump(), cpl_errorstate_dump_one_debug(), cpl_errorstate_get(), cpl_errorstate_is_equal(), cpl_errorstate_set(), cpl_polynomial_copy(), cpl_polynomial_delete(), cpl_polynomial_eval_1d(), cpl_polynomial_get_degree(), cpl_polynomial_get_dimension(), cpl_polynomial_shift_1d(), cpl_vector_delete(), cpl_vector_fill(), cpl_vector_get(), cpl_vector_get_data(), cpl_vector_get_data_const(), cpl_vector_get_size(), cpl_vector_new(), cpl_vector_set(), cpl_vector_unwrap(), and cpl_vector_wrap().

## cpl_wlcalib_slitmodel_delete()

void cpl_wlcalib_slitmodel_delete | ( | cpl_wlcalib_slitmodel * | self | ) |

Free memory associated with a cpl_wlcalib_slitmodel object.

Parameters

  self | The cpl_wlcalib_slitmodel object or NULL

Returns
  Nothing

See also
  cpl_wlcalib_slitmodel_new()

Note
  If self is `NULL` nothing is done and no error is set.

References cpl_bivector_delete(), cpl_free(), and cpl_vector_delete().

## cpl_wlcalib_slitmodel_new()

cpl_wlcalib_slitmodel * cpl_wlcalib_slitmodel_new | ( | void |  | ) |

Create a new line model to be initialized.

Returns
  1 newly allocated cpl_wlcalib_slitmodel

Note
  All elements are initialized to either zero or NULL.

See also
  cpl_wlcalib_slitmodel_delete() for object deallocation.

The model comprises these elements: Slit Width FWHM of transfer function Truncation threshold of the transfer function Catalog of lines (typically arc or sky)

The units of the X-values of the lines is a length, it is assumed to be the same as that of the Y-values of the dispersion relation (e.g. meter), the units of slit width and the FWHM are assumed to be the same as the X-values of the dispersion relation (e.g. pixel), while the units of the produced spectrum will be that of the Y-values of the lines.

References cpl_calloc().

## cpl_wlcalib_slitmodel_set_catalog()

cpl_error_code cpl_wlcalib_slitmodel_set_catalog | ( | cpl_wlcalib_slitmodel * | self,
|  | cpl_bivector * | catalog )

Set the catalog of lines to be used by the spectrum filler.

Parameters

  self | The cpl_wlcalib_slitmodel object
  catalog | The catalog of lines (e.g. arc lines)

Returns
  CPL_ERROR_NONE or the relevant _cpl_error_code_ on error

See also
  cpl_wlcalib_slitmodel_new()

Note
  The values in the X-vector must be increasing. Any previously set catalog is deallocated

Possible _cpl_error_code_ set in this function:

- CPL_ERROR_NULL_INPUT if an input pointer is NULL

References cpl_bivector_delete(), cpl_ensure_code, CPL_ERROR_NONE, and CPL_ERROR_NULL_INPUT.

## cpl_wlcalib_slitmodel_set_threshold()

cpl_error_code cpl_wlcalib_slitmodel_set_threshold | ( | cpl_wlcalib_slitmodel * | self,
|  | double | value )

The (positive) threshold for truncating the transfer function.

Parameters

  self | The cpl_wlcalib_slitmodel object
  value | The (non-negative) truncation threshold, 5 is a good value.

Returns
  CPL_ERROR_NONE or the relevant _cpl_error_code_ on error

See also
  cpl_wlcalib_slitmodel_new()

Note
  The threshold should be high enough to ensure a good line profile, but not too high to make the spectrum generation too costly.

The line profile is truncated at this distance [pixel] from its maximum: where is the slit width and where is the Full Width at Half Maximum (FWHM) of the transfer function and is the user supplied value.

Possible _cpl_error_code_ set in this function:

- CPL_ERROR_NULL_INPUT if an input pointer is NULL
- CPL_ERROR_ILLEGAL_INPUT the value is negative

References cpl_ensure_code, CPL_ERROR_ILLEGAL_INPUT, CPL_ERROR_NONE, and CPL_ERROR_NULL_INPUT.

## cpl_wlcalib_slitmodel_set_wfwhm()

cpl_error_code cpl_wlcalib_slitmodel_set_wfwhm | ( | cpl_wlcalib_slitmodel * | self,
|  | double | value )

Set the FWHM of the transfer function to be used by the spectrum filler.

Parameters

  self | The cpl_wlcalib_slitmodel object
  value | The (positive) FWHM

Returns
  CPL_ERROR_NONE or the relevant _cpl_error_code_ on error

See also
  cpl_wlcalib_slitmodel_new()

Possible _cpl_error_code_ set in this function:

- CPL_ERROR_NULL_INPUT if an input pointer is NULL
- CPL_ERROR_ILLEGAL_INPUT the value is non-positive

References cpl_ensure_code, CPL_ERROR_ILLEGAL_INPUT, CPL_ERROR_NONE, and CPL_ERROR_NULL_INPUT.

## cpl_wlcalib_slitmodel_set_wslit()

cpl_error_code cpl_wlcalib_slitmodel_set_wslit | ( | cpl_wlcalib_slitmodel * | self,
|  | double | value )

Set the slit width to be used by the spectrum filler.

Parameters

  self | The cpl_wlcalib_slitmodel object
  value | The (positive) width of the slit

Returns
  CPL_ERROR_NONE or the relevant _cpl_error_code_ on error

See also
  cpl_wlcalib_slitmodel_new()

Possible _cpl_error_code_ set in this function:

- CPL_ERROR_NULL_INPUT if an input pointer is NULL
- CPL_ERROR_ILLEGAL_INPUT the value is non-positive

References cpl_ensure_code, CPL_ERROR_ILLEGAL_INPUT, CPL_ERROR_NONE, and CPL_ERROR_NULL_INPUT.