Image list IO routines


Functions

cpl_imagelist * cpl_imagelist_new ()
 Create an empty imagelist.
cpl_imagelist * cpl_imagelist_load (const char *filename, cpl_type type, int extnum)
 Load a FITS file extension into a list of images.
cpl_imagelist * cpl_imagelist_load_window (const char *filename, cpl_type type, int extnum, int llx, int lly, int urx, int ury)
 Load images windows from a FITS file extension into an image list.
int cpl_imagelist_get_size (const cpl_imagelist *imlist)
 Get the number of images in the imagelist.
cpl_image * cpl_imagelist_get (const cpl_imagelist *imlist, int inum)
 Get an image from a list of images.
cpl_error_code cpl_imagelist_set (cpl_imagelist *imlist, cpl_image *im, int pos)
 Insert an image into an imagelist.
cpl_image * cpl_imagelist_unset (cpl_imagelist *imlist, int pos)
 Remove an image from an imagelist.
void cpl_imagelist_delete (cpl_imagelist *imlist)
 Free memory associated to a cpl_imagelist object.
cpl_imagelist * cpl_imagelist_duplicate (const cpl_imagelist *imlist)
 Copy an image list.
cpl_error_code cpl_imagelist_erase (cpl_imagelist *imlist, const cpl_vector *valid)
 Reject one or more images in a list according to an array of flags.
cpl_error_code cpl_imagelist_save (const cpl_imagelist *imlist, const char *filename, cpl_type_bpp bpp, const cpl_propertylist *pl, unsigned mode)
 Save an imagelist to disk in FITS format.
int cpl_imagelist_is_uniform (const cpl_imagelist *imlist)
 Determine if an imagelist contains images of equal size and type.

Detailed Description

This module provides IO functions to handle cpl_imagelist.

Synopsis:
   #include "cpl_imagelist_io.h"

Function Documentation

void cpl_imagelist_delete cpl_imagelist *  imlist  ) 
 

Free memory associated to a cpl_imagelist object.

Parameters:
imlist the image list

cpl_imagelist* cpl_imagelist_duplicate const cpl_imagelist *  imlist  ) 
 

Copy an image list.

Parameters:
imlist Source image list.
Returns:
1 newly allocated image list, or NULL on error.
Copy an image list into a new image list object. The returned image list must be deallocated using cpl_imagelist_delete().

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_imagelist_erase cpl_imagelist *  imlist,
const cpl_vector *  valid
 

Reject one or more images in a list according to an array of flags.

Parameters:
imlist Non-empty imagelist to examine for image rejection.
valid Vector of flags (>=-0.5: valid, <-0.5: invalid)
Returns:
CPL_ERROR_NONE or the relevant _cpl_error_code_ on error
This function takes an imagelist and a vector of flags. The imagelist and vector must have equal lengths.

Images flagged as invalid are removed from the list.

The removal of image(s) will reduce the length of the list accordingly.

Possible _cpl_error_code_ set in this function:

  • CPL_ERROR_NULL_INPUT if (one of) the input pointer(s) is NULL
  • CPL_ERROR_INCOMPATIBLE_INPUT if the vector size and the image list size are different

cpl_image* cpl_imagelist_get const cpl_imagelist *  imlist,
int  inum
 

Get an image from a list of images.

Parameters:
imlist the image list
inum the image id (from 0 to number of images-1)
Returns:
A pointer to the image 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
  • CPL_ERROR_ACCESS_OUT_OF_RANGE if inum is bigger thant the list size
  • CPL_ERROR_ILLEGAL_INPUT if inum is negative

int cpl_imagelist_get_size const cpl_imagelist *  imlist  ) 
 

Get the number of images in the imagelist.

Parameters:
imlist the list of image
Returns:
The number of images or -1 on error
Possible _cpl_error_code_ set in this function:
  • CPL_ERROR_NULL_INPUT if (one of) the input pointer(s) is NULL

int cpl_imagelist_is_uniform const cpl_imagelist *  imlist  ) 
 

Determine if an imagelist contains images of equal size and type.

Parameters:
imlist The imagelist to check
Returns:
Zero if uniform, positive if non-uniform and negative on error.
The function returns 1 if the list is empty.

Possible _cpl_error_code_ set in this function:

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

cpl_imagelist* cpl_imagelist_load const char *  filename,
cpl_type  type,
int  extnum
 

Load a FITS file extension into a list of images.

Parameters:
filename The FITS file name
type Type of the images in the created image list
extnum The extension number
Returns:
The loaded list of images or NULL on error.
See also:
cpl_image_load()
This function loads all the images of a specified extension (NAXIS=2 or 3) in an image list.

Type can be CPL_TYPE_DOUBLE, CPL_TYPE_FLOAT or CPL_TYPE_INT. The loaded images have an empty bad pixel map.

The returned cpl_imagelist must be deallocated using cpl_imagelist_delete()

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 extnum is negative
  • CPL_ERROR_TYPE_MISMATCH if the passed type is not supported
  • CPL_ERROR_ACCESS_OUT_OF_RANGE if extnum is bigger than the number of extensions in the FITS file
  • CPL_ERROR_BAD_FILE_FORMAT if the file cannot be parsed
  • CPL_ERROR_DATA_NOT_FOUND if the datacannot be read from the file

cpl_imagelist* cpl_imagelist_load_window const char *  filename,
cpl_type  type,
int  extnum,
int  llx,
int  lly,
int  urx,
int  ury
 

Load images windows from a FITS file extension into an image list.

Parameters:
filename The FITS file name
type Type of the images in the created image list
extnum The extension number
llx Specifies the window position
lly Specifies the window position
urx Specifies the window position
ury Specifies the window position
Returns:
The loaded list of image windows or NULL on error.
See also:
cpl_image_load_window()
This function loads all the image windows of a specified extension in an image list.

Type can be CPL_TYPE_DOUBLE, CPL_TYPE_FLOAT or CPL_TYPE_INT.

The window position is specified starting with 1 to the number of pixel. Lower left pixel is (1, 1).

The returned cpl_imagelist must be deallocated using cpl_imagelist_delete()

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 extnum is negative
  • CPL_ERROR_TYPE_MISMATCH if the passed type is not supported
  • CPL_ERROR_ACCESS_OUT_OF_RANGE if extnum is bigger than the number of extensions in the FITS file
  • CPL_ERROR_BAD_FILE_FORMAT if the file cannot be parsed
  • CPL_ERROR_DATA_NOT_FOUND if the datacannot be read from the file

cpl_imagelist* cpl_imagelist_new void   ) 
 

Create an empty imagelist.

Returns:
1 newly allocated cpl_imagelist
See also:
cpl_imagelist_set()
The returned cpl_imagelist must be deallocated using cpl_imagelist_delete()

cpl_error_code cpl_imagelist_save const cpl_imagelist *  imlist,
const char *  filename,
cpl_type_bpp  bpp,
const cpl_propertylist pl,
unsigned  mode
 

Save an imagelist to disk in FITS format.

Parameters:
imlist Imagelist to save
filename Name of the FITS file to write
bpp Bits per pixels
pl Property list for the output header or NULL
mode The desired output options (combined with bitwise or)
Returns:
the _cpl_error_code_ or CPL_ERROR_NONE
See also:
cpl_image_save()
This function saves an image list 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 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 images) and BZERO is set to 32768 as specified by the FITS standard.

Supported image lists 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.

Currently, the only supported output mode is CPL_IO_DEFAULT (create a new file).

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_FILE_IO if the file cannot be written
  • CPL_ERROR_TYPE_MISMATCH if the passed image list type is not supported

cpl_error_code cpl_imagelist_set cpl_imagelist *  imlist,
cpl_image *  im,
int  pos
 

Insert an image into an imagelist.

Parameters:
imlist The imagelist
im The image to insert
pos The list position (from 0 to number of images)
Returns:
CPL_ERROR_NONE or the relevant _cpl_error_code_ on error
The image is put at the position pos in the image list. The image that is already there is deallocated.

It is allowed to specify the position equal to the number of images in the list. This will increment the size of the imagelist.

No action occurs if an image is inserted more than once into the same position. It is not allowed to insert the same image into two different positions in a list.

It is not allowed to insert images of different size into a list.

You should not deallocate the image after it has been inserted into an imagelist, since the cpl_imagelist_delete() will deallocate its images.

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 pos is negative
  • CPL_ERROR_TYPE_MISMATCH if im and imlist are of different types
  • CPL_ERROR_INCOMPATIBLE_INPUT if im and imlist have different sizes
  • CPL_ERROR_ACCESS_OUT_OF_RANGE if pos is bigger than the number of images in imlist

cpl_image* cpl_imagelist_unset cpl_imagelist *  imlist,
int  pos
 

Remove an image from an imagelist.

Parameters:
imlist The imagelist
pos The list position (from 0 to number of images-1)
Returns:
The pointer to the removed image or NULL in error case
The specified image is not deallocated, it is simply removed from the list. The pointer to the image is returned to let the user decide to deallocate it or not. Eventually, the image will have to be deallocated with cpl_image_delete().

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 pos is negative
  • CPL_ERROR_ACCESS_OUT_OF_RANGE if pos is bigger than the number of images in imlist


Generated on Fri Mar 9 17:53:18 2007 for Common Pipeline Library Reference Manual by  doxygen 1.4.6