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_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_from_mask (const cpl_mask *mask)
 Create an int image from a mask.
cpl_image * cpl_image_labelise_mask_create (const cpl_mask *in, int *nbobjs)
 Labelise a mask to differentiate different objects.
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.
cpl_mask * cpl_image_get_bpm (const cpl_image *img)
 Gets the bad pixels map.
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.

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

cpl_mask* cpl_image_get_bpm 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.
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:

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

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_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_ERROR_NULL_INPUT if the input mask 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 (NAXIS=2 or 3), 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.

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

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_ERROR_FILE_IO if the file does not exist
  • CPL_ERROR_BAD_FILE_FORMAT if the data cannot be loaded from the file
  • 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_16_UNSIGNED (-16), CPL_BPP_32_SIGNED (32), CPL_BPP_IEEE_FLOAT (-32), CPL_BPP_IEEE_DOUBLE (-64) or CPL_BPP_DEFAULT.

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

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 Fri Mar 9 17:53:17 2007 for Common Pipeline Library Reference Manual by  doxygen 1.4.6