High level functions for geometric transformations

Functions
cpl_image **	cpl_geom_img_offset_combine (const cpl_imagelist *self, const cpl_bivector *offs, int refine, const cpl_bivector *aperts, const cpl_vector *sigmas, cpl_size *pisigma, cpl_size s_hx, cpl_size s_hy, cpl_size m_hx, cpl_size m_hy, cpl_size min_rej, cpl_size max_rej, cpl_geom_combine union_flag)
	Images list recombination.
cpl_bivector *	cpl_geom_img_offset_fine (const cpl_imagelist *ilist, const cpl_bivector *estimates, const cpl_bivector *anchors, cpl_size s_hx, cpl_size s_hy, cpl_size m_hx, cpl_size m_hy, cpl_vector *correl)
	Get the offsets by correlating the images.
cpl_image **	cpl_geom_img_offset_saa (const cpl_imagelist *ilist, const cpl_bivector *offs, cpl_kernel kernel, cpl_size rejmin, cpl_size rejmax, cpl_geom_combine union_flag, double *ppos_x, double *ppos_y)
	Shift and add an images list to a single image.
enum	cpl_geom_combine {   CPL_GEOM_INTERSECT ,   CPL_GEOM_UNION ,   CPL_GEOM_FIRST }
	The CPL Geometry combination modes. More...

Detailed Description

This module contains functions to compute the shift-and-add operation on an image list.

Synopsis:

#include "cpl_geom_img.h"

Enumeration Type Documentation

cpl_geom_combine

enum cpl_geom_combine

The CPL Geometry combination modes.

Enumerator
CPL_GEOM_INTERSECT	Combine using the intersection of the images.
CPL_GEOM_UNION	Combine using the union of the images.
CPL_GEOM_FIRST	Combine using the first image to aggregate the other ones.

Function Documentation

cpl_geom_img_offset_combine()

cpl_image ** cpl_geom_img_offset_combine	(	const cpl_imagelist *	self,
		const cpl_bivector *	offs,
		int	refine,
		const cpl_bivector *	aperts,
		const cpl_vector *	sigmas,
		cpl_size *	pisigma,
		cpl_size	s_hx,
		cpl_size	s_hy,
		cpl_size	m_hx,
		cpl_size	m_hy,
		cpl_size	min_rej,
		cpl_size	max_rej,
		cpl_geom_combine	union_flag
	)

Images list recombination.

Parameters

self	Input imagelist
offs	List of offsets in x and y
refine	Iff non-zero, the offsets will be refined
aperts	List of correlation apertures or NULL if unknown
sigmas	Positive, decreasing sigmas to apply
pisigma	Index of the sigma that was used or undefined on error
s_hx	Search area half-width.
s_hy	Search area half-height.
m_hx	Measurement area half-width.
m_hy	Measurement area half-height.
min_rej	number of low values to reject in stacking
max_rej	number of high values to reject in stacking
union_flag	Combination mode (CPL_GEOM_UNION or CPL_GEOM_INTERSECT)

Returns

Pointer to newly allocated images array, or NULL on error.

See also

cpl_geom_img_offset_saa()

cpl_apertures_extract()

cpl_geom_img_offset_fine()

With offset refinement enabled: This function detects cross correlation points in the first image (if not provided by the user), use them to refine the provided offsets with a cross correlation method, and then apply the shift and add to recombine the images together.

The supported types are CPL_TYPE_DOUBLE, CPL_TYPE_FLOAT.

The number of provided offsets shall be equal to the number of input images. The ith offset (offs_x, offs_y) is the offset that has to be used to shift the ith image to align it on the first one.

sigmas may be NULL if offset refinement is disabled or if aperts is non-NULL.

On success the returned image array contains 2 images:

• the combined image
• the contribution map

The returned cpl_image array must be deallocated like this:

if (array != NULL) {
    cpl_image_delete(array[0]);
    cpl_image_delete(array[1]);
    cpl_free(array);
}

Possible _cpl_error_code_ set in this function:

• CPL_ERROR_NULL_INPUT if self or offs is NULL, or if sigmas is NULL with refinement enabled and aperts NULL.
• CPL_ERROR_ILLEGAL_INPUT if self is not uniform
• CPL_ERROR_INCOMPATIBLE_INPUT if self and offs have different sizes
• CPL_ERROR_DATA_NOT_FOUND if the shift and add of the images fails

References cpl_apertures_delete(), cpl_apertures_extract(), cpl_apertures_get_pos_x(), cpl_apertures_get_pos_y(), cpl_apertures_sort_by_npix(), cpl_bivector_delete(), cpl_bivector_get_size(), cpl_bivector_get_x(), cpl_bivector_get_x_data(), cpl_bivector_get_y(), cpl_bivector_get_y_data(), cpl_bivector_new(), cpl_ensure, CPL_ERROR_DATA_NOT_FOUND, CPL_ERROR_ILLEGAL_INPUT, CPL_ERROR_INCOMPATIBLE_INPUT, CPL_ERROR_NULL_INPUT, cpl_geom_img_offset_fine(), cpl_geom_img_offset_saa(), cpl_imagelist_delete(), cpl_imagelist_get_const(), cpl_imagelist_get_size(), cpl_imagelist_is_uniform(), cpl_imagelist_new(), cpl_imagelist_set(), cpl_imagelist_unset(), CPL_SIZE_FORMAT, cpl_vector_delete(), cpl_vector_get_data_const(), cpl_vector_new(), and cpl_vector_set_size().

cpl_geom_img_offset_fine()

cpl_bivector * cpl_geom_img_offset_fine	(	const cpl_imagelist *	ilist,
		const cpl_bivector *	estimates,
		const cpl_bivector *	anchors,
		cpl_size	s_hx,
		cpl_size	s_hy,
		cpl_size	m_hx,
		cpl_size	m_hy,
		cpl_vector *	correl
	)

Get the offsets by correlating the images.

Parameters

ilist	Input image list
estimates	First-guess estimation of the offsets
anchors	List of anchor points
s_hx	Half-width of search area
s_hy	Half-height of search area
m_hx	Half-width of measurement area
m_hy	Half-height of measurement area
correl	List of cross-correlation quality factors

Returns

List of offsets or NULL on error

The matching is performed using a 2d cross-correlation, using a minimal squared differences criterion. One measurement is performed per input anchor point, and the median offset is returned together with a measure of similarity for each plane.

The images in the input list must only differ from a shift. In order from the correlation to work, they must have the same level (check the average values of your input images if the correlation does not work).

The supported types are CPL_TYPE_DOUBLE and CPL_TYPE_FLOAT. The bad pixel maps are ignored by this function.

The ith offset (offsx, offsy) in the returned offsets is the one that have to be used to shift the ith image to align it on the reference image (the first one).

If not NULL, the returned cpl_bivector must be deallocated with cpl_bivector_delete().

Possible _cpl_error_code_ set in this function:

• CPL_ERROR_NULL_INPUT if (one of) the input pointer(s) is NULL
• CPL_ERROR_ILLEGAL_INPUT if ilist is not valid
• CPL_ERROR_INCOMPATIBLE_INPUT if ilist and correl have different lengths

References cpl_bivector_get_size(), cpl_bivector_get_x_data(), cpl_bivector_get_x_data_const(), cpl_bivector_get_y_data(), cpl_bivector_get_y_data_const(), cpl_bivector_new(), CPL_BORDER_FILTER, cpl_ensure, CPL_ERROR_ILLEGAL_INPUT, CPL_ERROR_INCOMPATIBLE_INPUT, CPL_ERROR_NULL_INPUT, cpl_errorstate_get(), cpl_errorstate_set(), CPL_FILTER_MEDIAN, cpl_image_delete(), cpl_image_filter_mask(), cpl_image_get_size_x(), cpl_image_get_size_y(), cpl_image_get_type(), cpl_image_new(), cpl_imagelist_get_const(), cpl_imagelist_get_size(), cpl_imagelist_is_uniform(), cpl_mask_delete(), cpl_mask_new(), cpl_mask_not(), cpl_msg_debug(), CPL_SIZE_FORMAT, cpl_vector_get_data(), and cpl_vector_get_size().

Referenced by cpl_geom_img_offset_combine().

cpl_geom_img_offset_saa()

cpl_image ** cpl_geom_img_offset_saa	(	const cpl_imagelist *	ilist,
		const cpl_bivector *	offs,
		cpl_kernel	kernel,
		cpl_size	rejmin,
		cpl_size	rejmax,
		cpl_geom_combine	union_flag,
		double *	ppos_x,
		double *	ppos_y
	)

Shift and add an images list to a single image.

Parameters

ilist	Input image list
offs	List of offsets in x and y
kernel	Interpolation kernel to use for resampling
rejmin	Number of minimum value pixels to reject in stacking
rejmax	Number of maximum value pixels to reject in stacking
union_flag	Combination mode, CPL_GEOM_UNION, CPL_GEOM_INTERSECT or CPL_GEOM_FIRST
ppos_x	If non-NULL, *ppos_x is the X-position of the first image in the combined image
ppos_y	If non-NULL, *ppos_y is the Y- position of the first image in the combined image

Returns

Pointer to newly allocated images array, or NULL on error.

The supported types are CPL_TYPE_DOUBLE, CPL_TYPE_FLOAT.

The number of provided offsets shall be equal to the number of input images. The ith offset (offs_x, offs_y) is the offset that has to be used to shift the ith image to align it on the first one.

Provide the name of the kernel you want to generate. Supported kernel types are:

• CPL_KERNEL_DEFAULT: default kernel, currently CPL_KERNEL_TANH
• CPL_KERNEL_TANH: Hyperbolic tangent
• CPL_KERNEL_SINC: Sinus cardinal
• CPL_KERNEL_SINC2: Square sinus cardinal
• CPL_KERNEL_LANCZOS: Lanczos2 kernel
• CPL_KERNEL_HAMMING: Hamming kernel
• CPL_KERNEL_HANN: Hann kernel
• CPL_KERNEL_NEAREST: Nearest neighbor kernel (1 when dist < 0.5, else 0)

If the number of input images is lower or equal to 3, the rejection parameters are ignored. If the number of input images is lower or equal to 2*(rejmin+rejmax), the rejection parameters are ignored.

On success the returned image array contains 2 images:

• the combined image
• the contribution map

Pixels with a zero in the contribution map are flagged as bad in the combined image.

If not NULL, the returned cpl_image array arr must be deallocated like:

if (arr[0] != NULL) cpl_image_delete(arr[0]);
if (arr[1] != NULL) cpl_image_delete(arr[1]);
cpl_free(arr);

If the call is successful, (*ppos_x, *ppos_y) is the pixel coordinate in the created output image-pair where the lowermost-leftmost pixel of the first input image is located. So with CPL_GEOM_FIRST this will always be (1, 1).

Possible _cpl_error_code_ set in this function:

• CPL_ERROR_NULL_INPUT if (one of) the input pointer(s) is NULL
• CPL_ERROR_ILLEGAL_INPUT if ilist is invalid or if rejmin or rejmax is negative
• CPL_ERROR_INCOMPATIBLE_INPUT if ilist and offs have different sizes
• CPL_ERROR_ILLEGAL_OUTPUT if the CPL_GEOM_INTERSECT method is used with non-overlapping images.
• CPL_ERROR_INVALID_TYPE if the passed image list type is not supported
• CPL_ERROR_UNSUPPORTED_MODE if the union_flag is not one of the supported combination modes, which are CPL_GEOM_INTERSECT, CPL_GEOM_UNION, CPL_GEOM_FIRST.

References cpl_bivector_get_size(), cpl_bivector_get_x_const(), cpl_bivector_get_y_const(), cpl_ensure, CPL_ERROR_ILLEGAL_INPUT, CPL_ERROR_ILLEGAL_OUTPUT, CPL_ERROR_INCOMPATIBLE_INPUT, CPL_ERROR_INVALID_TYPE, CPL_ERROR_NULL_INPUT, CPL_ERROR_UNSUPPORTED_MODE, CPL_GEOM_FIRST, CPL_GEOM_INTERSECT, CPL_GEOM_UNION, cpl_image_accept_all(), cpl_image_delete(), cpl_image_duplicate(), cpl_image_fill_rejected(), cpl_image_get_bpm(), cpl_image_get_bpm_const(), cpl_image_get_size_x(), cpl_image_get_size_y(), cpl_image_get_type(), cpl_image_new(), cpl_image_new_from_mask(), cpl_image_wrap_int(), cpl_imagelist_get_const(), cpl_imagelist_get_size(), cpl_imagelist_is_uniform(), cpl_imagelist_unwrap(), cpl_malloc(), cpl_mask_is_empty(), cpl_mask_not(), CPL_TYPE_DOUBLE, CPL_TYPE_FLOAT, CPL_TYPE_INT, cpl_vector_delete(), cpl_vector_duplicate(), cpl_vector_fill_kernel_profile(), cpl_vector_get_data_const(), cpl_vector_get_max(), cpl_vector_get_min(), cpl_vector_new(), and cpl_vector_sort().

Referenced by cpl_geom_img_offset_combine().