Images functionalities that need resampling


Functions

cpl_image * cpl_image_extract_subsample (const cpl_image *image, int xstep, int ystep)
 Sub-sample an image.
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.
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.
cpl_image * cpl_image_rebin (const cpl_image *image, int xstart, int ystart, int xstep, int ystep)
 Rebin an image.
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.

Detailed Description

This module provides functions to warp images.

Synopsis:
   #include "cpl_image_resample.h"

Function Documentation

cpl_image* cpl_image_extract_subsample ( const cpl_image *  image,
int  xstep,
int  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 returned image must be deallocated using cpl_image_delete().

Possible _cpl_error_code_ set in this 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.

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

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.

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

Possible _cpl_error_code_ set in this function:

cpl_image* cpl_image_rebin ( const cpl_image *  image,
int  xstart,
int  ystart,
int  xstep,
int  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_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_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:


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