Main Page | Modules | Alphabetical List | Class List | Directories | Class Members

Images basic operation routines


Functions

cpl_image * cpl_image_add_create (const cpl_image *image1, const cpl_image *image2)
 Add two images.
cpl_image * cpl_image_subtract_create (const cpl_image *image1, const cpl_image *image2)
 Subtract two images.
cpl_image * cpl_image_multiply_create (const cpl_image *image1, const cpl_image *image2)
 Multiply two images.
cpl_image * cpl_image_divide_create (const cpl_image *image1, const cpl_image *image2)
 Divide two images.
cpl_error_code cpl_image_add (cpl_image *im1, const cpl_image *im2)
 Add two images, store the result in the first image.
cpl_error_code cpl_image_subtract (cpl_image *im1, const cpl_image *im2)
 Subtract two images, store the result in the first 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_error_code cpl_image_divide (cpl_image *im1, const cpl_image *im2)
 Divide two images, store the result in the first image.
cpl_error_code cpl_image_add_scalar (cpl_image *image, double addend)
 Elementwise addition of a scalar to an image.
cpl_error_code cpl_image_subtract_scalar (cpl_image *image, double subtrahend)
 Elementwise subtraction of a scalar from an image.
cpl_error_code cpl_image_multiply_scalar (cpl_image *image, double factor)
 Elementwise multiplication of an image with a scalar.
cpl_error_code cpl_image_divide_scalar (cpl_image *image, double divisor)
 Elementwise division of an image with a scalar.
cpl_error_code cpl_image_logarithm (cpl_image *image, double base)
 Compute the elementwise logarithm of the image.
cpl_error_code cpl_image_exponential (cpl_image *image, double base)
 Compute the elementwise exponential of the image.
cpl_error_code cpl_image_power (cpl_image *image, double exponent)
 Compute the elementwise power of the image.
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_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_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_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_divide_scalar_create (const cpl_image *image, double divisor)
 Create a new image by elementwise division of an image with a scalar.
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_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_power_create (const cpl_image *image, double exponent)
 Create a new image by elementwise raising of an image to a power.
cpl_error_code cpl_image_threshold (const cpl_image *image_in, double lo_cut, double hi_cut, double assign_lo_cut_in, double assign_hi_cut_in)
 Threshold an image to a given interval.
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_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_collapse_window_create (const cpl_image *in, int llx, int lly, int urx, int ury, int direction)
 Collapse an image region along its rows or columns.
cpl_image * cpl_image_collapse_create (const cpl_image *inimage, int direction)
 Collapse an image along its rows or columns.
cpl_image * cpl_image_collapse_median_create (const cpl_image *in, int direction, int discard_lo, int discard_hi)
 Collapse an image along its rows and columns, with filtering.
cpl_image * cpl_image_extract (const cpl_image *image_in, int loleft_x, int loleft_y, int upright_x, int upright_y)
 Extract a rectangular zone from an image into another image.
cpl_vector * cpl_vector_new_from_image_row (const cpl_image *image_in, int pos)
 Extract a row from an image.
cpl_vector * cpl_vector_new_from_image_column (const cpl_image *image_in, int pos)
 Extract a column from an image.
cpl_error_code cpl_image_turn (cpl_image *im, int rot)
 Rotate an image by a multiple of 90 deg clockwise.
cpl_error_code cpl_image_shift (cpl_image *im, int x_shift, int y_shift)
 Shift an image by integer offsets.
cpl_error_code cpl_image_copy (cpl_image *im1, const cpl_image *im2, int xpos, int ypos)
 Copy one image into another.
cpl_error_code cpl_image_flip (cpl_image *im, int angle)
 Flip an image on a given miror line.
cpl_error_code cpl_image_move (cpl_image *im, int nb_cut, const int *new_pos)
 Reorganize the pixels in an image.
cpl_error_code cpl_image_fit_gaussian (const cpl_image *im, int xpos, int ypos, int 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_get_fwhm (const cpl_image *in, int xpos, int ypos, double *fwhm_x, double *fwhm_y)
 Compute FWHM values in x and y for an object.
cpl_error_code cpl_image_fft (cpl_image *image, unsigned mode)
 Fast Fourier Transform an image.

Detailed Description

This module provides functions to handle basic image processing functions like simple image operations, thresholding, image collapsing, extraction, etc...

Synopsis:
   #include "cpl_image_basic.h"

Function Documentation

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.

If the image is of type CPL_TYPE_COMPLEX the type is changed to 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_TYPE_MISMATCH if the passed image type is not supported

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 in error case
See also:
cpl_image_abs
For each pixel, out = abs(in). The returned image must be deallocated using cpl_image_delete().

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 results of the operation. The function supports images with different types among CPL_TYPE_INT, CPL_TYPE_FLOAT and 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 the input images have different sizes
  • CPL_ERROR_TYPE_MISMATCH if the passed image type is not supported

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 in error case
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.

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 have different sizes
  • CPL_ERROR_TYPE_MISMATCH if the passed image type is not supported

cpl_error_code cpl_image_add_scalar cpl_image *  image,
double  addend
 

Elementwise addition of a scalar to an image.

Parameters:
image Image to be modified in place.
addend 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.

Images can be CPL_TYPE_INT, CPL_TYPE_FLOAT, CPL_TYPE_DOUBLE or CPL_TYPE_COMPLEX.

Possible _cpl_error_code_ set in this function:

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

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.

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 in error case
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 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_TYPE_MISMATCH if the passed image type is not supported

cpl_image* cpl_image_collapse_create const cpl_image *  inimage,
int  direction
 

Collapse an image along its rows or columns.

Parameters:
inimage Image to collapse.
direction Collapsing direction.
Returns:
1 newly allocated image having 1 row or 1 column or NULL for error
Collapsing an image means building up a 1d signal by adding up all pixels on the same row or column.

  Collapse along y:
 
  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
  

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 (sym of columns) to get an image with a single column in output. Only the good pixels are collapsed. Images can be 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 (one of) the input pointer(s) is NULL
  • CPL_ERROR_TYPE_MISMATCH if the passed image type is not supported

cpl_image* cpl_image_collapse_median_create const cpl_image *  in,
int  direction,
int  discard_lo,
int  discard_hi
 

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

Parameters:
in Input image.
direction Collapsing direction.
discard_lo Low rejection parameter.
discard_hi High rejection parameter.
Returns:
1 newly allocated image having 1 row or 1 column or NULL for error
See also:
cpl_image_collapse_create()
Collapsing is done as for cpl_image_collapse_create(). The difference is that pixels are not just summed along rows or columns but sorted, the highest and lowest pixel values are removed, and the median is computed on the remaining values. All pixels are collapsed, even the bad pixels. Images can be 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 (one of) the input pointer(s) is NULL
  • CPL_ERROR_ILLEGAL_INPUT if the sum of discarded pixels is bigger than the image size in the collapsing direction
  • CPL_ERROR_TYPE_MISMATCH if the passed image type is not supported

cpl_image* cpl_image_collapse_window_create const cpl_image *  in,
int  llx,
int  lly,
int  urx,
int  ury,
int  direction
 

Collapse an image region along its rows or columns.

Parameters:
in 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 in error case
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. Images can be 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 (one of) the input pointer(s) is NULL
  • CPL_ERROR_ILLEGAL_INPUT if the specified window is not valid

cpl_error_code cpl_image_copy cpl_image *  im1,
const cpl_image *  im2,
int  xpos,
int  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.
(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 or CPL_TYPE_COMPLEX.

Possible _cpl_error_code_ set in this function:

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

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 zero. Detection of division by zero must be done by the caller.

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 in error case
See also:
cpl_image_add_create()

cpl_image_divide()

cpl_error_code cpl_image_divide_scalar cpl_image *  image,
double  divisor
 

Elementwise division of an image with a scalar.

Parameters:
image Image to be modified in place.
divisor Non-zero number to divide with
Returns:
CPL_ERROR_NONE or the relevant the _cpl_error_code_ on error
Modifies the image by dividing each of its pixels with a number.

Images can be CPL_TYPE_INT, CPL_TYPE_FLOAT, CPL_TYPE_DOUBLE or CPL_TYPE_COMPLEX.

If divisor 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 (one of) the input pointer(s) is NULL
  • CPL_ERROR_TYPE_MISMATCH if the passed image type is not supported
  • CPL_ERROR_DIVISION_BY_ZERO a division by 0 occurs

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

cpl_error_code cpl_image_exponential cpl_image *  image,
double  base
 

Compute the elementwise exponential of the image.

Parameters:
image 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 CPL_TYPE_INT, CPL_TYPE_FLOAT or CPL_TYPE_DOUBLE.

If the base is zero all pixels must be positive and if the base is negative all pixels must be integer, otherwise a cpl_error_code is returned and the image is unmodified.

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 requirements on the image are not respected
  • CPL_ERROR_TYPE_MISMATCH if the passed image type is not supported
  • CPL_ERROR_DIVISION_BY_ZERO a division by 0 occurs

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

cpl_image* cpl_image_extract const cpl_image *  image_in,
int  loleft_x,
int  loleft_y,
int  upright_x,
int  upright_y
 

Extract a rectangular zone from an image into another image.

Parameters:
image_in Input image
loleft_x Lower left X coordinate
loleft_y Lower left Y coordinate
upright_x Upper right X coordinate
upright_y Upper right Y coordinate
Returns:
1 newly allocated image or NULL in error case
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 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 (one of) the input pointer(s) is NULL
  • CPL_ERROR_ILLEGAL_INPUT if the window coordinates are not valid
  • CPL_ERROR_TYPE_MISMATCH if the passed image type is not supported

cpl_error_code cpl_image_fft cpl_image *  image,
unsigned  mode
 

Fast Fourier Transform an image.

Parameters:
image The image 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
If the image type is not CPL_TYPE_DOUBLE, CPL_TYPE_COMPLEX, then the internal pointer to the pixel-buffer may change.

Any rejected pixel us 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_TO_REAL: Output is in absence of rounding errors known to be real, discard the imaginary part and return the image as type CPL_TYPE_COMPLEX. CPL_FFT_FROM_REAL: Input is in absence of rounding errors known to be real. Has no effect unless the image is of type CPL_TYPE_COMPLEX, in which case the imaginary component is ignored. 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_TYPE_MISMATCH if the passed image type is not supported

cpl_error_code cpl_image_fit_gaussian const cpl_image *  im,
int  xpos,
int  ypos,
int  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
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 sigma in x of the gaussian or NULL
sig_y the sigma in y 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
The computed norm, xcen, ycen, sig_x, sig_y coefficients are defining the gaussian:

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

fwhm_x and fwhm_y are derived from sig_x and sig_y like: fwhm = 2 * sqrt(2*ln(2)) * sigma

Images 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 the input image pointer is NULL
  • CPL_ERROR_ILLEGAL_INPUT if xpos, ypos or size or illegal
  • CPL_ERROR_TYPE_MISMATCH if the passed image type is not supported

cpl_error_code cpl_image_flip cpl_image *  im,
int  angle
 

Flip an image on a given miror 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 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 the angle is different from the allowed values
  • CPL_ERROR_TYPE_MISMATCH if the passed image type is not supported

cpl_error_code cpl_image_get_fwhm const cpl_image *  in,
int  xpos,
int  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 (one of) the input pointer(s) 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

cpl_error_code cpl_image_logarithm cpl_image *  image,
double  base
 

Compute the elementwise logarithm of the image.

Parameters:
image 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 CPL_TYPE_INT, CPL_TYPE_FLOAT or CPL_TYPE_DOUBLE.

The base and all the pixels must be positive and the base must be different from 1, or a cpl_error_code will be returned and the image will be left unmodified.

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 base is negative or if the image contains any negative value.
  • CPL_ERROR_TYPE_MISMATCH if the passed image type is not supported
  • CPL_ERROR_DIVISION_BY_ZERO a division by 0 occurs

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

cpl_error_code cpl_image_move cpl_image *  im,
int  nb_cut,
const int *  new_pos
 

Reorganize the pixels in an image.

Parameters:
im the image to reorganize
nb_cut the number of cut in x and y
new_pos array with the nb_cut^2 new positions
Returns:
the _cpl_error_code_ or CPL_ERROR_NONE
nb_cut^2 defines in how many tiles the images will be moved. Each tile will then be moved to an other place defined in new_pos. 1 will leave the image unchanged, 2 is used to move the quadrants, etc.. new_pos contains nb_cut^2 values between 1 and nb_cut^2. The zones 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 !).

Images can be CPL_TYPE_INT, CPL_TYPE_FLOAT or CPL_TYPE_DOUBLE.

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

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 nb_cut is not strictly positive or cannot divide one of the image sizes or if the new_pos array specifies to move two tiles to the same position.
  • CPL_ERROR_TYPE_MISMATCH if the passed image type is not supported

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

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 in error case
See also:
cpl_image_add_create()

cpl_error_code cpl_image_multiply_scalar cpl_image *  image,
double  factor
 

Elementwise multiplication of an image with a scalar.

Parameters:
image Image to be modified in place.
factor Number to multiply with
Returns:
CPL_ERROR_NONE or the relevant the _cpl_error_code_ on error
See also:
cpl_image_add_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.

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

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 (one of) the input pointer(s) is NULL

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 (one of) the input pointer(s) is NULL

cpl_error_code cpl_image_power cpl_image *  image,
double  exponent
 

Compute the elementwise power of the image.

Parameters:
image 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 CPL_TYPE_INT, CPL_TYPE_FLOAT or CPL_TYPE_DOUBLE.

If the exponent is non-positive all pixels must be non-zero and if the exponent is non-integer all pixels must be non-negative, otherwise a cpl_error_code is returned and the image is unmodified.

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 requirements on the image are not respected
  • CPL_ERROR_TYPE_MISMATCH if the passed image type is not supported
  • CPL_ERROR_DIVISION_BY_ZERO a division by 0 occurs

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_exponent

cpl_image_add_scalar_create

cpl_error_code cpl_image_shift cpl_image *  im,
int  x_shift,
int  y_shift
 

Shift an image by integer offsets.

Parameters:
im the image to shift.
x_shift x shift
y_shift y shift
Returns:
the _cpl_error_code_ or CPL_ERROR_NONE
This function operates locally on the pixel buffer. The new zones (in the result image) where no new value is computed are set to 0 and flagged as bad pixels.

Images 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 the requested shift is bigger than the image size
  • CPL_ERROR_TYPE_MISMATCH if the passed image type is not supported

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* 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 in error case
See also:
cpl_image_add_create()

cpl_error_code cpl_image_subtract_scalar cpl_image *  image,
double  subtrahend
 

Elementwise subtraction of a scalar from an image.

Parameters:
image Image to be modified in place.
subtrahend Number to subtract
Returns:
CPL_ERROR_NONE or the relevant the _cpl_error_code_ on error
See also:
cpl_image_add_scalar()

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

cpl_error_code cpl_image_threshold const cpl_image *  image_in,
double  lo_cut,
double  hi_cut,
double  assign_lo_cut_in,
double  assign_hi_cut_in
 

Threshold an image to a given interval.

Parameters:
image_in Image to threshold.
lo_cut Lower bound.
hi_cut Higher bound.
assign_lo_cut_in Value to assign to pixels below low bound.
assign_hi_cut_in 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. To specify no threshold on lower bound, set lo_cut to CPL_PIXEL_MINVAL. To specify no threshold on higher bound, set hi_cut to CPL_PIXEL_MAXVAL. Images 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_TYPE_MISMATCH if the passed image type is not supported

cpl_error_code cpl_image_turn cpl_image *  im,
int  rot
 

Rotate an image by a multiple of 90 deg clockwise.

Parameters:
im the image to rotate.
rot the mutiple: -1 is a rotation of 90 deg counterclockwise.
Returns:
the _cpl_error_code_ or CPL_ERROR_NONE
This function operates locally on the pixel buffer.

Images can be CPL_TYPE_INT, CPL_TYPE_FLOAT or CPL_TYPE_DOUBLE.

rot can take one of the following values:

  • +1 to turn 90 degrees clockwise.
  • -1 to turn 90 degrees counterclockwise.
  • +2 to turn 180 degrees.

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 rot is different from the allowed values
  • CPL_ERROR_TYPE_MISMATCH if the passed image type is not supported

cpl_vector* cpl_vector_new_from_image_column const cpl_image *  image_in,
int  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 in error case
Images can be CPL_TYPE_INT, CPL_TYPE_FLOAT or CPL_TYPE_DOUBLE. The returned vector must be deallocated using cpl_vector_delete().

Possible _cpl_error_code_ set in this function:

  • CPL_ERROR_NULL_INPUT if (one of) the input pointer(s) is NULL
  • CPL_ERROR_ILLEGAL_INPUT if pos is not valid
  • CPL_ERROR_TYPE_MISMATCH if the passed image type is not supported

cpl_vector* cpl_vector_new_from_image_row const cpl_image *  image_in,
int  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 in error case
Images can be CPL_TYPE_INT, CPL_TYPE_FLOAT or CPL_TYPE_DOUBLE. The returned vector must be deallocated using cpl_vector_delete().

Possible _cpl_error_code_ set in this function:

  • CPL_ERROR_NULL_INPUT if (one of) the input pointer(s) is NULL
  • CPL_ERROR_ILLEGAL_INPUT if pos is not valid
  • CPL_ERROR_TYPE_MISMATCH if the passed image type is not supported


Generated on Mon Sep 26 14:38:17 2005 for Common Pipeline Library Reference Manual by  doxygen 1.4.1