Lists of frames with properties.


Functions

irplib_framelist * irplib_framelist_new (void)
 Create an empty framelist.
void irplib_framelist_delete (irplib_framelist *self)
 Deallocate an irplib_framelist with its frames and properties.
irplib_framelist * irplib_framelist_cast (const cpl_frameset *frameset)
 Create an irplib_framelist from a cpl_framelist.
cpl_frameset * irplib_frameset_cast (const irplib_framelist *self)
 Create a CPL frameset from an irplib_framelist.
irplib_framelist * irplib_framelist_extract (const irplib_framelist *self, const char *tag)
 Extract the frames with the given tag from a framelist.
irplib_framelist * irplib_framelist_extract_regexp (const irplib_framelist *self, const char *regexp, cpl_boolean invert)
 Extract the frames with the given tag from a framelist.
int irplib_framelist_get_size (const irplib_framelist *self)
 Get the size of a framelist.
cpl_frame * irplib_framelist_get (irplib_framelist *self, int pos)
 Get the specified frame from the framelist.
const cpl_frame * irplib_framelist_get_const (const irplib_framelist *self, int pos)
 Get the specified frame from the framelist.
cpl_error_code irplib_framelist_set_propertylist (irplib_framelist *self, int pos, const cpl_propertylist *list)
 Duplicate a propertylist to the specified position in the framelist.
cpl_propertylist * irplib_framelist_get_propertylist (irplib_framelist *self, int pos)
 Get the propertylist of the specified frame in the framelist.
const cpl_propertylist * irplib_framelist_get_propertylist_const (const irplib_framelist *self, int pos)
 Get the propertylist of the specified frame in the framelist.
cpl_error_code irplib_framelist_load_propertylist (irplib_framelist *self, int pos, int ind, const char *regexp, cpl_boolean invert)
 Load the propertylist of the specified frame in the framelist.
cpl_error_code irplib_framelist_load_propertylist_all (irplib_framelist *self, int ind, const char *regexp, cpl_boolean invert)
 Load the propertylists of all frames in the framelist.
cpl_error_code irplib_framelist_set_tag_all (irplib_framelist *self, const char *tag)
 Set the tag of all frames in the list.
cpl_error_code irplib_framelist_set (irplib_framelist *self, cpl_frame *frame, int pos)
 Add a frame to a framelist.
cpl_error_code irplib_framelist_erase (irplib_framelist *self, int pos)
 Erase a frame from a framelist and delete it and its propertylist.
cpl_frame * irplib_framelist_unset (irplib_framelist *self, int pos, cpl_propertylist **plist)
 Erase a frame from a framelist and return it to the caller.
void irplib_framelist_empty (irplib_framelist *self)
 Erase all frames from a framelist.
cpl_error_code irplib_framelist_contains (const irplib_framelist *self, const char *key, cpl_type type, cpl_boolean is_equal, double fp_tol)
 Verify that a property is present for all frames.
cpl_imagelist * irplib_imagelist_load_framelist (const irplib_framelist *self, cpl_type pixeltype, int planenum, int extnum)
 Load an imagelist from a framelist.

Detailed Description

This module implements a container type for frames and their propertylists. It differs from the cpl_frameset in these ways: 1) A propertylist can be associated to each frame 2) Access by index is a O(1)-operation 3) It can not be corrupted due to caching bugs (e.g. DFS02731).

Synopsis:
     #include <irplib_framelist.h>
Example:
   static int rrecipe(cpl_frameset * frameset)
   {
      // Error handling omitted for brevity

      irplib_framelist * allframes = irplib_framelist_cast(frameset);

      // Get raw frames of either type
      irplib_framelist * rawframes = irplib_framelist_extract_regexp(allframes,
                                                                   "^("
                                                                   RAW_TYPE1 "|"
                                                                   RAW_TYPE2 ")$",
                                                                   CPL_FALSE);

      // Load the list of images
      cpl_imagelist * ilist = irplib_imagelist_load_framelist(rawframes,
                                                              CPL_TYPE_FLOAT,
                                                              0, 0);

      const cpl_propertylist * plist;

      // A regular expression of the FITS cards needed by this recipe
      const char cards[] = "^(RA|DEC|EXPTIME)$";
      double ra, dec;


      // Load the specified FITS cards for all raw frames
      irplib_framelist_load_propertylist_all(rawframes, 0, cards, CPL_FALSE));


      // Verify the presence and uniformity of the FITS cards
      if (irplib_framelist_contains(rawframes, "RA",
                                     CPL_TYPE_DOUBLE, CPL_TRUE, 1e-5)) {
         // RA is missing in one or more headers
         //  - or it varies by more than 1e-5
      }

       if (irplib_framelist_contains(rawframes, "DEC",
                                     CPL_TYPE_DOUBLE, CPL_TRUE, 1e-5)) {
         // DEC is missing in one or more headers
         //  - or it varies by more than 1e-5
      }

      // Process the FITS cards 
      plist = irplib_framelist_get_propertylist_const(rawframes, 0);

      ra  = cpl_propertylist_get_double(plist, "RA");
      dec = cpl_propertylist_get_double(plist, "DEC");

      // Object deallocation
      irplib_framelist_delete(allframes);
      irplib_framelist_delete(rawframes);
      cpl_imagelist_delete(ilist);

      return 0;

   }

Function Documentation

irplib_framelist* irplib_framelist_new ( void   ) 

Create an empty framelist.

Returns:
1 newly allocated irplib_framelist
Note:
The returned irplib_framelist must be deallocated using irplib_framelist_delete()

Definition at line 178 of file irplib_framelist.c.

Referenced by irplib_framelist_cast(), irplib_framelist_extract(), and irplib_framelist_extract_regexp().

void irplib_framelist_delete ( irplib_framelist *  self  ) 

Deallocate an irplib_framelist with its frames and properties.

Parameters:
self the framelist

Definition at line 191 of file irplib_framelist.c.

References irplib_framelist_empty().

Referenced by irplib_framelist_extract(), and irplib_framelist_extract_regexp().

irplib_framelist* irplib_framelist_cast ( const cpl_frameset *  frameset  ) 

Create an irplib_framelist from a cpl_framelist.

Parameters:
frameset The cpl_frameset
Returns:
1 newly allocated irplib_framelist or NULL on error
Note:
The returned irplib_framelist must be deallocated using irplib_framelist_delete()

Definition at line 209 of file irplib_framelist.c.

References irplib_framelist_new(), and irplib_framelist_set().

cpl_frameset* irplib_frameset_cast ( const irplib_framelist *  self  ) 

Create a CPL frameset from an irplib_framelist.

Parameters:
self The framelist
Returns:
1 newly allocated cpl_frameset or NULL on error
Note:
The returned cpl_frameset must be deallocated using cpl_frameset_delete()

Definition at line 251 of file irplib_framelist.c.

irplib_framelist* irplib_framelist_extract ( const irplib_framelist *  self,
const char *  tag 
)

Extract the frames with the given tag from a framelist.

Parameters:
self A non-empty framelist
tag The frame tag to search for.
Returns:
The newly created framelist or NULL on error
See also:
cpl_frameset_find
Note:
Any propertylists of the extracted frames are also extracted. It is an error if no matching frames are found, in which case an error is set.

Definition at line 290 of file irplib_framelist.c.

References irplib_framelist_delete(), irplib_framelist_new(), and irplib_framelist_set().

irplib_framelist* irplib_framelist_extract_regexp ( const irplib_framelist *  self,
const char *  regexp,
cpl_boolean  invert 
)

Extract the frames with the given tag from a framelist.

Parameters:
self A non-empty framelist
regexp The regular expression of frame tag(s) to search for.
invert Boolean to invert the sense of the pattern matching.
Returns:
The newly created framelist or NULL on error
See also:
irplib_framelist_extract

Definition at line 360 of file irplib_framelist.c.

References irplib_framelist_delete(), irplib_framelist_new(), and irplib_framelist_set().

int irplib_framelist_get_size ( const irplib_framelist *  self  ) 

Get the size of a framelist.

Parameters:
self The framelist
Returns:
The size or a negative number on error

Definition at line 438 of file irplib_framelist.c.

Referenced by irplib_dfs_check_framelist_tag(), irplib_pfits_set_airmass(), naco_framelist_set_tag(), and naco_imagelist_load_diff().

cpl_frame* irplib_framelist_get ( irplib_framelist *  self,
int  pos 
)

Get the specified frame from the framelist.

Parameters:
self The framelist
pos position (0 for first)
Returns:
The frame or NULL on error

Definition at line 456 of file irplib_framelist.c.

References irplib_framelist_get_const().

Referenced by naco_framelist_set_tag().

const cpl_frame* irplib_framelist_get_const ( const irplib_framelist *  self,
int  pos 
)

Get the specified frame from the framelist.

Parameters:
self The framelist
pos position (0 for first)
Returns:
The frame or NULL on error

Definition at line 472 of file irplib_framelist.c.

Referenced by irplib_dfs_check_framelist_tag(), irplib_framelist_get(), irplib_pfits_set_airmass(), and naco_imagelist_load_diff().

cpl_error_code irplib_framelist_set_propertylist ( irplib_framelist *  self,
int  pos,
const cpl_propertylist *  list 
)

Duplicate a propertylist to the specified position in the framelist.

Parameters:
self The framelist to modify
pos position (0 for first).
list The propertylist to copy
Returns:
CPL_ERROR_NONE or the relevant CPL error code

Definition at line 495 of file irplib_framelist.c.

cpl_propertylist* irplib_framelist_get_propertylist ( irplib_framelist *  self,
int  pos 
)

Get the propertylist of the specified frame in the framelist.

Parameters:
self The framelist
pos position (0 for first)
Returns:
The propertylist or NULL on error
Note:
The propertylist must first be created, for example with irplib_framelist_load_propertylist(self, pos, ...), otherwise an error occurs.

Definition at line 528 of file irplib_framelist.c.

References irplib_framelist_get_propertylist_const().

const cpl_propertylist* irplib_framelist_get_propertylist_const ( const irplib_framelist *  self,
int  pos 
)

Get the propertylist of the specified frame in the framelist.

Parameters:
self The framelist
pos position (0 for first)
Returns:
The propertylist or NULL on error
Note:
The propertylist must first be created, for example with irplib_framelist_load_propertylist(self, pos, ...), otherwise an error occurs.

Definition at line 550 of file irplib_framelist.c.

Referenced by irplib_dfs_check_framelist_tag(), irplib_framelist_get_propertylist(), irplib_pfits_set_airmass(), and naco_framelist_set_tag().

cpl_error_code irplib_framelist_load_propertylist ( irplib_framelist *  self,
int  pos,
int  ind,
const char *  regexp,
cpl_boolean  invert 
)

Load the propertylist of the specified frame in the framelist.

Parameters:
self The framelist to modify
pos position (0 for first).
ind The index of the date set to read
regexp The regular expression of properties to load
invert Boolean to invert the sense of the pattern matching.
Returns:
CPL_ERROR_NONE or the relevant CPL error code
See also:
cpl_propertylist_load_regexp()
Note:
Use a regexp of ".?" to load all properties. If a propertylist already exists it is deleted and replaced by the new one.

Definition at line 581 of file irplib_framelist.c.

Referenced by irplib_framelist_load_propertylist_all().

cpl_error_code irplib_framelist_load_propertylist_all ( irplib_framelist *  self,
int  ind,
const char *  regexp,
cpl_boolean  invert 
)

Load the propertylists of all frames in the framelist.

Parameters:
self The framelist to modify
ind The index of the date set to read
regexp The regular expression of properties to load
invert Boolean to invert the sense of the pattern matching.
Returns:
CPL_ERROR_NONE or the relevant CPL error code
See also:
irplib_framelist_load_propertylist()
Note:
Use a regexp of "" to load all properties. If a frame already has a propertylist, it is not modified (and no propertylist is loaded for that frame).

Definition at line 636 of file irplib_framelist.c.

References irplib_framelist_load_propertylist().

cpl_error_code irplib_framelist_set_tag_all ( irplib_framelist *  self,
const char *  tag 
)

Set the tag of all frames in the list.

Parameters:
self The framelist to modify
tag The new tag of the frames
Returns:
CPL_ERROR_NONE or the relevant _cpl_error_code_

Definition at line 680 of file irplib_framelist.c.

cpl_error_code irplib_framelist_set ( irplib_framelist *  self,
cpl_frame *  frame,
int  pos 
)

Add a frame to a framelist.

Parameters:
self The framelist to modify
frame The frame to insert into the framelist
pos position (0 for first).
Returns:
CPL_ERROR_NONE or the relevant CPL error code
Note:
It is an error to call cpl_frame_delete() on a frame that is inserted in a framelist.
It is allowed to specify the position equal to the size of the list. This will increment the size of the list.

Definition at line 712 of file irplib_framelist.c.

Referenced by irplib_framelist_cast(), irplib_framelist_extract(), and irplib_framelist_extract_regexp().

cpl_error_code irplib_framelist_erase ( irplib_framelist *  self,
int  pos 
)

Erase a frame from a framelist and delete it and its propertylist.

Parameters:
self The non-empty framelist to modify
pos position of frame to delete (0 for first).
Returns:
CPL_ERROR_NONE or the relevant CPL error code

Definition at line 751 of file irplib_framelist.c.

cpl_frame* irplib_framelist_unset ( irplib_framelist *  self,
int  pos,
cpl_propertylist **  plist 
)

Erase a frame from a framelist and return it to the caller.

Parameters:
self The non-empty framelist to modify
pos position of frame to delete (0 for first).
plist Pointer to a propertylist or NULL
Returns:
CPL_ERROR_NONE or the relevant CPL error code
The specified frame is removed from the framelist and its size is decreased by one. The frame is returned to the caller. The caller may also retrieve the propertylist of the frame by passing a non-NULL pointer. On success this may point to NULL, if a propertylist was not created for the frame. If the caller passes a NULL-pointer for the propertylist, the propertylist is deallocated.

Definition at line 801 of file irplib_framelist.c.

void irplib_framelist_empty ( irplib_framelist *  self  ) 

Erase all frames from a framelist.

Parameters:
self The framelist to modify, or NULL
Returns:
CPL_ERROR_NONE or the relevant CPL error code

Definition at line 847 of file irplib_framelist.c.

Referenced by irplib_framelist_delete().

cpl_error_code irplib_framelist_contains ( const irplib_framelist *  self,
const char *  key,
cpl_type  type,
cpl_boolean  is_equal,
double  fp_tol 
)

Verify that a property is present for all frames.

Parameters:
self The framelist to verify
key Property that must be present for all the frames
type The type the property must have, or CPL_TYPE_INVALID
is_equal If true, the value must be identical for all keys
fp_tol The non-negative tolerance for floating point comparison
Returns:
CPL_ERROR_NONE or the relevant CPL error code
Note:
It is allowed for a frame to have a NULL propertylist, in which case no check is performed. If type is CPL_TYPE_INVALID the check for a specific type is disabled. However, with is_equal true, all properties must nevertheless have the same type. fp_tol is used only when is_equal is true and the type is (explicitly or implicitly) CPL_TYPE_FLOAT or CPL_TYPE_DOUBLE.
To verify the presence of the MJD-OBS keyword:
       irplib_framelist_contains(myframes, "MJD-OBS", CPL_TYPE_INVALID,
                                 CPL_FALSE, 0.0);

To verify that the EXPTIME is identical to within 0.1 millisecond:

       irplib_framelist_contains(myframes, "EXPTIME", CPL_TYPE_INVALID,
                                 CPL_TRUE, 0.0001);

To verify that the keyword "ESO INS LAMP ST" is of type boolean and that it has the same value for all frames:

       irplib_framelist_contains(myframes, "ESO INS LAMP ST", CPL_TYPE_BOOL,
                                 CPL_TRUE, 0.0);

Definition at line 907 of file irplib_framelist.c.

Referenced by naco_imagelist_load_diff().

cpl_imagelist* irplib_imagelist_load_framelist ( const irplib_framelist *  self,
cpl_type  pixeltype,
int  planenum,
int  extnum 
)

Load an imagelist from a framelist.

Parameters:
self The framelist
pixeltype The required type of the pixels in the images
planenum The (non-negative ) plane number
extnum The non-negative extension (0 for primary data unit)
Returns:
The loaded list of images or NULL on error.
See also:
cpl_image_load()
Note:
The returned cpl_imagelist must be deallocated using cpl_imagelist_delete()

Definition at line 1048 of file irplib_framelist.c.


Generated on Wed Mar 9 15:46:17 2011 for NACO Pipeline Reference Manual by  doxygen 1.5.8