Main Page   Modules   Alphabetical List   Compound List   Compound Members  

Images input and output


Functions

cpl_image * cpl_image_new_empty (void)
 Allocate an empty image structure. More...

cpl_image * cpl_image_new_double (const int nx, const int ny, const double *pixels, const cpl_image *badpixelmap)
 Allocate an image structure and pixel buffer for a double image. More...

cpl_image * cpl_image_new_float (const int nx, const int ny, const float *pixels, const cpl_image *badpixelmap)
 Allocate an image structure and pixel buffer for a float image. More...

cpl_image * cpl_image_new_int (const int nx, const int ny, const int *pixels, const cpl_image *badpixelmap)
 Allocate an image structure and pixel buffer for a integer image. More...

cpl_image * cpl_image_new_bin (const int nx, const int ny, const cpl_binary *pixels, const cpl_image *badpixelmap)
 Allocate an image structure and pixel buffer for a cpl_binary image. More...

cpl_image * cpl_image_load (const char *filename, const cpl_type im_type, const int pnum, const int xtnum)
 Load an image from a FITS file as a float image. More...

cpl_type cpl_image_get_type (const cpl_image *img)
 Get the image type. More...

int cpl_image_get_nx (const cpl_image *img)
 Get the image x size. More...

int cpl_image_get_ny (const cpl_image *img)
 Get the image y size. More...

void * cpl_image_get_data (const cpl_image *img)
 Gets the pixel data. More...

double * cpl_image_get_data_double (const cpl_image *img)
 Get the data as a double array. More...

float * cpl_image_get_data_float (const cpl_image *img)
 Get the data as a float array. More...

int * cpl_image_get_data_int (const cpl_image *img)
 Get the data as a integer array. More...

cpl_binary * cpl_image_get_data_bin (const cpl_image *img)
 Get the data as a cpl_binary array. More...

cpl_error_code cpl_image_set_type (cpl_image *img, const cpl_type type)
 Sets the type of an image. More...

void cpl_image_delete (cpl_image *d)
 Free memory associated to an cpl_image object. More...

void cpl_image_delete_but_data (cpl_image *d)
 Free memory associated to an cpl_image object, but the pixel buffer. More...

cpl_error_code cpl_image_clear (cpl_image *img)
 Clears an image. More...

cpl_image * cpl_image_duplicate (const cpl_image *src)
 Copy an image. More...

cpl_image * cpl_image_convert (const cpl_image *im, const cpl_type type)
 convert a cpl_image to a given type. More...

cpl_error_code cpl_image_resize (cpl_image *img, const int nx, const int ny)
 Resizes an image. More...

int cpl_image_is_empty (const cpl_image *img)
 Check whether an image is empty. More...

cpl_error_code cpl_image_copy_from_fits (cpl_image *img, const char *filename, int pnum, int xtnum)
 Fill an image from a FITS file. More...

cpl_error_code cpl_image_set_badpixel (cpl_image *im, const double a)
 Set the bad pixels in an image to a fixed value. More...

cpl_error_code cpl_image_save (const cpl_image *to_save, const char *filename, const int bpp, cpl_plist *pl)
 Save an image to a FITS file. More...


Detailed Description

This module provides functions to handle input and output for images.

Functions are provided here to load and save images from and to FITS files, to generate empty images or to deallocated an image.

Synopsis:
   #include "cpl_image_io.h"

Function Documentation

cpl_error_code cpl_image_clear cpl_image *    img
 

Clears an image.

Parameters:
img  Image to clear.
Returns:
the _cpl_error_code_ or CPL_ERROR_NONE
See also:
cpl_image_is_empty()
The function clears an image structure, i.e. deallocates the any pixel buffer associated to the image.

Possible _cpl_error_code_ set in this function:

  • CPL_ERROR_NULL_INPUT

cpl_image* cpl_image_convert const cpl_image *    im,
const cpl_type    type
 

convert a cpl_image to a given type.

Parameters:
im  The image to convert.
type  The destination type
Returns:
the newly allocated cpl_image or NULL in error case
Supported allowed types are CPL_TYPE_DOUBLE, CPL_TYPE_FLOAT, CPL_TYPE_UCHAR (for binary image) or CPL_TYPE_INT.

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_copy_from_fits cpl_image *    img,
const char *    filename,
int    pnum,
int    xtnum
 

Fill an image from a FITS file.

Parameters:
img  Image structure to be filled.
filename  Name of the file.
pnum  Plane number in the file.
xtnum  Extension number in the file.
Returns:
the _cpl_error_code_ or CPL_ERROR_NONE
This function loads an image from a FITS file and fills an existing image structure. During loading the pixel data the pixel values are converted to the target type defined by the image structure.

Possible _cpl_error_code_ set in this function:

  • CPL_ERROR_NULL_INPUT
  • CPL_ERROR_ILLEGAL_INPUT

void cpl_image_delete cpl_image *    d
 

Free memory associated to an cpl_image object.

Parameters:
d  Image to destroy.
Returns:
void
Frees all memory associated to a cpl_image.

void cpl_image_delete_but_data cpl_image *    d
 

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

Parameters:
d  Image to destroy.
Returns:
void
Frees all memory associated to an cpl_image, except the pixel buffer. The pixel buffer must be deallocated by the caller. cpl_image_delete_but_data() is provided for images that are constructed by passing a pixel buffer to one of cpl_image_new_{double,float,int,bin}().

cpl_image* cpl_image_duplicate const cpl_image *    src
 

Copy an image.

Parameters:
src  Source image.
Returns:
1 newly allocated image, or NULL on error.
Copy an image into a new image object. The pixels and the bad pixel map are also copied. The returned image must be deallocated using cpl_image_delete().

Possible _cpl_error_code_ set in this function:

  • CPL_ERROR_NULL_INPUT
  • CPL_ERROR_ILLEGAL_INPUT
  • CPL_ERROR_TYPE_MISMATCH

void* cpl_image_get_data const cpl_image *    img
 

Gets the pixel data.

Parameters:
img  Image to query.
Returns:
A pointer to the image pixel data or NULL in error case.
The returned pointer refers to already allocated data.

Possible _cpl_error_code_ set in this function:

  • CPL_ERROR_NULL_INPUT

cpl_binary* cpl_image_get_data_bin const cpl_image *    img
 

Get the data as a cpl_binary array.

Parameters:
img  a cpl_image object
Returns:
pointer to the cpl_binary data array or NULL in error case.
See also:
cpl_image_get_data_double()

double* cpl_image_get_data_double const cpl_image *    img
 

Get the data as a double array.

Parameters:
img  a cpl_image object
Returns:
pointer to the double data array or NULL in error case.
The returned pointer refers to already allocated data.

Possible _cpl_error_code_ set in this function:

  • CPL_ERROR_NULL_INPUT
  • CPL_ERROR_TYPE_MISMATCH

float* cpl_image_get_data_float const cpl_image *    img
 

Get the data as a float array.

Parameters:
img  a cpl_image object
Returns:
pointer to the float data array or NULL in error case.
See also:
cpl_image_get_data_double()

int* cpl_image_get_data_int const cpl_image *    img
 

Get the data as a integer array.

Parameters:
img  a cpl_image object
Returns:
pointer to the integer data array or NULL in error case.
See also:
cpl_image_get_data_double()

int cpl_image_get_nx const cpl_image *    img
 

Get the image x size.

Parameters:
img  a cpl_image object
Returns:
The image x size, or -1 on NULL input
Possible _cpl_error_code_ set in this function:
  • CPL_ERROR_NULL_INPUT

int cpl_image_get_ny const cpl_image *    img
 

Get the image y size.

Parameters:
img  a cpl_image object
Returns:
The image y size, or -1 on NULL input
Possible _cpl_error_code_ set in this function:
  • CPL_ERROR_NULL_INPUT

cpl_type cpl_image_get_type const cpl_image *    img
 

Get the image type.

Parameters:
img  a cpl_image object
Returns:
The image type (CPL_TYPE_DOUBLE, CPL_TYPE_FLOAT, CPL_TYPE_INT, CPL_TYPE_UCHAR (binary images) or CPL_TYPE_INVALID on NULL input).
Possible _cpl_error_code_ set in this function:
  • CPL_ERROR_NULL_INPUT

int cpl_image_is_empty const cpl_image *    img
 

Check whether an image is empty.

Parameters:
img  Image to test.
Returns:
1 if the image is empty, 0 otherwise.
The function tests if an image is empty or not. An image is found to be empty if there is no pixel buffer associated to it and its x and y dimensions are both 0.

Possible _cpl_error_code_ set in this function:

  • CPL_ERROR_NULL_INPUT

cpl_image* cpl_image_load const char *    filename,
const cpl_type    im_type,
const int    pnum,
const int    xtnum
 

Load an image from a FITS file as a float image.

Parameters:
filename  Name of the file to load from.
im_type  Type of the created image
pnum  Plane number in the file.
xtnum  Extension number in the file.
Returns:
1 newly allocated image, or NULL if image cannot be loaded.
This function loads an image from a FITS file, using qfits.

The returned image has to be deallocated with cpl_image_delete().

The passed type for the output image can be : CPL_TYPE_FLOAT, CPL_TYPE_DOUBLE or CPL_TYPE_INT.

'xtnum' specifies from which extension the image should be loaded. This could be 0 for the main data section (files without extension), or any number between 1 and N, where N is the number of extensions present in the file.

The requested plane number runs from 0 to nplanes-1, where nplanes is the number of planes present in the requested data section.

Examples:

  // Load as a float image the only image in FITS file (a.fits) without ext. 
  // and NAXIS=2.
  cpl_image * im = cpl_image_load("a.fits", CPL_TYPE_FLOAT, 0, 0);
  // Load as a double image the first plane in a FITS cube (a.fits) without 
  // extension, NAXIS=3 and NAXIS3=128
  cpl_image * im = cpl_image_load("a.fits", CPL_TYPE_DOUBLE, 0, 0);
  // Load as an integer image the third plane in a FITS cube (a.fits) without 
  // extension, NAXIS=3 and NAXIS3=128
  cpl_image * im = cpl_image_load("a.fits", CPL_TYPE_INT, 2, 0);
  // Load as a double image the first plane from extension 5
  cpl_image * im = cpl_image_load("a.fits", CPL_TYPE_DOUBLE, 0, 5);
  // Load as a double image the third plane in extension 5
  cpl_image * im = cpl_image_load("a.fits", CPL_TYPE_DOUBLE, 2, 5);

Possible _cpl_error_code_ set in this function:

  • CPL_ERROR_FILE_NOT_FOUND
  • CPL_ERROR_FILE_IO
  • CPL_ERROR_TYPE_MISMATCH

cpl_image* cpl_image_new_bin const int    nx,
const int    ny,
const cpl_binary *    pixels,
const cpl_image *    badpixelmap
 

Allocate an image structure and pixel buffer for a cpl_binary image.

Parameters:
nx  Size in x
ny  Size in y
pixels  cpl_binary * pixel data or NULL.
badpixelmap  bad pixel map or NULL.
Returns:
1 newly allocated cpl_image or NULL in error case
See also:
cpl_image_new_double()

cpl_image* cpl_image_new_double const int    nx,
const int    ny,
const double *    pixels,
const cpl_image *    badpixelmap
 

Allocate an image structure and pixel buffer for a double image.

Parameters:
nx  Size in x
ny  Size in y
pixels  double * pixel data or NULL.
badpixelmap  bad pixel map or NULL.
Returns:
1 newly allocated cpl_image or NULL in error case
Allocates space for the cpl_image structure and sets the dimensions and type of pixel data. If NULL is passed as pixels, the pixel buffer is allocated and initialised to zero, otherwise the pixels array is set to that of the argument. This pixel array should contain nx*ny values being the image pixels from the lower left to the upper right line by line. A bad pixel map may also be passed as a cpl_binary image. if pixels is NULL the returned cpl_image must be deallocated using cpl_image_delete(), otherwise it must be deallocated with cpl_image_delete_but_data().

Possible _cpl_error_code_ set in this function:

  • CPL_ERROR_ILLEGAL_INPUT

cpl_image* cpl_image_new_empty void   
 

Allocate an empty image structure.

Returns:
1 newly allocated cpl_image or NULL in error case
Allocates memory for the cpl_image structure. No pixel buffer is allocated and the structure is initialises to be empty. The returned cpl_image must be deallocated using cpl_image_delete().

cpl_image* cpl_image_new_float const int    nx,
const int    ny,
const float *    pixels,
const cpl_image *    badpixelmap
 

Allocate an image structure and pixel buffer for a float image.

Parameters:
nx  Size in x
ny  Size in y
pixels  float * pixel data or NULL.
badpixelmap  bad pixel map or NULL.
Returns:
1 newly allocated cpl_image or NULL in error case
See also:
cpl_image_new_double()

cpl_image* cpl_image_new_int const int    nx,
const int    ny,
const int *    pixels,
const cpl_image *    badpixelmap
 

Allocate an image structure and pixel buffer for a integer image.

Parameters:
nx  Size in x
ny  Size in y
pixels  int * pixel data or NULL.
badpixelmap  bad pixel map or NULL.
Returns:
1 newly allocated cpl_image or NULL in error case
See also:
cpl_image_new_double()

cpl_error_code cpl_image_resize cpl_image *    img,
const int    nx,
const int    ny
 

Resizes an image.

Parameters:
img  Image to resize.
nx  New size in x
ny  New size in y
Returns:
the _cpl_error_code_ or CPL_ERROR_NONE
The function changes the size of an image discarding the pixel buffer and its contents if it exists. For empty images the function creates a pixel buffer of appropriate size for the image's pixel type.

Possible _cpl_error_code_ set in this function:

  • CPL_ERROR_NULL_INPUT
  • CPL_ERROR_ILLEGAL_INPUT

cpl_error_code cpl_image_save const cpl_image *    to_save,
const char *    filename,
const int    bpp,
cpl_plist   pl
 

Save an image to a FITS file.

Parameters:
to_save  Image to write to disk.
filename  Name of the file to load from.
bpp  Bits per pixel
pl  Property list for the output header
Returns:
the _cpl_error_code_ or CPL_ERROR_NONE
This function saves an image to a FITS file, using qfits. If a property list is provided, it is written to the named file before the pixels are written. The requested pixel depth (bpp) follows the FITS convention. Possible values are BPP_8_UNSIGNED (8), BPP_16_SIGNED (16), BPP_32_SIGNED (32), BPP_IEEE_FLOAT (-32), BPP_IEEE_DOUBLE (-64) or BPP_DEFAULT.

Possible _cpl_error_code_ set in this function:

  • CPL_ERROR_NULL_INPUT
  • CPL_ERROR_ILLEGAL_INPUT
  • CPL_ERROR_TYPE_MISMATCH
  • CPL_ERROR_FILE_NOT_CREATED
  • CPL_ERROR_FILE_IO

cpl_error_code cpl_image_set_badpixel cpl_image *    im,
const double    a
 

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

Parameters:
im  The image to modify.
a  The fixed value
Returns:
the _cpl_error_code_ or CPL_ERROR_NONE
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_set_type cpl_image *    img,
const cpl_type    type
 

Sets the type of an image.

Parameters:
img  Image to modify.
type  new type
Returns:
the _cpl_error_code_ or CPL_ERROR_NONE
The function changes the pixel type of an image. The type of an image may be changed only if it is empty.

Possible _cpl_error_code_ set in this function:

  • CPL_ERROR_NULL_INPUT
  • CPL_ERROR_ILLEGAL_INPUT


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