Loading...
Searching...
No Matches
Images

## Typedefs

typedef enum _cpl_value_ | cpl_value
| The CPL special value. It is a bit field.

## Enumerations

enum | _cpl_value_ { CPL_VALUE_NAN , CPL_VALUE_PLUSINF , CPL_VALUE_MINUSINF , CPL_VALUE_ZERO , CPL_VALUE_INF , CPL_VALUE_NOTFINITE }
| The special values that can be rejected They are a bit-field and can be combined with bitwise or. More...

## Functions

cpl_error_code | cpl_image_abs (cpl_image *image)
| Take the absolute value of an image.
cpl_image * | cpl_image_abs_create (const cpl_image *image_in)
| Take the absolute value of an image.
cpl_error_code | cpl_image_accept (cpl_image *im, cpl_size x, cpl_size y)
| Set a pixel as good in an image.
cpl_error_code | cpl_image_accept_all (cpl_image *self)
| Set all pixels in the image as good.
cpl_error_code | cpl_image_add (cpl_image *im1, const cpl_image *im2)
| Add two images, store the result in the first image.
cpl_image * | cpl_image_add_create (const cpl_image *image1, const cpl_image *image2)
| Add two images.
cpl_error_code | cpl_image_add_scalar (cpl_image *self, double scalar)
| Elementwise addition of a scalar to an image.
cpl_image * | cpl_image_add_scalar_create (const cpl_image *image, double addend)
| Create a new image by elementwise addition of a scalar to an image.
cpl_error_code | cpl_image_and (cpl_image *self, const cpl_image *first, const cpl_image *second)
| The bit-wise and of two images with integer pixels.
cpl_error_code | cpl_image_and_scalar (cpl_image *self, const cpl_image *first, cpl_bitmask second)
| The bit-wise and of a scalar and an image with integer pixels.
cpl_image * | cpl_image_average_create (const cpl_image *image_1, const cpl_image *image_2)
| Build the average of two images.
cpl_image * | cpl_image_cast (const cpl_image *self, cpl_type type)
| Convert a cpl_image to a given type.
cpl_image * | cpl_image_collapse_create (const cpl_image *self, int direction)
| Collapse an image along its rows or columns.
cpl_image * | cpl_image_collapse_median_create (const cpl_image *self, int direction, cpl_size drop_ll, cpl_size drop_ur)
| Collapse an image along its rows or columns, with filtering.
cpl_image * | cpl_image_collapse_window_create (const cpl_image *self, cpl_size llx, cpl_size lly, cpl_size urx, cpl_size ury, int direction)
| Collapse an image region along its rows or columns.
cpl_error_code | cpl_image_conjugate (cpl_image *self, const cpl_image *other)
| Complex conjugate the pixels in a complex image.
cpl_error_code | cpl_image_copy (cpl_image *im1, const cpl_image *im2, cpl_size xpos, cpl_size ypos)
| Copy one image into another.
cpl_size | cpl_image_count_rejected (const cpl_image *im)
| Count the number of bad pixels declared in an image.
void | cpl_image_delete (cpl_image *d)
| Free memory associated to an cpl_image object.
cpl_error_code | cpl_image_divide (cpl_image *im1, const cpl_image *im2)
| Divide two images, store the result in the first image.
cpl_image * | cpl_image_divide_create (const cpl_image *image1, const cpl_image *image2)
| Divide two images.
cpl_error_code | cpl_image_divide_scalar (cpl_image *self, double scalar)
| Elementwise division of an image with a scalar.
cpl_image * | cpl_image_divide_scalar_create (const cpl_image *image, double divisor)
| Create a new image by elementwise division of an image with a scalar.
cpl_error_code | cpl_image_dump_structure (const cpl_image *self, FILE *stream)
| Dump structural information of a CPL image.
cpl_error_code | cpl_image_dump_window (const cpl_image *self, cpl_size llx, cpl_size lly, cpl_size urx, cpl_size ury, FILE *stream)
| Dump pixel values in a CPL image.
cpl_image * | cpl_image_duplicate (const cpl_image *src)
| Copy an image.
cpl_error_code | cpl_image_exponential (cpl_image *self, double base)
| Compute the elementwise exponential of the image.
cpl_image * | cpl_image_exponential_create (const cpl_image *image, double base)
| Create a new image by elementwise exponentiation of an image.
cpl_image * | cpl_image_extract (const cpl_image *in, cpl_size llx, cpl_size lly, cpl_size urx, cpl_size ury)
| Extract a rectangular zone from an image into another image.
cpl_image * | cpl_image_extract_subsample (const cpl_image *image, cpl_size xstep, cpl_size ystep)
| Sub-sample an image.
cpl_error_code | cpl_image_fft (cpl_image *img_real, cpl_image *img_imag, unsigned mode)
| Fast Fourier Transform a square, power-of-two sized image.
cpl_error_code | cpl_image_fill_abs_arg (cpl_image *im_abs, cpl_image *im_arg, const cpl_image *self)
| Split a complex image into its absolute and argument part(s).
cpl_error_code | cpl_image_fill_gaussian (cpl_image *ima, double xcen, double ycen, double norm, double sig_x, double sig_y)
| Generate an image from a 2d gaussian function.
cpl_error_code | cpl_image_fill_jacobian (cpl_image *out, const cpl_image *deltax, const cpl_image *deltay)
| Compute area change ratio for a transformation map.
cpl_error_code | cpl_image_fill_jacobian_polynomial (cpl_image *out, const cpl_polynomial *poly_x, const cpl_polynomial *poly_y)
| Compute area change ratio for a 2D polynomial transformation.
cpl_error_code | cpl_image_fill_noise_uniform (cpl_image *ima, double min_pix, double max_pix)
| Generate an image with uniform random noise distribution.
cpl_error_code | cpl_image_fill_polynomial (cpl_image *ima, const cpl_polynomial *poly, double startx, double stepx, double starty, double stepy)
| Generate an image from a 2d polynomial function.
cpl_error_code | cpl_image_fill_re_im (cpl_image *im_real, cpl_image *im_imag, const cpl_image *self)
| Split a complex image into its real and/or imaginary part(s).
cpl_error_code | cpl_image_fill_rejected (cpl_image *im, double a)
| Set the bad pixels in an image to a fixed value.
cpl_image * | cpl_image_fill_test_create (cpl_size nx, cpl_size ny)
| Generate a test image with pixel type CPL_TYPE_DOUBLE.
cpl_error_code | cpl_image_fill_window (cpl_image *self, cpl_size llx, cpl_size lly, cpl_size urx, cpl_size ury, double value)
| Fill an image window with a constant.
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.
cpl_image * | cpl_image_filter_linear (const cpl_image *in, const cpl_matrix *ker)
| Compute a linear filtering.
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.
cpl_image * | cpl_image_filter_median (const cpl_image *in, const cpl_matrix *ker)
| Apply a spatial median filter to an image.
cpl_image * | cpl_image_filter_morpho (const cpl_image *in, const cpl_matrix *ker)
| Filter an image in spatial domain with a morpho kernel.
cpl_image * | cpl_image_filter_stdev (const cpl_image *in, const cpl_matrix *ker)
| Standard deviation filter.
cpl_error_code | cpl_image_fit_gaussian (const cpl_image *im, cpl_size xpos, cpl_size ypos, cpl_size size, double *norm, double *xcen, double *ycen, double *sig_x, double *sig_y, double *fwhm_x, double *fwhm_y)
| Apply a gaussian fit on an image sub window.
cpl_error_code | cpl_image_flip (cpl_image *im, int angle)
| Flip an image on a given mirror line.
double | cpl_image_get (const cpl_image *image, cpl_size xpos, cpl_size ypos, int *pis_rejected)
| Get the value of a pixel at a given position.
double | cpl_image_get_absflux (const cpl_image *image)
| Computes the sum of absolute values over an image.
double | cpl_image_get_absflux_window (const cpl_image *image, cpl_size llx, cpl_size lly, cpl_size urx, cpl_size ury)
| Computes the sum of absolute values over an image sub-window.
cpl_mask * | cpl_image_get_bpm (cpl_image *img)
| Gets the bad pixels map.
const cpl_mask * | cpl_image_get_bpm_const (const cpl_image *img)
| Gets the bad pixels map.
double | cpl_image_get_centroid_x (const cpl_image *image)
| Computes the x centroid value over the whole image.
double | cpl_image_get_centroid_x_window (const cpl_image *image, cpl_size llx, cpl_size lly, cpl_size urx, cpl_size ury)
| Computes the x centroid value over an image sub-window.
double | cpl_image_get_centroid_y (const cpl_image *image)
| Computes the y centroid value over the whole image.
double | cpl_image_get_centroid_y_window (const cpl_image *image, cpl_size llx, cpl_size lly, cpl_size urx, cpl_size ury)
| Computes the y centroid value over an image sub-window.
double complex | cpl_image_get_complex (const cpl_image *image, cpl_size xpos, cpl_size ypos, int *pis_rejected)
| Get the value of a complex pixel at a given position.
void * | cpl_image_get_data (cpl_image *img)
| Gets the pixel data.
const void * | cpl_image_get_data_const (const cpl_image *img)
| Gets the pixel data.
double * | cpl_image_get_data_double (cpl_image *img)
| Get the data as a double array.
double complex * | cpl_image_get_data_double_complex (cpl_image *img)
| Get the data as a double complex array.
const double complex * | cpl_image_get_data_double_complex_const (const cpl_image *img)
| Get the data as a double complex array.
const double * | cpl_image_get_data_double_const (const cpl_image *img)
| Get the data as a double array.
float * | cpl_image_get_data_float (cpl_image *img)
| Get the data as a float array.
float complex * | cpl_image_get_data_float_complex (cpl_image *img)
| Get the data as a float complex array.
const float complex * | cpl_image_get_data_float_complex_const (const cpl_image *img)
| Get the data as a float complex array.
const float * | cpl_image_get_data_float_const (const cpl_image *img)
| Get the data as a float array.
int * | cpl_image_get_data_int (cpl_image *img)
| Get the data as a integer array.
const int * | cpl_image_get_data_int_const (const cpl_image *img)
| Get the data as a integer array.
double | cpl_image_get_flux (const cpl_image *image)
| Computes the sum of pixel values over an image.
double | cpl_image_get_flux_window (const cpl_image *image, cpl_size llx, cpl_size lly, cpl_size urx, cpl_size ury)
| Computes the sum of pixel values over an image sub-window.
cpl_error_code | cpl_image_get_fwhm (const cpl_image *in, cpl_size xpos, cpl_size ypos, double *fwhm_x, double *fwhm_y)
| Compute FWHM values in x and y for an object.
double | cpl_image_get_interpolated (const cpl_image *source, double xpos, double ypos, const cpl_vector *xprofile, double xradius, const cpl_vector *yprofile, double yradius, double *pconfid)
| Interpolate a pixel from its neigbors.
double | cpl_image_get_mad (const cpl_image *image, double *sigma)
| Computes median and median absolute deviation (MAD) on an image.
double | cpl_image_get_mad_window (const cpl_image *image, cpl_size llx, cpl_size lly, cpl_size urx, cpl_size ury, double *sigma)
| Computes median and median absolute deviation (MAD) on an image window.
double | cpl_image_get_max (const cpl_image *image)
| computes maximum pixel value over an image.
double | cpl_image_get_max_window (const cpl_image *image, cpl_size llx, cpl_size lly, cpl_size urx, cpl_size ury)
| computes maximum pixel value over an image sub-window.
cpl_error_code | cpl_image_get_maxpos (const cpl_image *image, cpl_size *px, cpl_size *py)
| Computes maximum pixel value and position over an image.
cpl_error_code | cpl_image_get_maxpos_window (const cpl_image *image, cpl_size llx, cpl_size lly, cpl_size urx, cpl_size ury, cpl_size *px, cpl_size *py)
| Computes maximum pixel value and position over an image sub window.
double | cpl_image_get_mean (const cpl_image *image)
| computes mean pixel value over an image.
double | cpl_image_get_mean_window (const cpl_image *image, cpl_size llx, cpl_size lly, cpl_size urx, cpl_size ury)
| computes mean pixel value over an image sub-window.
double | cpl_image_get_median (const cpl_image *image)
| computes median pixel value over an image.
double | cpl_image_get_median_dev (const cpl_image *image, double *sigma)
| Computes median and mean absolute median deviation on an image window.
double | cpl_image_get_median_dev_window (const cpl_image *image, cpl_size llx, cpl_size lly, cpl_size urx, cpl_size ury, double *sigma)
| Computes median and mean absolute median deviation on an image window.
double | cpl_image_get_median_window (const cpl_image *image, cpl_size llx, cpl_size lly, cpl_size urx, cpl_size ury)
| computes median pixel value over an image sub-window.
double | cpl_image_get_min (const cpl_image *image)
| computes minimum pixel value over an image.
double | cpl_image_get_min_window (const cpl_image *image, cpl_size llx, cpl_size lly, cpl_size urx, cpl_size ury)
| computes minimum pixel value over an image sub-window.
cpl_error_code | cpl_image_get_minpos (const cpl_image *image, cpl_size *px, cpl_size *py)
| Computes minimum pixel value and position over an image.
cpl_error_code | cpl_image_get_minpos_window (const cpl_image *image, cpl_size llx, cpl_size lly, cpl_size urx, cpl_size ury, cpl_size *px, cpl_size *py)
| Computes minimum pixel value and position over an image sub window.
cpl_size | cpl_image_get_size_x (const cpl_image *img)
| Get the image x size.
cpl_size | cpl_image_get_size_y (const cpl_image *img)
| Get the image y size.
double | cpl_image_get_sqflux (const cpl_image *image)
| Computes the sum of squared values over an image.
double | cpl_image_get_sqflux_window (const cpl_image *image, cpl_size llx, cpl_size lly, cpl_size urx, cpl_size ury)
| Computes the sum of squared values over an image sub-window.
double | cpl_image_get_stdev (const cpl_image *image)
| computes pixel standard deviation over an image.
double | cpl_image_get_stdev_window (const cpl_image *image, cpl_size llx, cpl_size lly, cpl_size urx, cpl_size ury)
| computes pixel standard deviation over an image sub-window.
cpl_type | cpl_image_get_type (const cpl_image *img)
| Get the image type.
cpl_error_code | cpl_image_hypot (cpl_image *self, const cpl_image *first, const cpl_image *second)
| The pixel-wise Euclidean distance function of the images.
cpl_bivector * | cpl_image_iqe (const cpl_image *in, cpl_size llx, cpl_size lly, cpl_size urx, cpl_size ury)
| Compute an image quality estimation for an object.
int | cpl_image_is_rejected (const cpl_image *im, cpl_size x, cpl_size y)
| Test if a pixel is good or bad.
cpl_image * | cpl_image_labelise_mask_create (const cpl_mask *in, cpl_size *nbobjs)
| Labelise a mask to differentiate different objects.
cpl_image * | cpl_image_load (const char *filename, cpl_type im_type, cpl_size pnum, cpl_size xtnum)
| Load an image from a FITS file.
cpl_image * | cpl_image_load_window (const char *filename, cpl_type im_type, cpl_size pnum, cpl_size xtnum, cpl_size llx, cpl_size lly, cpl_size urx, cpl_size ury)
| Load an image from a FITS file.
cpl_error_code | cpl_image_logarithm (cpl_image *self, double base)
| Compute the elementwise logarithm of the image.
cpl_image * | cpl_image_logarithm_create (const cpl_image *image, double base)
| Create a new image by taking the elementwise logarithm of an image.
cpl_error_code | cpl_image_move (cpl_image *im, cpl_size nb_cut, const cpl_size *new_pos)
| Permute tiles in an image.
cpl_error_code | cpl_image_multiply (cpl_image *im1, const cpl_image *im2)
| Multiply two images, store the result in the first image.
cpl_image * | cpl_image_multiply_create (const cpl_image *image1, const cpl_image *image2)
| Multiply two images.
cpl_error_code | cpl_image_multiply_scalar (cpl_image *self, double scalar)
| Elementwise multiplication of an image with a scalar.
cpl_image * | cpl_image_multiply_scalar_create (const cpl_image *image, double factor)
| Create a new image by multiplication of a scalar and an image.
cpl_image * | cpl_image_new (cpl_size nx, cpl_size ny, cpl_type type)
| Allocate an image structure and pixel buffer for a image.
cpl_image * | cpl_image_new_from_mask (const cpl_mask *mask)
| Create an int image from a mask.
cpl_error_code | cpl_image_normalise (cpl_image *image, cpl_norm mode)
| Normalise pixels in an image.
cpl_image * | cpl_image_normalise_create (const cpl_image *image_in, cpl_norm mode)
| Create a new normalised image from an existing image.
cpl_error_code | cpl_image_not (cpl_image *self, const cpl_image *first)
| The bit-wise complement (not) of an image with integer pixels.
cpl_error_code | cpl_image_or (cpl_image *self, const cpl_image *first, const cpl_image *second)
| The bit-wise or of two images with integer pixels.
cpl_error_code | cpl_image_or_scalar (cpl_image *self, const cpl_image *first, cpl_bitmask second)
| The bit-wise or of a scalar and an image with integer pixels.
cpl_error_code | cpl_image_power (cpl_image *self, double exponent)
| Compute the elementwise power of the image.
cpl_image * | cpl_image_power_create (const cpl_image *image, double exponent)
| Create a new image by elementwise raising of an image to a power.
cpl_image * | cpl_image_rebin (const cpl_image *image, cpl_size xstart, cpl_size ystart, cpl_size xstep, cpl_size ystep)
| Rebin an image.
cpl_error_code | cpl_image_reject (cpl_image *im, cpl_size x, cpl_size y)
| Set a pixel as bad in an image.
cpl_error_code | cpl_image_reject_from_mask (cpl_image *im, const cpl_mask *map)
| Set the bad pixels in an image as defined in a mask.
cpl_error_code | cpl_image_reject_value (cpl_image *self, cpl_value mode)
| Reject pixels with the specified special value(s).
cpl_error_code | cpl_image_save (const cpl_image *self, const char *filename, cpl_type type, const cpl_propertylist *plist, unsigned mode)
| Save an image to a FITS file.
cpl_error_code | cpl_image_set (cpl_image *image, cpl_size xpos, cpl_size ypos, double value)
| Set the pixel at the given position to the given value.
cpl_mask * | cpl_image_set_bpm (cpl_image *self, cpl_mask *bpm)
| Replace the bad pixel map of the image.
cpl_error_code | cpl_image_set_complex (cpl_image *image, cpl_size xpos, cpl_size ypos, double complex value)
| Set the pixel at the given position to the given complex value.
cpl_error_code | cpl_image_shift (cpl_image *self, cpl_size dx, cpl_size dy)
| Shift an image by integer offsets.
cpl_error_code | cpl_image_subtract (cpl_image *im1, const cpl_image *im2)
| Subtract two images, store the result in the first image.
cpl_image * | cpl_image_subtract_create (const cpl_image *image1, const cpl_image *image2)
| Subtract two images.
cpl_error_code | cpl_image_subtract_scalar (cpl_image *self, double scalar)
| Elementwise subtraction of a scalar from an image.
cpl_image * | cpl_image_subtract_scalar_create (const cpl_image *image, double subtrahend)
| Create an image by elementwise subtraction of a scalar from an image.
cpl_error_code | cpl_image_threshold (cpl_image *image_in, double lo_cut, double hi_cut, double assign_lo_cut, double assign_hi_cut)
| Threshold an image to a given interval.
cpl_error_code | cpl_image_turn (cpl_image *self, int rot)
| Rotate an image by a multiple of 90 degrees clockwise.
cpl_mask * | cpl_image_unset_bpm (cpl_image *self)
| Remove the bad pixel map from the image.
void * | cpl_image_unwrap (cpl_image *d)
| Free memory associated to an cpl_image object, but the pixel buffer.
cpl_error_code | cpl_image_warp (cpl_image *out, const cpl_image *in, const cpl_image *deltax, const cpl_image *deltay, const cpl_vector *xprofile, double xradius, const cpl_vector *yprofile, double yradius)
| Warp an image.
cpl_error_code | cpl_image_warp_polynomial (cpl_image *out, const cpl_image *in, const cpl_polynomial *poly_x, const cpl_polynomial *poly_y, const cpl_vector *xprofile, double xradius, const cpl_vector *yprofile, double yradius)
| Warp an image according to a 2D polynomial transformation.
cpl_image * | cpl_image_wrap_double (cpl_size nx, cpl_size ny, double *pixels)
| Create a double image using an existing pixel buffer.
cpl_image * | cpl_image_wrap_double_complex (cpl_size nx, cpl_size ny, double complex *pixels)
| Create a double complex image using an existing pixel buffer.
cpl_image * | cpl_image_wrap_float (cpl_size nx, cpl_size ny, float *pixels)
| Create a float image using an existing pixel buffer.
cpl_image * | cpl_image_wrap_float_complex (cpl_size nx, cpl_size ny, float complex *pixels)
| Create a float complex image using an existing pixel buffer.
cpl_image * | cpl_image_wrap_int (cpl_size nx, cpl_size ny, int *pixels)
| Create an integer image using an existing pixel buffer.
cpl_error_code | cpl_image_xor (cpl_image *self, const cpl_image *first, const cpl_image *second)
| The bit-wise xor of two images with integer pixels.
cpl_error_code | cpl_image_xor_scalar (cpl_image *self, const cpl_image *first, cpl_bitmask second)
| The bit-wise xor of a scalar and an image with integer pixels.
cpl_vector * | cpl_vector_new_from_image_column (const cpl_image *image_in, cpl_size pos)
| Extract a column from an image.
cpl_vector * | cpl_vector_new_from_image_row (const cpl_image *image_in, cpl_size pos)
| Extract a row from an image.

## 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

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

## Typedef Documentation

## cpl_value

typedef enum _cpl_value_ cpl_value

The CPL special value. It is a bit field.

## Enumeration Type Documentation

## _cpl_value_

enum _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

## Function Documentation

## cpl_image_abs()

cpl_error_code cpl_image_abs | ( | cpl_image * | image | ) |

Take the absolute value of an image.

Parameters

  image | Image to be modified in place

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

## cpl_image_abs_create()

cpl_image * cpl_image_abs_create | ( | const cpl_image * | image_in | ) |

Take the absolute value of an image.

Parameters

  image_in | Image operand.

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

## cpl_image_accept()

cpl_error_code cpl_image_accept | ( | cpl_image * | im,
|  | cpl_size | x,
|  | cpl_size | y )

Set a pixel as good in an image.

Parameters

  im | the input image
  x | the x pixel position in the image (first pixel is 1)
  y | the y pixel position in the image (first pixel is 1)

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.

## cpl_image_accept_all()

cpl_error_code cpl_image_accept_all | ( | cpl_image * | self | ) |

Set all pixels in the image as good.

Parameters

  self | the input image

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

## cpl_image_add()

cpl_error_code cpl_image_add | ( | cpl_image * | im1,
|  | const cpl_image * | im2 )

Add two images, store the result in the first image.

Parameters

  im1 | first operand.
  im2 | second operand.

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

## cpl_image_add_create()

cpl_image * cpl_image_add_create | ( | const cpl_image * | image1,
|  | const cpl_image * | image2 )

Add two images.

Parameters

  image1 | first operand
  image2 | second operand

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

## cpl_image_add_scalar()

cpl_error_code cpl_image_add_scalar | ( | cpl_image * | self,
|  | double | scalar )

Elementwise addition of a scalar to an image.

Parameters

  self | Image to be modified in place.
  scalar | Number to add

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

## cpl_image_add_scalar_create()

cpl_image * cpl_image_add_scalar_create | ( | const cpl_image * | image,
|  | double | addend )

Create a new image by elementwise addition of a scalar to an image.

Parameters

  image | Image to add
  addend | Number to add

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

## cpl_image_and()

cpl_error_code cpl_image_and | ( | cpl_image * | self,
|  | const cpl_image * | first,
|  | const cpl_image * | second )

The bit-wise and of two images with integer pixels.

Parameters

  self | Pre-allocated image to hold the result
  first | First operand, or NULL for an in-place operation
  second | Second operand

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.

## cpl_image_and_scalar()

cpl_error_code cpl_image_and_scalar | ( | cpl_image * | self,
|  | const cpl_image * | first,
|  | cpl_bitmask | second )

The bit-wise and of a scalar and an image with integer pixels.

Parameters

  self | Pre-allocated image to hold the result
  first | First operand, or NULL for an in-place operation
  second | Second operand (scalar)

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

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.

## cpl_image_average_create()

cpl_image * cpl_image_average_create | ( | const cpl_image * | image_1,
|  | const cpl_image * | image_2 )

Build the average of two images.

Parameters

  image_1 | First image operand.
  image_2 | Second image operand.

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

## cpl_image_cast()

cpl_image * cpl_image_cast | ( | const cpl_image * | self,
|  | cpl_type | type )

Convert a cpl_image to a given type.

Parameters

  self | The image to convert
  type | The destination type

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

## cpl_image_collapse_create()

cpl_image * cpl_image_collapse_create | ( | const cpl_image * | self,
|  | int | direction )

Collapse an image along its rows or columns.

Parameters

  self | Input image to collapse.
  direction | Collapsing direction.

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

## cpl_image_collapse_median_create()

cpl_image * cpl_image_collapse_median_create | ( | const cpl_image * | self,
|  | int | direction,
|  | cpl_size | drop_ll,
|  | cpl_size | drop_ur )

Collapse an image along its rows or columns, with filtering.

Parameters

  self | Input image to collapse.
  direction | Collapsing direction.
  drop_ll | Ignore this many lower rows/leftmost columns
  drop_ur | Ignore this many upper rows/rightmost columns

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.

## cpl_image_collapse_window_create()

cpl_image * cpl_image_collapse_window_create | ( | const cpl_image * | self,
|  | cpl_size | llx,
|  | cpl_size | lly,
|  | cpl_size | urx,
|  | cpl_size | ury,
|  | int | direction )

Collapse an image region along its rows or columns.

Parameters

  self | Image to collapse.
  llx | lower left x coord.
  lly | lower left y coord
  urx | upper right x coord
  ury | upper right y coord
  direction | Collapsing direction.

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

## cpl_image_conjugate()

cpl_error_code cpl_image_conjugate | ( | cpl_image * | self,
|  | const cpl_image * | other )

Complex conjugate the pixels in a complex image.

Parameters

  self | Pre-allocated complex image to hold the result
  other | The complex image to conjugate, may equal self

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.

## cpl_image_copy()

cpl_error_code cpl_image_copy | ( | cpl_image * | im1,
|  | const cpl_image * | im2,
|  | cpl_size | xpos,
|  | cpl_size | ypos )

Copy one image into another.

Parameters

  im1 | the image in which im2 is inserted
  im2 | the inserted image
  xpos | the x pixel position in im1 where the lower left pixel of im2 should go (from 1 to the x size of im1)
  ypos | the y pixel position in im1 where the lower left pixel of im2 should go (from 1 to the y size of im1)

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

## cpl_image_count_rejected()

cpl_size cpl_image_count_rejected | ( | const cpl_image * | im | ) |

Count the number of bad pixels declared in an image.

Parameters

  im | the input image

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

## cpl_image_delete()

void cpl_image_delete | ( | cpl_image * | d | ) |

Free memory associated to an cpl_image object.

Parameters

  d | Image to destroy.

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

Referenced by cpl_apertures_extract_mask(), cpl_apertures_extract_window(), cpl_fit_image_gaussian(), cpl_geom_img_offset_fine(), cpl_geom_img_offset_saa(), cpl_image_abs_create(), cpl_image_add_scalar_create(), cpl_image_divide_create(), cpl_image_divide_scalar_create(), cpl_image_exponential_create(), 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_fit_gaussian(), cpl_image_iqe(), cpl_image_logarithm_create(), cpl_image_multiply_scalar_create(), cpl_image_normalise_create(), cpl_image_power_create(), cpl_image_subtract_scalar_create(), cpl_imagelist_cast(), cpl_imagelist_collapse_create(), cpl_imagelist_empty(), cpl_imagelist_erase(), cpl_imagelist_load_frameset(), cpl_imagelist_set(), cpl_plot_image(), cpl_plot_image_col(), and cpl_plot_image_row().

## cpl_image_divide()

cpl_error_code cpl_image_divide | ( | cpl_image * | im1,
|  | const cpl_image * | im2 )

Divide two images, store the result in the first image.

Parameters

  im1 | first operand.
  im2 | second operand.

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

## cpl_image_divide_create()

cpl_image * cpl_image_divide_create | ( | const cpl_image * | image1,
|  | const cpl_image * | image2 )

Divide two images.

Parameters

  image1 | first operand
  image2 | second operand

Returns
  1 newly allocated image or NULL on error

See also
  cpl_image_add_create()
  cpl_image_divide() 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, 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.

## cpl_image_divide_scalar()

cpl_error_code cpl_image_divide_scalar | ( | cpl_image * | self,
|  | double | scalar )

Elementwise division of an image with a scalar.

Parameters

  self | Image to be modified in place.
  scalar | Non-zero number to divide with

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

## cpl_image_divide_scalar_create()

cpl_image * cpl_image_divide_scalar_create | ( | const cpl_image * | image,
|  | double | divisor )

Create a new image by elementwise division of an image with a scalar.

Parameters

  image | Image to divide
  divisor | Non-zero number to divide with

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

See also
  cpl_image_divide_scalar
  cpl_image_add_scalar_create

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

## cpl_image_dump_structure()

cpl_error_code cpl_image_dump_structure | ( | const cpl_image * | self,
|  | FILE * | stream )

Dump structural information of a CPL image.

Parameters

  self | Image to dump
  stream | Output stream, accepts `stdout` or `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

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

## cpl_image_dump_window()

cpl_error_code cpl_image_dump_window | ( | const cpl_image * | self,
|  | cpl_size | llx,
|  | cpl_size | lly,
|  | cpl_size | urx,
|  | cpl_size | ury,
|  | FILE * | stream )

Dump pixel values in a CPL image.

Parameters

  self | Image to dump
  llx | Lower left x position (FITS convention, 1 for leftmost)
  lly | Lower left y position (FITS convention, 1 for lowest)
  urx | Specifies the window position
  ury | Specifies the window position
  stream | Output stream, accepts `stdout` or `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().

## cpl_image_duplicate()

cpl_image * cpl_image_duplicate | ( | const cpl_image * | src | ) |

Copy an image.

Parameters

  src | Source image.

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

## cpl_image_exponential()

cpl_error_code cpl_image_exponential | ( | cpl_image * | self,
|  | double | base )

Compute the elementwise exponential of the image.

Parameters

  self | Image to be modified in place.
  base | Base of the exponential.

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

## cpl_image_exponential_create()

cpl_image * cpl_image_exponential_create | ( | const cpl_image * | image,
|  | double | base )

Create a new image by elementwise exponentiation of an image.

Parameters

  image | Image to exponentiate
  base | Base of the exponential

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

See also
  cpl_image_logarithm
  cpl_image_add_scalar_create

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

## cpl_image_extract()

cpl_image * cpl_image_extract | ( | const cpl_image * | in,
|  | cpl_size | llx,
|  | cpl_size | lly,
|  | cpl_size | urx,
|  | cpl_size | ury )

Extract a rectangular zone from an image into another image.

Parameters

  in | Input image
  llx | Lower left X coordinate
  lly | Lower left Y coordinate
  urx | Upper right X coordinate
  ury | Upper right Y coordinate

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

## cpl_image_extract_subsample()

cpl_image * cpl_image_extract_subsample | ( | const cpl_image * | image,
|  | cpl_size | xstep,
|  | cpl_size | ystep )

Sub-sample an image.

Parameters

  image | The image to subsample
  xstep | Take every xstep pixel in x
  ystep | Take every ystep pixel in y

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

## cpl_image_fft()

cpl_error_code cpl_image_fft | ( | cpl_image * | img_real,
|  | cpl_image * | img_imag,
|  | unsigned | mode )

Fast Fourier Transform a square, power-of-two sized image.

Parameters

  img_real | The image real part to be transformed in place
  img_imag | The image imaginary part to be transformed in place
  mode | The desired FFT options (combined with bitwise or)

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.

## cpl_image_fill_abs_arg()

cpl_error_code cpl_image_fill_abs_arg | ( | cpl_image * | im_abs,
|  | cpl_image * | im_arg,
|  | const cpl_image * | self )

Split a complex image into its absolute and argument part(s).

Parameters

  im_abs | Pre-allocated image to hold the absolute part, or `NULL`
  im_arg | Pre-allocated image to hold the argument part, or `NULL`
  self | Complex image to process

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.

## cpl_image_fill_gaussian()

cpl_error_code cpl_image_fill_gaussian | ( | cpl_image * | ima,
|  | double | xcen,
|  | double | ycen,
|  | double | norm,
|  | double | sig_x,
|  | double | sig_y )

Generate an image from a 2d gaussian function.

Parameters

  ima | the gaussian image to generate
  xcen | x position of the center (1 for the first pixel)
  ycen | y position of the center (1 for the first pixel)
  norm | norm of the gaussian.
  sig_x | Sigma in x for the gaussian distribution.
  sig_y | Sigma in y for the gaussian distribution.

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

## cpl_image_fill_jacobian()

cpl_error_code cpl_image_fill_jacobian | ( | cpl_image * | out,
|  | const cpl_image * | deltax,
|  | const cpl_image * | deltay )

Compute area change ratio for a transformation map.

Parameters

  out | Pre-allocated image to hold the result
  deltax | The x shifts for each pixel
  deltay | The y shifts for each pixel

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.

## cpl_image_fill_jacobian_polynomial()

cpl_error_code cpl_image_fill_jacobian_polynomial | ( | cpl_image * | out,
|  | const cpl_polynomial * | poly_x,
|  | const cpl_polynomial * | poly_y )

Compute area change ratio for a 2D polynomial transformation.

Parameters

  out | Pre-allocated image to hold the result
  poly_x | Defines source x-pos corresponding to destination (u,v).
  poly_y | Defines source y-pos corresponding to destination (u,v).

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

## cpl_image_fill_noise_uniform()

cpl_error_code cpl_image_fill_noise_uniform | ( | cpl_image * | ima,
|  | double | min_pix,
|  | double | max_pix )

Generate an image with uniform random noise distribution.

Parameters

  ima | the image to generate
  min_pix | Minimum output pixel value.
  max_pix | Maximum output pixel value.

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

## cpl_image_fill_polynomial()

cpl_error_code cpl_image_fill_polynomial | ( | cpl_image * | ima,
|  | const cpl_polynomial * | poly,
|  | double | startx,
|  | double | stepx,
|  | double | starty,
|  | double | stepy )

Generate an image from a 2d polynomial function.

Parameters

  ima | the polynomial image to generate
  poly | the 2d polynomial
  startx | the x value associated with the left pixels column
  stepx | the x step
  starty | the y value associated with the bottom pixels row
  stepy | the y step

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

## cpl_image_fill_re_im()

cpl_error_code cpl_image_fill_re_im | ( | cpl_image * | im_real,
|  | cpl_image * | im_imag,
|  | const cpl_image * | self )

Split a complex image into its real and/or imaginary part(s).

Parameters

  im_real | Pre-allocated image to hold the real part, or `NULL`
  im_imag | Pre-allocated image to hold the imaginary part, or `NULL`
  self | Complex image to process

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.

## cpl_image_fill_rejected()

cpl_error_code cpl_image_fill_rejected | ( | cpl_image * | im,
|  | double | a )

Set the bad pixels in an image to a fixed value.

Parameters

  im | The image to modify.
  a | The fixed value

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

## cpl_image_fill_test_create()

cpl_image * cpl_image_fill_test_create | ( | cpl_size | nx,
|  | cpl_size | ny )

Generate a test image with pixel type CPL_TYPE_DOUBLE.

Parameters

  nx | x size
  ny | y size

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.

## cpl_image_fill_window()

cpl_error_code cpl_image_fill_window | ( | cpl_image * | self,
|  | cpl_size | llx,
|  | cpl_size | lly,
|  | cpl_size | urx,
|  | cpl_size | ury,
|  | double | value )

Fill an image window with a constant.

Parameters

  self | The image to fill
  llx | Lower left x position (FITS convention, 1 for leftmost)
  lly | Lower left y position (FITS convention, 1 for lowest)
  urx | Specifies the window position
  ury | Specifies the window position
  value | The value to fill with

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.

## 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.

Parameters

  self | Pre-allocated image to hold the filtered result
  other | Image to filter
  kernel | Pixel weigths
  filter | CPL_FILTER_LINEAR, CPL_FILTER_MORPHO
  border | CPL_BORDER_FILTER

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

## cpl_image_filter_linear()

cpl_image * cpl_image_filter_linear | ( | const cpl_image * | in,
|  | const cpl_matrix * | ker )

Compute a linear filtering.

Parameters

  in | The image to filter
  ker | The kernel

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

## 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.

Parameters

  self | Pre-allocated image to hold the filtered result
  other | Image to filter
  kernel | Pixels to use, if set to CPL_BINARY_1
  filter | CPL_FILTER_MEDIAN, CPL_FILTER_AVERAGE and more, see below
  border | CPL_BORDER_FILTER and more, see below

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:216
  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:1469

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

## cpl_image_filter_median()

cpl_image * cpl_image_filter_median | ( | const cpl_image * | in,
|  | const cpl_matrix * | ker )

Apply a spatial median filter to an image.

Parameters

  in | Image to filter.
  ker | the kernel

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

## cpl_image_filter_morpho()

cpl_image * cpl_image_filter_morpho | ( | const cpl_image * | in,
|  | const cpl_matrix * | ker )

Filter an image in spatial domain with a morpho kernel.

Parameters

  in | Image to filter.
  ker | Filter definition.

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

## cpl_image_filter_stdev()

cpl_image * cpl_image_filter_stdev | ( | const cpl_image * | in,
|  | const cpl_matrix * | ker )

Standard deviation filter.

Parameters

  in | input image
  ker | the kernel

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

## cpl_image_fit_gaussian()

cpl_error_code cpl_image_fit_gaussian | ( | const cpl_image * | im,
|  | cpl_size | xpos,
|  | cpl_size | ypos,
|  | cpl_size | size,
|  | double * | norm,
|  | double * | xcen,
|  | double * | ycen,
|  | double * | sig_x,
|  | double * | sig_y,
|  | double * | fwhm_x,
|  | double * | fwhm_y )

Apply a gaussian fit on an image sub window.

Parameters

  im | the input image
  xpos | the x position of the center (1 for the first pixel)
  ypos | the y position of the center (1 for the first pixel)
  size | the window size in pixels, at least 4
  norm | the norm of the gaussian or NULL
  xcen | the x center of the gaussian or NULL
  ycen | the y center of the gaussian or NULL
  sig_x | the semi-major axis of the gaussian or NULL
  sig_y | the semi-minor axis of the gaussian or NULL
  fwhm_x | the FHHM in x or NULL
  fwhm_y | the FHHM in y or NULL

Returns
  the _cpl_error_code_ or CPL_ERROR_NONE

See also
  cpl_fit_image_gaussian()
  cpl_image_iqe()

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.

## cpl_image_flip()

cpl_error_code cpl_image_flip | ( | cpl_image * | im,
|  | int | angle )

Flip an image on a given mirror line.

Parameters

  im | the image to flip.
  angle | mirror line in polar coord. is theta = (PI/4) * angle

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

## cpl_image_get()

double cpl_image_get | ( | const cpl_image * | image,
|  | cpl_size | xpos,
|  | cpl_size | ypos,
|  | int * | pis_rejected )

Get the value of a pixel at a given position.

Parameters

  image | Input image.
  xpos | Pixel x position (FITS convention, 1 for leftmost)
  ypos | Pixel y position (FITS convention, 1 for lowest)
  pis_rejected | 1 if the pixel is bad, 0 if good, negative on error

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

## cpl_image_get_absflux()

double cpl_image_get_absflux | ( | const cpl_image * | image | ) |

Computes the sum of absolute values over an image.

Parameters

  image | input image.

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

See also
  cpl_image_get_min()

Referenced by cpl_image_normalise().

## cpl_image_get_absflux_window()

double cpl_image_get_absflux_window | ( | const cpl_image * | image,
|  | cpl_size | llx,
|  | cpl_size | lly,
|  | cpl_size | urx,
|  | cpl_size | ury )

Computes the sum of absolute values over an image sub-window.

Parameters

  image | input image.
  llx | Lower left x position (FITS convention, 1 for leftmost)
  lly | Lower left y position (FITS convention, 1 for lowest)
  urx | Upper right x position (FITS convention)
  ury | Upper right y position (FITS convention)

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

See also
  cpl_image_get_min_window()

## cpl_image_get_bpm()

cpl_mask * cpl_image_get_bpm | ( | cpl_image * | img | ) |

Gets the bad pixels map.

Parameters

  img | Image to query.

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

## cpl_image_get_bpm_const()

const cpl_mask * cpl_image_get_bpm_const | ( | const cpl_image * | img | ) |

Gets the bad pixels map.

Parameters

  img | Image to query.

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

## cpl_image_get_centroid_x()

double cpl_image_get_centroid_x | ( | const cpl_image * | image | ) |

Computes the x centroid value over the whole image.

Parameters

  image | input image.

Returns
  the x centroid value

See also
  cpl_image_get_min_window()

## cpl_image_get_centroid_x_window()

double cpl_image_get_centroid_x_window | ( | const cpl_image * | image,
|  | cpl_size | llx,
|  | cpl_size | lly,
|  | cpl_size | urx,
|  | cpl_size | ury )

Computes the x centroid value over an image sub-window.

Parameters

  image | input image.
  llx | Lower left x position (FITS convention, 1 for leftmost)
  lly | Lower left y position (FITS convention, 1 for lowest)
  urx | Upper right x position (FITS convention)
  ury | Upper right y position (FITS convention)

Returns
  the x centroid value

See also
  cpl_image_get_min_window()

## cpl_image_get_centroid_y()

double cpl_image_get_centroid_y | ( | const cpl_image * | image | ) |

Computes the y centroid value over the whole image.

Parameters

  image | input image.

Returns
  the y centroid value

See also
  cpl_image_get_min_window()

## cpl_image_get_centroid_y_window()

double cpl_image_get_centroid_y_window | ( | const cpl_image * | image,
|  | cpl_size | llx,
|  | cpl_size | lly,
|  | cpl_size | urx,
|  | cpl_size | ury )

Computes the y centroid value over an image sub-window.

Parameters

  image | input image.
  llx | Lower left x position (FITS convention, 1 for leftmost)
  lly | Lower left y position (FITS convention, 1 for lowest)
  urx | Upper right x position (FITS convention)
  ury | Upper right y position (FITS convention)

Returns
  the y centroid value

See also
  cpl_image_get_min_window()

## cpl_image_get_complex()

double complex cpl_image_get_complex | ( | const cpl_image * | image,
|  | cpl_size | xpos,
|  | cpl_size | ypos,
|  | int * | pis_rejected )

Get the value of a complex pixel at a given position.

Parameters

  image | Input complex image.
  xpos | Pixel x position (FITS convention, 1 for leftmost)
  ypos | Pixel y position (FITS convention, 1 for lowest)
  pis_rejected | 1 if the pixel is bad, 0 if good, negative on error

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

## cpl_image_get_data()

void * cpl_image_get_data | ( | cpl_image * | img | ) |

Gets the pixel data.

Parameters

  img | Image to query.

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

## cpl_image_get_data_const()

const void * cpl_image_get_data_const | ( | const cpl_image * | img | ) |

Gets the pixel data.

Parameters

  img | Image to query.

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

See also
  cpl_image_get_data

References cpl_ensure, and CPL_ERROR_NULL_INPUT.

Referenced by cpl_image_filter(), cpl_image_filter_mask(), and cpl_mask_threshold_image().

## cpl_image_get_data_double()

double * cpl_image_get_data_double | ( | cpl_image * | img | ) |

Get the data as a double array.

Parameters

  img | a cpl_image object

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

## cpl_image_get_data_double_complex()

double complex * cpl_image_get_data_double_complex | ( | cpl_image * | img | ) |

Get the data as a double complex array.

Parameters

  img | a cpl_image object

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

## cpl_image_get_data_double_complex_const()

const double complex * cpl_image_get_data_double_complex_const | ( | const cpl_image * | img | ) |

Get the data as a double complex array.

Parameters

  img | a cpl_image object

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

See also
  cpl_image_get_data_double_complex()

## cpl_image_get_data_double_const()

const double * cpl_image_get_data_double_const | ( | const cpl_image * | img | ) |

Get the data as a double array.

Parameters

  img | a cpl_image object

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

## cpl_image_get_data_float()

float * cpl_image_get_data_float | ( | cpl_image * | img | ) |

Get the data as a float array.

Parameters

  img | a cpl_image object

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

## cpl_image_get_data_float_complex()

float complex * cpl_image_get_data_float_complex | ( | cpl_image * | img | ) |

Get the data as a float complex array.

Parameters

  img | a cpl_image object

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

See also
  cpl_image_get_data_double_complex()

## cpl_image_get_data_float_complex_const()

const float complex * cpl_image_get_data_float_complex_const | ( | const cpl_image * | img | ) |

Get the data as a float complex array.

Parameters

  img | a cpl_image object

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

See also
  cpl_image_get_data_double_complex()

## cpl_image_get_data_float_const()

const float * cpl_image_get_data_float_const | ( | const cpl_image * | img | ) |

Get the data as a float array.

Parameters

  img | a cpl_image object

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

See also
  cpl_image_get_data_float()

## cpl_image_get_data_int()

int * cpl_image_get_data_int | ( | cpl_image * | img | ) |

Get the data as a integer array.

Parameters

  img | a cpl_image object

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

## cpl_image_get_data_int_const()

const int * cpl_image_get_data_int_const | ( | const cpl_image * | img | ) |

Get the data as a integer array.

Parameters

  img | a cpl_image object

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

See also
  cpl_image_get_data_int()

## cpl_image_get_flux()

double cpl_image_get_flux | ( | const cpl_image * | image | ) |

Computes the sum of pixel values over an image.

Parameters

  image | input image.

Returns
  the flux value

See also
  cpl_image_get_min()

References cpl_ensure, CPL_ERROR_NULL_INPUT, and cpl_image_get_flux_window().

Referenced by cpl_image_normalise().

## cpl_image_get_flux_window()

double cpl_image_get_flux_window | ( | const cpl_image * | image,
|  | cpl_size | llx,
|  | cpl_size | lly,
|  | cpl_size | urx,
|  | cpl_size | ury )

Computes the sum of pixel values over an image sub-window.

Parameters

  image | input image.
  llx | Lower left x position (FITS convention, 1 for leftmost)
  lly | Lower left y position (FITS convention, 1 for lowest)
  urx | Upper right x position (FITS convention)
  ury | Upper right y position (FITS convention)

Returns
  the flux value

See also
  cpl_image_get_min_window()

Referenced by cpl_image_get_flux().

## cpl_image_get_fwhm()

cpl_error_code cpl_image_get_fwhm | ( | const cpl_image * | in,
|  | cpl_size | xpos,
|  | cpl_size | ypos,
|  | double * | fwhm_x,
|  | double * | fwhm_y )

Compute FWHM values in x and y for an object.

Parameters

  in | the input image
  xpos | the x position of the object (1 for the first pixel)
  ypos | the y position of the object (1 for the first pixel)
  fwhm_x | the computed FWHM in x or -1 on error
  fwhm_y | the computed FWHM in y or -1 on error

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

## cpl_image_get_interpolated()

double cpl_image_get_interpolated | ( | const cpl_image * | source,
|  | double | xpos,
|  | double | ypos,
|  | const cpl_vector * | xprofile,
|  | double | xradius,
|  | const cpl_vector * | yprofile,
|  | double | yradius,
|  | double * | pconfid )

Interpolate a pixel from its neigbors.

Parameters

  source | Interpolation source
  xpos | Pixel x floating-point position (FITS convention)
  ypos | Pixel y floating-point position (FITS convention)
  xprofile | Interpolation weight as a function of the distance in X
  xradius | Positive inclusion radius in the X-dimension
  yprofile | Interpolation weight as a function of the distance in Y
  yradius | Positive inclusion radius in the Y-dimension
  pconfid | Confidence level of the interpolated value (range 0 to 1)

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);
else
cpl_image_reject(unwarped, iu, iv);
}
}
cpl_vector_delete(xyprofile);
cpl_image_get_interpolated
double cpl_image_get_interpolated(const cpl_image *source, double xpos, double ypos, const cpl_vector *xprofile, double xradius, const cpl_vector *yprofile, double yradius, double *pconfid)
Interpolate a pixel from its neigbors.
Definition cpl_image_resample.c:704
cpl_image_set
cpl_error_code cpl_image_set(cpl_image *image, cpl_size xpos, cpl_size ypos, double value)
Set the pixel at the given position to the given value.
Definition cpl_image_io.c:1469
cpl_image_new
cpl_image * cpl_image_new(cpl_size nx, cpl_size ny, cpl_type type)
Allocate an image structure and pixel buffer for a image.
Definition cpl_image_io.c:132
cpl_image_reject
cpl_error_code cpl_image_reject(cpl_image *im, cpl_size x, cpl_size y)
Set a pixel as bad in an image.
Definition cpl_image_bpm.c:238
CPL_TYPE_DOUBLE
@ CPL_TYPE_DOUBLE
Definition cpl_type.h:134
cpl_vector_fill_kernel_profile
cpl_error_code cpl_vector_fill_kernel_profile(cpl_vector *profile, cpl_kernel type, double radius)
Fill a vector with a kernel profile.
Definition cpl_vector.c:2644
cpl_vector_new
cpl_vector * cpl_vector_new(cpl_size n)
Create a new cpl_vector.
Definition cpl_vector.c:137
cpl_vector_delete
void cpl_vector_delete(cpl_vector *v)
Delete a cpl_vector.
Definition cpl_vector.c:240

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

## cpl_image_get_mad()

double cpl_image_get_mad | ( | const cpl_image * | image,
|  | double * | sigma )

Computes median and median absolute deviation (MAD) on an image.

Parameters

  image | Input image.
  sigma | The median of the absolute median deviation of the good pixels

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.

## cpl_image_get_mad_window()

double cpl_image_get_mad_window | ( | const cpl_image * | image,
|  | cpl_size | llx,
|  | cpl_size | lly,
|  | cpl_size | urx,
|  | cpl_size | ury,
|  | double * | sigma )

Computes median and median absolute deviation (MAD) on an image window.

Parameters

  image | Input image.
  llx | Lower left x position (FITS convention, 1 for leftmost)
  lly | Lower left y position (FITS convention, 1 for lowest)
  urx | Upper right x position (FITS convention)
  ury | Upper right y position (FITS convention)
  sigma | The median of the absolute median deviation of the good pixels

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.

## cpl_image_get_max()

double cpl_image_get_max | ( | const cpl_image * | image | ) |

computes maximum pixel value over an image.

Parameters

  image | input image.

Returns
  the maximum value

See also
  cpl_image_get_min()

Referenced by cpl_plot_image().

## cpl_image_get_max_window()

double cpl_image_get_max_window | ( | const cpl_image * | image,
|  | cpl_size | llx,
|  | cpl_size | lly,
|  | cpl_size | urx,
|  | cpl_size | ury )

computes maximum pixel value over an image sub-window.

Parameters

  image | input image.
  llx | Lower left x position (FITS convention, 1 for leftmost)
  lly | Lower left y position (FITS convention, 1 for lowest)
  urx | Upper right x position (FITS convention)
  ury | Upper right y position (FITS convention)

Returns
  the maximum value

See also
  cpl_image_get_min_window()

## cpl_image_get_maxpos()

cpl_error_code cpl_image_get_maxpos | ( | const cpl_image * | image,
|  | cpl_size * | px,
|  | cpl_size * | py )

Computes maximum pixel value and position over an image.

Parameters

  image | Input image.
  px | ptr to the x coordinate of the maximum position
  py | ptr to the y coordinate of the maximum position

Returns
  CPL_ERROR_NONE or the _cpl_error_code_ on error

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

## cpl_image_get_maxpos_window()

cpl_error_code cpl_image_get_maxpos_window | ( | const cpl_image * | image,
|  | cpl_size | llx,
|  | cpl_size | lly,
|  | cpl_size | urx,
|  | cpl_size | ury,
|  | cpl_size * | px,
|  | cpl_size * | py )

Computes maximum pixel value and position over an image sub window.

Parameters

  image | Input image.
  llx | Lower left x position (FITS convention, 1 for leftmost)
  lly | Lower left y position (FITS convention, 1 for lowest)
  urx | Upper right x position (FITS convention)
  ury | Upper right y position (FITS convention)
  px | ptr to the x coordinate of the maximum position
  py | ptr to the y coordinate of the maximum position

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.

## cpl_image_get_mean()

double cpl_image_get_mean | ( | const cpl_image * | image | ) |

computes mean pixel value over an image.

Parameters

  image | input image.

Returns
  the mean value

See also
  cpl_image_get_min()

Referenced by cpl_fit_image_gaussian(), and cpl_image_normalise().

## cpl_image_get_mean_window()

double cpl_image_get_mean_window | ( | const cpl_image * | image,
|  | cpl_size | llx,
|  | cpl_size | lly,
|  | cpl_size | urx,
|  | cpl_size | ury )

computes mean pixel value over an image sub-window.

Parameters

  image | input image.
  llx | Lower left x position (FITS convention, 1 for leftmost)
  lly | Lower left y position (FITS convention, 1 for lowest)
  urx | Upper right x position (FITS convention)
  ury | Upper right y position (FITS convention)

Returns
  the mean value

See also
  cpl_image_get_min_window()

## cpl_image_get_median()

double cpl_image_get_median | ( | const cpl_image * | image | ) |

computes median pixel value over an image.

Parameters

  image | Input image.

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

## cpl_image_get_median_dev()

double cpl_image_get_median_dev | ( | const cpl_image * | image,
|  | double * | sigma )

Computes median and mean absolute median deviation on an image window.

Parameters

  image | Input image.
  sigma | The mean of the absolute median deviation of the (good) pixels

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

## cpl_image_get_median_dev_window()

double cpl_image_get_median_dev_window | ( | const cpl_image * | image,
|  | cpl_size | llx,
|  | cpl_size | lly,
|  | cpl_size | urx,
|  | cpl_size | ury,
|  | double * | sigma )

Computes median and mean absolute median deviation on an image window.

Parameters

  image | Input image.
  llx | Lower left x position (FITS convention, 1 for leftmost)
  lly | Lower left y position (FITS convention, 1 for lowest)
  urx | Upper right x position (FITS convention)
  ury | Upper right y position (FITS convention)
  sigma | The mean of the absolute median deviation of the (good) pixels

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.

## cpl_image_get_median_window()

double cpl_image_get_median_window | ( | const cpl_image * | image,
|  | cpl_size | llx,
|  | cpl_size | lly,
|  | cpl_size | urx,
|  | cpl_size | ury )

computes median pixel value over an image sub-window.

Parameters

  image | Input image.
  llx | Lower left x position (FITS convention, 1 for leftmost)
  lly | Lower left y position (FITS convention, 1 for lowest)
  urx | Upper right x position (FITS convention)
  ury | Upper right y position (FITS convention)

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

## cpl_image_get_min()

double cpl_image_get_min | ( | const cpl_image * | image | ) |

computes minimum pixel value over an image.

Parameters

  image | input image.

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

## cpl_image_get_min_window()

double cpl_image_get_min_window | ( | const cpl_image * | image,
|  | cpl_size | llx,
|  | cpl_size | lly,
|  | cpl_size | urx,
|  | cpl_size | ury )

computes minimum pixel value over an image sub-window.

Parameters

  image | input image.
  llx | Lower left x position (FITS convention, 1 for leftmost)
  lly | Lower left y position (FITS convention, 1 for lowest)
  urx | Upper right x position (FITS convention)
  ury | Upper right y position (FITS convention)

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

## cpl_image_get_minpos()

cpl_error_code cpl_image_get_minpos | ( | const cpl_image * | image,
|  | cpl_size * | px,
|  | cpl_size * | py )

Computes minimum pixel value and position over an image.

Parameters

  image | Input image.
  px | ptr to the x coordinate of the minimum position
  py | ptr to the y coordinate of the minimum position

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

## cpl_image_get_minpos_window()

cpl_error_code cpl_image_get_minpos_window | ( | const cpl_image * | image,
|  | cpl_size | llx,
|  | cpl_size | lly,
|  | cpl_size | urx,
|  | cpl_size | ury,
|  | cpl_size * | px,
|  | cpl_size * | py )

Computes minimum pixel value and position over an image sub window.

Parameters

  image | Input image.
  llx | Lower left x position (FITS convention, 1 for leftmost)
  lly | Lower left y position (FITS convention, 1 for lowest)
  urx | Upper right x position (FITS convention)
  ury | Upper right y position (FITS convention)
  px | ptr to the x coordinate of the minimum position
  py | ptr to the y coordinate of the minimum position

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.

## cpl_image_get_size_x()

cpl_size cpl_image_get_size_x | ( | const cpl_image * | img | ) |

Get the image x size.

Parameters

  img | a cpl_image object

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

## cpl_image_get_size_y()

cpl_size cpl_image_get_size_y | ( | const cpl_image * | img | ) |

Get the image y size.

Parameters

  img | a cpl_image object

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

## cpl_image_get_sqflux()

double cpl_image_get_sqflux | ( | const cpl_image * | image | ) |

Computes the sum of squared values over an image.

Parameters

  image | input image.

Returns
  the sqaure flux

See also
  cpl_image_get_min()

## cpl_image_get_sqflux_window()

double cpl_image_get_sqflux_window | ( | const cpl_image * | image,
|  | cpl_size | llx,
|  | cpl_size | lly,
|  | cpl_size | urx,
|  | cpl_size | ury )

Computes the sum of squared values over an image sub-window.

Parameters

  image | input image.
  llx | Lower left x position (FITS convention, 1 for leftmost)
  lly | Lower left y position (FITS convention, 1 for lowest)
  urx | Upper right x position (FITS convention)
  ury | Upper right y position (FITS convention)

Returns
  the square flux

See also
  cpl_image_get_min_window()

## cpl_image_get_stdev()

double cpl_image_get_stdev | ( | const cpl_image * | image | ) |

computes pixel standard deviation over an image.

Parameters

  image | input image.

Returns
  the standard deviation value

See also
  cpl_image_get_min()

## cpl_image_get_stdev_window()

double cpl_image_get_stdev_window | ( | const cpl_image * | image,
|  | cpl_size | llx,
|  | cpl_size | lly,
|  | cpl_size | urx,
|  | cpl_size | ury )

computes pixel standard deviation over an image sub-window.

Parameters

  image | input image.
  llx | Lower left x position (FITS convention, 1 for leftmost)
  lly | Lower left y position (FITS convention, 1 for lowest)
  urx | Upper right x position (FITS convention)
  ury | Upper right y position (FITS convention)

Returns
  the standard deviation value

See also
  cpl_image_get_min_window()

Referenced by cpl_flux_get_noise_ring().

## cpl_image_get_type()

cpl_type cpl_image_get_type | ( | const cpl_image * | img | ) |

Get the image type.

Parameters

  img | a cpl_image object

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

## cpl_image_hypot()

cpl_error_code cpl_image_hypot | ( | cpl_image * | self,
|  | const cpl_image * | first,
|  | const cpl_image * | second )

The pixel-wise Euclidean distance function of the images.

Parameters

  self | Pre-allocated image to hold the result
  first | First operand, or NULL for an in-place operation
  second | Second operand

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

## cpl_image_iqe()

cpl_bivector * cpl_image_iqe | ( | const cpl_image * | in,
|  | cpl_size | llx,
|  | cpl_size | lly,
|  | cpl_size | urx,
|  | cpl_size | ury )

Compute an image quality estimation for an object.

Parameters

  in | the input image
  llx |
  lly | the zone to analyse ((1, 1) for the first pixel)
  urx | The zone must be at least 4 by 4 pixels
  ury |

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

## cpl_image_is_rejected()

int cpl_image_is_rejected | ( | const cpl_image * | im,
|  | cpl_size | x,
|  | cpl_size | y )

Test if a pixel is good or bad.

Parameters

  im | the input image
  x | the x pixel position in the image (first pixel is 1)
  y | the y pixel position in the image (first pixel is 1)

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

## cpl_image_labelise_mask_create()

cpl_image * cpl_image_labelise_mask_create | ( | const cpl_mask * | in,
|  | cpl_size * | nbobjs )

Labelise a mask to differentiate different objects.

Parameters

  in | mask to labelise
  nbobjs | If non-NULL, number of objects found on success

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

## cpl_image_load()

cpl_image * cpl_image_load | ( | const char * | filename,
|  | cpl_type | im_type,
|  | cpl_size | pnum,
|  | cpl_size | xtnum )

Load an image from a FITS file.

Parameters

  filename | Name of the file to load from.
  im_type | Type of the created image
  pnum | Plane number in the Data Unit (0 for first)
  xtnum | Extension number in the file (0 for primary HDU)

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.

This function will seamlessly load an image from a tile compressed FITS file. Exactly because the loading works automatically whether the file is compressed or not, the dimension of a succesfully loaded image should be determined with calls to cpl_image_get_size_x() and cpl_image_get_size_y() and not by inspecting the values of the FITS file's NAXIS1 and NAXIS2, since these in the case of a compressed file will have values different from the dimension of the loaded image.

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);
cpl_image_load
cpl_image * cpl_image_load(const char *filename, cpl_type im_type, cpl_size pnum, cpl_size xtnum)
Load an image from a FITS file.
Definition cpl_image_io.c:390
CPL_TYPE_FLOAT
@ CPL_TYPE_FLOAT
Definition cpl_type.h:128
CPL_TYPE_INT
@ CPL_TYPE_INT
Definition cpl_type.h:92

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

## cpl_image_load_window()

cpl_image * cpl_image_load_window | ( | const char * | filename,
|  | cpl_type | im_type,
|  | cpl_size | pnum,
|  | cpl_size | xtnum,
|  | cpl_size | llx,
|  | cpl_size | lly,
|  | cpl_size | urx,
|  | cpl_size | ury )

Load an image from a FITS file.

Parameters

  filename | Name of the file to load from.
  im_type | Type of the created image
  pnum | Plane number in the Data Unit (0 for first)
  xtnum | Extension number in the file.
  llx | Lower left x position (FITS convention, 1 for leftmost)
  lly | Lower left y position (FITS convention, 1 for lowest)
  urx | Upper right x position (FITS convention)
  ury | Upper right y position (FITS convention)

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

## cpl_image_logarithm()

cpl_error_code cpl_image_logarithm | ( | cpl_image * | self,
|  | double | base )

Compute the elementwise logarithm of the image.

Parameters

  self | Image to be modified in place.
  base | Base of the logarithm.

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

## cpl_image_logarithm_create()

cpl_image * cpl_image_logarithm_create | ( | const cpl_image * | image,
|  | double | base )

Create a new image by taking the elementwise logarithm of an image.

Parameters

  image | Image to take logarithm of
  base | Base of the logarithm.

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

See also
  cpl_image_logarithm
  cpl_image_add_scalar_create

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

## cpl_image_move()

cpl_error_code cpl_image_move | ( | cpl_image * | im,
|  | cpl_size | nb_cut,
|  | const cpl_size * | new_pos )

Permute tiles in an image.

Parameters

  im | The image to modify
  nb_cut | The number of cuts in x and y
  new_pos | Array with the nb_cut^2 permuted positions

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

## cpl_image_multiply()

cpl_error_code cpl_image_multiply | ( | cpl_image * | im1,
|  | const cpl_image * | im2 )

Multiply two images, store the result in the first image.

Parameters

  im1 | first operand.
  im2 | second operand.

Returns
  the _cpl_error_code_ or CPL_ERROR_NONE

See also
  cpl_image_add()

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

## cpl_image_multiply_create()

cpl_image * cpl_image_multiply_create | ( | const cpl_image * | image1,
|  | const cpl_image * | image2 )

Multiply two images.

Parameters

  image1 | first operand
  image2 | second operand

Returns
  1 newly allocated image or NULL on error

See also
  cpl_image_add_create()

## cpl_image_multiply_scalar()

cpl_error_code cpl_image_multiply_scalar | ( | cpl_image * | self,
|  | double | scalar )

Elementwise multiplication of an image with a scalar.

Parameters

  self | Image to be modified in place.
  scalar | Number to multiply with

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

## cpl_image_multiply_scalar_create()

cpl_image * cpl_image_multiply_scalar_create | ( | const cpl_image * | image,
|  | double | factor )

Create a new image by multiplication of a scalar and an image.

Parameters

  image | Image to be multiplied
  factor | Number to multiply with

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

See also
  cpl_image_multiply_scalar
  cpl_image_add_scalar_create

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

## cpl_image_new()

cpl_image * cpl_image_new | ( | cpl_size | nx,
|  | cpl_size | ny,
|  | cpl_type | type )

Allocate an image structure and pixel buffer for a image.

Parameters

  nx | Size in x (the number of columns)
  ny | Size in y (the number of rows)
  type | The pixel type

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

## cpl_image_new_from_mask()

cpl_image * cpl_image_new_from_mask | ( | const cpl_mask * | mask | ) |

Create an int image from a mask.

Parameters

  mask | the original mask

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

## cpl_image_normalise()

cpl_error_code cpl_image_normalise | ( | cpl_image * | image,
|  | cpl_norm | mode )

Normalise pixels in an image.

Parameters

  image | Image operand.
  mode | Normalisation mode.

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

## cpl_image_normalise_create()

cpl_image * cpl_image_normalise_create | ( | const cpl_image * | image_in,
|  | cpl_norm | mode )

Create a new normalised image from an existing image.

Parameters

  image_in | Image operand.
  mode | Normalisation mode.

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

## cpl_image_not()

cpl_error_code cpl_image_not | ( | cpl_image * | self,
|  | const cpl_image * | first )

The bit-wise complement (not) of an image with integer pixels.

Parameters

  self | Pre-allocated image to hold the result
  first | First operand, or NULL for an in-place operation

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

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.

## cpl_image_or()

cpl_error_code cpl_image_or | ( | cpl_image * | self,
|  | const cpl_image * | first,
|  | const cpl_image * | second )

The bit-wise or of two images with integer pixels.

Parameters

  self | Pre-allocated image to hold the result
  first | First operand, or NULL for an in-place operation
  second | Second operand

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

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.

## cpl_image_or_scalar()

cpl_error_code cpl_image_or_scalar | ( | cpl_image * | self,
|  | const cpl_image * | first,
|  | cpl_bitmask | second )

The bit-wise or of a scalar and an image with integer pixels.

Parameters

  self | Pre-allocated image to hold the result
  first | First operand, or NULL for an in-place operation
  second | Second operand (scalar)

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

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.

## cpl_image_power()

cpl_error_code cpl_image_power | ( | cpl_image * | self,
|  | double | exponent )

Compute the elementwise power of the image.

Parameters

  self | Image to be modified in place.
  exponent | Scalar exponent.

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

## cpl_image_power_create()

cpl_image * cpl_image_power_create | ( | const cpl_image * | image,
|  | double | exponent )

Create a new image by elementwise raising of an image to a power.

Parameters

  image | Image to raise to a power
  exponent | scalar exponent

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

See also
  cpl_image_power
  cpl_image_add_scalar_create

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

## cpl_image_rebin()

cpl_image * cpl_image_rebin | ( | const cpl_image * | image,
|  | cpl_size | xstart,
|  | cpl_size | ystart,
|  | cpl_size | xstep,
|  | cpl_size | ystep )

Rebin an image.

Parameters

  image | The image to rebin
  xstart | start x position of binning (starting from 1...)
  ystart | start y position of binning (starting from 1...)
  xstep | Bin size in x.
  ystep | Bin size in y.

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

## cpl_image_reject()

cpl_error_code cpl_image_reject | ( | cpl_image * | im,
|  | cpl_size | x,
|  | cpl_size | y )

Set a pixel as bad in an image.

Parameters

  im | the input image
  x | the x pixel position in the image (first pixel is 1)
  y | the y pixel position in the image (first pixel is 1)

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.

## cpl_image_reject_from_mask()

cpl_error_code cpl_image_reject_from_mask | ( | cpl_image * | im,
|  | const cpl_mask * | map )

Set the bad pixels in an image as defined in a mask.

Parameters

  im | the input image
  map | the mask defining the bad pixels

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

## cpl_image_reject_value()

cpl_error_code cpl_image_reject_value | ( | cpl_image * | self,
|  | cpl_value | mode )

Reject pixels with the specified special value(s).

Parameters

  self | Input image to modify
  mode | Bit field specifying which special value(s) to reject

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.

## cpl_image_save()

cpl_error_code cpl_image_save | ( | const cpl_image * | self,
|  | const char * | filename,
|  | cpl_type | type,
|  | const cpl_propertylist * | plist,
|  | unsigned | mode )

Save an image to a FITS file.

Parameters

  self | Image to write to disk or NULL
  filename | Name of the file to write to
  type | The type used to represent the data in the file
  plist | Property list for the output header or NULL
  mode | The desired output options

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

## cpl_image_set()

cpl_error_code cpl_image_set | ( | cpl_image * | image,
|  | cpl_size | xpos,
|  | cpl_size | ypos,
|  | double | value )

Set the pixel at the given position to the given value.

Parameters

  image | input image.
  xpos | Pixel x position (FITS convention, 1 for leftmost)
  ypos | Pixel y position (FITS convention, 1 for lowest)
  value | New pixel value

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.

## cpl_image_set_bpm()

cpl_mask * cpl_image_set_bpm | ( | cpl_image * | self,
|  | cpl_mask * | bpm )

Replace the bad pixel map of the image.

Parameters

  self | Image to modfify
  bpm | Bad Pixel Map (BPM) to set, replacing the old one, or NULL

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

## cpl_image_set_complex()

cpl_error_code cpl_image_set_complex | ( | cpl_image * | image,
|  | cpl_size | xpos,
|  | cpl_size | ypos,
|  | double complex | value )

Set the pixel at the given position to the given complex value.

Parameters

  image | input image.
  xpos | Pixel x position (FITS convention, 1 for leftmost)
  ypos | Pixel y position (FITS convention, 1 for lowest)
  value | New pixel value

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.

## cpl_image_shift()

cpl_error_code cpl_image_shift | ( | cpl_image * | self,
|  | cpl_size | dx,
|  | cpl_size | dy )

Shift an image by integer offsets.

Parameters

  self | The image to shift in place
  dx | The shift in X
  dy | The shift in Y

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

## cpl_image_subtract()

cpl_error_code cpl_image_subtract | ( | cpl_image * | im1,
|  | const cpl_image * | im2 )

Subtract two images, store the result in the first image.

Parameters

  im1 | first operand.
  im2 | second operand.

Returns
  the _cpl_error_code_ or CPL_ERROR_NONE

See also
  cpl_image_add()

## cpl_image_subtract_create()

cpl_image * cpl_image_subtract_create | ( | const cpl_image * | image1,
|  | const cpl_image * | image2 )

Subtract two images.

Parameters

  image1 | first operand
  image2 | second operand

Returns
  1 newly allocated image or NULL on error

See also
  cpl_image_add_create()

## cpl_image_subtract_scalar()

cpl_error_code cpl_image_subtract_scalar | ( | cpl_image * | self,
|  | double | scalar )

Elementwise subtraction of a scalar from an image.

Parameters

  self | Image to be modified in place.
  scalar | Number to subtract

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

## cpl_image_subtract_scalar_create()

cpl_image * cpl_image_subtract_scalar_create | ( | const cpl_image * | image,
|  | double | subtrahend )

Create an image by elementwise subtraction of a scalar from an image.

Parameters

  image | Image to be subtracted from
  subtrahend | Number to subtract

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

See also
  cpl_image_subtract_scalar
  cpl_image_add_scalar_create

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

Referenced by cpl_plot_image().

## cpl_image_threshold()

cpl_error_code cpl_image_threshold | ( | cpl_image * | image_in,
|  | double | lo_cut,
|  | double | hi_cut,
|  | double | assign_lo_cut,
|  | double | assign_hi_cut )

Threshold an image to a given interval.

Parameters

  image_in | Image to threshold.
  lo_cut | Lower bound.
  hi_cut | Higher bound.
  assign_lo_cut | Value to assign to pixels below low bound.
  assign_hi_cut | Value to assign to pixels above high bound.

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

## cpl_image_turn()

cpl_error_code cpl_image_turn | ( | cpl_image * | self,
|  | int | rot )

Rotate an image by a multiple of 90 degrees clockwise.

Parameters

  self | The image to rotate in place.
  rot | The multiple: -1 is a rotation of 90 deg counterclockwise.

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

## cpl_image_unset_bpm()

cpl_mask * cpl_image_unset_bpm | ( | cpl_image * | self | ) |

Remove the bad pixel map from the image.

Parameters

  self | image to process

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

Note
  NULL is returned if the image has no bad pixel map
  The returned mask must be deallocated using cpl_mask_delete().

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

## cpl_image_unwrap()

void * cpl_image_unwrap | ( | cpl_image * | d | ) |

Free memory associated to an cpl_image object, but the pixel buffer.

Parameters

  d | Image to destroy.

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

## cpl_image_warp()

cpl_error_code cpl_image_warp | ( | cpl_image * | out,
|  | const cpl_image * | in,
|  | const cpl_image * | deltax,
|  | const cpl_image * | deltay,
|  | const cpl_vector * | xprofile,
|  | double | xradius,
|  | const cpl_vector * | yprofile,
|  | double | yradius )

Warp an image.

Parameters

  out | Pre-allocated destination image to hold the result
  in | Source image to warp
  deltax | The x shift of each pixel, same image size as out
  deltay | The y shift of each pixel, same image size as out
  xprofile | Interpolation weight as a function of the distance in X
  xradius | Positive inclusion radius in the X-dimension
  yprofile | Interpolation weight as a function of the distance in Y
  yradius | Positive inclusion radius in the Y-dimension

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

## cpl_image_warp_polynomial()

cpl_error_code cpl_image_warp_polynomial | ( | cpl_image * | out,
|  | const cpl_image * | in,
|  | const cpl_polynomial * | poly_x,
|  | const cpl_polynomial * | poly_y,
|  | const cpl_vector * | xprofile,
|  | double | xradius,
|  | const cpl_vector * | yprofile,
|  | double | yradius )

Warp an image according to a 2D polynomial transformation.

Parameters

  out | Pre-allocated image to hold the result
  in | Image to warp.
  poly_x | Defines source x-pos corresponding to destination (u,v).
  poly_y | Defines source y-pos corresponding to destination (u,v).
  xprofile | Interpolation weight as a function of the distance in X
  xradius | Positive inclusion radius in the X-dimension
  yprofile | Interpolation weight as a function of the distance in Y
  yradius | Positive inclusion radius in the Y-dimension

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));

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:

- 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_ensure, cpl_ensure_code, cpl_error_get_code(), CPL_ERROR_ILLEGAL_INPUT, CPL_ERROR_INVALID_TYPE, CPL_ERROR_NONE, CPL_ERROR_NULL_INPUT, cpl_image_reject_from_mask(), cpl_mask_delete(), cpl_mask_get_data(), cpl_mask_get_data_const(), cpl_mask_new(), cpl_polynomial_get_dimension(), cpl_vector_delete(), cpl_vector_get_data(), cpl_vector_get_data_const(), cpl_vector_get_size(), and cpl_vector_new().

## cpl_image_wrap_double()

cpl_image * cpl_image_wrap_double | ( | cpl_size | nx,
|  | cpl_size | ny,
|  | double * | pixels )

Create a double image using an existing pixel buffer.

Parameters

  nx | Size in x (the number of columns)
  ny | Size in y (the number of rows)
  pixels | double * pixel data

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

See also
  cpl_image_new

The pixel array is set to point to that of the argument. The pixel array must contain nx*ny doubles.

The allocated image must be deallocated with cpl_image_unwrap().

Possible _cpl_error_code_ set in this function:

- CPL_ERROR_NULL_INPUT if an input pointer is NULL
- CPL_ERROR_ILLEGAL_INPUT if nx or ny is non-positive or zero.

References cpl_ensure, CPL_ERROR_NULL_INPUT, and CPL_TYPE_DOUBLE.

Referenced by cpl_image_divide_create(), cpl_vector_cycle(), and cpl_vector_filter_median_create().

## cpl_image_wrap_double_complex()

cpl_image * cpl_image_wrap_double_complex | ( | cpl_size | nx,
|  | cpl_size | ny,
|  | double complex * | pixels )

Create a double complex image using an existing pixel buffer.

Parameters

  nx | Size in x (the number of columns)
  ny | Size in y (the number of rows)
  pixels | double complex * pixel data.

Returns
  1 newly allocated cpl_image or NULL on error

See also
  cpl_image_wrap_double()

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

References cpl_ensure, CPL_ERROR_NULL_INPUT, and CPL_TYPE_DOUBLE_COMPLEX.

Referenced by cpl_image_divide_create().

## cpl_image_wrap_float()

cpl_image * cpl_image_wrap_float | ( | cpl_size | nx,
|  | cpl_size | ny,
|  | float * | pixels )

Create a float image using an existing pixel buffer.

Parameters

  nx | Size in x (the number of columns)
  ny | Size in y (the number of rows)
  pixels | float * pixel data.

Returns
  1 newly allocated cpl_image or NULL on error

See also
  cpl_image_wrap_double()

References cpl_ensure, CPL_ERROR_NULL_INPUT, and CPL_TYPE_FLOAT.

Referenced by cpl_image_divide_create().

## cpl_image_wrap_float_complex()

cpl_image * cpl_image_wrap_float_complex | ( | cpl_size | nx,
|  | cpl_size | ny,
|  | float complex * | pixels )

Create a float complex image using an existing pixel buffer.

Parameters

  nx | Size in x (the number of columns)
  ny | Size in y (the number of rows)
  pixels | float complex * pixel data.

Returns
  1 newly allocated cpl_image or NULL on error

See also
  cpl_image_wrap_double_complex()

References cpl_ensure, CPL_ERROR_NULL_INPUT, and CPL_TYPE_FLOAT_COMPLEX.

Referenced by cpl_image_divide_create().

## cpl_image_wrap_int()

cpl_image * cpl_image_wrap_int | ( | cpl_size | nx,
|  | cpl_size | ny,
|  | int * | pixels )

Create an integer image using an existing pixel buffer.

Parameters

  nx | Size in x (the number of columns)
  ny | Size in y (the number of rows)
  pixels | int * pixel data.

Returns
  1 newly allocated cpl_image or NULL on error

See also
  cpl_image_wrap_double()

References cpl_ensure, CPL_ERROR_NULL_INPUT, and CPL_TYPE_INT.

Referenced by cpl_geom_img_offset_saa(), cpl_image_divide_create(), and cpl_image_new_from_mask().

## cpl_image_xor()

cpl_error_code cpl_image_xor | ( | cpl_image * | self,
|  | const cpl_image * | first,
|  | const cpl_image * | second )

The bit-wise xor of two images with integer pixels.

Parameters

  self | Pre-allocated image to hold the result
  first | First operand, or NULL for an in-place operation
  second | Second operand

Returns
  CPL_ERROR_NONE or the relevant the _cpl_error_code_ on error

Note
  CPL_TYPE_INT is required

See also
  cpl_mask_xor() 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.

## cpl_image_xor_scalar()

cpl_error_code cpl_image_xor_scalar | ( | cpl_image * | self,
|  | const cpl_image * | first,
|  | cpl_bitmask | second )

The bit-wise xor of a scalar and an image with integer pixels.

Parameters

  self | Pre-allocated image to hold the result
  first | First operand, or NULL for an in-place operation
  second | Second operand (scalar)

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

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.

## cpl_vector_new_from_image_column()

cpl_vector * cpl_vector_new_from_image_column | ( | const cpl_image * | image_in,
|  | cpl_size | pos )

Extract a column from an image.

Parameters

  image_in | Input image
  pos | Position of the column (1 for the left one)

Returns
  1 newly allocated cpl_vector or NULL on error

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

The bad pixels map is not taken into account in this function.

Possible _cpl_error_code_ set in this function:

- CPL_ERROR_NULL_INPUT if an input pointer is NULL
- CPL_ERROR_ILLEGAL_INPUT if pos is 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, CPL_ERROR_NULL_INPUT, cpl_vector_delete(), cpl_vector_get_data(), and cpl_vector_new().

Referenced by cpl_image_get_fwhm().

## cpl_vector_new_from_image_row()

cpl_vector * cpl_vector_new_from_image_row | ( | const cpl_image * | image_in,
|  | cpl_size | pos )

Extract a row from an image.

Parameters

  image_in | Input image
  pos | Position of the row (1 for the bottom one)

Returns
  1 newly allocated cpl_vector or NULL on error

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

The bad pixels map is not taken into account in this function.

Possible _cpl_error_code_ set in this function:

- CPL_ERROR_NULL_INPUT if an input pointer is NULL
- CPL_ERROR_ILLEGAL_INPUT if pos is 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, CPL_ERROR_NULL_INPUT, cpl_vector_delete(), cpl_vector_get_data(), and cpl_vector_new().

Referenced by cpl_image_get_fwhm().