Loading...
Searching...
No Matches
DFS related functions

## Macros

#define | CPL_DFS_PRO_CATG "ESO PRO CATG"
| The name of the Product Category key.
#define | CPL_DFS_PRO_SCIENCE "ESO PRO SCIENCE"
| The name of the Product Science key.
#define | CPL_DFS_PRO_TECH "ESO PRO TECH"
| The name of the Product Tech key.
#define | CPL_DFS_PRO_TYPE "ESO PRO TYPE"
| The name of the Product Type key.

## Enumerations

enum | { CPL_DFS_SIGNATURE_NONE , CPL_DFS_SIGNATURE_DATAMD5 , CPL_DFS_SIGNATURE_CHECKSUM }
| Pipeline products digital signature flags. More...

## Functions

cpl_error_code | cpl_dfs_save_imagelist (cpl_frameset *allframes, cpl_propertylist *header, const cpl_parameterlist *parlist, const cpl_frameset *usedframes, const cpl_frame *inherit, const cpl_imagelist *imagelist, cpl_type type, const char *recipe, const cpl_propertylist *applist, const char *remregexp, const char *pipe_id, const char *filename)
| Save an imagelist as a DFS-compliant pipeline product.
cpl_error_code | cpl_dfs_save_paf (const char *instrume, const char *recipe, const cpl_propertylist *paflist, const char *filename)
| Create a new PAF file.
cpl_error_code | cpl_dfs_save_propertylist (cpl_frameset *allframes, cpl_propertylist *header, const cpl_parameterlist *parlist, const cpl_frameset *usedframes, const cpl_frame *inherit, const char *recipe, const cpl_propertylist *applist, const char *remregexp, const char *pipe_id, const char *filename)
| Save a propertylist as a DFS-compliant pipeline product.
cpl_error_code | cpl_dfs_save_table (cpl_frameset *allframes, cpl_propertylist *header, const cpl_parameterlist *parlist, const cpl_frameset *usedframes, const cpl_frame *inherit, const cpl_table *table, const cpl_propertylist *tablelist, const char *recipe, const cpl_propertylist *applist, const char *remregexp, const char *pipe_id, const char *filename)
| Save a table as a DFS-compliant pipeline product.
cpl_error_code | cpl_dfs_setup_product_header (cpl_propertylist *header, const cpl_frame *product_frame, const cpl_frameset *framelist, const cpl_parameterlist *parlist, const char *recid, const char *pipeline_id, const char *dictionary_id, const cpl_frame *inherit_frame)
| Add product keywords to a pipeline product property list.
cpl_error_code | cpl_dfs_sign_products (const cpl_frameset *set, unsigned int flags)
| Update DFS and DICB required header information of product frames.
cpl_error_code | cpl_dfs_update_product_header (cpl_frameset *self)
| Perform any DFS-compliancy required actions (DATAMD5/PIPEFILE update).

## Detailed Description

## Macro Definition Documentation

## CPL_DFS_PRO_CATG

#define CPL_DFS_PRO_CATG "ESO PRO CATG"

The name of the Product Category key.

See also
  cpl_dfs_save_image()

Note
  A pipeline product must contain a string property with this name

## CPL_DFS_PRO_SCIENCE

#define CPL_DFS_PRO_SCIENCE "ESO PRO SCIENCE"

The name of the Product Science key.

See also
  cpl_dfs_save_image()

Note
  A pipeline product should contain a boolean property with this name

## CPL_DFS_PRO_TECH

#define CPL_DFS_PRO_TECH "ESO PRO TECH"

The name of the Product Tech key.

See also
  cpl_dfs_save_image()

Note
  A pipeline product should contain a string property with this name

## CPL_DFS_PRO_TYPE

#define CPL_DFS_PRO_TYPE "ESO PRO TYPE"

The name of the Product Type key.

See also
  cpl_dfs_save_image()

Note
  A pipeline product should contain a string property with this name

## Enumeration Type Documentation

## anonymous enum

anonymous enum

Pipeline products digital signature flags.

Flags to select the different digital signatures to compute for pipeline product files. The values may be combined using bitwise or.

Enumerator
CPL_DFS_SIGNATURE_NONE | Do not compute any signatures
CPL_DFS_SIGNATURE_DATAMD5 | Compute the DATAMD5 data hash
CPL_DFS_SIGNATURE_CHECKSUM | Compute FITS standard CHECKSUM and DATASUM

## Function Documentation

## cpl_dfs_save_imagelist()

cpl_error_code cpl_dfs_save_imagelist | ( | cpl_frameset * | allframes,
|  | cpl_propertylist * | header,
|  | const cpl_parameterlist * | parlist,
|  | const cpl_frameset * | usedframes,
|  | const cpl_frame * | inherit,
|  | const cpl_imagelist * | imagelist,
|  | cpl_type | type,
|  | const char * | recipe,
|  | const cpl_propertylist * | applist,
|  | const char * | remregexp,
|  | const char * | pipe_id,
|  | const char * | filename )

Save an imagelist as a DFS-compliant pipeline product.

Parameters

  allframes | The list of input frames for the recipe
  header | NULL, or filled with properties written to product header
  parlist | The list of input parameters
  usedframes | The list of raw/calibration frames used for this product
  inherit | NULL or product frames inherit their header from this frame
  imagelist | The imagelist to be saved
  type | The type used to represent the data in the file
  recipe | The recipe name
  applist | Propertylist to append to primary header, w. PRO.CATG
  remregexp | Optional regexp of properties not to put in main header
  pipe_id | PACKAGE "/" PACKAGE_VERSION
  filename | Filename of created product

Note
  remregexp may be NULL

Returns
  CPL_ERROR_NONE or the relevant CPL error code on error

See also
  cpl_dfs_save_image(), cpl_imagelist_save().

References cpl_ensure_code, CPL_ERROR_NONE, and CPL_ERROR_NULL_INPUT.

## cpl_dfs_save_paf()

cpl_error_code cpl_dfs_save_paf | ( | const char * | instrume,
|  | const char * | recipe,
|  | const cpl_propertylist * | paflist,
|  | const char * | filename )

Create a new PAF file.

Parameters

  instrume | Name of instrument in capitals (NACO, VISIR, etc.)
  recipe | Name of recipe
  paflist | Propertylist to save
  filename | Filename of created PArameter File

Returns
  CPL_ERROR_NONE or the relevant CPL error code on error

See also
  cpl_dfs_save_image().

The example below shows how to create a PAF from some FITS cards from the file ref_file and QC parameters in a propertylist qclist. Please note that qclist can be used also in calls to cpl_dfs_save_image() and cpl_dfs_save_table(). Error handling is omitted for brevity:

const char pafcopy[] = "^(DATE-OBS|ARCFILE|ESO TPL ID|ESO DET DIT|MJD-OBS)$";
cpl_propertylist * paflist = cpl_propertylist_load_regexp(ref_file, 0,
pafcopy, 0);
cpl_propertylist_append(paflist, qclist);
cpl_dfs_save_paf("IIINSTRUMENT", "rrrecipe", paflist, "rrrecipe.paf");
cpl_propertylist_delete(paflist);
cpl_dfs_save_paf
cpl_error_code cpl_dfs_save_paf(const char *instrume, const char *recipe, const cpl_propertylist *paflist, const char *filename)
Create a new PAF file.
Definition cpl_dfs.c:393
cpl_propertylist_append
cpl_error_code cpl_propertylist_append(cpl_propertylist *self, const cpl_propertylist *other)
Append a property list..
Definition cpl_propertylist.c:5134
cpl_propertylist
struct _cpl_propertylist_ cpl_propertylist
The opaque property list data type.
Definition cpl_propertylist.h:39
cpl_propertylist_load_regexp
cpl_propertylist * cpl_propertylist_load_regexp(const char *name, cpl_size position, const char *regexp, int invert)
Create a filtered property list from a file.
Definition cpl_propertylist.c:6596
cpl_propertylist_delete
void cpl_propertylist_delete(cpl_propertylist *self)
Destroy a property list.
Definition cpl_propertylist.c:925

References cpl_ensure_code, CPL_ERROR_FILE_IO, cpl_error_get_code(), CPL_ERROR_NONE, and CPL_ERROR_NULL_INPUT.

## cpl_dfs_save_propertylist()

cpl_error_code cpl_dfs_save_propertylist | ( | cpl_frameset * | allframes,
|  | cpl_propertylist * | header,
|  | const cpl_parameterlist * | parlist,
|  | const cpl_frameset * | usedframes,
|  | const cpl_frame * | inherit,
|  | const char * | recipe,
|  | const cpl_propertylist * | applist,
|  | const char * | remregexp,
|  | const char * | pipe_id,
|  | const char * | filename )

Save a propertylist as a DFS-compliant pipeline product.

Parameters

  allframes | The list of input frames for the recipe
  header | NULL, or filled with properties written to product header
  parlist | The list of input parameters
  usedframes | The list of raw/calibration frames used for this product
  inherit | NULL or product frames inherit their header from this frame
  recipe | The recipe name
  applist | Propertylist to append to primary header, w. PRO.CATG
  remregexp | Optional regexp of properties not to put in main header
  pipe_id | PACKAGE "/" PACKAGE_VERSION
  filename | Filename of created product

Note
  remregexp may be NULL

Returns
  CPL_ERROR_NONE or the relevant CPL error code on error

See also
  cpl_dfs_save_image(), cpl_propertylist_save().

The FITS header of the created product is created from the provided applist and the cards copied by cpl_dfs_setup_product_header(), with exception of the cards whose keys match the provided remregexp.

The FITS data unit will be empty.

References CPL_ERROR_NONE, and CPL_TYPE_INVALID.

## cpl_dfs_save_table()

cpl_error_code cpl_dfs_save_table | ( | cpl_frameset * | allframes,
|  | cpl_propertylist * | header,
|  | const cpl_parameterlist * | parlist,
|  | const cpl_frameset * | usedframes,
|  | const cpl_frame * | inherit,
|  | const cpl_table * | table,
|  | const cpl_propertylist * | tablelist,
|  | const char * | recipe,
|  | const cpl_propertylist * | applist,
|  | const char * | remregexp,
|  | const char * | pipe_id,
|  | const char * | filename )

Save a table as a DFS-compliant pipeline product.

Parameters

  allframes | The list of input frames for the recipe
  header | NULL, or filled with properties written to product header
  parlist | The list of input parameters
  usedframes | The list of raw/calibration frames used for this product
  inherit | NULL or product frames inherit their header from this frame
  table | The table to be saved
  tablelist | Optional propertylist to use in table extension or NULL
  recipe | The recipe name
  applist | Propertylist to append to primary header, w. PRO.CATG
  remregexp | Optional regexp of properties not to put in main header
  pipe_id | PACKAGE "/" PACKAGE_VERSION
  filename | Filename of created product

Returns
  CPL_ERROR_NONE or the relevant CPL error code on error

See also
  cpl_dfs_save_image(), cpl_table_save().

References cpl_ensure_code, CPL_ERROR_NONE, CPL_ERROR_NULL_INPUT, and CPL_TYPE_INVALID.

## cpl_dfs_setup_product_header()

cpl_error_code cpl_dfs_setup_product_header | ( | cpl_propertylist * | header,
|  | const cpl_frame * | product_frame,
|  | const cpl_frameset * | framelist,
|  | const cpl_parameterlist * | parlist,
|  | const char * | recid,
|  | const char * | pipeline_id,
|  | const char * | dictionary_id,
|  | const cpl_frame * | inherit_frame )

Add product keywords to a pipeline product property list.

Parameters

  header | Property list where keywords must be written
  product_frame | Frame describing the product
  framelist | List of frames including all input frames
  parlist | Recipe parameter list
  recid | Recipe name
  pipeline_id | Pipeline unique identifier
  dictionary_id | PRO dictionary identifier
  inherit_frame | Frame from which header information is inherited

Returns
  `CPL_ERROR_NONE` on success.

Errors

  CPL_ERROR_NULL_INPUT | An input pointer is NULL.
  CPL_ERROR_DATA_NOT_FOUND | The input framelist contains no input frames or a frame in the input framelist does not specify a file. In the former case the string "Empty set-of-frames" is appended to the error message returned by cpl_error_get_message().
  CPL_ERROR_ILLEGAL_INPUT | The product frame is not tagged or not grouped as CPL_FRAME_GROUP_PRODUCT. A specified inherit_frame doesn't belong to the input frame list, or it is not in FITS format.
  CPL_ERROR_FILE_NOT_FOUND | A frame in the input framelist specifies a non-existing file.
  CPL_ERROR_BAD_FILE_FORMAT | A frame in the input framelist specifies an invalid file.

This function checks the header associated to a pipeline product, to ensure that it is DICB compliant. In particular, this function does the following:

1. Selects a reference frame from which the primary and secondary keyword information is inherited. The primary information is contained in the FITS keywords ORIGIN, TELESCOPE, INSTRUME, OBJECT, RA, DEC, EPOCH, EQUINOX, RADECSYS, DATE-OBS, MJD-OBS, UTC, LST, PI-COI, OBSERVER, while the secondary information is contained in all the other keywords. If the inherit_frame is just a NULL pointer, both primary and secondary information is inherited from the first frame in the input framelist with group CPL_FRAME_GROUP_RAW, or if no such frames are present the first frame with group CPL_FRAME_GROUP_CALIB. If inherit_frame is non-NULL, the secondary information is inherited from inherit_frame instead.
2. Copy to header, if they are present, the following primary FITS keywords from the first input frame in the framelist: ORIGIN, TELESCOPE, INSTRUME, OBJECT, RA, DEC, EPOCH, EQUINOX, RADESYS, DATE-OBS, MJD-OBS, UTC, LST, PI-COI, OBSERVER. If those keywords are already present in the header property list, they are overwritten only in case they have the same type. If any of these keywords are present with an unexpected type, a warning is issued, but the keywords are copied anyway (provided that the above conditions are fulfilled), and no error is set.
3. Copy all the HIERARCH.ESO._ keywords from the primary FITS header of the inherit_frame in framelist, with the exception of the HIERARCH.ESO.DPR._, and of the .PRO._ and .DRS._ keywords if the inherit_frame is a calibration. If those keywords are already present in header, they are overwritten.
4. If found, remove the HIERARCH.ESO.DPR._ keywords from header.
5. If found, remove the ARCFILE and ORIGFILE keywords from header.
6. Add to header the following mandatory keywords from the PRO dictionary: PIPEFILE, PRO.DID, PRO.REC1.ID, PRO.REC1.DRS.ID, PRO.REC1.PIPE.ID, and PRO.CATG. If those keywords are already present in header, they are overwritten. The keyword PRO.CATG is always set identical to the tag in product_frame.
7. Only if missing, add to header the following mandatory keywords from the PRO dictionary: PRO.TYPE, PRO.TECH, and PRO.SCIENCE. The keyword PRO.TYPE will be set to "REDUCED". If the keyword DPR.TECH is found in the header of the first frame, PRO.TECH is given its value, alternatively if the keyword PRO.TECH is found it is copied instead, and if all fails the value "UNDEFINED" is set. Finally, if the keyword DPR.CATG is found in the header of the first frame and is set to "SCIENCE", the boolean keyword PRO.SCIENCE will be set to "true", otherwise it will be copied from an existing PRO.SCIENCE keyword, while it will be set to "false" in all other cases.
8. Check the existence of the keyword PRO.DATANCOM in header. If this keyword is missing, one is added, with the value of the total number of raw input frames.
9. Add to header the keywords PRO.REC1.RAW1.NAME, PRO.REC1.RAW1.CATG, PRO.REC1.CAL1.NAME, PRO.REC1.CAL1.CATG, to describe the content of the input set-of-frames.

See the DICB PRO dictionary to have details on the mentioned PRO keywords.

Note
  Non-FITS files are handled as files with an empty FITS header.

References cpl_ensure_code, CPL_ERROR_ACCESS_OUT_OF_RANGE, CPL_ERROR_DATA_NOT_FOUND, CPL_ERROR_FILE_NOT_FOUND, cpl_error_get_code(), CPL_ERROR_ILLEGAL_INPUT, CPL_ERROR_NONE, CPL_ERROR_NULL_INPUT, CPL_ERROR_UNSPECIFIED, cpl_errorstate_get(), cpl_errorstate_set(), cpl_frame_get_filename(), cpl_frame_get_group(), cpl_frame_get_tag(), CPL_FRAME_GROUP_CALIB, CPL_FRAME_GROUP_PRODUCT, CPL_FRAME_GROUP_RAW, cpl_frameset_get_size(), cpl_frameset_iterator_advance(), cpl_frameset_iterator_delete(), cpl_frameset_iterator_get_const(), cpl_frameset_iterator_new(), cpl_frameset_iterator_reset(), cpl_free(), cpl_msg_warning(), cpl_parameter_get_alias(), cpl_parameter_get_bool(), cpl_parameter_get_default_bool(), cpl_parameter_get_default_double(), cpl_parameter_get_default_int(), cpl_parameter_get_default_string(), cpl_parameter_get_double(), cpl_parameter_get_help(), cpl_parameter_get_int(), cpl_parameter_get_string(), cpl_parameter_get_type(), CPL_PARAMETER_MODE_CLI, cpl_parameterlist_get_first_const(), cpl_parameterlist_get_next_const(), cpl_property_delete(), cpl_property_duplicate(), cpl_property_get_bool(), cpl_property_get_size(), cpl_property_get_string(), cpl_property_get_type(), cpl_property_set_bool(), cpl_property_set_comment(), cpl_property_set_int(), cpl_property_set_name(), cpl_propertylist_append(), cpl_propertylist_append_property(), cpl_propertylist_delete(), cpl_propertylist_erase(), cpl_propertylist_get_property_const(), cpl_propertylist_has(), cpl_propertylist_new(), cpl_sprintf(), cpl_strdup(), CPL_TYPE_BOOL, CPL_TYPE_DOUBLE, cpl_type_get_name(), CPL_TYPE_INT, and CPL_TYPE_STRING.

## cpl_dfs_sign_products()

cpl_error_code cpl_dfs_sign_products | ( | const cpl_frameset * | set,
|  | unsigned int | flags )

Update DFS and DICB required header information of product frames.

Parameters

  set | The frameset from which the product frames are taken.
  flags | Bit mask for selecting the digital signatures to be written.

Returns
  The function returns `CPL_ERROR_NONE` on success, or an appropriate CPL error code otherwise.

Note
  Each product frame must correspond to a FITS file created with a CPL FITS saving function.

The function takes all frames marked as products from the input frameset set. For each product the header information `PIPEFILE` is updated unconditionally. In addition, depending on the bit mask flags, the `DATAMD5` data hash and/or the standard FITS checksums are computed and written to the product header. If a digital signature is not selected by flags when the function is called, its corresponding header keyword(s) are removed from the product frame.

Errors

  CPL_ERROR_NULL_INPUT | An input pointer is NULL.
  CPL_ERROR_DATA_NOT_FOUND | The input framelist contains a frame of type product with a missing filename.
  CPL_ERROR_BAD_FILE_FORMAT | The input framelist contains a frame of type product without a FITS card with key 'DATAMD5'.
  CPL_ERROR_FILE_IO | The input framelist contains a frame of type product for which the FITS card with key 'DATAMD5' could not be updated.

References CPL_DFS_SIGNATURE_NONE, cpl_ensure_code, CPL_ERROR_ACCESS_OUT_OF_RANGE, cpl_error_get_code(), CPL_ERROR_NONE, CPL_ERROR_NULL_INPUT, cpl_errorstate_get(), cpl_errorstate_set(), cpl_frame_get_group(), CPL_FRAME_GROUP_PRODUCT, cpl_frameset_is_empty(), cpl_frameset_iterator_advance(), cpl_frameset_iterator_delete(), cpl_frameset_iterator_get_const(), and cpl_frameset_iterator_new().

## cpl_dfs_update_product_header()

cpl_error_code cpl_dfs_update_product_header | ( | cpl_frameset * | self | ) |

Perform any DFS-compliancy required actions (DATAMD5/PIPEFILE update).

Parameters

  self | The list of frames with FITS products created by the recipe

Returns
  CPL_ERROR_NONE or the relevant CPL error code on error

Note
  Each product frame must correspond to a FITS file created with a CPL FITS saving function.

Errors

  CPL_ERROR_NULL_INPUT | An input pointer is NULL.
  CPL_ERROR_DATA_NOT_FOUND | The input framelist contains a frame of type product with a missing filename.
  CPL_ERROR_BAD_FILE_FORMAT | The input framelist contains a frame of type product without a FITS card with key 'DATAMD5'.
  CPL_ERROR_FILE_IO | The input framelist contains a frame of type product for which the FITS card with key 'DATAMD5' could not be updated.

References CPL_ERROR_NONE.