Images input and output


Functions

cpl_image * cpl_image_cast (const cpl_image *im, cpl_type type)
 convert a cpl_image to a given type
void cpl_image_delete (cpl_image *d)
 Free memory associated to an cpl_image object.
cpl_image * cpl_image_duplicate (const cpl_image *src)
 Copy an image.
cpl_error_code cpl_image_fill_rejected (cpl_image *im, double a)
 Set the bad pixels in an image to a fixed value.
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_mask * cpl_image_get_bpm (cpl_image *img)
 Gets the bad pixels map.
const cpl_mask * cpl_image_get_bpm_const (const cpl_image *img)
 Gets the bad pixels map.
void * cpl_image_get_data (cpl_image *img)
 Gets the pixel data.
const void * cpl_image_get_data_const (const cpl_image *img)
 Gets the pixel data.
double * cpl_image_get_data_double (cpl_image *img)
 Get the data as a double array.
const double * cpl_image_get_data_double_const (const cpl_image *img)
 Get the data as a double array.
float * cpl_image_get_data_float (cpl_image *img)
 Get the data as a float array.
const float * cpl_image_get_data_float_const (const cpl_image *img)
 Get the data as a float array.
int * cpl_image_get_data_int (cpl_image *img)
 Get the data as a integer array.
const int * cpl_image_get_data_int_const (const cpl_image *img)
 Get the data as a integer array.
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.
cpl_type cpl_image_get_type (const cpl_image *img)
 Get the image type.
cpl_image * cpl_image_labelise_mask_create (const cpl_mask *in, int *nbobjs)
 Labelise a mask to differentiate different objects.
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_load_window (const char *filename, cpl_type im_type, int pnum, int xtnum, int llx, int lly, int urx, int ury)
 Load an image from a FITS file.
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_new_from_mask (const cpl_mask *mask)
 Create an int image from a mask.
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.
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_unwrap (cpl_image *d)
 Free memory associated to an cpl_image object, but the pixel buffer.
cpl_image * cpl_image_wrap_double (int nx, int ny, double *pixels)
 Create a double image using an existing pixel buffer.
cpl_image * cpl_image_wrap_float (int nx, int ny, float *pixels)
 Create a float image using an existing pixel buffer.
cpl_image * cpl_image_wrap_int (int nx, int ny, int *pixels)
 Create an integer image using an existing pixel buffer.

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:

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. If the passed image is NULL, the function returns without doing anything.

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.

Possible _cpl_error_code_ set in this function:

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:

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_mask* cpl_image_get_bpm ( cpl_image *  img  ) 

Gets the bad pixels map.

Parameters:
img Image to query.
Returns:
A pointer to the mask identifiing the bad pixels or NULL.
The returned pointer refers to already allocated data. If the bad pixel map is NULL, an empty one is created.

Possible _cpl_error_code_ set in this function:

const cpl_mask* cpl_image_get_bpm_const ( const cpl_image *  img  ) 

Gets the bad pixels map.

Parameters:
img Image to query.
Returns:
A pointer to the mask identifiing the bad pixels or NULL.
See also:
cpl_image_get_bpm

void* cpl_image_get_data ( 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:

const void* cpl_image_get_data_const ( 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.
See also:
cpl_image_get_data

double* cpl_image_get_data_double ( 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:

const double* cpl_image_get_data_double_const ( 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.
See also:
cpl_image_get_data_double

float* cpl_image_get_data_float ( 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()

const float* cpl_image_get_data_float_const ( 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_float()

int* cpl_image_get_data_int ( 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()

const int* cpl_image_get_data_int_const ( 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_int()

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:

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_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_image* cpl_image_labelise_mask_create ( const cpl_mask *  in,
int *  nbobjs 
)

Labelise a mask to differentiate different objects.

Parameters:
in mask to labelise
nbobjs number of objects found.
Returns:
A newly allocated label image or NULL in error case
This function labelises all blobs in a mask. All 4-neighbour connected zones set to 1 in the input mask will end up in the returned integer image as zones where all pixels are set to the same (unique for this blob in this image) label. A non-recursive flood-fill is applied to label the zones. The flood-fill is dimensioned by the number of lines in the image, and the maximal number of lines possibly covered by a blob. The returned image must be deallocated with cpl_image_delete()

Possible _cpl_error_code_ set in this function:

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 (NAXIS=2 or 3), using cfitsio.

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.

The loaded image has an empty bad pixel map.

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_image* cpl_image_load_window ( const char *  filename,
cpl_type  im_type,
int  pnum,
int  xtnum,
int  llx,
int  lly,
int  urx,
int  ury 
)

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.
llx Specifies the window position
lly Specifies the window position
urx Specifies the window position
ury Specifies the window position
Returns:
1 newly allocated image, or NULL if image cannot be loaded.
See also:
cpl_image_load
The window position is specified starting with 1 to the number of pixel. Lower left pixel is (1, 1).

Possible _cpl_error_code_ set in this function:

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_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_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 cfitsio. 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_16_UNSIGNED (-16), CPL_BPP_32_SIGNED (32), CPL_BPP_IEEE_FLOAT (-32), CPL_BPP_IEEE_DOUBLE (-64)

In the case of CPL_BPP_16_UNSIGNED, the BITPIX stays 16, the data are stored as signed (32768 is subtracted to the image) and BZERO is set to 32768 as specified by the FITS standard.

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

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

Possible _cpl_error_code_ set in this function:

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,
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_image* cpl_image_wrap_float ( int  nx,
int  ny,
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,
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 Thu Mar 6 17:29:20 2008 for Common Pipeline Library Reference Manual by  doxygen 1.5.1