Loading...
Searching...
No Matches
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.