clipm_priv_image_resample.c File Reference

#include "clipm_priv_image_resample.h"
#include "clipm_math.h"
#include "clipm_priv_checks.h"
#include "clipm_priv_math.h"
#include "clipm_priv_matrix.h"
#include "clipm_priv_image.h"
#include "clipm_compatibility_replacements.h"
#include "clipm_priv_error.h"

Macros
#define	_clipm_priv_image_interpolate_bilinear_BODY(CTYPE)
#define	_clipm_priv_TRANSFORM(dimension_index, X, Y)
#define	clipm_priv_image_resample_bilinear_BODY(TYPE, input, result)

Functions
cpl_image *	clipm_priv_image_lineartrans_bilinear (const cpl_image *input, const cpl_matrix *transform, cpl_matrix *shift, const cpl_size window_xxyy[4], int adjust_size, int use_outside_wdw, int norm_flag, int set_bpm_flag, cpl_image **contrib_map)
	Linearly transform a 2d-image using bilinear interpolation. More...
cpl_image *	clipm_priv_image_resample_bilinear (const cpl_image *input, double scale)
	Resample an image using bilinear interpolation. More...
double	clipm_priv_image_resample_undo_position (double resampled_position, double scale)
	Backtransform a position (x or y) from a resampled image to the original position before resampling (FITS convention). More...
double	clipm_priv_image_resample_position (double original_position, double scale)
	Transform a position (x or y) from an image, which is to be resampled, to the new position in the resampled image (FITS convention). More...

Macro Definition Documentation

#define _clipm_priv_image_interpolate_bilinear_BODY

(

CTYPE

)

#define _clipm_priv_TRANSFORM	(		dimension_index,
			X,
			Y
	)

Value:

(   coeff[dimension_index][0] \
        + (double)X * coeff[dimension_index][1] \
        + (double)Y * coeff[dimension_index][2])

#define clipm_priv_image_resample_bilinear_BODY	(		TYPE,
			input,
			result
	)

Function Documentation

cpl_image* clipm_priv_image_lineartrans_bilinear	(	const cpl_image *	input,
		const cpl_matrix *	transform,
		cpl_matrix *	shift,
		const cpl_size	window_xxyy[4],
		int	adjust_size,
		int	use_outside_wdw,
		int	norm_flag,
		int	set_bpm_flag,
		cpl_image **	contrib_map
	)

Linearly transform a 2d-image using bilinear interpolation.

Parameters

input	Input image
transform	2x2 transformation matrix
shift	2x1 shift matrix, will be modified if adjust_size is true (see below)
window_xxyy	Coordinate buffer of the form {xa, xb, ya, yb}, can be NULL, minimum/maximum order is irrelevant
adjust_size	Flag to allow resizing the output
use_outside_wdw	Flag to use also data outside window_xxyy (if not NULL), only used if adjust_size is true (see below)
norm_flag	Flag whether to already normalize the output image by the contribution weight, should default to 1 if contrib_map is not used, otherwise 0 if the contrib_map will be applied individually
set_bpm_flag	Flag whether to mark output pixels with a contribution of 0 as bad
contrib_map	(Optional output) image containing the weighting of each pixel during the interpolation, the range is [0...1], reflecting the influence of bad pixels or image borders

Returns

Transformed image, NULL in the case of error

Principle:

• This function performs a simple interpolation. This means, that a position in the output image is backtransformed, and the 4 surrounding pixels of this backtransformed position in the input image contribute to the interpolation.
• This implicates, that with strong downscaling, not all input pixels might contribute. Therefore it is advisable in this case, to use clipm_priv_image_resample_bilinear() for downscaling first, and then this function for other transformations. The reason why this is not compensated is, that a free transformation might imply downscaling in one dimension and upscaling in the other, what results in unclear definition of the interpolation contribution in extreme cases.
• If adjust_size is true, then
  • the output image will be adjusted in its size to contain the full transformed image (window), and
  • shift will be modified to reflect this new image content position (in this case it is not necessary to initialise shift with any value),
  • if also use_outside_wdw is true, then also input data lying outside window_xxyy are used, which limits the function of window_xxyy to specify the corners that should define the output size.
• If adjust_size is false, then
  • extreme shift can lead to blank images, and
  • use_outside_wdw is ignored.

Bad Pixel Handling:

Since bad pixels are marked with a zero weight in the optional contrib_map, the bad pixel map of the output image is really ONLY created if set_bpm_flag is true.

Note

The flux is not preserved.

Error Handling:

The following errors may occur:

• CPL_ERROR_NULL_INPUT: input, transform or shift is NULL
• CPL_ERROR_ILLEGAL_INPUT:
  • the size of transform is not 2x2
  • the size of shift is not 2x1
• CPL_ERROR_SINGULAR_MATRIX: transform is not invertible
• CPL_ERROR_INVALID_TYPE: input is not of type CPL_TYPE_INT, CPL_TYPE_FLOAT, or CPL_TYPE_DOUBLE

Todo:

• Support transforming integer into double

cpl_image* clipm_priv_image_resample_bilinear	(	const cpl_image *	input,
		double	scale
	)

Resample an image using bilinear interpolation.

Parameters

input	The input image
scale	The scaling factor

Returns

The new image, NULL in the case of error

Principle:

• An image is resampled using bilinear sampling.
• The new image will have the size s_new = floor(s_in * scale), where s represents x and y respectively.
• The following coordinate transformation is applied (in FITS coordinates): x_new = scale*(x_old - 1/2) + 1/2
  x_old = (1/ scale)*(x_new - 1/2) + 1/2,
  and likewise with y.
• The interpolation direction depends on the scale:
  • with a scale >= 1, an output position is back-transformed, and the 4 surrounding input pixels contribute to the interpolation,
  • with a scale < 1, an input position is transformed, and contributes to the 4 surrounding output pixels,
  this way, always all input pixels are used.

Bad Pixel Handling:

Bad pixels are not supported, they are ignored.

Constraints:

The input image must be either of the type CPL_TYPE_FLOAT or CPL_TYPE_DOUBLE.

Note

The flux is not preserved.

Error Handling:

The following error codes are set by this function:

• CPL_ERROR_NULL_INPUT: input is NULL
• CPL_ERROR_ILLEGAL_INPUT: scale <= 0
• CPL_ERROR_INVALID_TYPE: input is neither of type CPL_TYPE_FLOAT nor CPL_TYPE_DOUBLE

Todo:

• Implement bad pixel handling

double clipm_priv_image_resample_position	(	double	original_position,
		double	scale
	)

Transform a position (x or y) from an image, which is to be resampled, to the new position in the resampled image (FITS convention).

Parameters

original_position	The input position in the original image
scale	The scaling factor

Returns

The position after resampling

Principle:

• This function applies to the resampling method of clipm_priv_image_resample_bilinear().
• scale must be greater 0.
• The input parameters are not checked for validity.

double clipm_priv_image_resample_undo_position	(	double	resampled_position,
		double	scale
	)

Backtransform a position (x or y) from a resampled image to the original position before resampling (FITS convention).

Parameters

resampled_position	The position in the resampled image
scale	The scaling factor

Returns

The position before resampling

Principle:

• This function applies to the resampling method of clipm_priv_image_resample_bilinear().
• scale must be greater 0.
• The input parameters are not checked for validity.