Common Pipeline Library Reference: Images

link管理

链接快照平台

输入网页链接，自动生成快照
标签化管理网页链接

Detailed Description

This module provides functions to create, use, and destroy a cpl_image . A cpl_image is a 2-dimensional data structure with a pixel type (one of CPL_TYPE_INT , CPL_TYPE_FLOAT , CPL_TYPE_DOUBLE , CPL_TYPE_FLOAT_COMPLEX or CPL_TYPE_DOUBLE_COMPLEX ) and an optional bad pixel map.

The pixel indexing follows the FITS convention in the sense that the lower left pixel in a CPL image has index (1, 1). The pixel buffer is stored row-wise so for optimum performance any pixel-wise access should be done likewise.

Functionality include: FITS I/O Image arithmetic, casting, extraction, thresholding, filtering, resampling Bad pixel handling Image statistics Generation of test images Special functions, such as the image quality estimator

Synopsis:

#include "cpl_image.h"

Usage: define the following preprocessor symbols as needed, then include this file

Typedef Documentation

◆ cpl_value

The special values that can be rejected They are a bit-field and can be combined with bitwise or.

Enumerator CPL_VALUE_NAN

Not-a-Number (NaN)

CPL_VALUE_PLUSINF

Plus Infinity

CPL_VALUE_MINUSINF

Minus Infinity

CPL_VALUE_ZERO

Zero

CPL_VALUE_INF

Infinity with any sign

CPL_VALUE_NOTFINITE

NaN or infinity with any sign

Returns: CPL_ERROR_NONE or the relevant the _cpl_error_code_ on error

Set each pixel to its absolute value.

Possible _cpl_error_code_ set in this function:

CPL_ERROR_NULL_INPUT if an input pointer is NULL

References cpl_ensure_code , CPL_ERROR_INVALID_TYPE , CPL_ERROR_NONE , and CPL_ERROR_NULL_INPUT .

Referenced by cpl_image_abs_create() , cpl_image_fill_jacobian() , and cpl_image_fill_jacobian_polynomial() .

Returns: 1 newly allocated image or NULL on error

See also: cpl_image_abs

For each pixel, out = abs(in). The returned image must be deallocated using cpl_image_delete() .

References cpl_ensure , cpl_error_get_code() , cpl_image_abs() , cpl_image_delete() , and cpl_image_duplicate() .

Returns: the _cpl_error_code_ or CPL_ERROR_NONE

Possible _cpl_error_code_ set in this function:

CPL_ERROR_NULL_INPUT if an input pointer is NULL
CPL_ERROR_ACCESS_OUT_OF_RANGE if the specified position is out of the image

References cpl_ensure_code , CPL_ERROR_ACCESS_OUT_OF_RANGE , CPL_ERROR_NONE , and CPL_ERROR_NULL_INPUT .

Returns: the _cpl_error_code_ or CPL_ERROR_NONE

Possible _cpl_error_code_ set in this function:

CPL_ERROR_NULL_INPUT if an input pointer is NULL

References CPL_ERROR_NONE , cpl_image_unset_bpm() , and cpl_mask_delete() .

Referenced by cpl_detector_interpolate_rejected() , cpl_geom_img_offset_saa() , and cpl_imagelist_collapse_create() .

Returns: the _cpl_error_code_ or CPL_ERROR_NONE

The first input image is modified to contain the result of the operation.

The bad pixel map of the first image becomes the union of the bad pixel maps of the input images.

Possible _cpl_error_code_ set in this function:

CPL_ERROR_NULL_INPUT if an input pointer is NULL
CPL_ERROR_INCOMPATIBLE_INPUT if the input images have different sizes
CPL_ERROR_TYPE_MISMATCH if the second input image has complex type while the first one does not

Referenced by cpl_image_fill_test_create() , and cpl_imagelist_collapse_create() .

Returns: 1 newly allocated image or NULL on error

Creates a new image, being the result of the operation, and returns it to the caller. The returned image must be deallocated using cpl_image_delete() . The function supports images with different types among CPL_TYPE_INT, CPL_TYPE_FLOAT and CPL_TYPE_DOUBLE. The returned image type is the one of the first passed image.

The bad pixels map of the result is the union of the bad pixels maps of the input images.

Possible _cpl_error_code_ set in this function:

CPL_ERROR_NULL_INPUT if an input pointer is NULL
CPL_ERROR_INCOMPATIBLE_INPUT if the input images have different sizes
CPL_ERROR_TYPE_MISMATCH if the second input image has complex type while the first one does not

Returns: CPL_ERROR_NONE or the relevant the _cpl_error_code_ on error

Modifies the image by adding a number to each of its pixels.

The operation is always performed in double precision, with a final cast of the result to the image pixel type.

Possible _cpl_error_code_ set in this function:

CPL_ERROR_NULL_INPUT if an input pointer is NULL

References cpl_ensure_code , CPL_ERROR_INVALID_TYPE , CPL_ERROR_NONE , CPL_ERROR_NULL_INPUT , and cpl_image_get_type() .

Referenced by cpl_image_add_scalar_create() , cpl_image_new_from_accepted() , and cpl_imagelist_add_scalar() .

Returns: 1 newly allocated image or NULL in case of an error

See also: cpl_image_add_scalar

Creates a new image, being the result of the operation, and returns it to the caller. The returned image must be deallocated using cpl_image_delete() . The function supports images with different types among CPL_TYPE_INT, CPL_TYPE_FLOAT and CPL_TYPE_DOUBLE. The type of the created image is that of the passed image.

References cpl_ensure , cpl_error_get_code() , cpl_image_add_scalar() , cpl_image_delete() , and cpl_image_duplicate() .

Returns: CPL_ERROR_NONE or the relevant the _cpl_error_code_ on error

Note: CPL_TYPE_INT is required

See also: cpl_mask_and() for the equivalent logical operation

Possible _cpl_error_code_ set in this function:

CPL_ERROR_NULL_INPUT if an input pointer is NULL
CPL_ERROR_INCOMPATIBLE_INPUT if the images have different sizes
CPL_ERROR_INVALID_TYPE if the passed image type is as required

References cpl_ensure_code , CPL_ERROR_INCOMPATIBLE_INPUT , CPL_ERROR_INVALID_TYPE , CPL_ERROR_NONE , CPL_ERROR_NULL_INPUT , cpl_image_get_type() , cpl_type_get_name() , cpl_type_get_sizeof() , and CPL_TYPE_INT .

Returns: CPL_ERROR_NONE or the relevant the _cpl_error_code_ on error

Note: CPL_TYPE_INT is required

Possible _cpl_error_code_ set in this function:

CPL_ERROR_NULL_INPUT if an input pointer is NULL
CPL_ERROR_INCOMPATIBLE_INPUT if the images have different sizes
CPL_ERROR_INVALID_TYPE if the passed image type is as required

Returns: 1 newly allocated image or NULL on error

Builds the average of two images and returns a newly allocated image, to be deallocated using cpl_image_delete() . The average is arithmetic, i.e. outpix=(pix1+pix2)/2 Images can be of type CPL_TYPE_INT, CPL_TYPE_FLOAT or CPL_TYPE_DOUBLE.

Possible _cpl_error_code_ set in this function:

CPL_ERROR_NULL_INPUT if an input pointer is NULL
CPL_ERROR_INVALID_TYPE if the passed image type is not supported

References cpl_ensure , CPL_ERROR_ILLEGAL_INPUT , CPL_ERROR_INVALID_TYPE , CPL_ERROR_NULL_INPUT , cpl_mask_duplicate() , and cpl_mask_or() .

Returns: the newly allocated cpl_image or NULL on error

Casting to non-complex types is only supported for non-complex types.

Possible _cpl_error_code_ set in this function:

CPL_ERROR_NULL_INPUT if an input pointer is NULL
CPL_ERROR_ILLEGAL_INPUT if the passed type is invalid
CPL_ERROR_TYPE_MISMATCH if the passed image type is complex and requested casting type is non-complex.
CPL_ERROR_INVALID_TYPE if the passed pixel type is not supported

References cpl_ensure , CPL_ERROR_ILLEGAL_INPUT , CPL_ERROR_INVALID_TYPE , CPL_ERROR_NULL_INPUT , CPL_ERROR_TYPE_MISMATCH , cpl_free() , cpl_image_duplicate() , cpl_malloc() , cpl_mask_duplicate() , CPL_TYPE_DOUBLE , CPL_TYPE_DOUBLE_COMPLEX , CPL_TYPE_FLOAT , CPL_TYPE_FLOAT_COMPLEX , cpl_type_get_name() , cpl_type_get_sizeof() , CPL_TYPE_INT , and CPL_TYPE_INVALID .

Referenced by cpl_image_fit_gaussian() , cpl_imagelist_cast() , cpl_plot_image() , cpl_plot_image_col() , and cpl_plot_image_row() .

Returns: 1 newly allocated 1D image or NULL on error

On success the function returns a 1D image, created by adding up all pixels on the same row or column.

Collapse along y (sum of rows):
p7  p8  p9     Input image is a 3x3 image containing 9 pixels.
p4  p5  p6     The output is an image containing one row with
p1  p2  p3     3 pixels A, B, C, where:
----------
A   B   C      A = p1+p4+p7
               B = p2+p5+p8
               C = p3+p6+p9
If p7 is a bad pixel, A = (p1+p4)*3/2.
If p1, p4, p7 are bad, A is flagged as bad.

Provide the collapsing direction as an int. Give 0 to collapse along y (sum of rows) and get an image with a single row in output, or give 1 to collapse along x (sum of columns) to get an image with a single column in output. Only the good pixels are collapsed. Images can be of type CPL_TYPE_INT, CPL_TYPE_FLOAT or CPL_TYPE_DOUBLE. The returned image must be deallocated using cpl_image_delete() .

Possible _cpl_error_code_ set in this function:

CPL_ERROR_NULL_INPUT if an input pointer is NULL
CPL_ERROR_INVALID_TYPE if the passed image type is not supported

References cpl_ensure , cpl_error_get_code() , cpl_image_collapse_window_create() , cpl_image_get_size_x() , and cpl_image_get_size_y() .

Returns: 1 newly allocated image having 1 row or 1 column or NULL on error

See also: cpl_image_collapse_create()

The collapsing direction is defined as for cpl_image_collapse_create() . For each output pixel, the median of the corresponding non-ignored pixels is computed. A combination of bad pixels and drop parameters can cause a median value in the output image to be undefined. Such pixels will be flagged as bad and set to zero.

If the output would contain only bad pixels an error is set.

Images can be of type CPL_TYPE_INT, CPL_TYPE_FLOAT or CPL_TYPE_DOUBLE. The returned image must be deallocated using cpl_image_delete() .

Possible _cpl_error_code_ set in this function:

CPL_ERROR_NULL_INPUT if an input pointer is NULL
CPL_ERROR_ILLEGAL_INPUT if a rejection parameter is negative, or if the sum of ignored pixels is bigger than the image size in the collapsing direction
CPL_ERROR_INVALID_TYPE if the passed image type is not supported
CPL_ERROR_DATA_NOT_FOUND if the output image would have only bad pixels

References cpl_ensure , CPL_ERROR_ILLEGAL_INPUT , CPL_ERROR_INVALID_TYPE , and CPL_ERROR_NULL_INPUT .

Returns: a newly allocated image or NULL on error

See also: cpl_image_collapse_create()

llx, lly, urx, ury are the image region coordinates in FITS convention. Those specified bounds are included in the collapsed region.

Possible _cpl_error_code_ set in this function:

CPL_ERROR_NULL_INPUT if an input pointer is NULL
CPL_ERROR_ILLEGAL_INPUT if the specified window is not valid

References cpl_image_get_type() , CPL_TYPE_DOUBLE , CPL_TYPE_FLOAT , and CPL_TYPE_INT .

Referenced by cpl_image_collapse_create() .

Returns: CPL_ERROR_NONE or _cpl_error_code_ on error

Note: The two images must match in size and precision

Any bad pixels are also conjugated.

Possible _cpl_error_code_ set in this function:

CPL_ERROR_NULL_INPUT If an input pointer is NULL
CPL_ERROR_INCOMPATIBLE_INPUT If the images have different sizes
CPL_ERROR_INVALID_TYPE If an input image is not of complex type
CPL_ERROR_TYPE_MISMATCH If the images have different precision

References cpl_ensure_code , CPL_ERROR_INCOMPATIBLE_INPUT , CPL_ERROR_INVALID_TYPE , CPL_ERROR_NONE , CPL_ERROR_NULL_INPUT , CPL_ERROR_TYPE_MISMATCH , CPL_TYPE_DOUBLE_COMPLEX , and CPL_TYPE_FLOAT_COMPLEX .

Returns: CPL_ERROR_NONE or the relevant _cpl_error_code_ on error.

Note: The two pixel buffers may not overlap

(xpos, ypos) must be a valid position in im1. If im2 is bigger than the place left in im1, the part that falls outside of im1 is simply ignored, an no error is raised. The bad pixels are inherited from im2 in the concerned im1 zone.

The two input images must be of the same type, namely one of CPL_TYPE_INT, CPL_TYPE_FLOAT, CPL_TYPE_DOUBLE.

Possible _cpl_error_code_ set in this function:

CPL_ERROR_TYPE_MISMATCH if the input images are of different types
CPL_ERROR_INVALID_TYPE if the passed image type is not supported
CPL_ERROR_ACCESS_OUT_OF_RANGE if xpos or ypos are outside the specified range

References cpl_ensure_code , CPL_ERROR_ACCESS_OUT_OF_RANGE , CPL_ERROR_NONE , CPL_ERROR_NULL_INPUT , CPL_ERROR_TYPE_MISMATCH , cpl_image_get_data() , cpl_image_get_size_x() , cpl_image_get_size_y() , cpl_image_get_type() , cpl_mask_copy() , cpl_mask_delete() , cpl_mask_new() , and cpl_type_get_sizeof() .

Referenced by cpl_image_filter_mask() .

Returns: the number of bad pixels or -1 if the input image is NULL

Possible _cpl_error_code_ set in this function:

CPL_ERROR_NULL_INPUT if an input pointer is NULL

References cpl_ensure , CPL_ERROR_NULL_INPUT , and cpl_mask_count() .

Returns: void

Frees all memory associated with a cpl_image. If the passed image is NULL, the function returns without doing anything.

References cpl_free() , and cpl_mask_delete() .

Returns: the _cpl_error_code_ or CPL_ERROR_NONE

See also: cpl_image_add()

Note: The result of division with a zero-valued pixel is marked as a bad pixel.

Possible _cpl_error_code_ set in this function:

CPL_ERROR_NULL_INPUT if an input pointer is NULL
CPL_ERROR_INCOMPATIBLE_INPUT if the input images have different sizes
CPL_ERROR_TYPE_MISMATCH if the second input image has complex type while the first one does not
CPL_ERROR_DIVISION_BY_ZERO is all pixels in the divisor are zero

References cpl_ensure_code , CPL_ERROR_DIVISION_BY_ZERO , CPL_ERROR_INCOMPATIBLE_INPUT , CPL_ERROR_INVALID_TYPE , CPL_ERROR_NONE , CPL_ERROR_NULL_INPUT , CPL_ERROR_TYPE_MISMATCH , cpl_mask_delete() , cpl_mask_duplicate() , cpl_mask_get_data() , cpl_mask_new() , cpl_mask_or() , CPL_TYPE_DOUBLE , CPL_TYPE_DOUBLE_COMPLEX , CPL_TYPE_FLOAT , CPL_TYPE_FLOAT_COMPLEX , and CPL_TYPE_INT .

Referenced by cpl_imagelist_collapse_create() .

See also: cpl_image_add_create()

Possible _cpl_error_code_ set in this function:

CPL_ERROR_NULL_INPUT if an input pointer is NULL
CPL_ERROR_INCOMPATIBLE_INPUT if the input images have different sizes
CPL_ERROR_TYPE_MISMATCH if the second input image has complex type while the first one does not
CPL_ERROR_DIVISION_BY_ZERO is all pixels in the divisor are zero

References cpl_ensure , CPL_ERROR_DIVISION_BY_ZERO , CPL_ERROR_INCOMPATIBLE_INPUT , CPL_ERROR_INVALID_TYPE , CPL_ERROR_NULL_INPUT , CPL_ERROR_TYPE_MISMATCH , cpl_free() , cpl_image_delete() , cpl_image_wrap_double() , cpl_image_wrap_double_complex() , cpl_image_wrap_float() , cpl_image_wrap_float_complex() , cpl_image_wrap_int() , cpl_malloc() , cpl_mask_delete() , cpl_mask_duplicate() , cpl_mask_get_data() , cpl_mask_new() , cpl_mask_or() , CPL_TYPE_DOUBLE , CPL_TYPE_DOUBLE_COMPLEX , CPL_TYPE_FLOAT , CPL_TYPE_FLOAT_COMPLEX , and CPL_TYPE_INT .

Returns: CPL_ERROR_NONE or the relevant the _cpl_error_code_ on error

See also: cpl_image_add_scalar()

Modifies the image by dividing each of its pixels with a number.

If the scalar is zero the image is not modified and an error is returned.

Possible _cpl_error_code_ set in this function:

CPL_ERROR_NULL_INPUT if an input pointer is NULL
CPL_ERROR_DIVISION_BY_ZERO a division by 0 occurs

References cpl_ensure_code , CPL_ERROR_DIVISION_BY_ZERO , CPL_ERROR_INVALID_TYPE , CPL_ERROR_NONE , CPL_ERROR_NULL_INPUT , and cpl_image_get_type() .

Referenced by cpl_image_divide_scalar_create() , cpl_image_fft() , cpl_image_normalise() , and cpl_imagelist_divide_scalar() .

Returns: 1 newly allocated image or NULL in case of an error

See also: cpl_image_divide_scalar

References cpl_ensure , cpl_error_get_code() , cpl_image_delete() , cpl_image_divide_scalar() , and cpl_image_duplicate() .

Returns: CPL_ERROR_NONE or the relevant _cpl_error_code_ on error

Possible _cpl_error_code_ set in this function:

CPL_ERROR_NULL_INPUT if an input pointer is NULL
CPL_ERROR_FILE_IO if a write operation fails

References cpl_ensure_code , CPL_ERROR_FILE_IO , CPL_ERROR_NONE , CPL_ERROR_NULL_INPUT , cpl_mask_count() , CPL_SIZE_FORMAT , and cpl_type_get_name() .

Referenced by cpl_imagelist_dump_structure() .


      stdout


      stderr

Returns: CPL_ERROR_NONE or the relevant _cpl_error_code_ on error

Possible _cpl_error_code_ set in this function:

CPL_ERROR_NULL_INPUT if an input pointer is NULL
CPL_ERROR_FILE_IO if a write operation fails
CPL_ERROR_ACCESS_OUT_OF_RANGE if the defined window is not in the image
CPL_ERROR_ILLEGAL_INPUT if the window definition is wrong (e.g llx > urx)

References cpl_ensure_code , CPL_ERROR_ACCESS_OUT_OF_RANGE , CPL_ERROR_FILE_IO , CPL_ERROR_ILLEGAL_INPUT , CPL_ERROR_NONE , CPL_ERROR_NULL_INPUT , cpl_image_get() , cpl_image_get_complex() , cpl_mask_get() , cpl_mask_is_empty() , CPL_SIZE_FORMAT , CPL_TYPE_DOUBLE_COMPLEX , CPL_TYPE_FLOAT_COMPLEX , and CPL_TYPE_INT .

Referenced by cpl_imagelist_dump_window() .

Returns: 1 newly allocated image, or NULL on error.

Copy an image into a new image object. The pixels and the bad pixel map are also copied. The returned image must be deallocated using cpl_image_delete() .

Possible _cpl_error_code_ set in this function:

CPL_ERROR_NULL_INPUT if an input pointer is NULL

References cpl_ensure , CPL_ERROR_NULL_INPUT , cpl_malloc() , cpl_mask_duplicate() , and cpl_type_get_sizeof() .

Referenced by cpl_geom_img_offset_saa() , cpl_image_abs_create() , cpl_image_add_scalar_create() , cpl_image_cast() , cpl_image_divide_scalar_create() , cpl_image_exponential_create() , cpl_image_logarithm_create() , cpl_image_multiply_scalar_create() , cpl_image_normalise_create() , cpl_image_power_create() , cpl_image_subtract_scalar_create() , cpl_imagelist_collapse_create() , and cpl_imagelist_duplicate() .

Returns: CPL_ERROR_NONE or the relevant the _cpl_error_code_ on error

Modifies the image by computing the base-scalar exponential of each of its pixels.

Images can be of type CPL_TYPE_INT, CPL_TYPE_FLOAT or CPL_TYPE_DOUBLE.

Pixels for which the power of the given base is not defined are rejected and set to zero.

Possible _cpl_error_code_ set in this function:

CPL_ERROR_NULL_INPUT if an input pointer is NULL
CPL_ERROR_INVALID_TYPE if the passed image type is not supported

References cpl_ensure_code , CPL_ERROR_INVALID_TYPE , CPL_ERROR_NONE , CPL_ERROR_NULL_INPUT , cpl_image_get_type() , CPL_TYPE_DOUBLE , CPL_TYPE_FLOAT , cpl_type_get_name() , and CPL_TYPE_INT .

Referenced by cpl_image_exponential_create() , and cpl_imagelist_exponential() .

Returns: 1 newly allocated image or NULL on error

Note: The returned image must be deallocated using cpl_image_delete()

The input coordinates define the extracted region by giving the coordinates of the lower left and upper right corners (inclusive).

Coordinates must be provided in the FITS convention: lower left corner of the image is at (1,1), x increasing from left to right, y increasing from bottom to top. Images can be of type CPL_TYPE_INT, CPL_TYPE_FLOAT or CPL_TYPE_DOUBLE.

If the input image has a bad pixel map and if the extracted rectangle has bad pixel(s), then the extracted image will have a bad pixel map, otherwise it will not.

Possible _cpl_error_code_ set in this function:

CPL_ERROR_NULL_INPUT if an input pointer is NULL
CPL_ERROR_ILLEGAL_INPUT if the window coordinates are not valid
CPL_ERROR_INVALID_TYPE if the passed image type is not supported

References cpl_ensure , CPL_ERROR_ILLEGAL_INPUT , CPL_ERROR_INVALID_TYPE , and CPL_ERROR_NULL_INPUT .

Referenced by cpl_apertures_extract_window() , cpl_fit_image_gaussian() , and cpl_image_iqe() .

Returns: The newly allocated sub-sampled image or NULL in error case

See also: cpl_image_extract

step represents the sampling step in x and y: both steps = 2 will create an image with a quarter of the pixels of the input image.

image type can be CPL_TYPE_INT, CPL_TYPE_FLOAT and CPL_TYPE_DOUBLE. If the image has bad pixels, they will be resampled in the same way.

The flux of the sampled pixels will be preserved, while the flux of the pixels not sampled will be lost. Using steps = 2 in each direction on a uniform image will thus create an image with a quarter of the flux.

The returned image must be deallocated using cpl_image_delete() .

Possible _cpl_error_code_ set in this function:

CPL_ERROR_NULL_INPUT if the input pointer is NULL
CPL_ERROR_ILLEGAL_INPUT if xstep, ystep are not positive
CPL_ERROR_INVALID_TYPE if the passed image type is not supported

References cpl_ensure , CPL_ERROR_ILLEGAL_INPUT , CPL_ERROR_INVALID_TYPE , CPL_ERROR_NULL_INPUT , and cpl_mask_extract_subsample() .

Returns: CPL_ERROR_NONE or the relevant _cpl_error_code_ on error

See also: cpl_fft_image()

The input images must be of double type.

If the second passed image is NULL, the resulting imaginary part cannot be returned. This can be useful if the input is real and the output is known to also be real. But if the output has a significant imaginary part, you might want to pass a 0-valued image as the second parameter.

Any rejected pixel is used as if it were a good pixel.

The image must be square with a size that is a power of two.

These are the supported FFT modes: CPL_FFT_DEFAULT: Default, forward FFT transform CPL_FFT_INVERSE: Inverse FFT transform CPL_FFT_UNNORMALIZED: Do not normalize (with N*N for N-by-N image) on inverse. Has no effect on forward transform. CPL_FFT_SWAP_HALVES: Swap the four quadrants of the result image.

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 the image is not square or if the image size is not a power of 2.
CPL_ERROR_INVALID_TYPE if mode is 1, e.g. due to a logical or (||) of the allowed FFT options.
CPL_ERROR_UNSUPPORTED_MODE if mode is otherwise different from the allowed FFT options.
CPL_ERROR_INVALID_TYPE if the passed image type is not supported

References cpl_calloc() , cpl_ensure_code , cpl_error_get_code() , CPL_ERROR_ILLEGAL_INPUT , CPL_ERROR_INVALID_TYPE , CPL_ERROR_NONE , CPL_ERROR_NULL_INPUT , CPL_ERROR_UNSUPPORTED_MODE , cpl_free() , cpl_image_divide_scalar() , cpl_image_move() , and CPL_TYPE_DOUBLE .


            NULL


            NULL

Returns: CPL_ERROR_NONE or _cpl_error_code_ on error

Note: At least one output image must be non-NULL. The images must match in size and precision

Any bad pixels are also processed.

Possible _cpl_error_code_ set in this function:

CPL_ERROR_NULL_INPUT If the input image or both output images are NULL
CPL_ERROR_INCOMPATIBLE_INPUT If the images have different sizes
CPL_ERROR_INVALID_TYPE If the input image is not of complex type
CPL_ERROR_TYPE_MISMATCH If the images have different precision

References cpl_ensure_code , CPL_ERROR_INCOMPATIBLE_INPUT , CPL_ERROR_INVALID_TYPE , CPL_ERROR_NONE , CPL_ERROR_NULL_INPUT , CPL_TYPE_COMPLEX , CPL_TYPE_DOUBLE_COMPLEX , and CPL_TYPE_FLOAT_COMPLEX .

Returns: the _cpl_error_code_ or CPL_ERROR_NONE

This function expects an already allocated image. This function generates an image of a 2d gaussian. The gaussian is defined by the position of its centre, given in pixel coordinates inside the image with the FITS convention (x from 1 to nx, y from 1 to ny), its norm and the value of sigma in x and y.

f(x, y) = (norm/(2*pi*sig_x*sig_y)) * exp(-(x-xcen)^2/(2*sig_x^2)) * exp(-(y-ycen)^2/(2*sig_y^2))

The input image type can be CPL_TYPE_FLOAT or CPL_TYPE_DOUBLE.

Possible _cpl_error_code_ set in this function:

CPL_ERROR_NULL_INPUT if (one of) the input pointer(s) is NULL
CPL_ERROR_INVALID_TYPE if the passed image type is not supported

References cpl_ensure_code , CPL_ERROR_INVALID_TYPE , CPL_ERROR_NONE , and CPL_ERROR_NULL_INPUT .

Referenced by cpl_image_fill_test_create() .

Returns: CPL_ERROR_NONE or the relevant _cpl_error_code_ on error

See also: cpl_image_warp()

The shifts images deltax and deltay , describing the transformation, must be of type CPL_TYPE_DOUBLE and of the same size as out . For each pixel (u, v) of the out image, the deltax and deltay code the following transformation:

u - deltax(u,v) = x

v - deltay(u,v) = y

This function writes the density of the (u, v) coordinate system relative to the (x, y) coordinates for each (u, v) pixel of image out .

This is trivially obtained by computing the absolute value of the determinant of the Jacobian of the transformation for each pixel of the (u, v) image out .

The partial derivatives are estimated at the position (u, v) in the following way:

               dx/du = 1 + 1/2 ( deltax(u-1, v) - deltax(u+1, v) )
              
               dx/dv =     1/2 ( deltax(u, v-1) - deltax(u, v+1) )
              
               dy/du =     1/2 ( deltay(u-1, v) - deltay(u+1, v) )
              
               dy/dv = 1 + 1/2 ( deltay(u, v-1) - deltay(u, v+1) )

Typically this function would be used to determine a flux-conservation factor map for the target image specified in function cpl_image_warp() . For example,

               
                cpl_image_warp
               
               (out, in, deltax, deltay, xprof, xrad, yprof, yrad);
              
               correction_map =
               
                cpl_image_new
               
               (
               
                cpl_image_get_size_x
               
               (out),
              
                cpl_image_get_size_y
               
               (out),
              
                cpl_image_get_type
               
               (out));
              
                cpl_image_fill_jacobian
               
               (correction_map, deltax, deltay);
              
               out_flux_corrected =
               
                cpl_image_multiply_create
               
               (out, correction_map);

where out_flux_corrected is the resampled image out after correction for flux conservation.

Note: The map produced by this function is not applicable for flux conservation in case the transformation implies severe undersampling of the original signal.

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 the polynomial dimensions are not 2
CPL_ERROR_INVALID_TYPE if the passed image type is not supported

References CPL_ERROR_ILLEGAL_INPUT , CPL_ERROR_INVALID_TYPE , CPL_ERROR_NONE , CPL_ERROR_NULL_INPUT , CPL_ERROR_UNSPECIFIED , cpl_image_abs() , cpl_image_delete() , cpl_image_get_data_double() , cpl_image_get_data_double_const() , cpl_image_get_data_float() , cpl_image_get_size_x() , cpl_image_get_size_y() , cpl_image_get_type() , cpl_image_new() , CPL_TYPE_DOUBLE , and CPL_TYPE_FLOAT .

Returns: CPL_ERROR_NONE or the relevant _cpl_error_code_ on error

See also: cpl_image_warp_polynomial()

Given an input image with pixel coordinates (x, y) which is mapped into an output image with pixel coordinates (u, v), and the polynomial inverse transformation (u, v) to (x, y) as in cpl_image_warp_polynomial() , this function writes the density of the (u, v) coordinate system relative to the (x, y) coordinates for each (u, v) pixel of image out .

This is trivially obtained by computing the absolute value of the determinant of the Jacobian of the transformation for each pixel of the (u, v) image out .

Typically this function would be used to determine a flux-conservation factor map for the target image specified in function cpl_image_warp_polynomial() . For example,

                
                 cpl_image_warp_polynomial
                
                (out, in, poly_x, poly_y, xprof, xrad, yprof, yrad);
               
                correction_map =
                
                 cpl_image_new
                
                (
                
                 cpl_image_get_size_x
                
                (out),
               
                 cpl_image_get_size_y
                
                (out),
               
                 cpl_image_get_type
                
                (out));
               
                 cpl_image_fill_jacobian_polynomial
                
                (correction_map, poly_x, poly_y);
               
                out_flux_corrected =
                
                 cpl_image_multiply_create
                
                (out, correction_map);

where out_flux_corrected is the resampled image out after correction for flux conservation.

Note: The map produced by this function is not applicable for flux conservation in case the transformation implies severe undersampling of the original signal.

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 the polynomial dimensions are not 2
CPL_ERROR_INVALID_TYPE if the passed image type is not supported

References CPL_ERROR_ILLEGAL_INPUT , CPL_ERROR_INVALID_TYPE , CPL_ERROR_NONE , CPL_ERROR_NULL_INPUT , CPL_ERROR_UNSPECIFIED , cpl_image_abs() , cpl_image_get_data_double() , cpl_image_get_data_float() , cpl_image_get_size_x() , cpl_image_get_size_y() , cpl_image_get_type() , cpl_polynomial_delete() , cpl_polynomial_derivative() , cpl_polynomial_duplicate() , cpl_polynomial_eval() , cpl_polynomial_get_dimension() , CPL_TYPE_DOUBLE , CPL_TYPE_FLOAT , cpl_vector_delete() , cpl_vector_get_data() , and cpl_vector_new() .

Returns: the _cpl_error_code_ or CPL_ERROR_NONE

Generate an image with a uniform random noise distribution. Pixel values are within the provided bounds. This function expects an already allocated image. The input image type can be CPL_TYPE_INT, CPL_TYPE_FLOAT or CPL_TYPE_DOUBLE.

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 min_pix is bigger than max_pix
CPL_ERROR_INVALID_TYPE if the passed image type is not supported

References cpl_ensure_code , CPL_ERROR_ILLEGAL_INPUT , CPL_ERROR_INVALID_TYPE , CPL_ERROR_NONE , and CPL_ERROR_NULL_INPUT .

Referenced by cpl_image_fill_test_create() .

Returns: the _cpl_error_code_ or CPL_ERROR_NONE

This function expects an already allocated image. The pixel value of the pixel (i, j) is set to poly(startx+(i-1)*stepx, starty+(j-1)*stepy).

The input image type can be CPL_TYPE_FLOAT or CPL_TYPE_DOUBLE.

If you want to generate an image whose pixel values are the values of the polynomial applied to the pixel positions, just call cpl_image_fill_polynomial(ima, poly, 1.0, 1.0, 1.0, 1.0);

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 the polynomial's dimension is not 2
CPL_ERROR_INVALID_TYPE if the passed image type is not supported

References cpl_ensure_code , CPL_ERROR_ILLEGAL_INPUT , CPL_ERROR_INVALID_TYPE , CPL_ERROR_NONE , CPL_ERROR_NULL_INPUT , and cpl_polynomial_get_dimension() .


                  NULL


                  NULL

Returns: CPL_ERROR_NONE or _cpl_error_code_ on error

Note: At least one output image must be non-NULL. The images must match in size and precision

Any bad pixels are also processed.

Possible _cpl_error_code_ set in this function:

CPL_ERROR_NULL_INPUT If the input image or both output images are NULL
CPL_ERROR_INCOMPATIBLE_INPUT If the images have different sizes
CPL_ERROR_INVALID_TYPE If the input image is not of complex type
CPL_ERROR_TYPE_MISMATCH If the images have different precision

References cpl_ensure_code , CPL_ERROR_INCOMPATIBLE_INPUT , CPL_ERROR_INVALID_TYPE , CPL_ERROR_NONE , CPL_ERROR_NULL_INPUT , CPL_TYPE_COMPLEX , CPL_TYPE_DOUBLE_COMPLEX , and CPL_TYPE_FLOAT_COMPLEX .

Returns: the _cpl_error_code_ or CPL_ERROR_NONE

Images can be CPL_TYPE_FLOAT, CPL_TYPE_INT, CPL_TYPE_DOUBLE.

Possible _cpl_error_code_ set in this function:

CPL_ERROR_NULL_INPUT if an input pointer is NULL
CPL_ERROR_ILLEGAL_INPUT
CPL_ERROR_INVALID_TYPE if the image pixel type is not supported

References cpl_ensure_code , CPL_ERROR_INVALID_TYPE , CPL_ERROR_NONE , CPL_ERROR_NULL_INPUT , cpl_mask_get_data() , and cpl_mask_is_empty() .

Referenced by cpl_geom_img_offset_saa() , and cpl_imagelist_collapse_create() .

Returns: 1 newly allocated image or NULL on error

Generates a reference pattern for testing purposes only. The created image has to be deallocated with cpl_image_delete() .

Possible _cpl_error_code_ set in this function:

CPL_ERROR_ILLEGAL_INPUT if nx or ny is non-positive

References cpl_ensure , CPL_ERROR_ILLEGAL_INPUT , cpl_image_add() , cpl_image_delete() , cpl_image_fill_gaussian() , cpl_image_fill_noise_uniform() , cpl_image_multiply_scalar() , cpl_image_new() , and CPL_TYPE_DOUBLE .

Returns: The _cpl_error_code_ or CPL_ERROR_NONE

Note: Any bad pixels are accepted

Possible _cpl_error_code_ set in this function:

CPL_ERROR_NULL_INPUT if an input pointer is NULL
CPL_ERROR_ILLEGAL_INPUT if the specified window is not valid

References cpl_ensure_code , CPL_ERROR_ILLEGAL_INPUT , CPL_ERROR_INVALID_TYPE , CPL_ERROR_NONE , CPL_ERROR_NULL_INPUT , and CPL_TYPE_COMPLEX .

Returns: CPL_ERROR_NONE or the relevant CPL error code

See also: cpl_image_filter_mask

The two images must have equal dimensions.

The kernel must have an odd number of rows and an odd number of columns and at least one non-zero element.

For scaling filters ( CPL_FILTER_LINEAR_SCALE and CPL_FILTER_MORPHO_SCALE ) the flux of the filtered image will be scaled with the sum of the weights of the kernel. If for a given input pixel location the kernel covers only bad pixels, the filtered pixel value is flagged as bad and set to zero.

For flux-preserving filters ( CPL_FILTER_LINEAR and CPL_FILTER_MORPHO ) the filtered pixel must have at least one input pixel with a non-zero weight available. Output pixels where this is not the case are set to zero and flagged as bad.

In-place filtering is not supported.

Supported filters: CPL_FILTER_LINEAR , CPL_FILTER_MORPHO , CPL_FILTER_LINEAR_SCALE , CPL_FILTER_MORPHO_SCALE .

Supported borders modes: CPL_BORDER_FILTER

Example:

cpl_image_filter (filtered, raw, kernel, CPL_FILTER_LINEAR ,

CPL_BORDER_FILTER );

CPL_BORDER_FILTER

@ CPL_BORDER_FILTER

Definition: cpl_filter.h:62

CPL_FILTER_LINEAR

@ CPL_FILTER_LINEAR

Definition: cpl_filter.h:140

cpl_image_filter

cpl_error_code cpl_image_filter(cpl_image *self, const cpl_image *other, const cpl_matrix *kernel, cpl_filter_mode filter, cpl_border_mode border)

Filter an image using a floating-point kernel.

Definition: cpl_image_filter.c:962

Beware that the 1st pixel - at (1,1) - in an image is the lower left, while the 1st element in a matrix - at (0,0) - is the top left. Thus to shift an image 1 pixel up and 1 pixel right with the CPL_FILTER_LINEAR and a 3 by 3 kernel, one should set to 1.0 the bottom leftmost matrix element which is at row 3, column 1, i.e.

cpl_matrix_set(kernel, 2, 0);

Possible _cpl_error_code_ set in this function:

CPL_ERROR_NULL_INPUT if an input pointer is NULL.
CPL_ERROR_ILLEGAL_INPUT if the kernel has a side of even length.
CPL_ERROR_DIVISION_BY_ZERO If the kernel is a zero-matrix.
CPL_ERROR_ACCESS_OUT_OF_RANGE If the kernel has a side longer than the input image.
CPL_ERROR_INVALID_TYPE if the passed image type is not supported.
CPL_ERROR_TYPE_MISMATCH if in median filtering the input and output pixel types differ.
CPL_ERROR_INCOMPATIBLE_INPUT If the input and output images have incompatible sizes.
CPL_ERROR_UNSUPPORTED_MODE If the output pixel buffer overlaps the input one (or the kernel), or the border/filter mode is unsupported.

References CPL_BORDER_CROP , CPL_BORDER_FILTER , cpl_ensure_code , CPL_ERROR_ACCESS_OUT_OF_RANGE , CPL_ERROR_DIVISION_BY_ZERO , CPL_ERROR_ILLEGAL_INPUT , CPL_ERROR_INCOMPATIBLE_INPUT , CPL_ERROR_INVALID_TYPE , CPL_ERROR_NONE , CPL_ERROR_NULL_INPUT , CPL_ERROR_UNSUPPORTED_MODE , CPL_FILTER_LINEAR , CPL_FILTER_LINEAR_SCALE , CPL_FILTER_MORPHO , CPL_FILTER_MORPHO_SCALE , cpl_image_get_data() , cpl_image_get_data_const() , cpl_image_get_size_x() , cpl_image_get_size_y() , cpl_image_get_type() , cpl_mask_get_data() , cpl_mask_get_data_const() , cpl_mask_is_empty() , cpl_mask_wrap() , cpl_matrix_get_data_const() , cpl_matrix_get_ncol() , cpl_matrix_get_nrow() , CPL_TYPE_DOUBLE , CPL_TYPE_FLOAT , cpl_type_get_sizeof() , and CPL_TYPE_INT .

Referenced by cpl_image_filter_linear() , and cpl_image_filter_morpho() .

Returns: The filtered image or NULL on error

See also: cpl_image_filter()

Deprecated:: Replace this call with cpl_image_filter() using CPL_FILTER_LINEAR and CPL_BORDER_FILTER.

References CPL_BORDER_FILTER , cpl_ensure , CPL_ERROR_NULL_INPUT , CPL_FILTER_LINEAR , cpl_image_delete() , cpl_image_filter() , and cpl_image_new() .

Returns: CPL_ERROR_NONE or the relevant CPL error code

The kernel must have an odd number of rows and an odd number of columns.

The two images must have equal dimensions, except for the border mode CPL_BORDER_CROP, where the input image must have 2 * hx columns more and 2 * hy rows more than the output image, where the kernel has size (1 + 2 * hx, 1 + 2 * hy).

In standard deviation filtering the kernel must have at least two elements set to CPL_BINARY_1, for others at least one element must be set to CPL_BINARY_1.

Supported pixel types are: CPL_TYPE_INT, CPL_TYPE_FLOAT and CPL_TYPE_DOUBLE.

In median filtering the two images must have the same pixel type.

In standard deviation filtering a filtered pixel must be computed from at least two input pixels, for other filters at least one input pixel must be available. Output pixels where this is not the case are set to zero and flagged as rejected.

In-place filtering is not supported.

Supported modes:

CPL_FILTER_MEDIAN: CPL_BORDER_FILTER, CPL_BORDER_COPY, CPL_BORDER_NOP, CPL_BORDER_CROP.

CPL_FILTER_AVERAGE: CPL_BORDER_FILTER

CPL_FILTER_AVERAGE_FAST: CPL_BORDER_FILTER

CPL_FILTER_STDEV: CPL_BORDER_FILTER

CPL_FILTER_STDEV_FAST: CPL_BORDER_FILTER

Example:

cpl_image_filter_mask (filtered, raw, kernel, CPL_FILTER_MEDIAN ,

CPL_BORDER_FILTER );

CPL_FILTER_MEDIAN

@ CPL_FILTER_MEDIAN

Definition: cpl_filter.h:220

cpl_image_filter_mask

cpl_error_code cpl_image_filter_mask(cpl_image *self, const cpl_image *other, const cpl_mask *kernel, cpl_filter_mode filter, cpl_border_mode border)

Filter an image using a binary kernel.

Definition: cpl_image_filter.c:241

To shift an image 1 pixel up and 1 pixel right with the CPL_FILTER_MEDIAN filter and a 3 by 3 kernel, one should set to CPL_BINARY_1 the bottom leftmost kernel element - at row 3, column 1, i.e.

cpl_mask * kernel = cpl_mask_new (3, 3);

cpl_mask_set (kernel, 1, 1);

cpl_mask_new

cpl_mask * cpl_mask_new(cpl_size nx, cpl_size ny)

Create a new cpl_mask.

Definition: cpl_mask.c:794

cpl_mask_set

cpl_error_code cpl_mask_set(cpl_mask *self, cpl_size xpos, cpl_size ypos, cpl_binary value)

Set a value in a mask at a given position.

Definition: cpl_mask.c:990

The kernel required to do a 5 x 5 median filtering is created like this:

cpl_mask * kernel = cpl_mask_new (5, 5);

cpl_mask_not (kernel);

cpl_mask_not

cpl_error_code cpl_mask_not(cpl_mask *in)

Performs a logical NOT on a mask.

Definition: cpl_mask.c:1446

Possible _cpl_error_code_ set in this function:

CPL_ERROR_NULL_INPUT if an input pointer is NULL.
CPL_ERROR_ILLEGAL_INPUT if the kernel has a side of even length.
CPL_ERROR_DATA_NOT_FOUND If the kernel is empty, or in case of CPL_FILTER_STDEV if the kernel has only one element set to CPL_BINARY_1.
CPL_ERROR_ACCESS_OUT_OF_RANGE If the kernel has a side longer than the input image.
CPL_ERROR_INVALID_TYPE if the passed image type is not supported.
CPL_ERROR_TYPE_MISMATCH if in median filtering the input and output pixel types differ.
CPL_ERROR_INCOMPATIBLE_INPUT If the input and output images have incompatible sizes.
CPL_ERROR_UNSUPPORTED_MODE If the output pixel buffer overlaps the input one (or the kernel), or the border/filter mode is unsupported.

References CPL_BORDER_CROP , CPL_BORDER_FILTER , cpl_ensure_code , CPL_ERROR_ACCESS_OUT_OF_RANGE , CPL_ERROR_DATA_NOT_FOUND , CPL_ERROR_ILLEGAL_INPUT , CPL_ERROR_INCOMPATIBLE_INPUT , CPL_ERROR_INVALID_TYPE , CPL_ERROR_NONE , CPL_ERROR_NULL_INPUT , CPL_ERROR_TYPE_MISMATCH , CPL_ERROR_UNSUPPORTED_MODE , CPL_FILTER_AVERAGE , CPL_FILTER_AVERAGE_FAST , CPL_FILTER_MEDIAN , CPL_FILTER_STDEV , CPL_FILTER_STDEV_FAST , cpl_image_copy() , cpl_image_get_data() , cpl_image_get_data_const() , cpl_image_get_size_x() , cpl_image_get_size_y() , cpl_image_get_type() , cpl_mask_get_data() , cpl_mask_get_data_const() , cpl_mask_get_size_x() , cpl_mask_get_size_y() , cpl_mask_is_empty() , cpl_mask_wrap() , CPL_TYPE_DOUBLE , CPL_TYPE_FLOAT , cpl_type_get_sizeof() , and CPL_TYPE_INT .

Referenced by cpl_geom_img_offset_fine() , cpl_image_filter_median() , cpl_image_filter_stdev() , and cpl_vector_filter_median_create() .

Returns: 1 newly allocated image or NULL in error case

See also: cpl_image_filter_mask

Deprecated:: Replace this call with cpl_image_filter_mask() using CPL_FILTER_MEDIAN and CPL_BORDER_FILTER.

References CPL_BORDER_FILTER , cpl_ensure , cpl_error_get_code() , CPL_ERROR_NULL_INPUT , CPL_FILTER_MEDIAN , cpl_image_delete() , cpl_image_filter_mask() , cpl_image_new() , and cpl_mask_delete() .

Returns: 1 newly allocated image or NULL in error case.

See also: cpl_image_filter()

Deprecated:: Replace this call with cpl_image_filter() using CPL_FILTER_MORPHO and CPL_BORDER_FILTER.

References CPL_BORDER_FILTER , cpl_ensure , CPL_ERROR_NULL_INPUT , CPL_FILTER_MORPHO , cpl_image_delete() , cpl_image_filter() , and cpl_image_new() .

Returns: a newly allocated filtered image or NULL on error

See also: cpl_image_filter_mask

Deprecated:: Replace this call with cpl_image_filter_mask() using CPL_FILTER_STDEV and CPL_BORDER_FILTER.

References CPL_BORDER_FILTER , cpl_ensure , cpl_error_get_code() , CPL_ERROR_NULL_INPUT , CPL_FILTER_STDEV , cpl_image_delete() , cpl_image_filter_mask() , cpl_image_new() , cpl_mask_delete() , cpl_mask_get_size_x() , and cpl_mask_get_size_y() .

Returns: the _cpl_error_code_ or CPL_ERROR_NONE

See also: cpl_fit_image_gaussian()

Deprecated:: If you need a 2D gaussian fit please use the function cpl_fit_image_gaussian() . Please note that on CPL versions earlier than 5.1.0 this function was wrongly documented: the parameters sig_x and sig_y were defined as "the sigma in x (or y) of the gaussian", while actually they returned the semi-major and semi-minor axes of the gaussian distribution at 1-sigma. PLEASE NOTE THAT IF YOU USED THIS FUNCTION FOR DETERMINING THE SPREAD OF A DISTRIBUTION ALONG THE X DIRECTION, THIS WAS VERY LIKELY OVERESTIMATED (because sig_x was always assigned the semi-major axis of the distribution ignoring the rotation), WHILE THE SPREAD ALONG THE Y DIRECTION WOULD BE UNDERESTIMATED . In addition to that, even with circular distributions this function may lead to an underestimation of sig_x and sig_y (up to 25% underestimation in the case of noiseless data with a box 4 times the sigma, 1% underestimation in the case of noiseless data with a box 7 times the sigma). This latter problem is related to the function cpl_image_iqe() .

This function is only acceptable for determining the position of a peak.

References cpl_bivector_delete() , cpl_bivector_get_x_data() , cpl_ensure_code , CPL_ERROR_ILLEGAL_INPUT , CPL_ERROR_NONE , CPL_ERROR_NULL_INPUT , cpl_image_cast() , cpl_image_delete() , cpl_image_get_type() , cpl_image_iqe() , CPL_MATH_2PI , CPL_MATH_FWHM_SIG , and CPL_TYPE_FLOAT .

Returns: the _cpl_error_code_ or CPL_ERROR_NONE

This function operates locally on the pixel buffer.

angle can take one of the following values:

0 (theta=0) to flip the image around the horizontal
1 (theta=pi/4) to flip the image around y=x
2 (theta=pi/2) to flip the image around the vertical
3 (theta=3pi/4) to flip the image around y=-x

Images can be of type CPL_TYPE_INT, CPL_TYPE_FLOAT or CPL_TYPE_DOUBLE.

Possible _cpl_error_code_ set in this function:

CPL_ERROR_NULL_INPUT if an input pointer is NULL
CPL_ERROR_ILLEGAL_INPUT if the angle is different from the allowed values
CPL_ERROR_INVALID_TYPE if the passed image type is not supported

References cpl_ensure_code , CPL_ERROR_INVALID_TYPE , CPL_ERROR_NONE , CPL_ERROR_NULL_INPUT , and cpl_mask_flip() .

Returns: The pixel value (cast to a double), zero if bad, undefined on error

See also: cpl_image_get_complex()

If the pixel is flagged as bad, 0.0 is returned.

In case of an error, the _cpl_error_code_ code is set.

Images can be CPL_TYPE_FLOAT, CPL_TYPE_INT or CPL_TYPE_DOUBLE.

Possible _cpl_error_code_ set in this function:

CPL_ERROR_NULL_INPUT if an input pointer is NULL
CPL_ERROR_ACCESS_OUT_OF_RANGE if the passed position is not in the image
CPL_ERROR_INVALID_TYPE if the image pixel type is not supported

References cpl_ensure , CPL_ERROR_ACCESS_OUT_OF_RANGE , CPL_ERROR_INVALID_TYPE , CPL_ERROR_NULL_INPUT , and CPL_TYPE_COMPLEX .

Referenced by cpl_fit_image_gaussian() , cpl_image_dump_window() , and cpl_image_get_fwhm() .

Returns: the absolute flux (sum of |pixels|) value

See also: cpl_image_get_min_window()

Returns: A pointer to the mask identifying the bad pixels or NULL.

The returned pointer refers to already allocated data. If the bad pixel map is NULL, an empty one is created.

Possible _cpl_error_code_ set in this function:

CPL_ERROR_NULL_INPUT if an input pointer is NULL

References cpl_ensure , CPL_ERROR_NULL_INPUT , and cpl_mask_new() .

Referenced by cpl_geom_img_offset_saa() , and cpl_image_reject_from_mask() .

Returns: A pointer to the mask identifying the bad pixels or NULL.

Note: NULL is returned if the image has no bad pixel map

See also: cpl_image_get_bpm

Possible _cpl_error_code_ set in this function:

CPL_ERROR_NULL_INPUT if an input pointer is NULL

References cpl_ensure , and CPL_ERROR_NULL_INPUT .

Referenced by cpl_detector_interpolate_rejected() , cpl_fit_image_gaussian() , cpl_fit_imagelist_polynomial_window() , cpl_geom_img_offset_saa() , cpl_image_new_from_accepted() , cpl_imagelist_cast() , cpl_imagelist_collapse_create() , cpl_imagelist_empty() , cpl_imagelist_erase() , cpl_imagelist_set() , and cpl_mask_threshold_image() .

Returns: the x centroid value

See also: cpl_image_get_min_window()

Returns: the y centroid value

See also: cpl_image_get_min_window()

Returns: The pixel value (cast to a double complex), zero if bad, undefined on error

See also: cpl_image_get()

Note: This function is available iff the application includes complex.h

If the pixel is flagged as bad, 0.0 is returned.

In case of an error, the _cpl_error_code_ code is set.

Possible _cpl_error_code_ set in this function:

CPL_ERROR_NULL_INPUT if an input pointer is NULL
CPL_ERROR_ACCESS_OUT_OF_RANGE if the passed position is not in the image

References cpl_ensure , CPL_ERROR_ACCESS_OUT_OF_RANGE , CPL_ERROR_INVALID_TYPE , and CPL_ERROR_NULL_INPUT .

Referenced by cpl_image_dump_window() .

Returns: A pointer to the image pixel data or NULL on error.

The returned pointer refers to already allocated data.

Possible _cpl_error_code_ set in this function:

CPL_ERROR_NULL_INPUT if an input pointer is NULL

References cpl_ensure , and CPL_ERROR_NULL_INPUT .

Referenced by cpl_detector_interpolate_rejected() , cpl_image_copy() , cpl_image_filter() , and cpl_image_filter_mask() .

Returns: pointer to the double data array or NULL on error.

The returned pointer refers to already allocated data.

The pixels are stored in a one dimensional array. The pixel value PIXVAL at position (i, j) in the image - (0, 0) is the lower left pixel, i gives the column position from left to right, j gives the row position from bottom to top - is given by : PIXVAL = array[i + j*nx]; where nx is the x size of the image and array is the data array returned by this function. array can be used to access or modify the pixel value in the image.

Possible _cpl_error_code_ set in this function:

CPL_ERROR_NULL_INPUT if an input pointer is NULL
CPL_ERROR_TYPE_MISMATCH if the passed image type is not double

Referenced by cpl_image_fill_jacobian() , cpl_image_fill_jacobian_polynomial() , and cpl_plot_image() .

Returns: pointer to the double complex data array or NULL on error.

See also: cpl_image_get_data_double()

Note: This function is available iff the application includes complex.h

Returns: pointer to the double data array or NULL on error.

See also: cpl_image_get_data_double

Referenced by cpl_fit_image_gaussian() , cpl_image_fill_jacobian() , cpl_image_warp() , cpl_plot_image() , cpl_plot_image_col() , and cpl_plot_image_row() .

Returns: pointer to the float data array or NULL on error.

See also: cpl_image_get_data_double()

Referenced by cpl_image_fill_jacobian() , cpl_image_fill_jacobian_polynomial() , and cpl_image_iqe() .

Returns: pointer to the integer data array or NULL on error.

See also: cpl_image_get_data_double()

Referenced by cpl_image_labelise_mask_create() , and cpl_imagelist_collapse_sigclip_create() .

See also: cpl_image_get_min()

References cpl_ensure , CPL_ERROR_NULL_INPUT , and cpl_image_get_flux_window() .

Referenced by cpl_image_normalise() .

Returns: the flux value

See also: cpl_image_get_min_window()

Referenced by cpl_image_get_flux() .

Returns: CPL_ERROR_NONE or the relevant _cpl_error_code_

This function uses a basic method: start from the center of the object and go away until the half maximum value is reached in x and y.

For the FWHM in x (resp. y) to be computed, the image size in the x (resp. y) direction should be at least of 5 pixels.

If for any reason, one of the FHWMs cannot be computed, its returned value is -1.0, but an error is not necessarily raised. For example, if a 4 column image is passed, the fwhm_x would be -1.0, the fwhm_y would be correctly computed, and no error would be raised.

Possible _cpl_error_code_ set in this function:

CPL_ERROR_NULL_INPUT if an input pointer is NULL
CPL_ERROR_DATA_NOT_FOUND if (xpos, ypos) specifies a rejected pixel or a pixel with a non-positive value
CPL_ERROR_ACCESS_OUT_OF_RANGE if xpos or ypos is outside the image size range

References cpl_ensure_code , CPL_ERROR_DATA_NOT_FOUND , cpl_error_get_code() , CPL_ERROR_NONE , CPL_ERROR_NULL_INPUT , cpl_errorstate_get() , cpl_errorstate_is_equal() , cpl_image_get() , cpl_vector_delete() , cpl_vector_new_from_image_column() , and cpl_vector_new_from_image_row() .

Referenced by cpl_apertures_get_fwhm() .

Returns: The interpolated pixel value, or undefined on error

See also: cpl_image_get()

This function interpolates a single pixel value as a weighted average of its neigbors, specified as being inside a circle or ellipse with the distance dependent weights provided by the caller.

If the X- and Y-radii are identical the area of inclusion is a circle, otherwise it is an ellipse, with the larger of the two radii as the semimajor axis and the other as the semiminor axis.

The radii are only required to be positive. However, for small radii, especially radii less than 1/sqrt(2), (xpos, ypos) may be located such that no source pixels are included in the interpolation, causing the interpolated pixel value to be undefined.

The X- and Y-profiles can be generated with cpl_vector_fill_kernel_profile(profile, radius). For profiles generated with cpl_vector_fill_kernel_profile() it is important to use the same radius both there and in cpl_image_get_interpolated() .

A good profile length is CPL_KERNEL_DEF_SAMPLES, using radius CPL_KERNEL_DEF_WIDTH.

On error *pconfid is negative (unless pconfid is NULL). Otherwise, if *pconfid is zero, the interpolated pixel-value is undefined. Otherwise, if *pconfid is less than 1, the area of inclusion is close to the image border or contains rejected pixels.

The input image type can be CPL_TYPE_INT, CPL_TYPE_FLOAT and CPL_TYPE_DOUBLE.

Here is an example of a simple image unwarping (with error-checking omitted for brevity):

                                    
                                     const
                                    
                                     double
                                    
                                    xyradius = CPL_KERNEL_DEF_WIDTH;
                                   
                                    cpl_vector * xyprofile =
                                    
                                     cpl_vector_new
                                    
                                    (CPL_KERNEL_DEF_SAMPLES);
                                   
                                    cpl_image  * unwarped  =
                                    
                                     cpl_image_new
                                    
                                    (nx, ny,
                                    
                                     CPL_TYPE_DOUBLE
                                    
                                    );
                                   
                                     cpl_vector_fill_kernel_profile
                                    
                                    (xyprofile, CPL_KERNEL_DEFAULT, xyradius);
                                   
                                     for
                                    
                                    (iv = 1; iv <= ny; iv++) {
                                   
                                     for
                                    
                                    (iu = 1; iu <= nx; iu++) {
                                   
                                     double
                                    
                                    confidence;
                                   
                                     const
                                    
                                     double
                                    
                                    x = my_unwarped_x();
                                   
                                     const
                                    
                                     double
                                    
                                    y = my_unwarped_y();
                                   
                                     const
                                    
                                     double
                                    
                                    value =
                                    
                                     cpl_image_get_interpolated
                                    
                                    (warped, x, y,
                                   
                                    xyprofile, xyradius,
                                   
                                    xyprofile, xyradius,
                                   
                                    &confidence);
                                   
                                     if
                                    
                                    (confidence > 0)
                                   
                                     cpl_image_set
                                    
                                    (unwarped, iu, iv, value);
                                   
                                     cpl_image_reject
                                    
                                    (unwarped, iu, iv);
                                   
                                     cpl_vector_delete
                                    
                                    (xyprofile);

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 xradius, xprofile, yprofile and yradius are not as requested
CPL_ERROR_INVALID_TYPE if the passed image type is not supported

References cpl_ensure , cpl_error_get_code() , CPL_ERROR_ILLEGAL_INPUT , CPL_ERROR_INVALID_TYPE , CPL_ERROR_NULL_INPUT , cpl_image_get_size_x() , cpl_image_get_size_y() , cpl_mask_get_data_const() , CPL_TYPE_DOUBLE , CPL_TYPE_FLOAT , CPL_TYPE_INT , cpl_vector_get_data_const() , and cpl_vector_get_size() .

Returns: The median of the non-bad pixels

See also: cpl_image_get_mad_window()

Possible _cpl_error_code_ set in this function:

CPL_ERROR_NULL_INPUT if an input pointer is NULL
CPL_ERROR_INVALID_TYPE if the passed image type is not supported
CPL_ERROR_DATA_NOT_FOUND if all the pixels are bad in the image

References cpl_ensure_code , CPL_ERROR_NULL_INPUT , cpl_stats_get_mad() , cpl_stats_get_median() , and CPL_STATS_MAD .

Returns: The median of the non-bad pixels

See also: cpl_image_get_median_window() , CPL_MATH_STD_MAD

For each non-bad pixel in the window the absolute deviation from the median is computed. The median of these absolute deviations in returned via sigma, while the median itself is returned by the function.

If the pixels are gaussian, the computed sigma is a robust and consistent estimate of the standard deviation in the sense that the standard deviation is approximately k * MAD, where k is a constant equal to approximately 1.4826. CPL defines CPL_MATH_STD_MAD as this scaling constant.

Images can be CPL_TYPE_FLOAT, CPL_TYPE_INT or CPL_TYPE_DOUBLE. On error the _cpl_error_code_ code is set and the return value is undefined.

Possible _cpl_error_code_ set in this function:

CPL_ERROR_NULL_INPUT if an input pointer is NULL
CPL_ERROR_INVALID_TYPE if the passed image type is not supported
CPL_ERROR_ILLEGAL_INPUT if the specified window is illegal
CPL_ERROR_DATA_NOT_FOUND if all the pixels are bad in the image window

References cpl_ensure_code , CPL_ERROR_NULL_INPUT , cpl_stats_get_mad() , cpl_stats_get_median() , and CPL_STATS_MAD .

Returns: the maximum value

See also: cpl_image_get_min_window()

See also: cpl_image_get_minpos()

References cpl_ensure_code , CPL_ERROR_NONE , CPL_ERROR_NULL_INPUT , cpl_stats_get_max_x() , cpl_stats_get_max_y() , and CPL_STATS_MAXPOS .

Referenced by cpl_fit_image_gaussian() .

Returns: CPL_ERROR_NONE or the _cpl_error_code_ on error

See also: cpl_image_get_minpos_window()

References cpl_ensure_code , CPL_ERROR_NONE , CPL_ERROR_NULL_INPUT , cpl_stats_get_max_x() , cpl_stats_get_max_y() , and CPL_STATS_MAXPOS .

Returns: the mean value

See also: cpl_image_get_min_window()

Returns: the median value

See also: cpl_image_get_median_window()

In case of error, the _cpl_error_code_ code is set, and the returned double is undefined. Images can be CPL_TYPE_FLOAT, CPL_TYPE_INT or CPL_TYPE_DOUBLE.

Possible _cpl_error_code_ set in this function:

CPL_ERROR_NULL_INPUT if an input pointer is NULL

Referenced by cpl_fit_image_gaussian() .

Returns: The median of the non-bad pixels

See also: cpl_image_get_median_dev_window()

Possible _cpl_error_code_ set in this function:

CPL_ERROR_NULL_INPUT if an input pointer is NULL
CPL_ERROR_INVALID_TYPE if the passed image type is not supported
CPL_ERROR_DATA_NOT_FOUND if all the pixels are bad in the image

References cpl_ensure_code , CPL_ERROR_NULL_INPUT , cpl_stats_get_median() , cpl_stats_get_median_dev() , and CPL_STATS_MEDIAN_DEV .

Referenced by cpl_apertures_extract_sigma() .

Returns: The median of the non-bad pixels

See also: cpl_image_get_mad_window()

For each non-bad pixel in the window the absolute deviation from the median is computed. The mean of these absolute deviations in returned via sigma, while the median itself is returned by the function. The computed median and sigma may be a robust estimate of the mean and standard deviation of the pixels. The sigma is however still sensitive to outliers. See cpl_image_get_mad_window() for a more robust estimator.

Images can be CPL_TYPE_FLOAT, CPL_TYPE_INT or CPL_TYPE_DOUBLE. On error the _cpl_error_code_ code is set and the return value is undefined.

Possible _cpl_error_code_ set in this function:

CPL_ERROR_NULL_INPUT if an input pointer is NULL
CPL_ERROR_INVALID_TYPE if the passed image type is not supported
CPL_ERROR_ILLEGAL_INPUT if the specified window is illegal
CPL_ERROR_DATA_NOT_FOUND if all the pixels are bad in the image window

References cpl_ensure_code , CPL_ERROR_NULL_INPUT , cpl_stats_get_median() , cpl_stats_get_median_dev() , and CPL_STATS_MEDIAN_DEV .

Returns: The median value, or undefined on error

The specified bounds are included in the specified region.

In case of error, the _cpl_error_code_ code is set, and the returned value is undefined. Images can be CPL_TYPE_FLOAT, CPL_TYPE_INT or CPL_TYPE_DOUBLE.

For a finite population or sample, the median is the middle value of an odd number of values (arranged in ascending order) or any value between the two middle values of an even number of values. For an even number of elements in the array, the mean of the two central values is returned. Note that in this case, the median might not belong to the input array.

Possible _cpl_error_code_ set in this function:

CPL_ERROR_NULL_INPUT if an input pointer is NULL
CPL_ERROR_ILLEGAL_INPUT if the window is outside the image or if there are only bad pixels in the window
CPL_ERROR_INVALID_TYPE if the passed image type is not supported

Returns: the minimum value

See also: cpl_image_get_min_window()

In case of error, the _cpl_error_code_ code is set, and the returned double is undefined. Images can be CPL_TYPE_FLOAT, CPL_TYPE_INT or CPL_TYPE_DOUBLE.

Possible _cpl_error_code_ set in this function:

CPL_ERROR_NULL_INPUT if an input pointer is NULL

Referenced by cpl_plot_image() .

Returns: the minimum value, or undefined on error

See also: cpl_stats_new_from_window()

Note: In case of error, the _cpl_error_code_ code is set.

The specified bounds are included in the specified region.

Images can be CPL_TYPE_FLOAT, CPL_TYPE_INT or CPL_TYPE_DOUBLE.

Possible _cpl_error_code_ set in this function:

CPL_ERROR_NULL_INPUT if an input pointer is NULL

Returns: CPL_ERROR_NONE or the _cpl_error_code_ on error

See also: cpl_image_get_minpos_window()

Images can be CPL_TYPE_FLOAT, CPL_TYPE_INT or CPL_TYPE_DOUBLE.

Possible _cpl_error_code_ set in this function:

CPL_ERROR_NULL_INPUT if an input pointer is NULL

References cpl_ensure_code , CPL_ERROR_NONE , CPL_ERROR_NULL_INPUT , cpl_stats_get_min_x() , cpl_stats_get_min_y() , and CPL_STATS_MINPOS .

Referenced by cpl_fit_image_gaussian() .

Returns: CPL_ERROR_NONE or the _cpl_error_code_ on error

See also: cpl_image_get_min_window()

The specified bounds are included in the specified region.

Images can be CPL_TYPE_FLOAT, CPL_TYPE_INT or CPL_TYPE_DOUBLE.

Possible _cpl_error_code_ set in this function:

CPL_ERROR_NULL_INPUT if an input pointer is NULL

References cpl_ensure_code , CPL_ERROR_NONE , CPL_ERROR_NULL_INPUT , cpl_stats_get_min_x() , cpl_stats_get_min_y() , and CPL_STATS_MINPOS .

Returns: The image x size, or -1 on NULL input

Possible _cpl_error_code_ set in this function:

CPL_ERROR_NULL_INPUT if an input pointer is NULL

References cpl_ensure , and CPL_ERROR_NULL_INPUT .

Referenced by cpl_detector_interpolate_rejected() , cpl_fit_image_gaussian() , cpl_fit_imagelist_polynomial() , cpl_fit_imagelist_polynomial_window() , cpl_flux_get_noise_ring() , cpl_geom_img_offset_fine() , cpl_geom_img_offset_saa() , cpl_image_collapse_create() , cpl_image_copy() , cpl_image_fill_jacobian() , cpl_image_fill_jacobian_polynomial() , cpl_image_filter() , cpl_image_filter_mask() , cpl_image_get_interpolated() , cpl_image_iqe() , cpl_image_new_from_accepted() , cpl_image_rebin() , cpl_image_warp() , cpl_imagelist_collapse_median_create() , cpl_imagelist_collapse_minmax_create() , cpl_imagelist_collapse_sigclip_create() , cpl_imagelist_is_uniform() , cpl_imagelist_set() , cpl_imagelist_swap_axis_create() , cpl_mask_threshold_image() , cpl_mask_threshold_image_create() , cpl_plot_image() , cpl_plot_image_col() , cpl_plot_image_row() , and cpl_test_get_bytes_image() .

Returns: The image y size, or -1 on NULL input

Possible _cpl_error_code_ set in this function:

CPL_ERROR_NULL_INPUT if an input pointer is NULL

References cpl_ensure , and CPL_ERROR_NULL_INPUT .

Referenced by cpl_detector_interpolate_rejected() , cpl_fit_image_gaussian() , cpl_fit_imagelist_polynomial() , cpl_fit_imagelist_polynomial_window() , cpl_flux_get_noise_ring() , cpl_geom_img_offset_fine() , cpl_geom_img_offset_saa() , cpl_image_collapse_create() , cpl_image_copy() , cpl_image_fill_jacobian() , cpl_image_fill_jacobian_polynomial() , cpl_image_filter() , cpl_image_filter_mask() , cpl_image_get_interpolated() , cpl_image_iqe() , cpl_image_new_from_accepted() , cpl_image_warp() , cpl_imagelist_collapse_median_create() , cpl_imagelist_collapse_minmax_create() , cpl_imagelist_collapse_sigclip_create() , cpl_imagelist_is_uniform() , cpl_imagelist_set() , cpl_imagelist_swap_axis_create() , cpl_mask_threshold_image() , cpl_mask_threshold_image_create() , cpl_plot_image() , cpl_plot_image_col() , cpl_plot_image_row() , and cpl_test_get_bytes_image() .

Returns: the square flux

See also: cpl_image_get_min_window()

Returns: the standard deviation value

See also: cpl_image_get_min_window()

Referenced by cpl_flux_get_noise_ring() .

Returns: The image type or CPL_TYPE_INVALID on NULL input.

Possible _cpl_error_code_ set in this function:

CPL_ERROR_NULL_INPUT if an input pointer is NULL

References cpl_ensure , CPL_ERROR_NULL_INPUT , and CPL_TYPE_INVALID .

Referenced by cpl_detector_interpolate_rejected() , cpl_fit_image_gaussian() , cpl_geom_img_offset_fine() , cpl_geom_img_offset_saa() , cpl_image_add_scalar() , cpl_image_and() , cpl_image_and_scalar() , cpl_image_collapse_window_create() , cpl_image_copy() , cpl_image_divide_scalar() , cpl_image_exponential() , cpl_image_fill_jacobian() , cpl_image_fill_jacobian_polynomial() , cpl_image_filter() , cpl_image_filter_mask() , cpl_image_fit_gaussian() , cpl_image_hypot() , cpl_image_logarithm() , cpl_image_multiply_scalar() , cpl_image_not() , cpl_image_or() , cpl_image_or_scalar() , cpl_image_power() , cpl_image_reject_value() , cpl_image_subtract_scalar() , cpl_image_warp() , cpl_image_xor() , cpl_image_xor_scalar() , cpl_imagelist_cast() , cpl_imagelist_collapse_median_create() , cpl_imagelist_collapse_minmax_create() , cpl_imagelist_collapse_sigclip_create() , cpl_imagelist_is_uniform() , cpl_imagelist_set() , cpl_imagelist_swap_axis_create() , cpl_mask_threshold_image() , cpl_plot_image() , cpl_plot_image_col() , cpl_plot_image_row() , and cpl_test_get_bytes_image() .

Returns: CPL_ERROR_NONE or the relevant the _cpl_error_code_ on error

The Euclidean distance function is useful for gaussian error propagation on addition/subtraction operations.

For pixel values a and b the Euclidean distance c is defined as: $$c = sqrt{a^2 + b^2}$$

first may be NULL, in this case the distance is computed in-place on self using second as the other operand.

Images can be of type CPL_TYPE_FLOAT or CPL_TYPE_DOUBLE.

If both input operands are of type CPL_TYPE_FLOAT the distance is computed in single precision (using hypotf()), otherwise in double precision (using hypot()).

Possible _cpl_error_code_ set in this function:

CPL_ERROR_NULL_INPUT if an input pointer is NULL
CPL_ERROR_INCOMPATIBLE_INPUT if the images have different sizes
CPL_ERROR_INVALID_TYPE if the passed image type is not supported

References cpl_ensure_code , CPL_ERROR_INCOMPATIBLE_INPUT , CPL_ERROR_INVALID_TYPE , CPL_ERROR_NONE , CPL_ERROR_NULL_INPUT , cpl_image_get_type() , CPL_TYPE_DOUBLE , CPL_TYPE_FLOAT , and cpl_type_get_name() .

Returns: a newly allocated cpl_bivector containing the results or NULL in error case.

This function makes internal use of the iqe() MIDAS function (called here cpl_iqe()) written by P. Grosbol. Refer to the MIDAS documentation for more details. This function has proven to give good results over the years when called from RTD. The goal is to provide the exact same functionality in CPL as the one provided in RTD. The code is simply copied from the MIDAS package, it is not maintained by the CPL team.

The returned object must be deallocated with cpl_bivector_delete() . It contains in the first vector the computed values, and in the second one, the associated errors. The computed values are:

x position of the object
y position of the object
FWHM along the major axis
FWHM along the minor axis
the angle of the major axis with the horizontal in degrees
the peak value of the object
the background computed

The bad pixels map of the image is not taken into account. The input image must be of type float.

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 the specified zone is not valid or if the computation fails on this zone
CPL_ERROR_INVALID_TYPE if the input image has the wrong type

Note: This function may lead to a strong underestimation of the sigmas and FWHMs (up to 25% underestimation in the case of noiseless data with a box 4 times the sigma, 1% underestimation in the case of noiseless data with a box 7 times the sigma).

References cpl_bivector_get_x_data() , cpl_bivector_get_y_data() , cpl_bivector_new() , cpl_ensure , CPL_ERROR_ILLEGAL_INPUT , CPL_ERROR_INVALID_TYPE , CPL_ERROR_NULL_INPUT , cpl_image_delete() , cpl_image_extract() , cpl_image_get_data_float() , cpl_image_get_size_x() , cpl_image_get_size_y() , and CPL_TYPE_FLOAT .

Referenced by cpl_image_fit_gaussian() .

Returns: 1 if the pixel is bad, 0 if the pixel is good, negative on error.

Possible _cpl_error_code_ set in this function:

CPL_ERROR_NULL_INPUT if an input pointer is NULL
CPL_ERROR_ACCESS_OUT_OF_RANGE if the specified position is out of the image

References cpl_ensure , CPL_ERROR_ACCESS_OUT_OF_RANGE , CPL_ERROR_NULL_INPUT , and cpl_mask_get() .

Returns: A newly allocated label image or NULL on error

This function labelises all blobs in a mask. All 4-neighbour connected zones set to 1 in the input mask will end up in the returned integer image as zones where all pixels are set to the same (unique for this blob in this image) label. A non-recursive flood-fill is applied to label the zones. The flood-fill is dimensioned by the number of lines in the image, and the maximal number of lines possibly covered by a blob. The returned image must be deallocated with cpl_image_delete()

Possible _cpl_error_code_ set in this function:

CPL_ERROR_NULL_INPUT if the input mask is NULL

References cpl_ensure , CPL_ERROR_NULL_INPUT , cpl_free() , cpl_image_get_data_int() , cpl_image_new() , cpl_malloc() , cpl_mask_get_data_const() , cpl_mask_get_size_x() , cpl_mask_get_size_y() , and CPL_TYPE_INT .

Referenced by cpl_apertures_extract_mask() .

Returns: 1 newly allocated image or NULL on error

This function loads an image from a FITS file (NAXIS=2 or 3).

The returned image has to be deallocated with cpl_image_delete() .

The passed type for the output image can be : CPL_TYPE_FLOAT, CPL_TYPE_DOUBLE or CPL_TYPE_INT.

This type is there to specify the type of the cpl_image that will be created by the function. It is totally independant from the way the data are stored in the FITS file. A FITS image containg float pixels can be loaded as a cpl_image of type double. In this case, the user would specify CPL_TYPE_DOUBLE as im_type.

Additionally, CPL_TYPE_UNSPECIFIED can be passed to inherit the FITS file type. The type of the image is defined based on the BITPIX information of the FITS file. After a successful call, the type of the created image can be accessed via cpl_image_get_type() .

'xtnum' specifies from which extension the image should be loaded. This could be 0 for the main data section (files without extension), or any number between 1 and N, where N is the number of extensions present in the file.

The requested plane number runs from 0 to nplanes-1, where nplanes is the number of planes present in the requested data section.

The created image has an empty bad pixel map.

Examples:

                                                       
                                                        // Load as a float image the only image in FITS file (a.fits) without ext.
                                                       
                                                        // and NAXIS=2.
                                                       
                                                       cpl_image * im =
                                                       
                                                        cpl_image_load
                                                       
                                                       (
                                                       
                                                        "a.fits"
                                                       
                                                       ,
                                                       
                                                        CPL_TYPE_FLOAT
                                                       
                                                       , 0, 0);
                                                      
                                                        // Load as a double image the first plane in a FITS cube (a.fits) without
                                                       
                                                        // extension, NAXIS=3 and NAXIS3=128
                                                       
                                                       cpl_image * im =
                                                       
                                                        cpl_image_load
                                                       
                                                       (
                                                       
                                                        "a.fits"
                                                       
                                                       ,
                                                       
                                                        CPL_TYPE_DOUBLE
                                                       
                                                       , 0, 0);
                                                      
                                                        // Load as an integer image the third plane in a FITS cube (a.fits) without
                                                       
                                                        // extension, NAXIS=3 and NAXIS3=128
                                                       
                                                       cpl_image * im =
                                                       
                                                        cpl_image_load
                                                       
                                                       (
                                                       
                                                        "a.fits"
                                                       
                                                       ,
                                                       
                                                        CPL_TYPE_INT
                                                       
                                                       , 2, 0);
                                                      
                                                        // Load as a double image the first plane from extension 5
                                                       
                                                       cpl_image * im =
                                                       
                                                        cpl_image_load
                                                       
                                                       (
                                                       
                                                        "a.fits"
                                                       
                                                       ,
                                                       
                                                        CPL_TYPE_DOUBLE
                                                       
                                                       , 0, 5);
                                                      
                                                        // Load as a double image the third plane in extension 5
                                                       
                                                       cpl_image * im =
                                                       
                                                        cpl_image_load
                                                       
                                                       (
                                                       
                                                        "a.fits"
                                                       
                                                       ,
                                                       
                                                        CPL_TYPE_DOUBLE
                                                       
                                                       , 2, 5);

Possible _cpl_error_code_ set in this function:

CPL_ERROR_NULL_INPUT if an input pointer is NULL
CPL_ERROR_ILLEGAL_INPUT if the passed extension number is negative
CPL_ERROR_FILE_IO if the file cannot be opened or does not exist
CPL_ERROR_DATA_NOT_FOUND if the specified extension has no image data
CPL_ERROR_BAD_FILE_FORMAT if the data cannot be loaded from the file including attempting to read beyond EOF
CPL_ERROR_INVALID_TYPE if the requested pixel type is not supported

Returns: 1 newly allocated image or NULL on error

See also: cpl_image_load()

Possible _cpl_error_code_ set in this function:

CPL_ERROR_NULL_INPUT if an input pointer is NULL
CPL_ERROR_ILLEGAL_INPUT if the passed extension number is negative or the window position is invalid
CPL_ERROR_FILE_IO if the file cannot be opened or does not exist
CPL_ERROR_DATA_NOT_FOUND if the specified extension has no image data
CPL_ERROR_BAD_FILE_FORMAT if the data cannot be loaded from the file including attempting to read beyond EOF
CPL_ERROR_INVALID_TYPE if the requested pixel type is not supported

Returns: CPL_ERROR_NONE or the relevant the _cpl_error_code_ on error

Modifies the image by computing the base-scalar logarithm of each of its pixels.

Images can be of type CPL_TYPE_INT, CPL_TYPE_FLOAT or CPL_TYPE_DOUBLE.

Pixels for which the logarithm is not defined are rejected and set to zero.

Possible _cpl_error_code_ set in this function:

CPL_ERROR_NULL_INPUT if an input pointer is NULL
CPL_ERROR_INVALID_TYPE if the passed image type is not supported
CPL_ERROR_ILLEGAL_INPUT if base is non-positive
CPL_ERROR_DIVISION_BY_ZERO if the base equals 1

References cpl_ensure_code , CPL_ERROR_INVALID_TYPE , CPL_ERROR_NONE , CPL_ERROR_NULL_INPUT , cpl_image_get_type() , CPL_TYPE_DOUBLE , CPL_TYPE_FLOAT , cpl_type_get_name() , and CPL_TYPE_INT .

Referenced by cpl_image_logarithm_create() , and cpl_imagelist_logarithm() .

Returns: the _cpl_error_code_ or CPL_ERROR_NONE

Note: The permutation array must contain nb_cut-squared elements

nb_cut^2 defines in how many tiles the images will be permuted. Each tile will then be moved to another place defined in new_pos. nb_cut equal 1 will leave the image unchanged, 2 is used to permute the four image quadrants, etc.. new_pos contains nb_cut^2 values between 1 and nb_cut^2, i.e. a permutation of the values from 1 to nb_cut^2. The zone positions are counted from the lower left part of the image. It is not allowed to move two tiles to the same position (the relation between th new tiles positions and the initial position is bijective !). The array with the permuted positions must contain nb_cut^2 values, the function is unable to verify this.

The image x and y sizes have to be multiples of nb_cut.

Example:
16   17   18           6    5    4
13   14   15           3    2    1
10   11   12   ---->  12   11   10
 7    8    9           9    8    7
 4    5    6          18   17   16
 1    2    3          15   14   13
 image 3x6            cpl_image_move(image, 3, new_pos);
                      with new_pos = {9,8,7,6,5,4,3,2,1};

The bad pixels are moved in the same way.

Possible _cpl_error_code_ set in this function:

CPL_ERROR_NULL_INPUT if an input pointer is NULL
CPL_ERROR_ILLEGAL_INPUT if nb_cut is not strictly positive or cannot divide one of the image sizes or if the new_pos array does not contain a permutation of the values from 1 through nb_cut squared.
CPL_ERROR_INVALID_TYPE if the passed image type is not supported

References cpl_ensure_code , CPL_ERROR_ILLEGAL_INPUT , CPL_ERROR_INVALID_TYPE , CPL_ERROR_NONE , CPL_ERROR_NULL_INPUT , cpl_free() , cpl_malloc() , and cpl_mask_move() .

Referenced by cpl_image_fft() .

Returns: CPL_ERROR_NONE or the relevant the _cpl_error_code_ on error

See also: cpl_image_add_scalar()

References cpl_ensure_code , CPL_ERROR_INVALID_TYPE , CPL_ERROR_NONE , CPL_ERROR_NULL_INPUT , and cpl_image_get_type() .

Referenced by cpl_image_fill_test_create() , cpl_image_multiply_scalar_create() , cpl_imagelist_multiply_scalar() , and cpl_plot_image() .

Returns: 1 newly allocated image or NULL in case of an error

See also: cpl_image_multiply_scalar

References cpl_ensure , cpl_error_get_code() , cpl_image_delete() , cpl_image_duplicate() , and cpl_image_multiply_scalar() .

Returns: 1 newly allocated cpl_image or NULL in case of an error

Allocates space for the cpl_image structure and sets the dimensions and type of pixel data. The pixel buffer is allocated and initialised to zero. The pixel array will contain nx*ny values being the image pixels from the lower left to the upper right line by line.

Supported pixel types are CPL_TYPE_INT, CPL_TYPE_FLOAT, CPL_TYPE_DOUBLE, CPL_TYPE_FLOAT_COMPLEX and CPL_TYPE_DOUBLE_COMPLEX.

The returned cpl_image must be deallocated using cpl_image_delete() .

Possible _cpl_error_code_ set in this function:

CPL_ERROR_ILLEGAL_INPUT if nx or ny is non-positive
CPL_ERROR_INVALID_TYPE if the passed pixel type is not supported

Referenced by cpl_geom_img_offset_fine() , cpl_geom_img_offset_saa() , cpl_image_fill_jacobian() , cpl_image_fill_test_create() , cpl_image_filter_linear() , cpl_image_filter_median() , cpl_image_filter_morpho() , cpl_image_filter_stdev() , cpl_image_labelise_mask_create() , and cpl_image_new_from_accepted() .

Returns: 1 newly allocated cpl_image or NULL on error

The created image is of type CPL_TYPE_INT.

Possible _cpl_error_code_ set in this function:

CPL_ERROR_NULL_INPUT if an input pointer is NULL

References cpl_ensure , CPL_ERROR_NULL_INPUT , cpl_image_wrap_int() , cpl_malloc() , cpl_mask_get_data_const() , cpl_mask_get_size_x() , and cpl_mask_get_size_y() .

Referenced by cpl_geom_img_offset_saa() .

Returns: CPL_ERROR_NONE, or the relevant _cpl_error_code_ on error.

Normalises an image according to a given criterion.

Possible normalisations are:

CPL_NORM_SCALE sets the pixel interval to [0,1].
CPL_NORM_MEAN sets the mean value to 1.
CPL_NORM_FLUX sets the flux to 1.
CPL_NORM_ABSFLUX sets the absolute flux to 1.

Possible _cpl_error_code_ set in this function:

CPL_ERROR_NULL_INPUT if an input pointer is NULL

References cpl_ensure_code , cpl_error_get_code() , CPL_ERROR_INVALID_TYPE , CPL_ERROR_NONE , CPL_ERROR_NULL_INPUT , cpl_image_divide_scalar() , cpl_image_get_absflux() , cpl_image_get_flux() , cpl_image_get_mean() , cpl_image_subtract_scalar() , cpl_stats_get_max() , cpl_stats_get_min() , CPL_STATS_MAX , and CPL_STATS_MIN .

Referenced by cpl_image_normalise_create() , and cpl_imagelist_normalise() .

Returns: 1 newly allocated image or NULL on error

See also: cpl_image_normalise

Stores the result in a newly allocated image and returns it. The returned image must be deallocated using cpl_image_delete() .

CPL_ERROR_NULL_INPUT if an input pointer is NULL

References cpl_ensure , CPL_ERROR_NULL_INPUT , cpl_image_delete() , cpl_image_duplicate() , and cpl_image_normalise() .

Returns: CPL_ERROR_NONE or the relevant the _cpl_error_code_ on error

Note: CPL_TYPE_INT is required

See also: cpl_mask_not() for the equivalent logical operation

Possible _cpl_error_code_ set in this function:

CPL_ERROR_NULL_INPUT if an input pointer is NULL
CPL_ERROR_INCOMPATIBLE_INPUT if the images have different sizes
CPL_ERROR_INVALID_TYPE if the passed image type is as required

Returns: CPL_ERROR_NONE or the relevant the _cpl_error_code_ on error

Note: CPL_TYPE_INT is required

See also: cpl_mask_or() for the equivalent logical operation

Possible _cpl_error_code_ set in this function:

CPL_ERROR_NULL_INPUT if an input pointer is NULL
CPL_ERROR_INCOMPATIBLE_INPUT if the images have different sizes
CPL_ERROR_INVALID_TYPE if the passed image type is as required

Returns: CPL_ERROR_NONE or the relevant the _cpl_error_code_ on error

Note: CPL_TYPE_INT is required

Possible _cpl_error_code_ set in this function:

CPL_ERROR_NULL_INPUT if an input pointer is NULL
CPL_ERROR_INCOMPATIBLE_INPUT if the images have different sizes
CPL_ERROR_INVALID_TYPE if the passed image type is as required

Returns: CPL_ERROR_NONE or the relevant the _cpl_error_code_ on error

Modifies the image by lifting each of its pixels to exponent.

Images can be of type CPL_TYPE_INT, CPL_TYPE_FLOAT or CPL_TYPE_DOUBLE.

Pixels for which the power to the given exponent is not defined are rejected and set to zero.

Possible _cpl_error_code_ set in this function:

CPL_ERROR_NULL_INPUT if an input pointer is NULL
CPL_ERROR_INVALID_TYPE if the passed image type is not supported

References cpl_ensure_code , CPL_ERROR_INVALID_TYPE , CPL_ERROR_NONE , CPL_ERROR_NULL_INPUT , cpl_image_get_type() , CPL_TYPE_DOUBLE , CPL_TYPE_FLOAT , cpl_type_get_name() , and CPL_TYPE_INT .

Referenced by cpl_image_power_create() , and cpl_imagelist_power() .

Returns: The newly allocated rebinned image or NULL in case of error

If both bin sizes in x and y are = 2, an image with (about) a quarter of the pixels of the input image will be created. Each new pixel will be the sum of the values of all contributing input pixels. If a bin is incomplete (i.e., the input image size is not a multiple of the bin sizes), it is not computed.

xstep and ystep must not be greater than the sizes of the rebinned region.

The input image type can be CPL_TYPE_INT, CPL_TYPE_FLOAT and CPL_TYPE_DOUBLE. If the image has bad pixels, they will be propagated to the rebinned image "pessimistically", i.e., if at least one of the contributing input pixels is bad, then the corresponding output pixel will also be flagged "bad". If you need an image of "weights" for each rebinned pixel, just cast the input image bpm into a CPL_TYPE_INT image, and apply cpl_image_rebin() to it too.

The returned image must be deallocated using cpl_image_delete() .

Possible _cpl_error_code_ set in this function:

CPL_ERROR_NULL_INPUT if the input pointer is NULL
CPL_ERROR_ILLEGAL_INPUT if xstep, ystep, xstart, ystart are not positive
CPL_ERROR_INVALID_TYPE if the passed image type is not supported

References cpl_ensure , CPL_ERROR_ILLEGAL_INPUT , CPL_ERROR_INVALID_TYPE , CPL_ERROR_NULL_INPUT , cpl_image_get_size_x() , cpl_mask_get_data() , cpl_mask_get_data_const() , and cpl_mask_new() .

Returns: the _cpl_error_code_ or CPL_ERROR_NONE

Possible _cpl_error_code_ set in this function:

CPL_ERROR_NULL_INPUT if an input pointer is NULL
CPL_ERROR_ACCESS_OUT_OF_RANGE if the specified position is out of the image

References cpl_ensure_code , CPL_ERROR_ACCESS_OUT_OF_RANGE , CPL_ERROR_NONE , and CPL_ERROR_NULL_INPUT .

Returns: the _cpl_error_code_ or CPL_ERROR_NONE

If the input image has a bad pixel map prior to the call, it is overwritten.

Possible _cpl_error_code_ set in this function:

CPL_ERROR_NULL_INPUT if the input image or the input map is NULL
CPL_ERROR_INCOMPATIBLE_INPUT if the image and the map have different sizes

References cpl_ensure_code , CPL_ERROR_INCOMPATIBLE_INPUT , CPL_ERROR_NONE , CPL_ERROR_NULL_INPUT , cpl_image_get_bpm() , cpl_mask_get_data() , cpl_mask_get_data_const() , cpl_mask_get_size_x() , and cpl_mask_get_size_y() .

Referenced by cpl_image_warp() , cpl_image_warp_polynomial() , and cpl_imagelist_swap_axis_create() .

Possible _cpl_error_code_ set in this function:

CPL_ERROR_NULL_INPUT if an input pointer is NULL
CPL_ERROR_INVALID_TYPE if mode is 1, e.g. due to a logical or (||) of the allowed options or if the pixel type is complex
CPL_ERROR_UNSUPPORTED_MODE if mode is otherwise different from the allowed options.

References CPL_ERROR_INVALID_TYPE , CPL_ERROR_NONE , CPL_ERROR_NULL_INPUT , cpl_image_get_type() , CPL_TYPE_DOUBLE , CPL_TYPE_DOUBLE_COMPLEX , CPL_TYPE_FLOAT , CPL_TYPE_FLOAT_COMPLEX , and CPL_TYPE_INT .

Returns: CPL_ERROR_NONE or the relevant _cpl_error_code_ on error

See also: cpl_propertylist_save()

This function saves an image to a FITS file. If a property list is provided, it is written to the header where the image is written. The image may be NULL, in this case only the propertylist is saved.

Supported image types are CPL_TYPE_DOUBLE, CPL_TYPE_FLOAT, CPL_TYPE_INT.

The type used in the file can be one of: CPL_TYPE_UCHAR (8 bit unsigned), CPL_TYPE_SHORT (16 bit signed), CPL_TYPE_USHORT (16 bit unsigned), CPL_TYPE_INT (32 bit signed), CPL_TYPE_FLOAT (32 bit floating point), or CPL_TYPE_DOUBLE (64 bit floating point). Additionally, the special value CPL_TYPE_UNSPECIFIED is allowed. This value means that the type used for saving is the pixel type of the input image. Using the image pixel type as saving type ensures that the saving incurs no loss of information.

Supported output modes are CPL_IO_CREATE (create a new file) and CPL_IO_EXTEND (append a new extension to an existing file).

Upon success the image will reside in a FITS data unit with NAXIS = 2. Is it possible to save a single image in a FITS data unit with NAXIS = 3, see cpl_imagelist_save() .

When the data written to disk are of an integer type, the output mode CPL_IO_EXTEND can be combined (via bit-wise or) with an option for tile-compression. This compression of integer data is lossless. The options are: CPL_IO_COMPRESS_GZIP, CPL_IO_COMPRESS_RICE, CPL_IO_COMPRESS_HCOMPRESS, CPL_IO_COMPRESS_PLIO. With compression the type must be CPL_TYPE_UNSPECIFIED or CPL_TYPE_INT.

Note that in append mode the file must be writable (and do not take for granted that a file is writable just because it was created by the same application, as this depends from the system umask ).

Possible _cpl_error_code_ set in this function:

CPL_ERROR_NULL_INPUT if an input pointer is NULL
CPL_ERROR_ILLEGAL_INPUT if the type or the mode is not supported
CPL_ERROR_INVALID_TYPE if the passed pixel type is not supported
CPL_ERROR_FILE_NOT_CREATED if the output file cannot be created
CPL_ERROR_FILE_IO if the data cannot be written to the file

References CPL_ERROR_NONE , and cpl_propertylist_save() .

Returns: CPL_ERROR_NONE or the relevant _cpl_error_code_ on error

Images can be CPL_TYPE_FLOAT, CPL_TYPE_INT, CPL_TYPE_DOUBLE.

If the pixel is flagged as rejected, this flag is removed.

Possible _cpl_error_code_ set in this function:

CPL_ERROR_NULL_INPUT if an input pointer is NULL
CPL_ERROR_ACCESS_OUT_OF_RANGE if the passed position is not in the image
CPL_ERROR_INVALID_TYPE if the image pixel type is not supported

References cpl_ensure_code , CPL_ERROR_ACCESS_OUT_OF_RANGE , CPL_ERROR_INVALID_TYPE , CPL_ERROR_NONE , CPL_ERROR_NULL_INPUT , and CPL_TYPE_COMPLEX .

Returns: A pointer to the old mask of bad pixels, or NULL

Note: NULL is returned if the image had no bad pixel map, while a non-NULL returned mask must be deallocated by the caller using cpl_mask_delete() .

See also: cpl_image_get_bpm_const()

Possible _cpl_error_code_ set in this function:

CPL_ERROR_NULL_INPUT if self is NULL

References cpl_ensure , and CPL_ERROR_NULL_INPUT .

Referenced by cpl_image_unset_bpm() .

Returns: CPL_ERROR_NONE or the relevant _cpl_error_code_ on error

See also: cpl_image_set()

Note: This function is available iff the application includes complex.h

Images can be CPL_TYPE_FLOAT_COMPLEX or CPL_TYPE_DOUBLE_COMPLEX.

If the pixel is flagged as rejected, this flag is removed.

Possible _cpl_error_code_ set in this function:

CPL_ERROR_NULL_INPUT if an input pointer is NULL
CPL_ERROR_ACCESS_OUT_OF_RANGE if the passed position is not in the image
CPL_ERROR_INVALID_TYPE if the image pixel type is not supported

References cpl_ensure_code , CPL_ERROR_ACCESS_OUT_OF_RANGE , CPL_ERROR_NONE , CPL_ERROR_NULL_INPUT , and CPL_TYPE_FLOAT_COMPLEX .

Returns: the _cpl_error_code_ or CPL_ERROR_NONE

The new zones (in the result image) where no new value is computed are set to 0 and flagged as bad pixels. The shift values have to be valid: -nx < dx < nx and -ny < dy < ny

Possible _cpl_error_code_ set in this function:

CPL_ERROR_NULL_INPUT if an input pointer is NULL
CPL_ERROR_ILLEGAL_INPUT if the requested shift is bigger than the image size

References cpl_ensure_code , CPL_ERROR_NONE , CPL_ERROR_NULL_INPUT , cpl_mask_new() , cpl_mask_shift() , and cpl_type_get_sizeof() .

Returns: CPL_ERROR_NONE or the relevant the _cpl_error_code_ on error

See also: cpl_image_add_scalar()

References cpl_ensure_code , CPL_ERROR_INVALID_TYPE , CPL_ERROR_NONE , CPL_ERROR_NULL_INPUT , and cpl_image_get_type() .

Referenced by cpl_image_normalise() , cpl_image_subtract_scalar_create() , cpl_imagelist_subtract_scalar() , and cpl_plot_image() .

Returns: 1 newly allocated image or NULL in case of an error

See also: cpl_image_subtract_scalar

References cpl_ensure , cpl_error_get_code() , cpl_image_delete() , cpl_image_duplicate() , and cpl_image_subtract_scalar() .

Referenced by cpl_plot_image() .

Returns: the _cpl_error_code_ or CPL_ERROR_NONE

Pixels outside of the provided interval are assigned the given values.

Use FLT_MIN and FLT_MAX for floating point images and DBL_MIN and DBL_MAX for double images for the lo_cut and hi_cut to avoid any pixel replacement.

Images can be of type CPL_TYPE_INT, CPL_TYPE_FLOAT or CPL_TYPE_DOUBLE. lo_cut must be smaller than or equal to hi_cut.

Possible _cpl_error_code_ set in this function:

CPL_ERROR_NULL_INPUT if an input pointer is NULL
CPL_ERROR_INVALID_TYPE if the passed image type is not supported
CPL_ERROR_ILLEGAL_INPUT if lo_cut is greater than hi_cut

References cpl_ensure_code , CPL_ERROR_ILLEGAL_INPUT , CPL_ERROR_INVALID_TYPE , CPL_ERROR_NONE , and CPL_ERROR_NULL_INPUT .

Referenced by cpl_imagelist_threshold() .

Returns: CPL_ERROR_NONE on success, otherwise the relevant _cpl_error_code_

Note: The dimension of a rectangular image is changed.

Images can be of type CPL_TYPE_INT, CPL_TYPE_FLOAT or CPL_TYPE_DOUBLE.

The definition of the rotation relies on the FITS convention: The lower left corner of the image is at (1,1), x increasing from left to right, y increasing from bottom to top.

For rotations of +90 or -90 degrees on rectangular non-1D-images, the pixel buffer is temporarily duplicated.

rot may be any integer value, its modulo 4 determines the rotation:

-3 to turn 270 degrees counterclockwise.
-2 to turn 180 degrees counterclockwise.
-1 to turn 90 degrees counterclockwise.
0 to not turn
+1 to turn 90 degrees clockwise (same as -3)
+2 to turn 180 degrees clockwise (same as -2).
+3 to turn 270 degrees clockwise (same as -1).

Possible _cpl_error_code_ set in this function:

CPL_ERROR_NULL_INPUT if an input pointer is NULL
CPL_ERROR_INVALID_TYPE if the passed image type is not supported

References cpl_ensure_code , CPL_ERROR_INVALID_TYPE , CPL_ERROR_NONE , CPL_ERROR_NULL_INPUT , and cpl_mask_turn() .

Returns: A pointer to the cpl_mask of bad pixels, or NULL

Note: NULL is returned if the image has no bad pixel map

See also: cpl_image_set_bpm()

Possible _cpl_error_code_ set in this function:

CPL_ERROR_NULL_INPUT if an input pointer is NULL

References cpl_ensure , CPL_ERROR_NULL_INPUT , and cpl_image_set_bpm() .

Referenced by cpl_image_accept_all() , cpl_imagelist_cast() , cpl_imagelist_empty() , cpl_imagelist_erase() , and cpl_imagelist_set() .

Returns: A pointer to the data array or NULL if the input is NULL.

Frees all memory associated to an cpl_image, except the pixel buffer. cpl_image_unwrap() is provided for images that are constructed by passing a pixel buffer to one of cpl_image_wrap_{double,float,int}().

Note: The pixel buffer must subsequently be deallocated. Failure to do so will result in a memory leak.

References cpl_free() , and cpl_mask_delete() .

Referenced by cpl_vector_cycle() , and cpl_vector_filter_median_create() .

Returns: CPL_ERROR_NONE or the relevant _cpl_error_code_ on error

See also: cpl_image_get_interpolated()

The pixel value at the (integer) position (u, v) in the destination image is interpolated from the (typically non-integer) pixel position (x, y) in the source image, where

x = u - deltax(u, v),

y = v - deltay(u, v).

The identity transform is thus given by deltax and deltay filled with zeros.

The first pixel is (1, 1), located in the lower left. 'out' and 'in' may have different sizes, while deltax and deltay must have the same size as 'out'. deltax and deltay must have pixel type CPL_TYPE_DOUBLE.

Beware that extreme transformations may lead to blank images.

'out' and 'in' may be of type CPL_TYPE_INT, CPL_TYPE_FLOAT or CPL_TYPE_DOUBLE.

Examples of profiles and radius are:

                                            xprofile =
                                            
                                             cpl_vector_new
                                            
                                            (CPL_KERNEL_DEF_SAMPLES);
                                           
                                             cpl_vector_fill_kernel_profile
                                            
                                            (profile, CPL_KERNEL_DEFAULT,
                                           
                                            CPL_KERNEL_DEF_WIDTH);
                                           
                                            xradius = CPL_KERNEL_DEF_WIDTH;

In case a correction for flux conservation were required, please create a correction map using the function cpl_image_fill_jacobian() .

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 the input images sizes are incompatible or if the delta images are not of type CPL_TYPE_DOUBLE
CPL_ERROR_INVALID_TYPE if the passed image type is not supported

References cpl_ensure_code , CPL_ERROR_ILLEGAL_INPUT , CPL_ERROR_INVALID_TYPE , CPL_ERROR_NONE , CPL_ERROR_NULL_INPUT , cpl_image_get_data_double_const() , cpl_image_get_size_x() , cpl_image_get_size_y() , cpl_image_get_type() , cpl_image_reject_from_mask() , cpl_mask_delete() , cpl_mask_get_data() , cpl_mask_get_data_const() , cpl_mask_new() , CPL_TYPE_DOUBLE , cpl_vector_get_data_const() , and cpl_vector_get_size() .

Returns: CPL_ERROR_NONE or the relevant _cpl_error_code_ on error

See also: cpl_image_get_interpolated()

'out' and 'in' may have different dimensions and types.

The pair of 2D polynomials are used internally like this

x = cpl_polynomial_eval (poly_x, (u, v));

y = cpl_polynomial_eval (poly_y, (u, v));

cpl_polynomial_eval

double cpl_polynomial_eval(const cpl_polynomial *self, const cpl_vector *x)

Evaluate the polynomial at the given point using Horner's rule.

Definition: cpl_polynomial.c:959

where (u,v) are (integer) pixel positions in the destination image and (x,y) are the corresponding pixel positions (typically non-integer) in the source image.

The identity transform (poly_x(u,v) = u, poly_y(u,v) = v) would thus overwrite the 'out' image with the 'in' image, starting from the lower left if the two images are of different sizes.

Beware that extreme transformations may lead to blank images.

The input image type may be CPL_TYPE_INT, CPL_TYPE_FLOAT or CPL_TYPE_DOUBLE.

In case a correction for flux conservation were required, please create a correction map using the function cpl_image_fill_jacobian_polynomial() .

Possible _cpl_error_code_ set in this function: