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

Images input and output


Functions

cpl_image * cpl_image_new (int nx, int ny, cpl_type type)
 Allocate an image structure and pixel buffer for a image.
cpl_image * cpl_image_wrap_double (int nx, int ny, const double *pixels)
 Create a double image using an existing pixel buffer.
cpl_image * cpl_image_wrap_float (int nx, int ny, const float *pixels)
 Create a float image using an existing pixel buffer.
cpl_image * cpl_image_wrap_int (int nx, int ny, const int *pixels)
 Create an integer image using an existing pixel buffer.
cpl_image * cpl_image_load (const char *filename, cpl_type im_type, int pnum, int xtnum)
 Load an image from a FITS file.
cpl_image * cpl_image_new_from_mask (const cpl_mask *mask)
 Create an int image from a mask.
cpl_type cpl_image_get_type (const cpl_image *img)
 Get the image type.
int cpl_image_get_size_x (const cpl_image *img)
 Get the image x size.
int cpl_image_get_size_y (const cpl_image *img)
 Get the image y size.
double cpl_image_get (const cpl_image *image, int xpos, int ypos, int *pis_rejected)
 Get the value of a pixel at a given position.
cpl_error_code cpl_image_set (cpl_image *image, int xpos, int ypos, double value)
 Set the pixel at the given position to the given value.
void * cpl_image_get_data (const cpl_image *img)
 Gets the pixel data.
double * cpl_image_get_data_double (const cpl_image *img)
 Get the data as a double array.
float * cpl_image_get_data_float (const cpl_image *img)
 Get the data as a float array.
int * cpl_image_get_data_int (const cpl_image *img)
 Get the data as a integer array.
void cpl_image_delete (cpl_image *d)
 Free memory associated to an cpl_image object.
void * cpl_image_unwrap (cpl_image *d)
 Free memory associated to an cpl_image object, but the pixel buffer.
cpl_image * cpl_image_duplicate (const cpl_image *src)
 Copy an image.
cpl_image * cpl_image_cast (const cpl_image *im, cpl_type type)
 convert a cpl_image to a given type
cpl_error_code cpl_image_fill_rejected (cpl_image *im, double a)
 Set the bad pixels in an image to a fixed value.
cpl_error_code cpl_image_save (const cpl_image *to_save, const char *filename, cpl_type_bpp bpp, const cpl_propertylist *pl, unsigned mode)
 Save an image to a FITS file.
void cpl_image_delete_imaginary (cpl_image *image)
 Cast a complex image to real by freeing its imaginary part.

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_image* cpl_image_cast const cpl_image *  im,
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 or CPL_TYPE_INT.

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

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 with a cpl_image.

void cpl_image_delete_imaginary cpl_image *  image  ) 
 

Cast a complex image to real by freeing its imaginary part.

Parameters:
image Image to cast
Returns:
void
Do nothing if the image NULL or if it is of a type other than CPL_TYPE_COMPLEX, otherwise on return the image is of type CPL_TYPE_DOUBLE.

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

Images can be CPL_TYPE_FLOAT, CPL_TYPE_INT, 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_ILLEGAL_INPUT
  • CPL_ERROR_TYPE_MISMATCH if the passed image type is not supported

cpl_error_code cpl_image_fill_rejected cpl_image *  im,
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
Images can be CPL_TYPE_FLOAT, CPL_TYPE_INT, 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
  • CPL_ERROR_TYPE_MISMATCH if the passed image type is not supported

double cpl_image_get const cpl_image *  image,
int  xpos,
int  ypos,
int *  pis_rejected
 

Get the value of a pixel at a given position.

Parameters:
image Input image.
xpos Pixel x position (FITS convention)
ypos Pixel y position (FITS convention)
pis_rejected 1 if the pixel is bad, 0 if good, negative on error
Returns:
The pixel value (cast to a double) or undefined if *pis_rejected
The return value is defined iff the pixel is not flagged as rejected, i. e. when *pis_rejected == 0.

In case of an error, the _cpl_error_code_ code is set.

Images can be CPL_TYPE_FLOAT, CPL_TYPE_INT 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

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

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.

The pixels are stored in a one dimensional array. The pixel value PIXVAL at position (i, j) in the image - (0, 0) is the lower left pixel, i gives the column position from left to right, j gives the row position from bottom to top - is given by : PIXVAL = array[i + j*nx] ; where nx is the x size of the image and array is the data array returned by this function. array can be used to access or modify the pixel value in the image.

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 double

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

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

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, or CPL_TYPE_INVALID on NULL input).
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_load const char *  filename,
cpl_type  im_type,
int  pnum,
int  xtnum
 

Load an image from a FITS file.

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. This type is there to specify the type of the cpl_image that will be created by the function. It is totally independant from the way the data are stored in the FITS file. A FITS image containg float pixels can be loaded as a cpl_image of type double. In this case, the user would specify CPL_TYPE_DOUBLE as im_type.

'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_IO if the data cannot be loaded from the file or if the file does not exist
  • CPL_ERROR_TYPE_MISMATCH if the passed image type is not supported

cpl_image* cpl_image_new int  nx,
int  ny,
cpl_type  type
 

Allocate an image structure and pixel buffer for a image.

Parameters:
nx Size in x
ny Size in y
type The pixel type
Returns:
1 newly allocated cpl_image or NULL in case of an error
Allocates space for the cpl_image structure and sets the dimensions and type of pixel data. The pixel buffer is allocated and initialised to zero. The pixel array will contain nx*ny values being the image pixels from the lower left to the upper right line by line.

Supported pixel types are CPL_TYPE_INT, CPL_TYPE_FLOAT and CPL_TYPE_DOUBLE.

The returned cpl_image must be deallocated using cpl_image_delete().

Possible _cpl_error_code_ set in this function:

  • CPL_ERROR_ILLEGAL_INPUT if nx or ny is negative
  • CPL_ERROR_TYPE_MISMATCH if the passed image type is not supported

cpl_image* cpl_image_new_from_mask const cpl_mask *  mask  ) 
 

Create an int image from a mask.

Parameters:
mask the original mask
Returns:
1 newly allocated cpl_image or NULL in error case
The created image is of type CPL_TYPE_INT.

Possible _cpl_error_code_ set in this function:

  • CPL_ERROR_NULL_INPUT if (one of) the input pointer(s) is NULL

cpl_error_code cpl_image_save const cpl_image *  to_save,
const char *  filename,
cpl_type_bpp  bpp,
const cpl_propertylist pl,
unsigned  mode
 

Save an image to a FITS file.

Parameters:
to_save Image to write to disk or NULL
filename Name of the file to write
bpp Bits per pixel
pl Property list for the output header or NULL
mode The desired output options (combined with bitwise or)
Returns:
CPL_ERROR_NONE or the relevant _cpl_error_code_ on error
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. If the image is not provided, the created file will only contain the primary header. This can be useful to create multiple extension files.

The requested pixel depth (bpp) follows the FITS convention. Possible values are CPL_BPP_8_UNSIGNED (8), CPL_BPP_16_SIGNED (16), CPL_BPP_32_SIGNED (32), CPL_BPP_IEEE_FLOAT (-32), CPL_BPP_IEEE_DOUBLE (-64) or CPL_BPP_DEFAULT.

Supported image types are CPL_TYPE_DOUBLE, CPL_TYPE_FLOAT, CPL_TYPE_INT.

Supported output modes are CPL_IO_DEFAULT (create a new file) and CPL_IO_EXTEND (append to an existing file)

If you are in append mode, make sure that the file has writing permissions. You may have problems if you create a file in your application and append something to it with the umask set to 222. In this case, the file created by your application would not be writable, and the append would fail.

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 bpp value or the mode is not supported
  • CPL_ERROR_TYPE_MISMATCH if the passed image type is not supported
  • CPL_ERROR_FILE_NOT_CREATED if the output file cannot be created
  • CPL_ERROR_FILE_IO if the data cannot be written in the file

cpl_error_code cpl_image_set cpl_image *  image,
int  xpos,
int  ypos,
double  value
 

Set the pixel at the given position to the given value.

Parameters:
image input image.
xpos pixel x position (FITS convention)
ypos pixel y position (FITS convention)
value New pixel value
Returns:
CPL_ERROR_NONE or the relevant _cpl_error_code_ on error
Images can be CPL_TYPE_FLOAT, CPL_TYPE_INT, CPL_TYPE_DOUBLE or CPL_TYPE_COMPLEX.

If the pixel is flagged as rejected, this flag is removed.

Possible _cpl_error_code_ set in this function:

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

void* cpl_image_unwrap cpl_image *  d  ) 
 

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

Parameters:
d Image to destroy.
Returns:
A pointer to the data array or NULL if the input is NULL.
Frees all memory associated to an cpl_image, except the pixel buffer. cpl_image_unwrap() is provided for images that are constructed by passing a pixel buffer to one of cpl_image_wrap_{double,float,int}().

Note:
The pixel buffer must subsequently be deallocated. Failure to do so will result in a memory leak.

cpl_image* cpl_image_wrap_double int  nx,
int  ny,
const double *  pixels
 

Create a double image using an existing pixel buffer.

Parameters:
nx Size in x
ny Size in y
pixels double * pixel data
Returns:
1 newly allocated cpl_image or NULL in case of an error
See also:
cpl_image_new
The pixel array is set to point to that of the argument. The pixel array must contain nx*ny doubles.

The allocated image must be deallocated with cpl_image_unwrap().

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 nx or ny is negative or zero.

cpl_image* cpl_image_wrap_float int  nx,
int  ny,
const float *  pixels
 

Create a float image using an existing pixel buffer.

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

cpl_image* cpl_image_wrap_int int  nx,
int  ny,
const int *  pixels
 

Create an integer image using an existing pixel buffer.

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


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