SINFONI Pipeline Reference Manual  2.6.0
Functions
Lists of frames with properties.

Functions

irplib_framelist * irplib_framelist_new (void)
 Create an empty framelist. More...
 
void irplib_framelist_delete (irplib_framelist *self)
 Deallocate an irplib_framelist with its frames and properties. More...
 
irplib_framelist * irplib_framelist_cast (const cpl_frameset *frameset)
 Create an irplib_framelist from a cpl_framelist. More...
 
cpl_frameset * irplib_frameset_cast (const irplib_framelist *self)
 Create a CPL frameset from an irplib_framelist. More...
 
irplib_framelist * irplib_framelist_extract (const irplib_framelist *self, const char *tag)
 Extract the frames with the given tag from a framelist. More...
 
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. More...
 
int irplib_framelist_get_size (const irplib_framelist *self)
 Get the size of a framelist. More...
 
cpl_frame * irplib_framelist_get (irplib_framelist *self, int pos)
 Get the specified frame from the framelist. More...
 
const cpl_frame * irplib_framelist_get_const (const irplib_framelist *self, int pos)
 Get the specified frame from the framelist. More...
 
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. More...
 
cpl_propertylist * irplib_framelist_get_propertylist (irplib_framelist *self, int pos)
 Get the propertylist of the specified frame in the framelist. More...
 
const cpl_propertylist * irplib_framelist_get_propertylist_const (const irplib_framelist *self, int pos)
 Get the propertylist of the specified frame in the framelist. More...
 
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. More...
 
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. More...
 
cpl_error_code irplib_framelist_set_tag_all (irplib_framelist *self, const char *tag)
 Set the tag of all frames in the list. More...
 
cpl_error_code irplib_framelist_set (irplib_framelist *self, cpl_frame *frame, int pos)
 Add a frame to a framelist. More...
 
cpl_error_code irplib_framelist_erase (irplib_framelist *self, int pos)
 Erase a frame from a framelist and delete it and its propertylist. More...
 
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. More...
 
void irplib_framelist_empty (irplib_framelist *self)
 Erase all frames from a framelist. More...
 
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. More...
 
cpl_imagelist * irplib_imagelist_load_framelist (const irplib_framelist *self, cpl_type pixeltype, int planenum, int extnum)
 Load an imagelist from a framelist. More...
 

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 900 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 840 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 744 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 281 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 351 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 447 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 464 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 520 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 543 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 429 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 574 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 629 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 705 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 487 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 673 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 794 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 242 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 1043 of file irplib_framelist.c.