Modules
	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.

Modules

Typedefs

Enumerations

Functions

Detailed Description

Typedef Documentation

◆ cpl_multiframe

◆ cpl_multiframe_id_mode

Enumeration Type Documentation

◆ _cpl_multiframe_id_mode_

Function Documentation

◆ cpl_multiframe_add_empty()

◆ cpl_multiframe_append_datagroup()

◆ cpl_multiframe_append_datagroup_from_position()

◆ cpl_multiframe_append_dataset()

◆ cpl_multiframe_append_dataset_from_position()

◆ cpl_multiframe_dataset_get_id()

◆ cpl_multiframe_dataset_get_position()

◆ cpl_multiframe_dataset_properties_remove()

◆ cpl_multiframe_dataset_properties_update()

◆ cpl_multiframe_delete()

◆ cpl_multiframe_get_size()

◆ cpl_multiframe_new()

◆ cpl_multiframe_write()