DETMON Pipeline Reference Manual  1.2.7
Functions
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
ra = cpl_propertylist_get_double(plist, "RA");
dec = cpl_propertylist_get_double(plist, "DEC");
// Object deallocation
cpl_imagelist_delete(ilist);
return 0;
}

Function Documentation

irplib_framelist* irplib_framelist_cast ( const cpl_frameset *  frameset)

Create an irplib_framelist from a cpl_framelist.

Parameters:
framesetThe 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 201 of file irplib_framelist.c.

References irplib_framelist_new(), and irplib_framelist_set().

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:
selfThe framelist to verify
keyProperty that must be present for all the frames
typeThe type the property must have, or CPL_TYPE_INVALID
is_equalIf true, the value must be identical for all keys
fp_tolThe 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 901 of file irplib_framelist.c.

void irplib_framelist_delete ( irplib_framelist *  self)

Deallocate an irplib_framelist with its frames and properties.

Parameters:
selfthe framelist

Definition at line 183 of file irplib_framelist.c.

References irplib_framelist_empty().

Referenced by irplib_framelist_extract(), and irplib_framelist_extract_regexp().

void irplib_framelist_empty ( irplib_framelist *  self)

Erase all frames from a framelist.

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

Definition at line 841 of file irplib_framelist.c.

Referenced by irplib_framelist_delete().

cpl_error_code irplib_framelist_erase ( irplib_framelist *  self,
int  pos 
)

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

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

Definition at line 745 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:
selfA non-empty framelist
tagThe 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 282 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:
selfA non-empty framelist
regexpThe regular expression of frame tag(s) to search for.
invertBoolean 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 352 of file irplib_framelist.c.

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

cpl_frame* irplib_framelist_get ( irplib_framelist *  self,
int  pos 
)

Get the specified frame from the framelist.

Parameters:
selfThe framelist
posposition (0 for first)
Returns:
The frame or NULL on error

Definition at line 448 of file irplib_framelist.c.

References irplib_framelist_get_const().

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

Get the specified frame from the framelist.

Parameters:
selfThe framelist
posposition (0 for first)
Returns:
The frame or NULL on error

Definition at line 465 of file irplib_framelist.c.

Referenced by irplib_framelist_get().

cpl_propertylist* irplib_framelist_get_propertylist ( irplib_framelist *  self,
int  pos 
)

Get the propertylist of the specified frame in the framelist.

Parameters:
selfThe framelist
posposition (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 521 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:
selfThe framelist
posposition (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 544 of file irplib_framelist.c.

Referenced by irplib_framelist_get_propertylist().

int irplib_framelist_get_size ( const irplib_framelist *  self)

Get the size of a framelist.

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

Definition at line 430 of file irplib_framelist.c.

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:
selfThe framelist to modify
posposition (0 for first).
indThe index of the date set to read
regexpThe regular expression of properties to load
invertBoolean 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 575 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:
selfThe framelist to modify
indThe index of the date set to read
regexpThe regular expression of properties to load
invertBoolean 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 630 of file irplib_framelist.c.

References irplib_framelist_load_propertylist().

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 170 of file irplib_framelist.c.

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

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

Add a frame to a framelist.

Parameters:
selfThe framelist to modify
frameThe frame to insert into the framelist
posposition (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 706 of file irplib_framelist.c.

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

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:
selfThe framelist to modify
posposition (0 for first).
listThe propertylist to copy
Returns:
CPL_ERROR_NONE or the relevant CPL error code

Definition at line 488 of file irplib_framelist.c.

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

Set the tag of all frames in the list.

Parameters:
selfThe framelist to modify
tagThe new tag of the frames
Returns:
CPL_ERROR_NONE or the relevant cpl_error_code

Definition at line 674 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:
selfThe non-empty framelist to modify
posposition of frame to delete (0 for first).
plistPointer 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 795 of file irplib_framelist.c.

cpl_frameset* irplib_frameset_cast ( const irplib_framelist *  self)

Create a CPL frameset from an irplib_framelist.

Parameters:
selfThe 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 243 of file irplib_framelist.c.

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

Load an imagelist from a framelist.

Parameters:
selfThe framelist
pixeltypeThe required type of the pixels in the images
planenumThe (non-negative ) plane number
extnumThe 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 1044 of file irplib_framelist.c.