Main Page   Modules   Alphabetical List   Compound List   Compound Members  

Images basic operation routines


Functions

cpl_image * cpl_image_add (const cpl_image *image1, const cpl_image *image2)
 Add two images. More...

cpl_image * cpl_image_subtract (const cpl_image *image1, const cpl_image *image2)
 Subtract two images. More...

cpl_image * cpl_image_multiply (const cpl_image *image1, const cpl_image *image2)
 Multiply two images. More...

cpl_image * cpl_image_divide (const cpl_image *image1, const cpl_image *image2)
 Divide two images. More...

cpl_error_code cpl_image_add_local (cpl_image *im1, const cpl_image *im2)
 Add two images, store the result in the first image. More...

cpl_error_code cpl_image_subtract_local (cpl_image *im1, const cpl_image *im2)
 Subtract two images, store the result in the first image. More...

cpl_error_code cpl_image_multiply_local (cpl_image *im1, const cpl_image *im2)
 Multiply two images, store the result in the first image. More...

cpl_error_code cpl_image_divide_local (cpl_image *im1, const cpl_image *im2)
 Divide two images, store the result in the first image. More...

cpl_image * cpl_image_const_op (const cpl_image *image_in, const double constant, const int operation)
 Arithmetic between an image and a constant. More...

cpl_error_code cpl_image_const_op_local (cpl_image *image_out, const double constant, const int operation)
 Arithmetic between an image and a constant. More...

cpl_image * cpl_image_normalize (const cpl_image *image_in, const int mode)
 Normalise pixels in an image. More...

cpl_error_code cpl_image_threshold (const cpl_image *image_in, const double lo_cut, const double hi_cut, const double assign_lo_cut_in, const double assign_hi_cut_in)
 Threshold an image to a given interval. More...

cpl_image * cpl_image_abs (const cpl_image *image_in)
 Take the absolute value of an image. More...

cpl_image * cpl_image_average (const cpl_image *image_1, const cpl_image *image_2)
 Build the average of two images. More...

cpl_image * cpl_image_collapse_subw (const cpl_image *in, const int llx, const int lly, const int urx, const int ury, const int direction)
 Collapse an image region along its rows or columns. More...

cpl_image * cpl_image_collapse (const cpl_image *inimage, const int direction)
 Collapse an image along its rows or columns. More...

cpl_image * cpl_image_collapse_median (const cpl_image *in, const int direction, const int discard_lo, const int discard_hi)
 Collapse an image along its rows and columns, with filtering. More...

cpl_image * cpl_image_extract (const cpl_image *image_in, const int loleft_x, const int loleft_y, const int upright_x, const int upright_y)
 Extract a rectangular zone from an image into another image. More...

cpl_error_code cpl_image_flip_local (cpl_image *im, const int angle)
 Flip an image on a given miror line. More...


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_image* cpl_image_abs 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
For each pixel, out = abs(in). The returned image must be deallocated using cpl_image_delete(). 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
  • CPL_ERROR_ILLEGAL_INPUT
  • CPL_ERROR_TYPE_MISMATCH

cpl_image* cpl_image_add 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
  • CPL_ERROR_ILLEGAL_INPUT
  • CPL_ERROR_TYPE_MISMATCH

cpl_error_code cpl_image_add_local 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
  • CPL_ERROR_ILLEGAL_INPUT
  • CPL_ERROR_TYPE_MISMATCH

cpl_image* cpl_image_average 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
  • CPL_ERROR_ILLEGAL_INPUT
  • CPL_ERROR_TYPE_MISMATCH

cpl_image* cpl_image_collapse const cpl_image *    inimage,
const 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
  • CPL_ERROR_ILLEGAL_INPUT
  • CPL_ERROR_TYPE_MISMATCH

cpl_image* cpl_image_collapse_median const cpl_image *    in,
const int    direction,
const int    discard_lo,
const 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
Collapsing is done as for cpl_collapse_image(). 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
  • CPL_ERROR_ILLEGAL_INPUT
  • CPL_ERROR_TYPE_MISMATCH

cpl_image* cpl_image_collapse_subw const cpl_image *    in,
const int    llx,
const int    lly,
const int    urx,
const int    ury,
const 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
llx, lly, urx, ury are the image region coordinates in FITS convention. 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
  • CPL_ERROR_ILLEGAL_INPUT

cpl_image* cpl_image_const_op const cpl_image *    image_in,
const double    constant,
const int    operation
 

Arithmetic between an image and a constant.

Parameters:
image_in  Image operand.
constant  Constant operand.
operation  Operation to perform.
Returns:
1 newly allocated image or NULL on error.
See also:
cpl_image_const_op_local()
Performs an operation between an image and a constant, returns a newly allocated image containing the result. Possible operations are:
  • '+' Addition
  • '-' Subtraction
  • '*' Multiplication
  • '/' Division
  • 'l' Logarithm
  • '^' Power
  • 'e' Exponentiation 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
  • CPL_ERROR_ILLEGAL_INPUT
  • CPL_ERROR_DIVISION_BY_ZERO
  • CPL_ERROR_TYPE_MISMATCH

cpl_error_code cpl_image_const_op_local cpl_image *    image_out,
const double    constant,
const int    operation
 

Arithmetic between an image and a constant.

Parameters:
image_out  Image operand.
constant  Constant operand.
operation  Operation to perform.
Returns:
the _cpl_error_code_ or CPL_ERROR_NONE
See also:
cpl_image_const_op()
Performs an operation between an image and a constant, stores the results in the input image buffer. Possible operations are:
  • '+' Addition
  • '-' Subtraction
  • '*' Multiplication
  • '/' Division
  • 'l' Logarithm
  • '^' Power
  • 'e' Exponentiation In case of a CPL_ERROR_ILLEGAL_INPUT, the 'l', '^' and 'e' operations may return a partly altered image. 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
  • CPL_ERROR_ILLEGAL_INPUT
  • CPL_ERROR_DIVISION_BY_ZERO
  • CPL_ERROR_TYPE_MISMATCH

cpl_image* cpl_image_divide 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()

cpl_error_code cpl_image_divide_local 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_local()

cpl_image* cpl_image_extract const cpl_image *    image_in,
const int    loleft_x,
const int    loleft_y,
const int    upright_x,
const 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
  • CPL_ERROR_ILLEGAL_INPUT

cpl_error_code cpl_image_flip_local cpl_image *    im,
const 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
Possible _cpl_error_code_ set in this function:
  • CPL_ERROR_NULL_INPUT
  • CPL_ERROR_ILLEGAL_INPUT
  • CPL_ERROR_TYPE_MISMATCH

cpl_image* cpl_image_multiply 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()

cpl_error_code cpl_image_multiply_local 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_local()

cpl_image* cpl_image_normalize const cpl_image *    image_in,
const int    mode
 

Normalise pixels in an image.

Parameters:
image_in  Image operand.
mode  Normalisation mode.
Returns:
1 newly allocated image or NULL on error
Normalises an image according to a given criterion, stores the results in a newly allocated image and returns it. The returned image must be deallocated using cpl_image_delete().

Possible normalisations are:

  • NORM_SCALE sets the pixel interval to [0,1].
  • NORM_MEAN sets the mean value to 1.
  • NORM_FLUX sets the flux to 1.
  • NORM_AFLUX sets the absolute flux to 1. Images can be CPL_TYPE_FLOAT or CPL_TYPE_DOUBLE.
Possible _cpl_error_code_ set in this function:
  • CPL_ERROR_NULL_INPUT
  • CPL_ERROR_ILLEGAL_INPUT
  • CPL_ERROR_DIVISION_BY_ZERO

cpl_image* cpl_image_subtract 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()

cpl_error_code cpl_image_subtract_local 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_local()

cpl_error_code cpl_image_threshold const cpl_image *    image_in,
const double    lo_cut,
const double    hi_cut,
const double    assign_lo_cut_in,
const 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 MIN_PIX_VALUE. To specify no threshold on higher bound, set hi_cut to MAX_PIX_VALUE. 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
  • CPL_ERROR_ILLEGAL_INPUT
  • CPL_ERROR_TYPE_MISMATCH


Generated on Mon May 24 14:58:05 2004 for Common Pipeline Library Reference Manual by doxygen1.2.14 written by Dimitri van Heesch, © 1997-2002