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);

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);

Each line profile is given by the convolution of the Dirac delta function with a Gaussian with $\sigma = w_{FWHM}/(2\sqrt(2\log(2))),$ 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()(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.

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: $x_{max} = w/2 + k * \sigma,$ where is the slit width and $\sigma = w_{FWHM}/(2\sqrt(2\log(2))),$ where $w_{FWHM}$ is the Full Width at Half Maximum (FWHM) of the transfer function and is the user supplied value.