Frames

Macros
#define	CPL_FRAME_GROUP_CALIB_ID   "CALIB"
	Frame group tag for calibration data.
#define	CPL_FRAME_GROUP_PRODUCT_ID   "PRODUCT"
	Frame group tag for processed data.
#define	CPL_FRAME_GROUP_RAW_ID   "RAW"
	Frame group tag for unprocessed data.

Typedefs
typedef struct _cpl_frame_	cpl_frame
	The frame data type.
typedef int(*	cpl_frame_compare_func) (const cpl_frame *self, const cpl_frame *other)
	Frame comparison function.
typedef enum _cpl_frame_group_	cpl_frame_group
	The frame group data type.
typedef enum _cpl_frame_level_	cpl_frame_level
	The frame level data type.
typedef enum _cpl_frame_type_	cpl_frame_type
	The frame type data type.

Enumerations
enum	_cpl_frame_group_ {   CPL_FRAME_GROUP_NONE ,   CPL_FRAME_GROUP_RAW ,   CPL_FRAME_GROUP_CALIB ,   CPL_FRAME_GROUP_PRODUCT }
	Supported frame groups. More...
enum	_cpl_frame_level_ {   CPL_FRAME_LEVEL_NONE ,   CPL_FRAME_LEVEL_TEMPORARY ,   CPL_FRAME_LEVEL_INTERMEDIATE ,   CPL_FRAME_LEVEL_FINAL }
	Supported frame processing levels. More...
enum	_cpl_frame_type_ {   CPL_FRAME_TYPE_NONE ,   CPL_FRAME_TYPE_IMAGE ,   CPL_FRAME_TYPE_MATRIX ,   CPL_FRAME_TYPE_TABLE ,   CPL_FRAME_TYPE_PAF ,   CPL_FRAME_TYPE_ANY }
	Supported frame types. More...

Functions
void	cpl_frame_delete (cpl_frame *self)
	Destroy a frame.
void	cpl_frame_dump (const cpl_frame *frame, FILE *stream)
	Dump the frame debugging information to the given stream.
cpl_frame *	cpl_frame_duplicate (const cpl_frame *other)
	Create a copy of a frame.
const char *	cpl_frame_get_filename (const cpl_frame *self)
	Get the file name to which a frame refers.
cpl_frame_group	cpl_frame_get_group (const cpl_frame *self)
	Get the current group of a frame.
cpl_frame_level	cpl_frame_get_level (const cpl_frame *self)
	Get the current level of a frame.
cpl_size	cpl_frame_get_nextensions (const cpl_frame *self)
	Get the number of extensions of this frame.
const char *	cpl_frame_get_tag (const cpl_frame *self)
	Get the category tag of a frame.
cpl_frame_type	cpl_frame_get_type (const cpl_frame *self)
	Get the type of a frame.
cpl_frame *	cpl_frame_new (void)
	Create a new, empty frame.
cpl_error_code	cpl_frame_set_filename (cpl_frame *self, const char *filename)
	Set the file name to which a frame refers.
cpl_error_code	cpl_frame_set_group (cpl_frame *self, cpl_frame_group group)
	Set the group attribute of a frame.
cpl_error_code	cpl_frame_set_level (cpl_frame *self, cpl_frame_level level)
	Set the level attribute of a frame.
cpl_error_code	cpl_frame_set_tag (cpl_frame *self, const char *tag)
	Set a frame's category tag.
cpl_error_code	cpl_frame_set_type (cpl_frame *self, cpl_frame_type type)
	Set the type of a frame.

Detailed Description

This module implements the cpl_frame type. A frame is a container for descriptive attributes related to a data file. The attributes are related to a data file through the file name member of the frame type. Among the attributes which may be assigned to a data file is an attribute identifying the type of the data stored in the file (image or table data), a classification tag indicating the kind of data the file contains and an attribute denoting to which group the data file belongs (raw, processed or calibration file). For processed data a processing level indicates whether the product is an temporary, intermediate or final product.

Synopsis:

#include <cpl_frame.h>

Macro Definition Documentation

CPL_FRAME_GROUP_CALIB_ID

#define CPL_FRAME_GROUP_CALIB_ID   "CALIB"

Frame group tag for calibration data.

CPL_FRAME_GROUP_PRODUCT_ID

#define CPL_FRAME_GROUP_PRODUCT_ID   "PRODUCT"

Frame group tag for processed data.

CPL_FRAME_GROUP_RAW_ID

#define CPL_FRAME_GROUP_RAW_ID   "RAW"

Frame group tag for unprocessed data.

Typedef Documentation

cpl_frame

typedef struct _cpl_frame_ cpl_frame

The frame data type.

cpl_frame_compare_func

typedef int(* cpl_frame_compare_func) (const cpl_frame *self, const cpl_frame *other)

Frame comparison function.

Type definition for functions which compares the frame other with the frame self.

All function of this type must return -1, 0, or 1 if self is considered to be less than, equal or greater than other respectively.

cpl_frame_group

typedef enum _cpl_frame_group_ cpl_frame_group

The frame group data type.

cpl_frame_level

typedef enum _cpl_frame_level_ cpl_frame_level

The frame level data type.

cpl_frame_type

typedef enum _cpl_frame_type_ cpl_frame_type

The frame type data type.

Enumeration Type Documentation

_cpl_frame_group_

enum _cpl_frame_group_

Supported frame groups.

Defines the possible values for the frame's group attribute.

Enumerator
CPL_FRAME_GROUP_NONE	The frame does not belong to any supported group.
CPL_FRAME_GROUP_RAW	The frame is associated to unprocessed data.
CPL_FRAME_GROUP_CALIB	The frame is associated to calibration data.
CPL_FRAME_GROUP_PRODUCT	The frame is associated to processed data.

_cpl_frame_level_

enum _cpl_frame_level_

Supported frame processing levels.

Note

The processing levels are just flags and it is left to the application to trigger the appropriate action for the different levels.

Enumerator
CPL_FRAME_LEVEL_NONE	Undefined processing level
CPL_FRAME_LEVEL_TEMPORARY	Temporary product. The corresponding file will be deleted when the processing chain is completed.
CPL_FRAME_LEVEL_INTERMEDIATE	Intermediate product. The corresponding file is only kept on request. The default is to delete these products at the end of the processing chain.
CPL_FRAME_LEVEL_FINAL	Final data product, which is always written to a file at the end of the processing chain.

_cpl_frame_type_

enum _cpl_frame_type_

Supported frame types.

Defines the possible values for the frame's type attribute.

Enumerator
CPL_FRAME_TYPE_NONE	Undefined frame type
CPL_FRAME_TYPE_IMAGE	Image frame type identifier
CPL_FRAME_TYPE_MATRIX	Matrix frame type identifier
CPL_FRAME_TYPE_TABLE	Table frame type identifier
CPL_FRAME_TYPE_PAF	paf frame type identifier
CPL_FRAME_TYPE_ANY	identifier for any other type

Function Documentation

cpl_frame_delete()

void cpl_frame_delete

(

cpl_frame *

self

)

Destroy a frame.

Parameters

self

A frame.

Returns

Nothing.

The function deallocates the memory used by the frame self. If self is NULL, nothing is done, and no error is set.

Referenced by cpl_frameset_join(), and cpl_frameset_new().

cpl_frame_dump()

void cpl_frame_dump	(	const cpl_frame *	frame,
		FILE *	stream
	)

Dump the frame debugging information to the given stream.

Parameters

frame	The frame.
stream	The output stream to use.

Returns

Nothing.

The function dumps the contents of the frame frame to the output stream stream. If stream is NULL the function writes to the standard output. If frame is NULL the function does nothing.

References cpl_frame_get_filename(), cpl_frame_get_group(), cpl_frame_get_level(), cpl_frame_get_tag(), cpl_frame_get_type(), CPL_FRAME_GROUP_CALIB, CPL_FRAME_GROUP_PRODUCT, CPL_FRAME_GROUP_RAW, CPL_FRAME_LEVEL_FINAL, CPL_FRAME_LEVEL_INTERMEDIATE, CPL_FRAME_LEVEL_TEMPORARY, CPL_FRAME_TYPE_ANY, CPL_FRAME_TYPE_IMAGE, CPL_FRAME_TYPE_MATRIX, CPL_FRAME_TYPE_PAF, and CPL_FRAME_TYPE_TABLE.

Referenced by cpl_frameset_dump().

cpl_frame_duplicate()

cpl_frame * cpl_frame_duplicate

(

const cpl_frame *

other

)

Create a copy of a frame.

Parameters

other

The frame to copy.

Returns

The function returns a handle for the created clone. If an error occurs the function returns NULL and sets an appropriate error code.

Errors

CPL_ERROR_NULL_INPUT

The parameter other is a NULL pointer.

The function creates a clone of the input frame other. All members of the input frame are copied.

References CPL_ERROR_NULL_INPUT.

Referenced by cpl_frameset_duplicate(), cpl_frameset_extract(), and cpl_frameset_join().

cpl_frame_get_filename()

const char * cpl_frame_get_filename

(

const cpl_frame *

self

)

Get the file name to which a frame refers.

Parameters

self

A frame.

Returns

The file name to which the frame refers, or NULL if a file name has not been set.

Errors

CPL_ERROR_NULL_INPUT	The parameter self is a NULL pointer.
CPL_ERROR_DATA_NOT_FOUND	The frame self is not associated to a file.

The function returns the read-only name of a file associated to self. A file is associated to self by calling cpl_frame_set_filename() for self. If self is not associated to a file this function returns NULL.

References CPL_ERROR_DATA_NOT_FOUND, and CPL_ERROR_NULL_INPUT.

Referenced by cpl_dfs_setup_product_header(), cpl_frame_dump(), cpl_imagelist_load_frameset(), cpl_multiframe_append_datagroup(), cpl_multiframe_append_datagroup_from_position(), cpl_multiframe_append_dataset(), cpl_multiframe_append_dataset_from_position(), and cpl_multiframe_new().

cpl_frame_get_group()

cpl_frame_group cpl_frame_get_group

(

const cpl_frame *

self

)

Get the current group of a frame.

Parameters

self

A frame.

Returns

The frame's current group. The function returns CPL_FRAME_GROUP_NONE if an error occurs and sets an appropriate error code.

Errors

CPL_ERROR_NULL_INPUT

The parameter self is a NULL pointer.

The function returns the group attribute of the frame self.

References CPL_ERROR_NULL_INPUT, and CPL_FRAME_GROUP_NONE.

Referenced by cpl_dfs_setup_product_header(), cpl_dfs_sign_products(), and cpl_frame_dump().

cpl_frame_get_level()

cpl_frame_level cpl_frame_get_level

(

const cpl_frame *

self

)

Get the current level of a frame.

Parameters

self

A frame.

Returns

The frame's current level. The function returns CPL_FRAME_LEVEL_NONE if an error occurs and sets an appropriate error code.

Errors

CPL_ERROR_NULL_INPUT

The parameter self is a NULL pointer.

The function returns the level attribute of the frame self.

References CPL_ERROR_NULL_INPUT, and CPL_FRAME_LEVEL_NONE.

Referenced by cpl_frame_dump().

cpl_frame_get_nextensions()

cpl_size cpl_frame_get_nextensions

(

const cpl_frame *

self

)

Get the number of extensions of this frame.

Parameters

self

A frame.

Returns

The number of extensions in the file

Errors

CPL_ERROR_NULL_INPUT	The parameter self is a NULL pointer.
CPL_ERROR_DATA_NOT_FOUND	The frame self is not associated to a file.

The function returns the number of extensions in the frame or -1 in case of error.

References CPL_ERROR_DATA_NOT_FOUND, CPL_ERROR_NULL_INPUT, cpl_error_set, and cpl_fits_count_extensions().

cpl_frame_get_tag()

const char * cpl_frame_get_tag

(

const cpl_frame *

self

)

Get the category tag of a frame.

Parameters

self

A frame.

Returns

The frame's category tag or NULL if the tag is not set. The function returns NULL if an error occurs and an appropriate error code is set.

Errors

CPL_ERROR_NULL_INPUT

The parameter self is a NULL pointer.

The function returns the read-only frame's category tag. If a tag has not yet been set a NULL pointer is returned.

References CPL_ERROR_NULL_INPUT.

Referenced by cpl_dfs_setup_product_header(), cpl_frame_dump(), cpl_frameset_duplicate(), cpl_frameset_erase_frame(), and cpl_frameset_insert().

cpl_frame_get_type()

cpl_frame_type cpl_frame_get_type

(

const cpl_frame *

self

)

Get the type of a frame.

Parameters

self

A frame.

Returns

The frame's type. The returns CPL_FRAME_TYPE_NONE if an error occurs and sets an appropriate error code.

Errors

CPL_ERROR_NULL_INPUT

The parameter self is a NULL pointer.

The function returns the type of the data object to which it currently refers.

References CPL_ERROR_NULL_INPUT, and CPL_FRAME_TYPE_NONE.

Referenced by cpl_frame_dump().

cpl_frame_new()

cpl_frame * cpl_frame_new

(

void

)

Create a new, empty frame.

Returns

A handle for the newly created frame.

The function allocates the memory for the new frame and initializes it to an empty frame, i.e. it is created without tag and file information, and the type, group and level set to CPL_FRAME_TYPE_NONE, CPL_FRAME_GROUP_NONE, and CPL_FRAME_LEVEL_NONE, respectively.

References CPL_FRAME_GROUP_NONE, CPL_FRAME_LEVEL_NONE, and CPL_FRAME_TYPE_NONE.

cpl_frame_set_filename()

cpl_error_code cpl_frame_set_filename	(	cpl_frame *	self,
		const char *	filename
	)

Set the file name to which a frame refers.

Parameters

self	A frame.
filename	The new file name.

Returns

The function returns CPL_ERROR_NONE on success or a CPL error code otherwise.

Errors

CPL_ERROR_NULL_INPUT

The parameter self or filename is a NULL pointer.

The function sets the name of the file, to which the frame self refers. Any file name which was previously set by a call to this function is replaced. If no file name is present yet it is created and initialised to filename.

References CPL_ERROR_NONE, and CPL_ERROR_NULL_INPUT.

cpl_frame_set_group()

cpl_error_code cpl_frame_set_group	(	cpl_frame *	self,
		cpl_frame_group	group
	)

Set the group attribute of a frame.

Parameters

self	A frame.
group	New group attribute.

Returns

The function returns CPL_ERROR_NONE on success or a CPL error code otherwise.

Errors

CPL_ERROR_NULL_INPUT

The parameter self is a NULL pointer.

The function sets the group attribute of the frame self to group.

References CPL_ERROR_NONE, and CPL_ERROR_NULL_INPUT.

cpl_frame_set_level()

cpl_error_code cpl_frame_set_level	(	cpl_frame *	self,
		cpl_frame_level	level
	)

Set the level attribute of a frame.

Parameters

self	A frame.
level	New level attribute.

Returns

The function returns CPL_ERROR_NONE on success or a CPL error code otherwise.

Errors

CPL_ERROR_NULL_INPUT

The parameter self is a NULL pointer.

The function sets the level attribute of the frame self to level.

References CPL_ERROR_NONE, and CPL_ERROR_NULL_INPUT.

cpl_frame_set_tag()

cpl_error_code cpl_frame_set_tag	(	cpl_frame *	self,
		const char *	tag
	)

Set a frame's category tag.

Parameters

self	A frame.
tag	The new category tag.

Returns

The function returns CPL_ERROR_NONE on success or a CPL error code otherwise.

Errors

CPL_ERROR_NULL_INPUT

The parameter self or tag is a NULL pointer.

The function sets the category tag of self, replacing any previously set tag. If the frame does not yet have a tag is is created and initialised to tag.

References CPL_ERROR_NONE, and CPL_ERROR_NULL_INPUT.

cpl_frame_set_type()

cpl_error_code cpl_frame_set_type	(	cpl_frame *	self,
		cpl_frame_type	type
	)

Set the type of a frame.

Parameters

self	A frame.
type	New frame type.

Returns

The function returns CPL_ERROR_NONE on success or a CPL error code otherwise.

Errors

CPL_ERROR_NULL_INPUT

The parameter self is a NULL pointer.

The function sets the type of the frame self to type.

References CPL_ERROR_NONE, and CPL_ERROR_NULL_INPUT.