Common Pipeline Library Reference Manual
7.0b1
|
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. More... | |
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. More... | |
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. More... | |
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. More... | |
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. More... | |
void | cpl_wlcalib_slitmodel_delete (cpl_wlcalib_slitmodel *self) |
Free memory associated with a cpl_wlcalib_slitmodel object. More... | |
cpl_wlcalib_slitmodel * | cpl_wlcalib_slitmodel_new (void) |
Create a new line model to be initialized. More... | |
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. More... | |
cpl_error_code | cpl_wlcalib_slitmodel_set_threshold (cpl_wlcalib_slitmodel *self, double value) |
The (positive) threshold for truncating the transfer function. More... | |
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. More... | |
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. More... | |
This module contains functions to perform 1D-wavelength calibration, typically of long-slit spectroscopy data.
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.
self | Vector to fill with spectrum |
model | Pointer to cpl_wlcalib_slitmodel object |
disp | 1D-Dispersion relation, at least of degree 1 |
The fill a vector with a spectrum, one must first initialize the parameters of the model (error checks omitted for brevity):
With that the spectrum can be filled:
Clean-up when no more spectra are needed (lines are deleted with the model):
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:
References cpl_ensure_code, CPL_ERROR_NONE, and CPL_ERROR_NULL_INPUT.
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.
self | Vector to fill with spectrum |
model | Pointer to cpl_wlcalib_slitmodel object |
disp | 1D-Dispersion relation, at least of degree 1 |
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_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.
self | Vector to fill with spectrum |
model | Pointer to cpl_wlcalib_slitmodel object |
disp | 1D-Dispersion relation, at least of degree 1 |
References cpl_ensure_code, CPL_ERROR_NONE, and CPL_ERROR_NULL_INPUT.
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.
self | Vector to fill with spectrum |
model | Pointer to cpl_wlcalib_slitmodel object |
disp | 1D-Dispersion relation, at least of degree 1 |
References cpl_ensure_code, CPL_ERROR_NONE, and CPL_ERROR_NULL_INPUT.
cpl_error_code cpl_wlcalib_find_best_1d | ( | cpl_polynomial * | self, |
const cpl_polynomial * | guess, | ||
const cpl_vector * | spectrum, | ||
void * | model, | ||
cpl_error_code(*)(cpl_vector *, void *, const cpl_polynomial *) | filler, | ||
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.
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 |
Find the polynomial that maximizes the cross-correlation between an observed 1D-spectrum and a model spectrum based on the polynomial dispersion relation.
The wavelength search range is in the same units as the Y-values of the dispersion relation.
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_error.
xcorrs must be NULL or have a size of (at least) N^D*(1 + 2 * hsize).
Possible _cpl_error_code_ set by this function:
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_new(), 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().
void cpl_wlcalib_slitmodel_delete | ( | cpl_wlcalib_slitmodel * | self | ) |
Free memory associated with a cpl_wlcalib_slitmodel object.
self | The cpl_wlcalib_slitmodel object or NULL |
NULL
nothing is done and no error is set. References cpl_bivector_delete(), cpl_free(), and cpl_vector_delete().
cpl_wlcalib_slitmodel* cpl_wlcalib_slitmodel_new | ( | void | ) |
Create a new line model to be initialized.
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_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.
self | The cpl_wlcalib_slitmodel object |
catalog | The catalog of lines (e.g. arc lines) |
Possible _cpl_error_code_ set in this function:
References cpl_bivector_delete(), cpl_ensure_code, CPL_ERROR_NONE, and CPL_ERROR_NULL_INPUT.
cpl_error_code cpl_wlcalib_slitmodel_set_threshold | ( | cpl_wlcalib_slitmodel * | self, |
double | value | ||
) |
The (positive) threshold for truncating the transfer function.
self | The cpl_wlcalib_slitmodel object |
value | The (non-negative) truncation threshold, 5 is a good value. |
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:
References cpl_ensure_code, CPL_ERROR_ILLEGAL_INPUT, CPL_ERROR_NONE, and CPL_ERROR_NULL_INPUT.
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.
self | The cpl_wlcalib_slitmodel object |
value | The (positive) FWHM |
Possible _cpl_error_code_ set in this function:
References cpl_ensure_code, CPL_ERROR_ILLEGAL_INPUT, CPL_ERROR_NONE, and CPL_ERROR_NULL_INPUT.
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.
self | The cpl_wlcalib_slitmodel object |
value | The (positive) width of the slit |
Possible _cpl_error_code_ set in this function:
References cpl_ensure_code, CPL_ERROR_ILLEGAL_INPUT, CPL_ERROR_NONE, and CPL_ERROR_NULL_INPUT.