Loading...
Searching...
No Matches
Multi Frames

## Topics

| Regular Expression Filter

## Typedefs

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.

## 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.
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.
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.
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.
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.
const char * | cpl_multiframe_dataset_get_id (const cpl_multiframe *self, cpl_size position)
| Get the unique dataset identifier of a dataset in a multi-frame container given by its position.
cpl_size | cpl_multiframe_dataset_get_position (const cpl_multiframe *self, const char *id)
| Get the position of a dataset in a multi-frame container given its unique identifier.
cpl_error_code | cpl_multiframe_dataset_properties_remove (cpl_multiframe *self, cpl_size position, const cpl_propertylist *properties)
| Remove header entries of a dataset in a multi-frame container, given its position.
cpl_error_code | cpl_multiframe_dataset_properties_update (cpl_multiframe *self, cpl_size position, const cpl_propertylist *properties)
| Update the metadata of a dataset in a multi-frame container given by its position.
void | cpl_multiframe_delete (cpl_multiframe *self)
| Destroys a multi-frame container object.
cpl_size | cpl_multiframe_get_size (const cpl_multiframe *self)
| Get the size of a multi-frame container object.
cpl_multiframe * | cpl_multiframe_new (const cpl_frame *head, const char *id, cpl_regex *filter)
| Create a new multi-frame container object.
cpl_error_code | cpl_multiframe_write (cpl_multiframe *self, const char *filename)
| Write a multi-frame container to a file.

## Detailed Description

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.

Synopsis:
  #include <cpl_multiframe.h>

Note
  This feature should be considered as experimental!

## Typedef Documentation

## cpl_multiframe

typedef struct _cpl_multiframe_ cpl_multiframe

The opaque multi-frame data type.

## cpl_multiframe_id_mode

typedef enum _cpl_multiframe_id_mode_ cpl_multiframe_id_mode

The flags indicating the naming scheme to use for multi-frame datasets.

## Enumeration Type Documentation

## _cpl_multiframe_id_mode_

enum _cpl_multiframe_id_mode_

The flags indicating the naming scheme to use for multi-frame datasets.

Enumerator
CPL_MULTIFRAME_ID_SET | Use the given identifier as dataset name
CPL_MULTIFRAME_ID_PREFIX | Create the dataset name from the given identifier by appending the name of the source dataset.
CPL_MULTIFRAME_ID_JOIN | Create the dataset name by concatenating the names of the involved source datasets. The given identifier is used as separator.

## Function Documentation

## cpl_multiframe_add_empty()

cpl_error_code cpl_multiframe_add_empty | ( | cpl_multiframe * | self,
|  | const char * | id )

Add a placeholder to a multi-frame container.

Parameters

  self | The multi-frame object.
  id | Unique dataset identifier.

Returns
  The function returns `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_multiframe_append_datagroup()

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.

Parameters

  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.

Returns
  The function returns `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_NONE, CPL_ERROR_NULL_INPUT, cpl_error_set_where, cpl_fits_find_extension(), cpl_frame_get_filename(), CPL_MULTIFRAME_ID_JOIN, and CPL_MULTIFRAME_ID_PREFIX.

## cpl_multiframe_append_datagroup_from_position()

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.

Parameters

  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.

Returns
  The function returns `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_NONE, CPL_ERROR_NULL_INPUT, cpl_error_set_where, cpl_frame_get_filename(), CPL_MULTIFRAME_ID_JOIN, and CPL_MULTIFRAME_ID_PREFIX.

## cpl_multiframe_append_dataset()

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.

Parameters

  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.

Returns
  The function returns `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_NONE, CPL_ERROR_NULL_INPUT, cpl_error_set_where, cpl_frame_get_filename(), CPL_MULTIFRAME_ID_JOIN, CPL_MULTIFRAME_ID_PREFIX, and CPL_MULTIFRAME_ID_SET.

## cpl_multiframe_append_dataset_from_position()

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.

Parameters

  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.

Returns
  The function returns `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_NONE, CPL_ERROR_NULL_INPUT, cpl_error_set_where, cpl_frame_get_filename(), CPL_MULTIFRAME_ID_JOIN, CPL_MULTIFRAME_ID_PREFIX, and CPL_MULTIFRAME_ID_SET.

## cpl_multiframe_dataset_get_id()

const char * cpl_multiframe_dataset_get_id | ( | const cpl_multiframe * | self,
|  | cpl_size | position )

Get the unique dataset identifier of a dataset in a multi-frame container given by its position.

Parameters

  self | The multi-frame object.
  position | Position of the dataset in the multi-frame container.

Returns
  The function returns the unique identifier of the dataset on success. On error the function returns `NULL` and sets an appropriate error code.

Errors

  CPL_ERROR_NULL_INPUT | The given multi-frame container pointer is a `NULL` pointer.
  CPL_ERROR_ILLEGAL_INPUT | The given dataset positions is invalid (out of bounds).
  CPL_ERROR_DATA_NOT_FOUND | The multi-frame container itself is empty.

The function retrieves the unique identifier of the dataset found at position position in the multi-frame container self.

References cpl_ensure, CPL_ERROR_DATA_NOT_FOUND, CPL_ERROR_ILLEGAL_INPUT, and CPL_ERROR_NULL_INPUT.

## cpl_multiframe_dataset_get_position()

cpl_size cpl_multiframe_dataset_get_position | ( | const cpl_multiframe * | self,
|  | const char * | id )

Get the position of a dataset in a multi-frame container given its unique identifier.

Parameters

  self | The multi-frame object.
  id | Unique id of the dataset in the multi-frame container.

Returns
  The function returns the position of the dataset on success. If an error occurs the function returns `0` and sets an appropriate error code.

Errors

  CPL_ERROR_NULL_INPUT | The given multi-frame container pointer is a `NULL` pointer.
  CPL_ERROR_DATA_NOT_FOUND | Either the multi-frame container is empty, or the given dataset id cannot be found.

Given the unique identifier id of the dataset, the function locates the dataset in the multi-frame container self and returns its position.

References cpl_ensure, CPL_ERROR_DATA_NOT_FOUND, and CPL_ERROR_NULL_INPUT.

## cpl_multiframe_dataset_properties_remove()

cpl_error_code cpl_multiframe_dataset_properties_remove | ( | cpl_multiframe * | self,
|  | cpl_size | position,
|  | const cpl_propertylist * | properties )

Remove header entries of a dataset in a multi-frame container, given its position.

Parameters

  self | The multi-frame object.
  position | Position of the dataset in the multi-frame container.
  properties | The list of properties to remove.

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

Errors

  CPL_ERROR_NULL_INPUT | The given multi-frame container pointer, the property list or both are a `NULL` pointer.
  CPL_ERROR_ILLEGAL_INPUT | The given position of a dataset in the multi-frame container is out of bounds.

The function searches the header of the dataset at position position in the multi-frame container self for each property in properties. If a property is present in the header of the given dataset it is removed. It is not an error if a property which is present in properties is is not found in the header of the dataset. It is also not an error if properties is empty. Note that only the name of the properties in properties is taken into account when removing properties. Any mismatch in the property type or the property value is ignored.

References cpl_ensure_code, CPL_ERROR_ILLEGAL_INPUT, CPL_ERROR_NONE, CPL_ERROR_NULL_INPUT, cpl_property_get_name(), cpl_propertylist_get_const(), cpl_propertylist_get_size(), and cpl_propertylist_is_empty().

## cpl_multiframe_dataset_properties_update()

cpl_error_code cpl_multiframe_dataset_properties_update | ( | cpl_multiframe * | self,
|  | cpl_size | position,
|  | const cpl_propertylist * | properties )

Update the metadata of a dataset in a multi-frame container given by its position.

Parameters

  self | The multi-frame object.
  position | Position of the dataset in the multi-frame container.
  properties | The list of properties to add or modify.

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

Errors

  CPL_ERROR_NULL_INPUT | The given multi-frame container pointer or the property list is a `NULL` pointer.
  CPL_ERROR_ILLEGAL_INPUT | The requested data set position is out of range list is a `NULL` pointer, or the property list contains entries which cannot be parsed into a valid FITS record.
  CPL_ERROR_INVALID_TYPE | The data type of a property to be modified in the data set cannot be determined.
  CPL_ERROR_TYPE_MISMATCH | The data type of a property in the data set does not match the data type it has in the input property list.
  CPL_ERROR_ILLEGAL_OUTPUT | The metadata of the data set could not be updated with the properties in the property list.

The function updates the header of the dataset found at position position in the multi-frame container self with the properties of the property list properties. If a property is present in properties but not in the header of the data set it is appended to the data set header. If a property is already present in the data set header its value and comment will be replaced by the value and comment the property has in properties, provided that the both properties have the same data type.

References cpl_ensure_code, CPL_ERROR_ILLEGAL_INPUT, CPL_ERROR_ILLEGAL_OUTPUT, CPL_ERROR_INVALID_TYPE, CPL_ERROR_NONE, CPL_ERROR_NULL_INPUT, cpl_error_set_message, CPL_ERROR_TYPE_MISMATCH, cpl_property_get_comment(), cpl_property_get_name(), cpl_property_get_type(), cpl_propertylist_get_const(), cpl_propertylist_get_size(), and cpl_propertylist_is_empty().

## cpl_multiframe_delete()

void cpl_multiframe_delete | ( | cpl_multiframe * | self | ) |

Destroys a multi-frame container object.

Parameters

  self | The multi-frame container.

Returns
  Nothing.

The function deallocates the multi-frame container self.

Referenced by cpl_multiframe_new().

## cpl_multiframe_get_size()

cpl_size cpl_multiframe_get_size | ( | const cpl_multiframe * | self | ) |

Get the size of a multi-frame container object.

Parameters

  self | The multi-frame object.

Returns
  The function returns the current number of datasets referenced by the multi-frame container.

The function returns the number of dataset entries stored in the multi-frame self.

References CPL_ERROR_NULL_INPUT.

## cpl_multiframe_new()

cpl_multiframe * cpl_multiframe_new | ( | const cpl_frame * | head,
|  | const char * | id,
|  | cpl_regex * | filter )

Create a new multi-frame container object.

Parameters

  head | The first dataset of the multi-frame object
  id | Unique dataset identifier.
  filter | Filter to be applied to the dataset properties on merge.

Returns
  The function returns a newly allocated multi-frame object on success, or `NULL` otherwise.

The function allocates the memory for a multi-frame container and adds the frame head 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 head, which pass the filter filter will be propagated to the created multi-frame container.

References CPL_ERROR_NULL_INPUT, cpl_frame_get_filename(), cpl_multiframe_delete(), cpl_regex_delete(), CPL_REGEX_EXTENDED, cpl_regex_new(), and CPL_REGEX_NOSUBS.

## cpl_multiframe_write()

cpl_error_code cpl_multiframe_write | ( | cpl_multiframe * | self,
|  | const char * | filename )

Write a multi-frame container to a file.

Parameters

  self | The multi-frame container object.
  filename | Name of the file to which the multi-frame object is written.

Returns
  The function returns `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.