Common Pipeline Library Reference Manual 6.0
Defines | Typedefs | Enumerations | Functions

Frames

Defines

#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 typedefCX_BEGIN_DECLS
struct _cpl_frame_ 
cpl_frame
 The frame data type.
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_framecpl_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_framecpl_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>

Define Documentation

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


Typedef Documentation

typedef typedefCX_BEGIN_DECLS struct _cpl_frame_ cpl_frame

The frame data type.

The frame group data type.

The frame level data type.

The frame type data type.


Enumeration Type Documentation

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.

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.

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

void cpl_frame_delete ( cpl_frame self)

Destroy a frame.

Parameters:
selfA 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.

void cpl_frame_dump ( const cpl_frame frame,
FILE *  stream 
)

Dump the frame debugging information to the given stream.

Parameters:
frameThe frame.
streamThe 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.

cpl_frame* cpl_frame_duplicate ( const cpl_frame other)

Create a copy of a frame.

Parameters:
otherThe 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.

const char* cpl_frame_get_filename ( const cpl_frame self)

Get the file name to which a frame refers.

Parameters:
selfA 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.

cpl_frame_group cpl_frame_get_group ( const cpl_frame self)

Get the current group of a frame.

Parameters:
selfA 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.

cpl_frame_level cpl_frame_get_level ( const cpl_frame self)

Get the current level of a frame.

Parameters:
selfA 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.

cpl_size cpl_frame_get_nextensions ( const cpl_frame self)

Get the number of extensions of this frame.

Parameters:
selfA 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.

const char* cpl_frame_get_tag ( const cpl_frame self)

Get the category tag of a frame.

Parameters:
selfA 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.

cpl_frame_type cpl_frame_get_type ( const cpl_frame self)

Get the type of a frame.

Parameters:
selfA 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.

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 initialises 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, resepctively.

cpl_error_code cpl_frame_set_filename ( cpl_frame self,
const char *  filename 
)

Set the file name to which a frame refers.

Parameters:
selfA frame.
filenameThe 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.

cpl_error_code cpl_frame_set_group ( cpl_frame self,
cpl_frame_group  group 
)

Set the group attribute of a frame.

Parameters:
selfA frame.
groupNew 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.

cpl_error_code cpl_frame_set_level ( cpl_frame self,
cpl_frame_level  level 
)

Set the level attribute of a frame.

Parameters:
selfA frame.
levelNew 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.

cpl_error_code cpl_frame_set_tag ( cpl_frame self,
const char *  tag 
)

Set a frame's category tag.

Parameters:
selfA frame.
tagThe 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.

cpl_error_code cpl_frame_set_type ( cpl_frame self,
cpl_frame_type  type 
)

Set the type of a frame.

Parameters:
selfA frame.
typeNew 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.