Images basic operation routines


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_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 *image, double addend)
 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_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_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 *in, int direction, int discard_lo, int discard_hi)
 Collapse an image along its rows and columns, with filtering.
cpl_image * cpl_image_collapse_window_create (const cpl_image *self, int llx, int lly, int urx, int ury, int direction)
 Collapse an image region along its rows or columns.
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_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 *image, double divisor)
 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_exponential (cpl_image *image, 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, int llx, int lly, int urx, int ury)
 Extract a rectangular zone from an image into another image.
cpl_error_code cpl_image_fft (cpl_image *real, cpl_image *imaginary, unsigned mode)
 Fast Fourier Transform 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_flip (cpl_image *im, int angle)
 Flip an image on a given miror line.
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_logarithm (cpl_image *image, 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, int nb_cut, const int *new_pos)
 Reorganize the pixels 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 *image, double factor)
 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_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_power (cpl_image *image, 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_error_code cpl_image_shift (cpl_image *self, int dx, int 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 *image, double subtrahend)
 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 counterclockwise.
cpl_vector * cpl_vector_new_from_image_column (const cpl_image *image_in, int pos)
 Extract a column from an image.
cpl_vector * cpl_vector_new_from_image_row (const cpl_image *image_in, int pos)
 Extract a row from 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.

Possible _cpl_error_code_ set in this function:

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

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.

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

Possible _cpl_error_code_ set in this function:

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

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

Images can be CPL_TYPE_INT, CPL_TYPE_FLOAT, CPL_TYPE_DOUBLE.

Possible _cpl_error_code_ set in this function:

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

Possible _cpl_error_code_ set in this function:

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

Collapse an image along its rows or columns.

Parameters:
self Image to collapse.
direction Collapsing direction.
Returns:
1 newly allocated image having 1 row or 1 column or NULL on 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

  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 (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_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. The bad pixel map of the collapsed image is empty whatever the input is, the bad pixel maps are not used in this function. 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_image* cpl_image_collapse_window_create ( const cpl_image *  self,
int  llx,
int  lly,
int  urx,
int  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_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.
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_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.

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.

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.

If divisor is zero, the image is not modified (and an error is returned).

Possible _cpl_error_code_ set in this function:

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_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 *  in,
int  llx,
int  lly,
int  urx,
int  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 CPL_TYPE_INT, CPL_TYPE_FLOAT or CPL_TYPE_DOUBLE.

Possible _cpl_error_code_ set in this function:

cpl_error_code cpl_image_fft ( cpl_image *  real,
cpl_image *  imaginary,
unsigned  mode 
)

Fast Fourier Transform an image.

Parameters:
real The image real part to be transformed in place
imaginary 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
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 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_SWAP_HALVES: Swap the four quadrants of the result image.

Possible _cpl_error_code_ set in this function:

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, 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 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
See also:
cpl_image_iqe()
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))

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

Images can be CPL_TYPE_INT, CPL_TYPE_FLOAT or CPL_TYPE_DOUBLE.

The cpl_image_iqe() function is directly called by this function.

Possible _cpl_error_code_ set in this function:

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:

Images can be CPL_TYPE_INT, CPL_TYPE_FLOAT or CPL_TYPE_DOUBLE.

Possible _cpl_error_code_ set in this function:

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_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_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_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 on error
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:

Possible _cpl_error_code_ set in this function:

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_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 negative 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.

Following the behaviour of C99 pow() function, this function sets 0^0 = 1.

Possible _cpl_error_code_ set in this function:

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 *  self,
int  dx,
int  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_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 on error
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 ( 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 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_code cpl_image_turn ( cpl_image *  self,
int  rot 
)

Rotate an image by a multiple of 90 degrees counterclockwise.

Parameters:
self The image to rotate in place.
rot The multiple: -1 is a rotation of 90 deg clockwise.
Returns:
CPL_ERROR_NONE on success, otherwise the relevant _cpl_error_code_
Note:
The dimension of a rectangular image is changed.
Images can be CPL_TYPE_INT, CPL_TYPE_FLOAT or CPL_TYPE_DOUBLE.

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:

Possible _cpl_error_code_ set in this function:

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 on error
Images can be 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_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 on error
Images can be 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:


Generated on Wed Mar 18 09:40:12 2009 for Common Pipeline Library Reference Manual by  doxygen 1.4.7