General Utility Functions

Macros
#define	EOP_LINE_SIZE   188

Functions
const char *	hdrl_get_license (void)
	Get the pipeline copyright and license.
cpl_table *	hdrl_eop_data_totable (const char *eop_data, cpl_size data_length)
	Export a raw string buffer containing EOP data to a CPL table.
hdrl_parameter *	hdrl_rect_region_parameter_create (cpl_size llx, cpl_size lly, cpl_size urx, cpl_size ury)
	Creates Rect Region Parameters object.
cpl_error_code	hdrl_rect_region_parameter_update (hdrl_parameter *rect_region, cpl_size llx, cpl_size lly, cpl_size urx, cpl_size ury)
	Update Rect Region Parameters object.
cpl_boolean	hdrl_rect_region_parameter_check (const hdrl_parameter *self)
	Check that the parameter is hdrl_rect_region parameter.
cpl_size	hdrl_rect_region_get_llx (const hdrl_parameter *p)
	get lower left x coordinate of rectangual region
cpl_size	hdrl_rect_region_get_lly (const hdrl_parameter *p)
	get lower left y coordinate of rectangual region
cpl_size	hdrl_rect_region_get_urx (const hdrl_parameter *p)
	get upper right x coordinate of rectangular region
cpl_size	hdrl_rect_region_get_ury (const hdrl_parameter *p)
	get upper right y coordinate of rectangual region
cpl_error_code	hdrl_rect_region_parameter_verify (const hdrl_parameter *param, const cpl_size max_x, const cpl_size max_y)
	Verify basic correctness of the parameters.
cpl_parameterlist *	hdrl_rect_region_parameter_create_parlist (const char *base_context, const char *prefix, const char *name_prefix, const hdrl_parameter *defaults)
	Create parameter list for hdrl_rect_region.
hdrl_parameter *	hdrl_rect_region_parameter_parse_parlist (const cpl_parameterlist *parlist, const char *base_context, const char *name_prefix)
	parse parameterlist for rectangle parameters
cpl_error_code	hdrl_rect_region_fix_negatives (hdrl_parameter *rect_region, const cpl_size nx, const cpl_size ny)
	wrap negative or zero coordinates around full image size
cpl_boolean	hdrl_is_strictly_monotonic_increasing (const double *x, cpl_size l)
	returns CPL_TRUE if x is strictly monotonic increasing
void	hdrl_sort_on_x (double *x, double *y1, double *y2, const cpl_size sample_len, const cpl_boolean sort_decreasing)
	sort in increasing or decreasing order x. Keep aligned with y1 and y2.
char *	hdrl_join_string (const char *sep_, int n,...)
	join strings together
hdrl_value	hdrl_utils_airmass (hdrl_value aRA, hdrl_value aDEC, hdrl_value aLST, hdrl_value aExptime, hdrl_value aLatitude, hdrl_airmass_approx type)
	Compute the effective airmass of an observation. Takes in count the error propagation if you enter the relative error of the input parameters in a hdrl_value structure {data,error}.

Detailed Description

This module contain various utilities functions that might be used in several of the HDRL modules.

Macro Definition Documentation

EOP_LINE_SIZE

#define EOP_LINE_SIZE   188

Function Documentation

hdrl_eop_data_totable()

cpl_table * hdrl_eop_data_totable	(	const char *	eop_data,
		cpl_size	data_length
	)

Export a raw string buffer containing EOP data to a CPL table.

Parameters

eop_data	The string buffer with the data
data_length	The total size of the data buffer

Returns

A string buffer with the full contents of the data

This function convert the ascii file retrieve from the internet and convert it to a CPL table.

Possible cpl-error-code set in this function:

• CPL_ERROR_NULL_INPUT if eop_data is NULL
• CPL_ERROR_NULL_INPUT if data_length doesn't correspond with the expected EOP records length

hdrl_get_license()

const char * hdrl_get_license

(

void

)

Get the pipeline copyright and license.

Returns

The copyright and license string

The function returns a pointer to the statically allocated license string. This string should not be modified using the returned pointer.

hdrl_is_strictly_monotonic_increasing()

cpl_boolean hdrl_is_strictly_monotonic_increasing	(	const double *	x,
		cpl_size	l
	)

returns CPL_TRUE if x is strictly monotonic increasing

Parameters

x	array to check for being strictly monotonic increasing
l	length of the array

Returns

CPL_TRUE if x is strictly monotonic increasing, CPL_FALSE otherwise

hdrl_join_string()

char * hdrl_join_string	(	const char *	sep_,
		int	n,
			...
	)

join strings together

Parameters

sep_	separator to place between strings, NULL equals empty string
n	number of strings to join

The input strings may be empty or NULL in which case it skips the entry adding no extra separator.

Returns

joined string, must be deallocated by user with cpl_free

hdrl_rect_region_fix_negatives()

cpl_error_code hdrl_rect_region_fix_negatives	(	hdrl_parameter *	rect_region,
		const cpl_size	nx,
		const cpl_size	ny
	)

wrap negative or zero coordinates around full image size

Parameters

rect_region	rect region to wrap
nx	image size in x, nx is added to entries < 1
ny	image size in y, ny is added to entries < 1

Returns

cpl_error_code

allows reverse indexing: 0 would be nx, -2 would be nx - 2 etc Wrapping is based in FITS convention: 1 first pixel, nx last pixel inclusive

hdrl_rect_region_get_llx()

cpl_size hdrl_rect_region_get_llx

(

const hdrl_parameter *

p

)

get lower left x coordinate of rectangual region

hdrl_rect_region_get_lly()

cpl_size hdrl_rect_region_get_lly

(

const hdrl_parameter *

p

)

get lower left y coordinate of rectangual region

hdrl_rect_region_get_urx()

cpl_size hdrl_rect_region_get_urx

(

const hdrl_parameter *

p

)

get upper right x coordinate of rectangular region

hdrl_rect_region_get_ury()

cpl_size hdrl_rect_region_get_ury

(

const hdrl_parameter *

p

)

get upper right y coordinate of rectangual region

hdrl_rect_region_parameter_check()

cpl_boolean hdrl_rect_region_parameter_check

(

const hdrl_parameter *

self

)

Check that the parameter is hdrl_rect_region parameter.

Returns

the parameter to check

hdrl_rect_region_parameter_create()

hdrl_parameter * hdrl_rect_region_parameter_create	(	cpl_size	llx,
		cpl_size	lly,
		cpl_size	urx,
		cpl_size	ury
	)

Creates Rect Region Parameters object.

Parameters

llx
lly
urx
ury

Returns

the Rect Region parameters

hdrl_rect_region_parameter_create_parlist()

cpl_parameterlist * hdrl_rect_region_parameter_create_parlist	(	const char *	base_context,
		const char *	prefix,
		const char *	name_prefix,
		const hdrl_parameter *	defaults
	)

Create parameter list for hdrl_rect_region.

Parameters

base_context	base context of parameter (e.g. recipe name)
prefix	prefix of parameter, may be empty string
name_prefix	prefix for the parameter names, may be empty string
defaults	default parameters values

Returns

cpl_parameterlist Creates a parameterlist containing base_context.prefix.name-prefixllx base_context.prefix.name-prefixlly base_context.prefix.name-prefixurx base_context.prefix.name-prefixury The CLI aliases omit the base_context.

hdrl_rect_region_parameter_parse_parlist()

hdrl_parameter * hdrl_rect_region_parameter_parse_parlist	(	const cpl_parameterlist *	parlist,
		const char *	base_context,
		const char *	name_prefix
	)

parse parameterlist for rectangle parameters

Parameters

parlist	parameter list to parse
base_context	prefix of parameter
name_prefix	prefix of parameter name, may be empty string

See also

hdrl_rect_get_parlist()

Returns

A newly allocated hdrl_rect_region parameter or NULL in error case

The returned object must be deallocated with hdrl_parameter_delete() parameterlist should have been created with hdrl_rect_get_parlist or have the same name hierachy

hdrl_rect_region_parameter_update()

cpl_error_code hdrl_rect_region_parameter_update	(	hdrl_parameter *	rect_region,
		cpl_size	llx,
		cpl_size	lly,
		cpl_size	urx,
		cpl_size	ury
	)

Update Rect Region Parameters object.

Parameters

rect_region	The region to update
llx
lly
urx
ury

Returns

the error code in case of error or CPL_ERROR_NONE

hdrl_rect_region_parameter_verify()

cpl_error_code hdrl_rect_region_parameter_verify	(	const hdrl_parameter *	param,
		const cpl_size	max_x,
		const cpl_size	max_y
	)

Verify basic correctness of the parameters.

Parameters

param	rect region parameters
max_x	max value for upper x bound, set to < 0 to skip check
max_y	max value for upper y bound, set to < 0 to skip check

Returns

CPL_ERROR_NONE if everything is ok, an error code otherwise

hdrl_sort_on_x()

void hdrl_sort_on_x	(	double *	x,
		double *	y1,
		double *	y2,
		const cpl_size	sample_len,
		const cpl_boolean	sort_decreasing
	)

sort in increasing or decreasing order x. Keep aligned with y1 and y2.

Parameters

x	x array
y1	y1 array
y2	y2 array
sample_len	length of the arrays
sort_decreasing	if CPL_TRUE sort as decreasing, otherwise increasing

hdrl_utils_airmass()

hdrl_value hdrl_utils_airmass	(	hdrl_value	aRA,
		hdrl_value	aDEC,
		hdrl_value	aLST,
		hdrl_value	aExptime,
		hdrl_value	aLatitude,
		hdrl_airmass_approx	type
	)

Compute the effective airmass of an observation. Takes in count the error propagation if you enter the relative error of the input parameters in a hdrl_value structure {data,error}.

The function calculates the average airmass for the line of sight given by the right ascension (ra) and the declination (dec). The latitude (geolat) in degrees of the observatory site and the local siderial time (lst) at observation start has to be given, as well as the duration of the observation, i.e. the exposure time (exptime). If the exposure time is zero then only one value of airmass is computed, instead of weighting beginning, middle, and end of exposure according to Stetson (Stetson P., 1987, PASP 99, 191).

Parameters

aRA	right ascension in degrees
aDEC	declination in degrees
aLST	local sideral time (s.) elapsed since siderial midnight
aExptime	integration time in seconds
aLatitude	latitude of the observatory site in degrees
type	kind of approximation (see hdrl_airmass_approx enumtype)

Returns

The computed average airmass or {-1,0.} on error.

Note

This function can be calcule different kinds of approximation specified in the hdrl_airmass_approx enum type, explain as follow. 1) The formula given by Hardie (Hardie 1962, In: "Astronomical Techniques", ed. Hiltner, p. 184) to compute the airmass as a function of zenith distance. 2) The formula of Young and Irvine (Young A. T., Irvine W. M., 1967, Astron. J. 72, 945). The range of trustworthy airmass outputs is only between 1 and 4. 3) The formula of Young (Young A. T., 1994 ApOpt, 33, 1108).

You can to find in Interpolative formulas an interesting collection of approximations.