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_error_code cpl_image_dump_structure (const cpl_image *self, FILE *stream)
 Dump structural information of a CPL image.
cpl_error_code cpl_image_dump_window (const cpl_image *self, int llx, int lly, int urx, int ury, FILE *stream)
 Dump pixel values in a CPL image.
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.
double complex cpl_image_get_complex (const cpl_image *image, int xpos, int ypos, int *pis_rejected)
 Get the value of a complex pixel at a given position.
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.
double complex * cpl_image_get_data_double_complex (cpl_image *img)
 Get the data as a double complex array.
const double complex * cpl_image_get_data_double_complex_const (const cpl_image *img)
 Get the data as a double complex 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.
float complex * cpl_image_get_data_float_complex (cpl_image *img)
 Get the data as a float complex array.
const float complex * cpl_image_get_data_float_complex_const (const cpl_image *img)
 Get the data as a float complex 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 *self, 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.
cpl_error_code cpl_image_set_complex (cpl_image *image, int xpos, int ypos, double complex value)
 Set the pixel at the given position to the given complex 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_double_complex (int nx, int ny, double complex *pixels)
 Create a double complex 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_float_complex (int nx, int ny, float complex *pixels)
 Create a float complex 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, CPL_TYPE_INT CPL_TYPE_DOUBLE_COMPLEX and CPL_TYPE_FLOAT_COMPLEX.

However, casting to non-complex types is only supported for non-complex types. The same is valid for complex types.

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_error_code cpl_image_dump_structure ( const cpl_image *  self,
FILE *  stream 
)

Dump structural information of a CPL image.

Parameters:
self Image to dump
stream Output stream, accepts stdout or stderr
Returns:
CPL_ERROR_NONE or the relevant _cpl_error_code_ on error
Possible _cpl_error_code_ set in this function:

cpl_error_code cpl_image_dump_window ( const cpl_image *  self,
int  llx,
int  lly,
int  urx,
int  ury,
FILE *  stream 
)

Dump pixel values in a CPL image.

Parameters:
self Image to dump
llx Specifies the window position
lly Specifies the window position
urx Specifies the window position
ury Specifies the window position
stream Output stream, accepts stdout or stderr
Returns:
CPL_ERROR_NONE or the relevant _cpl_error_code_ on error
Possible _cpl_error_code_ set in this function:

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_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 if 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 identifying 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 identifying the bad pixels or NULL.
Note:
NULL is returned if the image has no bad pixel map
See also:
cpl_image_get_bpm
Possible _cpl_error_code_ set in this function:

double complex cpl_image_get_complex ( const cpl_image *  image,
int  xpos,
int  ypos,
int *  pis_rejected 
)

Get the value of a complex pixel at a given position.

Parameters:
image Input complex 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 complex) or undefined if *pis_rejected
The return value is defined if 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_COMPLEX or CPL_TYPE_DOUBLE_COMPLEX.

Possible _cpl_error_code_ set in this function:

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:

double complex* cpl_image_get_data_double_complex ( cpl_image *  img  ) 

Get the data as a double complex array.

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

const double complex* cpl_image_get_data_double_complex_const ( const cpl_image *  img  ) 

Get the data as a double complex array.

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

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

float complex* cpl_image_get_data_float_complex ( cpl_image *  img  ) 

Get the data as a float complex array.

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

const float complex* cpl_image_get_data_float_complex_const ( const cpl_image *  img  ) 

Get the data as a float complex array.

Parameters:
img a cpl_image object
Returns:
pointer to the float complex 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 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.

Additionally, CPL_TYPE_UNSPECIFIED can be passed to inherit the FITS file type. The type of the image is defined based on the BITPIX information of the FITS file. In a later step, the type can be known through a call to cpl_image_get_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, CPL_TYPE_DOUBLE, CPL_TYPE_FLOAT_COMPLEX and CPL_TYPE_DOUBLE_COMPLEX.

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 *  self,
const char *  filename,
cpl_type_bpp  bpp,
const cpl_propertylist pl,
unsigned  mode 
)

Save an image to a FITS file.

Parameters:
self 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
Returns:
CPL_ERROR_NONE or the relevant _cpl_error_code_ on error
This function saves an image to a FITS file. If a property list is provided, it is written to the header where the image is written. The image may be NULL, in this case only the propertylist is written.

The requested bits per pixel (bpp) follows the FITS convention. Possible values are CPL_BPP_8_UNSIGNED, CPL_BPP_16_SIGNED, CPL_BPP_32_SIGNED, CPL_BPP_IEEE_FLOAT, CPL_BPP_IEEE_DOUBLE.

Additionally, the mode CPL_BPP_16_UNSIGNED is supported. In this case the data are saved as CPL_BPP_16_SIGNED, with 32768 subtracted from each pixel and BZERO 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_CREATE (create a new file) and CPL_IO_EXTEND (append to an existing file)

Note that in append mode the file must be writable (and do not take for granted that a file is writable just because it was created by the same application, as this depends from the system umask).

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:

cpl_error_code cpl_image_set_complex ( cpl_image *  image,
int  xpos,
int  ypos,
double complex  value 
)

Set the pixel at the given position to the given complex 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_COMPLEX or CPL_TYPE_DOUBLE_COMPLEX.

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_double_complex ( int  nx,
int  ny,
double complex *  pixels 
)

Create a double complex image using an existing pixel buffer.

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

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_float_complex ( int  nx,
int  ny,
float complex *  pixels 
)

Create a float complex image using an existing pixel buffer.

Parameters:
nx Size in x
ny Size in y
pixels float complex * 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 Wed Mar 18 09:40:12 2009 for Common Pipeline Library Reference Manual by  doxygen 1.4.7