Loading...
Searching...
No Matches
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);
}
cpl_image_delete
void cpl_image_delete(cpl_image *d)
Free memory associated to an cpl_image object.
Definition cpl_image_io.c:1881
cpl_free
void cpl_free(void *memblk)
Memory block deallocation.
Definition cpl_memory.c:224

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().