Common Pipeline Library Reference Manual
7.1.3
|
Modules | |
Regular Expression Filter | |
Typedefs | |
typedef struct _cpl_multiframe_ | cpl_multiframe |
The opaque multi-frame data type. More... | |
typedef enum _cpl_multiframe_id_mode_ | cpl_multiframe_id_mode |
The flags indicating the naming scheme to use for multi-frame datasets. More... | |
Enumerations | |
enum | _cpl_multiframe_id_mode_ { CPL_MULTIFRAME_ID_SET , CPL_MULTIFRAME_ID_PREFIX , CPL_MULTIFRAME_ID_JOIN } |
The flags indicating the naming scheme to use for multi-frame datasets. More... | |
Functions | |
cpl_error_code | cpl_multiframe_add_empty (cpl_multiframe *self, const char *id) |
Add a placeholder to a multi-frame container. More... | |
cpl_error_code | cpl_multiframe_append_datagroup (cpl_multiframe *self, const char *id, const cpl_frame *frame, cpl_size nsets, const char **names, const cpl_regex **filter1, const cpl_regex **filter2, const char **properties, unsigned int flags) |
Adds a group of dataset references given by name to a multi-frame container object. More... | |
cpl_error_code | cpl_multiframe_append_datagroup_from_position (cpl_multiframe *self, const char *id, const cpl_frame *frame, cpl_size nsets, cpl_size *positions, const cpl_regex **filter1, const cpl_regex **filter2, const char **properties, unsigned int flags) |
Adds a group of dataset references given by position to a multi-frame container object. More... | |
cpl_error_code | cpl_multiframe_append_dataset (cpl_multiframe *self, const char *id, const cpl_frame *frame, const char *name, const cpl_regex *filter1, const cpl_regex *filter2, unsigned int flags) |
Adds a dataset reference given by name to a multi-frame container object. More... | |
cpl_error_code | cpl_multiframe_append_dataset_from_position (cpl_multiframe *self, const char *id, const cpl_frame *frame, cpl_size position, const cpl_regex *filter1, const cpl_regex *filter2, unsigned int flags) |
Adds a dataset reference given by position to a multi-frame container object. More... | |
void | cpl_multiframe_delete (cpl_multiframe *self) |
Destroys a multi-frame container object. More... | |
cpl_size | cpl_multiframe_get_size (const cpl_multiframe *self) |
Get the size of a multi-frame container object. More... | |
cpl_multiframe * | cpl_multiframe_new (const cpl_frame *head, const char *id, cpl_regex *filter) |
Create a new multi-frame container object. More... | |
cpl_error_code | cpl_multiframe_write (cpl_multiframe *self, const char *filename) |
Write a multi-frame container to a file. More... | |
This module implements the cpl_multiframe
container type. A multi frame contains references to datasets (FITS extensions) which may be distributed across several physical files. These references can then be merged into a new product file.
typedef struct _cpl_multiframe_ cpl_multiframe |
The opaque multi-frame data type.
typedef enum _cpl_multiframe_id_mode_ cpl_multiframe_id_mode |
The flags indicating the naming scheme to use for multi-frame datasets.
The flags indicating the naming scheme to use for multi-frame datasets.
cpl_error_code cpl_multiframe_add_empty | ( | cpl_multiframe * | self, |
const char * | id | ||
) |
Add a placeholder to a multi-frame container.
self | The multi-frame object. |
id | Unique dataset identifier. |
CPL_ERROR_NONE
on success, and an appropriate error code otherwise.The function adds an empty dataset, a placeholder to a multi-frame container. An empty dataset is special since it is not attached to an underlying data file. When the multi-frame object is written to a file, an empty dataset appears as a named, but otherwise empty unit.
References CPL_ERROR_ILLEGAL_INPUT, CPL_ERROR_ILLEGAL_OUTPUT, and CPL_ERROR_NONE.
cpl_error_code cpl_multiframe_append_datagroup | ( | cpl_multiframe * | self, |
const char * | id, | ||
const cpl_frame * | frame, | ||
cpl_size | nsets, | ||
const char ** | names, | ||
const cpl_regex ** | filter1, | ||
const cpl_regex ** | filter2, | ||
const char ** | properties, | ||
unsigned int | flags | ||
) |
Adds a group of dataset references given by name to a multi-frame container object.
self | The multi-frame object. |
id | Unique dataset identifier. |
frame | The source data frame from which the datasets are taken. |
nsets | The number of datasets to be merged. |
names | The names of the source datasets in the source data frame. |
filter1 | Property filters to apply to the primary header of each source dataset. |
filter2 | Property filters to apply to the extension header of each source dataset. |
properties | Property names to be updated. |
flags | Flag controlling the creation of the dataset's target id. |
CPL_ERROR_NONE
on success, and an appropriate error code otherwise.The function is equivalent to cpl_multiframe_append_datagroup_from_position(), but the source datasets to be added are looked up in the source data frame frame using their names given in the array names.
References CPL_ERROR_DATA_NOT_FOUND, CPL_ERROR_ILLEGAL_INPUT, CPL_ERROR_NULL_INPUT, cpl_fits_find_extension(), cpl_frame_get_filename(), CPL_MULTIFRAME_ID_JOIN, and CPL_MULTIFRAME_ID_PREFIX.
cpl_error_code cpl_multiframe_append_datagroup_from_position | ( | cpl_multiframe * | self, |
const char * | id, | ||
const cpl_frame * | frame, | ||
cpl_size | nsets, | ||
cpl_size * | positions, | ||
const cpl_regex ** | filter1, | ||
const cpl_regex ** | filter2, | ||
const char ** | properties, | ||
unsigned int | flags | ||
) |
Adds a group of dataset references given by position to a multi-frame container object.
self | The multi-frame object. |
id | Unique dataset identifier. |
frame | The source data frame from which the datasets are taken. |
nsets | The number of datasets to be merged. |
positions | Positions of the source datasets in the source data frame. |
filter1 | Property filters to apply to the primary header of each source dataset. |
filter2 | Property filters to apply to the extension header of each source dataset. |
properties | Property names to be updated. |
flags | Flag controlling the creation of the dataset's target id. |
CPL_ERROR_NONE
on success, and an appropriate error code otherwise.The function adds nsets new dataset entry to the multi-frame self. The datasets to add are taken from the source data frame frame and are specified by the first nsets positions passed through the array positions. Before each selected dataset is added to the multi-frame self, the dataset's primary and supplementary properties are merged. If the filter arguments are given, i.e. the respective entries in filter1 and/or filter2 are non NULL
, they are applied to the primary and the supplementary properties before both are merged. The arrays filter1 and filter2 must be given, and they must have nsets elements. The array elements, i.e. an individual filter may be set to NULL
if no filter should be applied.
The creation of the dataset's target id is controlled by the argument flags. It can be only set to CPL_MULTIFRAME_ID_PREFIX
or CPL_MULTIFRAME_ID_JOIN
. If flags is set to CPL_MULTIFRAME_ID_PREFIX
then id is used as prefix for the current dataset's original name (extension name). If the dataset to be appended does not have a name, id is used as the dataset identifier. If flags is set to CPL_MULTIFRAME_ID_JOIN
, the dataset's identifier is created by concatenating the dataset name found in the primary properties, and the dataset name taken from the supplementary properties, using id as separator string. If no dataset name is found in the supplementary properties, only the dataset name found in the primary properties is used as identifier and the given separator is not appended. Note that for this last method it is an error if there is no dataset name present in the primary properties of the source dataset.
The argument id may be the empty string for the method CPL_MULTIFRAME_ID_JOIN
. For the method CPL_MULTIFRAME_ID_PREFIX
this is an error.
If properties is given it has to be a NULL
terminated array of property names. For each specified property name their value is changed according to the naming scheme selected by flags, i.e. the value is either prefixed by id, or it is set to the concatenation of the source dataset name found in its primary properties, id, and its original value. This can be used to correctly change properties used to reference one of the other datasets in the given group through their value. If a given property is not found, it is ignored.
References CPL_ERROR_ILLEGAL_INPUT, CPL_ERROR_NULL_INPUT, cpl_frame_get_filename(), CPL_MULTIFRAME_ID_JOIN, and CPL_MULTIFRAME_ID_PREFIX.
cpl_error_code cpl_multiframe_append_dataset | ( | cpl_multiframe * | self, |
const char * | id, | ||
const cpl_frame * | frame, | ||
const char * | name, | ||
const cpl_regex * | filter1, | ||
const cpl_regex * | filter2, | ||
unsigned int | flags | ||
) |
Adds a dataset reference given by name to a multi-frame container object.
self | The multi-frame object. |
id | Unique dataset identifier. |
frame | The source data frame from which the dataset is taken. |
name | Name of the source dataset in the source data frame. |
filter1 | Property filter to apply to the primary header of the source dataset. |
filter2 | Property filter to apply to the extension header of the source dataset. |
flags | Flag controlling the creation of the dataset's target id. |
CPL_ERROR_NONE
on success, and an appropriate error code otherwise.The function adds a new dataset entry to the multi-frame self. The dataset to add is looked up in the source data frame frame using its name name. It is an error if no dataset with the given name name is found. Before the selected dataset is added to the multi-frame self, the dataset's primary and supplementary properties are merged. If the filter arguments are given, i.e. filter1 and/or filter2 are non NULL
, they are applied to the primary and the supplementary properties before both are merged.
The creation of the dataset's target id is controlled by the argument flags. It can be set to one of the values defined by the enumeration cpl_multiframe_id_mode. If flags is set to CPL_MULTIFRAME_ID_SET
, the argument id is used as dataset identifier. If flags is set to CPL_MULTIFRAME_ID_PREFIX
then id is used as prefix for the dataset's original name (extension name). If the dataset to be appended does not have a name, id is used as the full dataset identifier. If flags is set to CPL_MULTIFRAME_ID_JOIN
, the dataset's identifier is created by concatenating the dataset name found in the primary properties, and the dataset name taken from the supplementary properties, using id as separator string. If no dataset name is found in the supplementary properties, only the dataset name found in the primary properties is used as identifier and the given separator is not appended. Note that for this last method it is an error if there is no dataset name present in the primary properties of the source dataset.
The argument id may be the empty string for the methods CPL_MULTIFRAME_ID_SET
and CPL_MULTIFRAME_ID_JOIN
. For the method CPL_MULTIFRAME_ID_PREFIX
this is an error.
References CPL_ERROR_DATA_NOT_FOUND, CPL_ERROR_ILLEGAL_INPUT, CPL_ERROR_NULL_INPUT, cpl_frame_get_filename(), CPL_MULTIFRAME_ID_JOIN, CPL_MULTIFRAME_ID_PREFIX, and CPL_MULTIFRAME_ID_SET.
cpl_error_code cpl_multiframe_append_dataset_from_position | ( | cpl_multiframe * | self, |
const char * | id, | ||
const cpl_frame * | frame, | ||
cpl_size | position, | ||
const cpl_regex * | filter1, | ||
const cpl_regex * | filter2, | ||
unsigned int | flags | ||
) |
Adds a dataset reference given by position to a multi-frame container object.
self | The multi-frame object. |
id | Unique dataset identifier. |
frame | The source data frame from which the dataset is taken. |
position | Position of the source dataset in the source data frame. |
filter1 | Property filter to apply to the primary header of the source dataset. |
filter2 | Property filter to apply to the extension header of the source dataset. |
flags | Flag controlling the creation of the dataset's target id. |
CPL_ERROR_NONE
on success, and an appropriate error code otherwise.The function adds a new dataset entry to the multi-frame self. The dataset to add is the taken from position position of the source data frame frame. Before the selected dataset is added to the multi-frame self, the dataset's primary and supplementary properties are merged. If the filter arguments are given, i.e. filter1 and/or filter2 are non NULL
, they are applied to the primary and the supplementary properties before both are merged.
The creation of the dataset's target id is controlled by the argument flags. It can be set to one of the values defined by the enumeration cpl_multiframe_id_mode. If flags is set to CPL_MULTIFRAME_ID_SET
, the argument id is used as dataset identifier. If flags is set to CPL_MULTIFRAME_ID_PREFIX
then id is used as prefix for the dataset's original name (extension name). If the dataset to be appended does not have a name, id is used as the full dataset identifier. If flags is set to CPL_MULTIFRAME_ID_JOIN
, the dataset's identifier is created by concatenating the dataset name found in the primary properties, and the dataset name taken from the supplementary properties, using id as separator string. If no dataset name is found in the supplementary properties, only the dataset name found in the primary properties is used as identifier and the given separator is not appended. Note that for this last method it is an error if there is no dataset name present in the primary properties of the source dataset.
The argument id may be the empty string for the methods CPL_MULTIFRAME_ID_SET
and CPL_MULTIFRAME_ID_JOIN
. For the method CPL_MULTIFRAME_ID_PREFIX
this is an error.
References CPL_ERROR_ILLEGAL_INPUT, CPL_ERROR_NULL_INPUT, cpl_frame_get_filename(), CPL_MULTIFRAME_ID_JOIN, CPL_MULTIFRAME_ID_PREFIX, and CPL_MULTIFRAME_ID_SET.
void cpl_multiframe_delete | ( | cpl_multiframe * | self | ) |
Destroys a multi-frame container object.
self | The multi-frame container. |
The function deallocates the multi-frame container self.
cpl_size cpl_multiframe_get_size | ( | const cpl_multiframe * | self | ) |
Get the size of a multi-frame container object.
self | The multi-frame object. |
The function returns the number of dataset entries stored in the multi-frame self.
References CPL_ERROR_NULL_INPUT.
cpl_multiframe* cpl_multiframe_new | ( | const cpl_frame * | head, |
const char * | id, | ||
cpl_regex * | filter | ||
) |
Create a new multi-frame container object.
head | The first dataset of the multi-frame object |
id | Unique dataset identifier. |
filter | Filter to be applied to the dataset properties on merge. |
NULL
otherwise.The function allocates the memory for a multi-frame container and adds the frame master as the head, i.e. the first and emtpy dataset of the multi-frame object. A unique dataset identifier id may be given. The identifier id may be the empty string, in which case it is ignored when writing the multi-frame object to a file. Furthermore a regular expression filter object may be given which will be applied to each of the properties of the dataset head. Only those properties of em head, which pass the filter filter will be propagated to the created multi-frame container.
References CPL_ERROR_NULL_INPUT.
cpl_error_code cpl_multiframe_write | ( | cpl_multiframe * | self, |
const char * | filename | ||
) |
Write a multi-frame container to a file.
self | The multi-frame container object. |
filename | Name of the file to which the multi-frame object is written. |
CPL_ERROR_NONE
on success, and an appropriate error code otherwise.The function writes the multi-frame object self to the file filename. A multi-frame object contains only the properties and the references to the data units, which may be located in different files. Only when this function is called the all referenced datasets are copied and written to the output file.
References CPL_ERROR_DATA_NOT_FOUND, CPL_ERROR_FILE_NOT_CREATED, CPL_ERROR_NONE, and CPL_ERROR_NULL_INPUT.