Functions
cpl_error_code	eris_ifu_combine_jittered_images (cpl_image imagesData, cpl_image imagesError, int nx_out, int ny_out, cpl_image mergedImageData, cpl_image mergedImageError, cpl_image *mergedImageDIT, int n_cubes, const float offsetx, const float offsety, const double exptimes, const double kappa, const char *compute_mode, const int pclip)
	Combine jittered images into a merged image with optional kappa-sigma clipping.

cpl_error_code	eris_ifu_combine_divide_DIT (cpl_imagelist *cubesData, const int n_cubes, const double exptimes)
	Divide each cube in a list by its exposure time.

cpl_error_code	eris_ifu_combine_auto_size_cube (const float offsetx, const float offsety, const int nframes, float ref_offx, float ref_offy, int size_x, int size_y)
	Computes size of coadded cube.

cpl_error_code	eris_ifu_combine_build_mask (cpl_imagelist *cubesDataShifted, cpl_image mergedImgDIT, const int n_cubes, const int llx, const int lly, const double *exptimes)
	Build the mask data image.

cpl_error_code	eris_ifu_combine_build_mask_cube (cpl_image imagesDataShifted, cpl_image mergedImgDIT, const int llx, const int lly, const double *exptimes, int n_cubes, cpl_size nx_out, cpl_size ny_out)
	Build the mask data cube.

cpl_error_code	eris_ifu_combine_coadd_ks_clip (const int n_frames, const double kappa, int llx, int lly, const double exptimes, cpl_image imgMergedCubeData, cpl_image imgMergedCubeError, cpl_image mergedImgDIT, cpl_image imagesDataShifted, cpl_image imagesErrorShifted, const char *compute_mode, const int pclip, const int nx_out, const int ny_out)
	Coadd images with kappa-sigma clipping.

cpl_error_code	eris_ifu_combine_coadd_ks_clip_internal (cpl_image *imagesDataShifted, const int n_frames, const int n_contributions, const int x, const int y, int llx, int lly, const double kappa, cpl_vector msk, const char compute_mode, const int pclip)
	Internal routine for kappa-sigma clipping at a single pixel.

cpl_error_code	eris_ifu_combine_coadd (const int n_cubes, cpl_image imgMergedCubeData, cpl_image imgMergedCubeError, cpl_image mergedImgDIT, cpl_image imagesDataShifted, cpl_image imagesErrorShifted, const double exptimes, int llx, int lly, const char *compute_mode, const int nx_out, const int ny_out)
	Compute weighted mean or median of shifted images.

int	eris_ifu_combine_calc_contributions (cpl_image *imagesDataShifted, const int n_frames, const int llx, const int *lly, const int x, const int y)
	Calculate the number of frames contributing to a pixel.

cpl_error_code	eris_ifu_combine_subtract_background (cpl_image img, bool warn)
	Subtract spatial median from an image.

void	eris_ifu_combine_get_xy_min_max (const int nframes, const float offsetx, const float offsety, float min_offx, float max_offx, float min_offy, float max_offy)
	eris_ifu_combine_get_xy_min_max

int	eris_ifu_combine_nearest_int (const double x)
	Determine the nearest integer to a specified real value.

cpl_image *	eris_ifu_combine_shift_image (const cpl_image img_in, const double shift_x, const double shift_y, const double kernel)
	Shift an image by a given (non-integer) 2d offset.

void	eris_ifu_combine_convert_0_to_NaN_img (cpl_image *img)
	eris_ifu_combine_convert_0_to_NaN_img

double	eris_ifu_combine_calc_error (eris_ifu_vector data_vec, eris_ifu_vector err_vec, const char *compute_mode)
	Calculate error for coadded pixel.

cpl_error_code	eris_ifu_reject_nan (cpl_image *img)
	Rejects NaN values in the internal badpixelmask.

cpl_image *	eris_ifu_combine_shift_image_kmos (const cpl_image img_in, double xshift, double yshift, const char method, const enum extrapolationType extrapolation)
	Shifts each image of an image cube.

cpl_error_code	eris_ifu_combine_read_image_planes (const cpl_frameset frameset, cpl_image imagesData, cpl_image *imagesError, int z, int edge_trim, bool subtract_background)
	Read image planes from a frameset.

int	eris_ifu_combine_min_cube_size (const cpl_frameset *fs)
	eris_ifu_combine_min_cube_size

Detailed Description

This module provides functions for combining and coadding jittered IFU images and cubes, including sub-pixel shifting, kappa-sigma clipping, and weighted averaging operations.

Synopsis:: #include "eris_ifu_combine_static.h"

Function Documentation

◆ eris_ifu_combine_auto_size_cube()

cpl_error_code eris_ifu_combine_auto_size_cube	(	const float *	offsetx,
		const float *	offsety,
		const int	nframes,
		float *	ref_offx,
		float *	ref_offy,
		int *	size_x,
		int *	size_y
	)

Computes size of coadded cube.

Parameters

offsetx	Input offset list
offsety	Input offset list
nframes	Input number of values
ref_offx	Input reference offset array
ref_offy	Input reference offset array
size_x	Input/output coadded cube x size
size_y	Input/output coadded cube y size

Returns: CPL_ERROR_NONE on success, otherwise an error code

Note: This routine differs from the sinfo_auto_size_cube5 one because allows to input cubes of size different from the one of a single cube component (64).

Copied from sinfo_auto_size_cube

Definition at line 291 of file eris_ifu_combine_static.c.

References eris_ifu_combine_get_xy_min_max().

◆ eris_ifu_combine_build_mask()

cpl_error_code eris_ifu_combine_build_mask	(	cpl_imagelist **	cubesDataShifted,
		cpl_image *	mergedImgDIT,
		const int	n_cubes,
		const int *	llx,
		const int *	lly,
		const double *	exptimes
	)

Build the mask data image.

Parameters

cubesDataShifted	List of shifted image lists
mergedImgDIT	Output DIT image
n_cubes	number of cubes in the list to merge
llx	lower left edge x position of the shifted cubes.
lly	lower left edge y position of the shifted cubes.
exptimes	exposure times array giving the time in the same sequence as the cube list

Returns: CPL_ERROR_NONE on success, otherwise an error code

Build the mask data cube. The mask is 0 where no data is available, otherwise the integration time of one frame, respectively the summed integration times in the overlapping regions are inserted

This version is based on eris_build_mask_cube_thomas() which in fact does pretty the same than eris_build_mask_cube(). Just the loops are sorted differently. This function has been added by Alex Agudo (MPE) in order not to delete old (somehow) working and to create a consistent workflow for all cases (mean/median and ks-clipping/no-clipping).

Copied from sinfo_build_mask_cube

Definition at line 363 of file eris_ifu_combine_static.c.

◆ eris_ifu_combine_build_mask_cube()

cpl_error_code eris_ifu_combine_build_mask_cube	(	cpl_image **	imagesDataShifted,
		cpl_image **	mergedImgDIT,
		const int *	llx,
		const int *	lly,
		const double *	exptimes,
		int	n_cubes,
		cpl_size	nx_out,
		cpl_size	ny_out
	)

Build the mask data cube.

Parameters

imagesDataShifted	Array of shifted input images
mergedImgDIT	Output DIT image (pointer to image pointer)
llx	lower left edge x position of the shifted cubes.
lly	lower left edge y position of the shifted cubes.
exptimes	exposure times array giving the time in the same sequence as the cube list
n_cubes	number of cubes in the list to merge
nx_out	Output image x size
ny_out	Output image y size

Returns: CPL_ERROR_NONE on success, otherwise an error code

This is a variation of eris_ifu_combine_build_mask which is doing just one mask for a single slice. But just the first one. NaNs are not taken into account. Here we do hence a mask for every slice is calculated.

Definition at line 429 of file eris_ifu_combine_static.c.

References BRK_IF_NULL, CATCH, CATCH_MSGS, eris_ifu_free_image(), eris_ifu_is_nan_or_inf(), and TRY.

Referenced by eris_ifu_combine_jittered_images().

◆ eris_ifu_combine_calc_contributions()

int eris_ifu_combine_calc_contributions	(	cpl_image **	imagesDataShifted,
		const int	n_frames,
		const int *	llx,
		const int *	lly,
		const int	x,
		const int	y
	)

Calculate the number of frames contributing to a pixel.

Parameters

imagesDataShifted	Array of shifted input images
n_frames	Number of frames
llx	Array of lower left X positions
lly	Array of lower left Y positions
x	X coordinate of pixel
y	Y coordinate of pixel

Returns: Number of frames contributing valid data to the pixel

Definition at line 992 of file eris_ifu_combine_static.c.

Referenced by eris_ifu_combine_coadd_ks_clip().

◆ eris_ifu_combine_calc_error()

double eris_ifu_combine_calc_error	(	eris_ifu_vector *	data_vec,
		eris_ifu_vector *	err_vec,
		const char *	compute_mode
	)

Calculate error for coadded pixel.

Parameters

data_vec	Vector of data values
err_vec	Vector of error values
compute_mode	MEAN or MEDIAN mode

Returns: Calculated error value

Definition at line 1337 of file eris_ifu_combine_static.c.

References eris_ifu_vector_count_non_rejected(), eris_ifu_vector_get(), eris_ifu_vector_get_stdev(), eris_ifu_vector_get_stdev_median(), and eris_ifu_vector_is_rejected().

Referenced by eris_ifu_combine_coadd(), and eris_ifu_combine_coadd_ks_clip().

◆ eris_ifu_combine_coadd()

cpl_error_code eris_ifu_combine_coadd	(	const int	n_cubes,
		cpl_image **	imgMergedCubeData,
		cpl_image **	imgMergedCubeError,
		cpl_image *	mergedImgDIT,
		cpl_image **	imagesDataShifted,
		cpl_image **	imagesErrorShifted,
		const double *	exptimes,
		int *	llx,
		int *	lly,
		const char *	compute_mode,
		const int	nx_out,
		const int	ny_out
	)

Compute weighted mean or median of shifted images.

Parameters

n_cubes	Number of images to coadd
imgMergedCubeData	Output merged image data (pointer to image pointer)
imgMergedCubeError	Output merged image error (pointer to image pointer)
mergedImgDIT	Input DIT image
imagesDataShifted	Array of shifted input images
imagesErrorShifted	Array of shifted input error images
exptimes	Array of exposure times
llx	Array of lower left X positions
lly	Array of lower left Y positions
compute_mode	MEAN or MEDIAN mode
nx_out	Output image x size
ny_out	Output image y size

Returns: CPL_ERROR_NONE on success, otherwise an error code

Note: calculate a weighted average using the exposure time of the single frames of the overlapping regions of the cubes

Copied from sinfo_compute_weight_average

Definition at line 861 of file eris_ifu_combine_static.c.

References eris_ifu_combine_calc_error(), eris_ifu_free_vector(), eris_ifu_vector_delete(), eris_ifu_vector_new(), eris_ifu_vector_reject(), and eris_ifu_vector_set().

Referenced by eris_ifu_combine_jittered_images().

◆ eris_ifu_combine_coadd_ks_clip()

cpl_error_code eris_ifu_combine_coadd_ks_clip	(	const int	n_frames,
		const double	kappa,
		int *	llx,
		int *	lly,
		const double *	exptimes,
		cpl_image **	imgMergedCubeData,
		cpl_image **	imgMergedCubeError,
		cpl_image *	mergedImgDIT,
		cpl_image **	imagesDataShifted,
		cpl_image **	imagesErrorShifted,
		const char *	compute_mode,
		const int	pclip,
		const int	nx_out,
		const int	ny_out
	)

Coadd images with kappa-sigma clipping.

Parameters

n_frames	Number of frames to be coadded
kappa	Value for kappa-sigma clip rejection
llx	Array holding lower left X for each input cube
lly	Array holding lower left Y for each input cube
exptimes	Array holding exposure times for each input cube
imgMergedCubeData	Output coadded cube data (pointer to image pointer)
imgMergedCubeError	Output coadded cube errors (pointer to image pointer)
mergedImgDIT	Input coadded cube DIT contributions
imagesDataShifted	Input cubes data to be coadded
imagesErrorShifted	Input cubes error to be coadded
compute_mode	MEAN or MEDIAN, for the combined cube
pclip	Percentile clip value (0-100)
nx_out	Output image x size
ny_out	Output image y size

Returns: CPL_ERROR_NONE on success, otherwise an error code

MEAN: data_exp_sum = sum(cubesDataShifted * mergedCubeDIT) exp_sum = sum(cubesDataShifted * mergedCubeDIT) mergedCubeData = data_exp_sum / exp_sum

MEDIAN: No division by exptime! All data cubes should have the same exposure time!

Definition at line 527 of file eris_ifu_combine_static.c.

References BRK_IF_ERROR, BRK_IF_NULL, CATCH, eris_ifu_combine_calc_contributions(), eris_ifu_combine_calc_error(), eris_ifu_combine_coadd_ks_clip_internal(), eris_ifu_free_image(), eris_ifu_free_vector(), eris_ifu_vector_delete(), eris_ifu_vector_new(), eris_ifu_vector_reject(), eris_ifu_vector_set(), and TRY.

Referenced by eris_ifu_combine_jittered_images().

◆ eris_ifu_combine_coadd_ks_clip_internal()

cpl_error_code eris_ifu_combine_coadd_ks_clip_internal	(	cpl_image **	imagesDataShifted,
		const int	n_frames,
		const int	n_contributions,
		const int	x,
		const int	y,
		int *	llx,
		int *	lly,
		const double	kappa,
		cpl_vector **	msk,
		const char *	compute_mode,
		const int	pclip
	)

Internal routine for kappa-sigma clipping at a single pixel.

Parameters

imagesDataShifted	Array of shifted input images
n_frames	Number of frames
n_contributions	Number of frames contributing to this pixel
x	X coordinate of pixel to process
y	Y coordinate of pixel to process
llx	Array of lower left X positions
lly	Array of lower left Y positions
kappa	Kappa value for clipping
msk	Mask vector (input/output)
compute_mode	MEAN or MEDIAN mode
pclip	Percentile clip value

Returns: CPL_ERROR_NONE on success, otherwise an error code

Note: This is an internal routine called from eris_ifu_combine_coadd_ks_clip()

Definition at line 699 of file eris_ifu_combine_static.c.

References BRK_IF_ERROR, CATCH, eris_ifu_free_vector(), and TRY.

Referenced by eris_ifu_combine_coadd_ks_clip().

◆ eris_ifu_combine_convert_0_to_NaN_img()

void eris_ifu_combine_convert_0_to_NaN_img ( cpl_image * img )

eris_ifu_combine_convert_0_to_NaN_img

Parameters

img	Image in which all zero values are converted to NaN

Definition at line 1308 of file eris_ifu_combine_static.c.

◆ eris_ifu_combine_divide_DIT()

cpl_error_code eris_ifu_combine_divide_DIT	(	cpl_imagelist **	cubesData,
		const int	n_cubes,
		const double *	exptimes
	)

Divide each cube in a list by its exposure time.

Parameters

cubesData	List of Data cubes
n_cubes	Number of data cubes
exptimes	Vector with exposuretimes for each cube

Returns: Error code

Divides each cube by its exposure time.

Definition at line 256 of file eris_ifu_combine_static.c.

References BRK_IF_ERROR, CATCH, and TRY.

◆ eris_ifu_combine_get_xy_min_max()

void eris_ifu_combine_get_xy_min_max	(	const int	nframes,
		const float *	offsetx,
		const float *	offsety,
		float *	min_offx,
		float *	max_offx,
		float *	min_offy,
		float *	max_offy
	)

eris_ifu_combine_get_xy_min_max

Parameters

nframes	Input number of values
offsetx	Input offset list
offsety	Input offset list
min_offx	Minimum offset in offsetx
max_offx	Maximum offset in offsetx
min_offy	Minimum offset in offsety
max_offy	Maximum offset in offsety

Copied from sinfo_get_xy_min_max

Definition at line 1093 of file eris_ifu_combine_static.c.

Referenced by eris_ifu_combine_auto_size_cube().

◆ eris_ifu_combine_jittered_images()

cpl_error_code eris_ifu_combine_jittered_images	(	cpl_image **	imagesData,
		cpl_image **	imagesError,
		int	nx_out,
		int	ny_out,
		cpl_image **	mergedImageData,
		cpl_image **	mergedImageError,
		cpl_image **	mergedImageDIT,
		int	n_cubes,
		const float *	offsetx,
		const float *	offsety,
		const double *	exptimes,
		const double	kappa,
		const char *	compute_mode,
		const int	pclip
	)

Combine jittered images into a merged image with optional kappa-sigma clipping.

Parameters

imagesData	Array of input images to combine
imagesError	Array of input error images
nx_out	Output image x size
ny_out	Output image y size
mergedImageData	Output merged image data (pointer to image pointer)
mergedImageError	Output merged image error (pointer to image pointer)
mergedImageDIT	Output DIT image (pointer to image pointer)
n_cubes	Number of images in the list to merge
offsetx	Array of x pixel offsets
offsety	Array of y pixel offsets
exptimes	Exposure times array
kappa	Value for kappa-sigma clipping (use -1 to disable)
compute_mode	MEAN or MEDIAN mode for the combined image
pclip	Percentile clip to be initially applied (use -1 to disable)

Returns: CPL_ERROR_NONE on success, otherwise an error code

Merges jittered data cubes to one bigger cube by averaging the overlap regions weighted by the integration times. The x, y size of the final data cube is user given, and should be between 32 and 64 pixels, while the relative pixel-offset (sub-pixel accuracy) of the single cubes with respect to the first cube in the list is read from the SEQ CUMOFFSETX,Y fits header keyword.

Note: The function handles sub-pixel shifting using nearest-neighbor interpolation. If kappa and pclip are both >= 0, kappa-sigma clipping is performed. Otherwise, a simple weighted average is computed.

Copied from sinfo_new_combine_jittered_cubes_thomas_range()

Definition at line 83 of file eris_ifu_combine_static.c.

References BRK_IF_ERROR, BRK_IF_NULL, CATCH, CATCH_MSGS, CHECK_ERROR_STATE, eris_ifu_combine_build_mask_cube(), eris_ifu_combine_coadd(), eris_ifu_combine_coadd_ks_clip(), eris_ifu_combine_nearest_int(), eris_ifu_combine_shift_image_kmos(), eris_ifu_free_image(), and TRY.

◆ eris_ifu_combine_min_cube_size()

int eris_ifu_combine_min_cube_size ( const cpl_frameset * fs )

eris_ifu_combine_min_cube_size

Parameters

fs	Input frameset

Returns: The minimum number of planes in all cubes

It is checked as well if CRPIX3, CRVAL3 and CD3_3 are all the same. If these conditions are met, it is safe just to omit any extra planes on individual cubes at the top/far end.

Definition at line 1806 of file eris_ifu_combine_static.c.

References BRK_IF_ERROR, BRK_IF_NULL, BRK_WITH_ERROR_MSG, CATCH, CATCH_MSGS, CHECK_ERROR_STATE, eris_ifu_free_propertylist(), and TRY.

◆ eris_ifu_combine_nearest_int()

int eris_ifu_combine_nearest_int ( const double x )

Determine the nearest integer to a specified real value.

Parameters

x	Double value to convert to int

Returns: Nearest integer to specified real value

Copied from sinfo_new_nint()

Definition at line 1131 of file eris_ifu_combine_static.c.

Referenced by eris_ifu_combine_jittered_images().

◆ eris_ifu_combine_read_image_planes()

cpl_error_code eris_ifu_combine_read_image_planes	(	const cpl_frameset *	frameset,
		cpl_image **	imagesData,
		cpl_image **	imagesError,
		int	z,
		int	edge_trim,
		bool	subtract_background
	)

Read image planes from a frameset.

Parameters

frameset	Input frameset
imagesData	Output array of data images
imagesError	Output array of error images
z	Plane number to read
edge_trim	Number of edge pixels to trim (0 to disable)
subtract_background	If true, subtract spatial median from each image

Returns: CPL_ERROR_NONE on success, otherwise an error code

Definition at line 1705 of file eris_ifu_combine_static.c.

References BRK_IF_ERROR, BRK_IF_NULL, CATCH, CATCH_MSGS, CHECK_ERROR_STATE, eris_ifu_combine_subtract_background(), eris_ifu_free_image(), eris_ifu_free_mask(), eris_ifu_free_propertylist(), eris_pfits_get_naxis1(), eris_pfits_get_naxis2(), and TRY.

◆ eris_ifu_combine_shift_image()

cpl_image * eris_ifu_combine_shift_image	(	const cpl_image *	img_in,
		const double	shift_x,
		const double	shift_y,
		const double *	kernel
	)

Shift an image by a given (non-integer) 2d offset.

Parameters

img_in	Image to shift.
shift_x	Shift in x.
shift_y	Shift in y.
kernel	Interpolation kernel to use

Returns: Newly allocated image with shifted input image

See also: sinfo_generate_interpolation_kernel

Note

This function is a conversion to CPL of the ECLIPSE function shift_image() but slightly changed. If a blank (ZERO) pixel appears the blank pixel is shifted but preserved as blank. If a blank (ZERO) pixel appears within the interpolation kernel the blank pixel is set to 0.

This function shifts an image by a non-integer offset, using interpolation. You can either generate an interpolation kernel once and pass it to this function, or let it generate a default kernel. In the former case, use sinfo_generate_interpolation_kernel() to generate an appropriate kernel. In the latter case, pass NULL as last argument. A default interpolation kernel is then generated then discarded before this function returns.

The returned image is a newly allocated object, it must be deallocated using cpl_image_delete().

Definition at line 1181 of file eris_ifu_combine_static.c.

◆ eris_ifu_combine_shift_image_kmos()

cpl_image * eris_ifu_combine_shift_image_kmos	(	const cpl_image *	img_in,
		double	xshift,
		double	yshift,
		const char *	method,
		const enum extrapolationType	extrapolation
	)

Shifts each image of an image cube.

Parameters

img_in	Input image to shift
xshift	Fraction of pixel (< 1) to be shifted in x direction
yshift	Fraction of pixel (< 1) to be shifted in y direction
method	Interpolation method: either "BCS" for bicubic splines or "NN" for nearest neighbor
extrapolation	How to handle extrapolation, see description

Returns: Newly allocated shifted image, or NULL on error

was kmclipm_shift() in KMOS pipeline

This function is written as recipe as defined in the ESO Document VLT-TRE-KMO-146611-003 (KMOS Data Reduction Library Design), it will also be used in the Data Reduction Pipeline.

Extrapolation is done in following ways as requested by the "extrapolation" parameter:

NONE_NANS:
no extrapolation will be done, points outside the input images will be set to NaN
NONE_CLIPPING
no extrapolation will be done, points outside the input images will be removed, the output image will be smaller
BCS_NATURAL:
only valid for the "BCS" interpolation, which will be of type natural, i.e. at the image edge the first derivate is assumed to be zero
BCS_ESTIMATED
only valid for the "BCS" interpolation, the second derivate at the image egde will be estimated by interpolation using the last three points.

The returned imagelist has to be deallocated with cpl_imagelist_delete().

Possible cpl_error_code set in this function:

CPL_ERROR_ILLEGAL_INPUT if the input cube is NULL
CPL_ERROR_ILLEGAL_INPUT if the input cube is empty
CPL_ERROR_ILLEGAL_INPUT if either xshift or yshift is greater than 1
CPL_ERROR_ILLEGAL_INPUT if interpolation method is neither "BCS" nore "NN
CPL_ERROR_ILLEGAL_INPUT if extrapolation type is unknown

FUTURE: First an empty rectilinear cube of the required dimensions is created and then the values from the input data are interpolated, conserving the flux from the 2D frame into the 3D cube if requested.The errors are propagated into a new noise cube if the input noise map is provided.

Definition at line 1514 of file eris_ifu_combine_static.c.

References BRK_IF_ERROR, BRK_IF_NULL, BRK_WITH_ERROR_MSG, CATCH, CATCH_MSGS, eris_ifu_free_image(), eris_ifu_reject_nan(), and TRY.

Referenced by eris_ifu_combine_jittered_images().