ENVISAT Product Reader C API: Main Page

ENVISAT Product Reader API for C |

# epr_api.h File Reference

`#include <stdio.h>`
`#include "epr_ptrarray.h"`
`#include <stdlib.h>`

Go to the source code of this file.

## Data Structures
struct | EPR_ProductId
| The `EPR_ProductId` structure contains information about an ENVISAT product file which has been opened with the `epr_open_product()` function. More...
struct | EPR_DatasetId
| The `EPR_DatasetId` structure contains information about a dataset within an ENVISAT product file which has been opened with the `epr_open_product()` API function. More...
struct | EPR_DSD
| The `EPR_DSD` structure contains information about the propertier of a dataset properties and its location within an ENVISAT product file. More...
struct | EPR_Record
| The `EPR_Record` structure represents a record instance read from an ENVISAT dataset. More...
struct | EPR_Field
| Represents a field within a record. More...
struct | EPR_Raster
| Represents a raster in which data will be stored. More...
struct | EPR_DatasetRef
| The `EPR_DatasetRef` structure represents the information from `dddb` with the reference to data name (in dddb), field-name and index of the element in field-array, in which (by name) searchable values are located. More...
struct | EPR_FlagDef
| Represents a flag-field within a flag-record. More...
struct | EPR_BandId
| The `EPR_BandId` structure contains information about a band within an ENVISAT product file which has been opened with the `epr_open_product()` API function. More...
struct | EPR_Time
| Represents a binary time value field in ENVISAT records. More...
## Defines
#define | EPR_PRODUCT_API_NAME_STR "ENVISAT Product Reader API"
#define | EPR_PRODUCT_API_VERSION_STR "2.2"
#define | EPR_MAGIC_PRODUCT_ID 0xCAFFEE64
#define | EPR_MAGIC_DATASET_ID 0xEFEABDCA
#define | EPR_MAGIC_BAND_ID 0xFEC21ABD
#define | EPR_MAGIC_RECORD 0x7BABACAE
#define | EPR_MAGIC_FIELD 0xBA0BABBA
#define | EPR_MAGIC_RASTER 0x0BABA0EB
#define | EPR_MAGIC_FLAG_DEF 0xCABA11AD
#define | TRUE 1
#define | FALSE 0
#define | EPR_PRODUCT_ID_STRLEN 48
## Typedefs
typedef enum EPR_DataTypeId | EPR_EDataTypeId
typedef enum EPR_ErrCode | EPR_EErrCode
typedef enum EPR_LogLevel | EPR_ELogLevel
typedef enum EPR_SampleModel | EPR_ESampleModel
typedef enum EPR_ScalingMethod | EPR_EScalingMethod
typedef struct EPR_ProductId | EPR_SProductId
typedef struct EPR_DatasetId | EPR_SDatasetId
typedef struct EPR_BandId | EPR_SBandId
typedef struct EPR_Record | EPR_SRecord
typedef struct EPR_RecordInfo | EPR_SRecordInfo
typedef struct EPR_Field | EPR_SField
typedef struct EPR_FieldInfo | EPR_SFieldInfo
typedef struct EPR_DSD | EPR_SDSD
typedef struct EPR_Raster | EPR_SRaster
typedef struct EPR_FlagDef | EPR_SFlagDef
typedef struct EPR_ParamElem | EPR_SParamElem
typedef struct EPR_Time | EPR_STime
typedef struct EPR_DatasetRef | EPR_SDatasetRef
typedef struct EPR_BitmaskTerm | EPR_SBitmaskTerm
typedef struct EPR_FlagSet | EPR_SFlagSet
typedef void(* | EPR_FErrHandler )(EPR_EErrCode err_code, const char *err_message)
typedef void(* | EPR_FLogHandler )(EPR_ELogLevel log_level, const char *log_message)
typedef int | epr_boolean
typedef unsigned char | uchar
typedef unsigned short | ushort
typedef unsigned int | uint
typedef unsigned long | ulong
typedef int | EPR_Magic
## Enumerations
enum | EPR_DataTypeId { e_tid_unknown = 0, e_tid_uchar = 1, e_tid_char = 2, e_tid_ushort = 3, e_tid_short = 4, e_tid_uint = 5, e_tid_int = 6, e_tid_float = 7, e_tid_double = 8, e_tid_string = 11, e_tid_spare = 13, e_tid_time = 21 }
| The `EPR_DataTypeId` enumeration lists all possible data types for field elements in ENVISAT dataset records. More...
enum | EPR_ErrCode { e_err_none = 0, e_err_null_pointer = 1, e_err_illegal_arg = 2, e_err_illegal_state = 3, e_err_out_of_memory = 4, e_err_index_out_of_range = 5, e_err_illegal_conversion = 6, e_err_illegal_data_type = 7, e_err_file_not_found = 101, e_err_file_access_denied = 102, e_err_file_read_error = 103, e_err_file_write_error = 104, e_err_file_open_failed = 105, e_err_file_close_failed = 106, e_err_api_not_initialized = 201, e_err_invalid_product_id = 203, e_err_invalid_record = 204, e_err_invalid_band = 205, e_err_invalid_raster = 206, e_err_invalid_dataset_name = 207, e_err_invalid_field_name = 208, e_err_invalid_record_name = 209, e_err_invalid_product_name = 210, e_err_invalid_band_name = 211, e_err_invalid_data_format = 212, e_err_invalid_value = 213, e_err_invalid_keyword_name = 214, e_err_unknown_endian_order = 216, e_err_flag_not_found = 301, e_err_invalid_ddbb_format = 402 }
| The `EPR_ErrCode` enumeration lists all possible error codes for the ENVISAT product reader API. More...
enum | EPR_LogLevel { e_log_debug = -1, e_log_info = 0, e_log_warning = 1, e_log_error = 2 }
| The `EPR_LogLevel` enumeration lists possible log levels for the ENVISAT product reader API. More...
enum | EPR_SampleModel { e_smod_1OF1 = 0, e_smod_1OF2 = 1, e_smod_2OF2 = 2, e_smod_3TOI = 3, e_smod_2TOF = 4 }
enum | EPR_ScalingMethod { e_smid_non = 0, e_smid_lin = 1, e_smid_log = 2 }
## Functions
int | epr_init_api (EPR_ELogLevel log_level, EPR_FLogHandler log_handler, EPR_FErrHandler err_handler)
| Initializes the ENVISAT product reader API.
void | epr_close_api ()
| Closes the ENVISAT product reader API by releasing all resources allocated by the API.
int | epr_set_log_level (EPR_ELogLevel log_level)
| Sets the log level for the ENVISAT API.
void | epr_set_log_handler (EPR_FLogHandler log_handler)
| Sets the log handler for the ENVISAT API.
void | epr_log_message (EPR_ELogLevel log_level, const char *log_message)
| A default implementation for a logging function to be passed into the `epr_init()` function.
void | epr_set_err_handler (EPR_FErrHandler err_handler)
| Sets the error handler for the ENVISAT API.
EPR_EErrCode | epr_get_last_err_code ()
| Gets the error code of the error that occured during the last API function call.
const char * | epr_get_last_err_message ()
| Gets the error message of the error that occured during the last API function call.
void | epr_clear_err ()
| Clears the last error.
EPR_SProductId * | epr_open_product (const char *product_file_path)
| Opens the ENVISAT product file with the given file path, reads MPH, SPH and all DSDs, organized the table with parameter of line length and tie points number; returns a file identifier for the product.
int | epr_close_product (EPR_SProductId *product_id)
| Closes the ENVISAT product file determined by the given product identifier.
void | epr_print_record (const EPR_SRecord *record, FILE *ostream)
void | epr_print_field (const EPR_SField *field, FILE *ostream)
void | epr_print_element (const EPR_SRecord *record, uint field_index, uint element_index, FILE *ostream)
void | epr_dump_record (const EPR_SRecord *record)
void | epr_dump_field (const EPR_SField *field)
void | epr_dump_element (const EPR_SRecord *record, uint field_index, uint element_index)
uint | epr_get_scene_width (const EPR_SProductId *product_id)
| Gets the product's scene width in pixels.
uint | epr_get_scene_height (const EPR_SProductId *product_id)
| Gets the product's scene height in pixels.
uint | epr_get_num_datasets (EPR_SProductId *product_id)
| Gets the number off all datasets contained in a product.
EPR_SDatasetId * | epr_get_dataset_id_at (EPR_SProductId *product_id, uint index)
| Gets the dataset_id at the specified position within the product.
EPR_SDatasetId * | epr_get_dataset_id (EPR_SProductId *product_id, const char *dataset_name)
| Gets the dataset_id coresponding to the specified dataset name.
const char * | epr_get_dataset_name (EPR_SDatasetId *dataset_id)
| Gets the name of the dataset for the given dataset ID.
const char * | epr_get_dsd_name (const EPR_SDatasetId *dataset_id)
| Gets the name of the dsd for the given dataset ID.
EPR_SRecord * | epr_get_mph (const EPR_SProductId *product_id)
| Gets the MPH record from the given `product_id`.
EPR_SRecord * | epr_get_sph (const EPR_SProductId *product_id)
| Gets the SPH record from the given `product_id`.
const EPR_SDSD * | epr_get_dsd (const EPR_SDatasetId *dataset_id)
| Gets the dataset descriptor (DSD) for the dataset specified by `dataset_id`.
uint | epr_get_num_records (const EPR_SDatasetId *dataset_id)
| Gets the number of records of the dataset specified by `dataset_id`.
uint | epr_get_num_dsds (const EPR_SProductId *product_id)
EPR_SDSD * | epr_get_dsd_at (const EPR_SProductId *product_id, uint dsd_index)
EPR_SRecord * | epr_create_record (EPR_SDatasetId *dataset_id)
| Creates a new, empty record with a structure compatible with the dataset specified by dataset_id.
EPR_SRecord * | epr_read_record (EPR_SDatasetId *dataset_id, uint record_index, EPR_SRecord *record)
| Reads a record of a dataset specified by dataset_id.
void | epr_free_record (EPR_SRecord *record)
| Frees the memory allocated through the given record.
const EPR_SField * | epr_get_field (const EPR_SRecord *record, const char *field_name)
| Gets a field from the given record.
uint | epr_get_num_fields (const EPR_SRecord *record)
| Gets the number of fields contained in the given record.
const EPR_SField * | epr_get_field_at (const EPR_SRecord *record, uint field_index)
| Gets a field at the specified position within the record.
const char * | epr_get_field_unit (const EPR_SField *field)
| Gets the unit of the field.
const char * | epr_get_field_description (const EPR_SField *field)
| Gets the description of the field.
uint | epr_get_field_num_elems (const EPR_SField *field)
| Gets the number of elements of the field.
const char * | epr_get_field_name (const EPR_SField *field)
| Gets the name of the field.
EPR_EDataTypeId | epr_get_field_type (const EPR_SField *field)
| Gets the type of the field.
char | epr_get_field_elem_as_char (const EPR_SField *field, uint elem_index)
uchar | epr_get_field_elem_as_uchar (const EPR_SField *field, uint elem_index)
short | epr_get_field_elem_as_short (const EPR_SField *field, uint elem_index)
ushort | epr_get_field_elem_as_ushort (const EPR_SField *field, uint elem_index)
int | epr_get_field_elem_as_int (const EPR_SField *field, uint elem_index)
uint | epr_get_field_elem_as_uint (const EPR_SField *field, uint elem_index)
float | epr_get_field_elem_as_float (const EPR_SField *field, uint elem_index)
double | epr_get_field_elem_as_double (const EPR_SField *field, uint elem_index)
const EPR_STime * | epr_get_field_elem_as_mjd (const EPR_SField *field)
const char * | epr_get_field_elem_as_str (const EPR_SField *field)
const char * | epr_get_field_elems_char (const EPR_SField *field)
const uchar * | epr_get_field_elems_uchar (const EPR_SField *field)
const short * | epr_get_field_elems_short (const EPR_SField *field)
const ushort * | epr_get_field_elems_ushort (const EPR_SField *field)
const int * | epr_get_field_elems_int (const EPR_SField *field)
const uint * | epr_get_field_elems_uint (const EPR_SField *field)
const float * | epr_get_field_elems_float (const EPR_SField *field)
const double * | epr_get_field_elems_double (const EPR_SField *field)
uint | epr_copy_field_elems_as_ints (const EPR_SField *field, int *buffer, uint num_elems)
uint | epr_copy_field_elems_as_uints (const EPR_SField *field, uint *buffer, uint num_elems)
uint | epr_copy_field_elems_as_floats (const EPR_SField *field, float *buffer, uint num_elems)
uint | epr_copy_field_elems_as_doubles (const EPR_SField *field, double *buffer, uint num_elems)
EPR_SRaster * | epr_create_compatible_raster (EPR_SBandId *band_id, uint source_width, uint source_height, uint source_step_x, uint source_step_y)
| Creates a raster which is compatible with the data type contained in the band identified by band_id.
EPR_SRaster * | epr_create_raster (EPR_EDataTypeId data_type, uint source_width, uint source_height, uint source_step_x, uint source_step_y)
| Creates a raster of the specified data type.
EPR_SRaster * | epr_create_bitmask_raster (uint source_width, uint source_height, uint source_step_x, uint source_step_y)
| Creates a raster to be used for reading bitmasks.
int | epr_read_band_raster (EPR_SBandId *band_id, int offset_x, int offset_y, EPR_SRaster *raster)
| Reads (geo-)physical values of the given band of the specified source-region.
uint | epr_get_raster_elem_size (const EPR_SRaster *raster)
void * | epr_get_raster_elem_addr (const EPR_SRaster *raster, uint offset)
void * | epr_get_raster_pixel_addr (const EPR_SRaster *raster, uint x, uint y)
void * | epr_get_raster_line_addr (const EPR_SRaster *raster, uint y)
uint | epr_get_raster_width (EPR_SRaster *raster)
| Gets the raster's scene width in pixels.
uint | epr_get_raster_height (EPR_SRaster *raster)
| Gets the raster's scene height in pixels.
uint | epr_get_num_bands (EPR_SProductId *product_id)
| Gets the number of all bands contained in a product.
EPR_SBandId * | epr_get_band_id_at (EPR_SProductId *product_id, uint index)
| Gets the band ID at the specified position within the product.
EPR_SBandId * | epr_get_band_id (EPR_SProductId *product_id, const char *band_name)
| Gets the band ID corresponding to the specified name.
const char * | epr_get_band_name (EPR_SBandId *band_id)
| Gets the name of the band for the given band ID.
void | epr_free_raster (EPR_SRaster *raster)
| Release the memory allocated through a raster.
uint | epr_get_pixel_as_uint (const EPR_SRaster *raster, int x, int y)
| This group of functions is for getting the values of the elements of a raster (i.e.
int | epr_get_pixel_as_int (const EPR_SRaster *raster, int x, int y)
float | epr_get_pixel_as_float (const EPR_SRaster *raster, int x, int y)
double | epr_get_pixel_as_double (const EPR_SRaster *raster, int x, int y)
int | epr_read_bitmask_raster (EPR_SProductId *product_id, const char *bm_expr, int offset_x, int offset_y, EPR_SRaster *raster)
| Calculates a bit-mask, composed of flags of the given product and combined as described in the given bit-mask expression, for the a certain dimension and sub-sampling as defined in the given raster.
uint | epr_get_data_type_size (EPR_EDataTypeId data_type_id)
| Gets the size in bytes for an element of the given data type.
const char * | epr_data_type_id_to_str (EPR_EDataTypeId data_type_id)
| Gets the 'C' data type string for the given data type.

## Define Documentation

#define EPR_PRODUCT_API_NAME_STR "ENVISAT Product Reader API"

#define EPR_PRODUCT_API_VERSION_STR "2.2"

#define EPR_MAGIC_PRODUCT_ID 0xCAFFEE64

#define EPR_MAGIC_DATASET_ID 0xEFEABDCA

#define EPR_MAGIC_BAND_ID 0xFEC21ABD

#define EPR_MAGIC_RECORD 0x7BABACAE

#define EPR_MAGIC_FIELD 0xBA0BABBA

#define EPR_MAGIC_RASTER 0x0BABA0EB

#define EPR_MAGIC_FLAG_DEF 0xCABA11AD

#define TRUE 1

#define FALSE 0

#define EPR_PRODUCT_ID_STRLEN 48

## Typedef Documentation

typedef enum EPR_DataTypeId EPR_EDataTypeId

typedef enum EPR_ErrCode EPR_EErrCode

typedef enum EPR_LogLevel EPR_ELogLevel

typedef enum EPR_SampleModel EPR_ESampleModel

typedef enum EPR_ScalingMethod EPR_EScalingMethod

typedef struct EPR_ProductId EPR_SProductId

typedef struct EPR_DatasetId EPR_SDatasetId

typedef struct EPR_BandId EPR_SBandId

typedef struct EPR_Record EPR_SRecord

typedef struct EPR_RecordInfo EPR_SRecordInfo

typedef struct EPR_Field EPR_SField

typedef struct EPR_FieldInfo EPR_SFieldInfo

typedef struct EPR_DSD EPR_SDSD

typedef struct EPR_Raster EPR_SRaster

typedef struct EPR_FlagDef EPR_SFlagDef

typedef struct EPR_ParamElem EPR_SParamElem

typedef struct EPR_Time EPR_STime

typedef struct EPR_DatasetRef EPR_SDatasetRef

typedef struct EPR_BitmaskTerm EPR_SBitmaskTerm

typedef struct EPR_FlagSet EPR_SFlagSet

typedef void(* EPR_FErrHandler)(EPR_EErrCode err_code, const char *err_message)

typedef void(* EPR_FLogHandler)(EPR_ELogLevel log_level, const char *log_message)

typedef int epr_boolean

typedef unsigned char uchar

typedef unsigned short ushort

typedef unsigned int uint

typedef unsigned long ulong

typedef int EPR_Magic

## Enumeration Type Documentation

enum EPR_DataTypeId

The `EPR_DataTypeId` enumeration lists all possible data types for field elements in ENVISAT dataset records.

Enumerator:

  e_tid_unknown | The ID for unknown types.
  e_tid_uchar | An array of unsigned 8-bit integers, C type is `uchar*`
  e_tid_char | An array of signed 8-bit integers, C type is `char*`
  e_tid_ushort | An array of unsigned 16-bit integers, C type is `ushort*`
  e_tid_short | An array of signed 16-bit integers, C type is `short*`
  e_tid_uint | An array of unsigned 32-bit integers, C type is `uint*`
  e_tid_int | An array of signed 32-bit integers, C type is `int*`
  e_tid_float | An array of 32-bit floating point numbers, C type is `float*`
  e_tid_double | An array of 64-bit floating point numbers, C type is `double*`
  e_tid_string | A zero-terminated ASCII string, C type is `char*`
  e_tid_spare | An array of unsigned character, C type is `uchar*`
  e_tid_time | A time (MJD) structure, C type is `EPR_Time`

enum EPR_ErrCode

The `EPR_ErrCode` enumeration lists all possible error codes for the ENVISAT product reader API.

Enumerator:

  e_err_none |
  e_err_null_pointer |
  e_err_illegal_arg |
  e_err_illegal_state |
  e_err_out_of_memory |
  e_err_index_out_of_range |
  e_err_illegal_conversion |
  e_err_illegal_data_type |
  e_err_file_not_found |
  e_err_file_access_denied |
  e_err_file_read_error |
  e_err_file_write_error |
  e_err_file_open_failed |
  e_err_file_close_failed |
  e_err_api_not_initialized |
  e_err_invalid_product_id |
  e_err_invalid_record |
  e_err_invalid_band |
  e_err_invalid_raster |
  e_err_invalid_dataset_name |
  e_err_invalid_field_name |
  e_err_invalid_record_name |
  e_err_invalid_product_name |
  e_err_invalid_band_name |
  e_err_invalid_data_format |
  e_err_invalid_value |
  e_err_invalid_keyword_name |
  e_err_unknown_endian_order |
  e_err_flag_not_found |
  e_err_invalid_ddbb_format |

enum EPR_LogLevel

The `EPR_LogLevel` enumeration lists possible log levels for the ENVISAT product reader API.

Enumerator:

  e_log_debug |
  e_log_info |
  e_log_warning |
  e_log_error |

enum EPR_SampleModel

Enumerator:

  e_smod_1OF1 |
  e_smod_1OF2 |
  e_smod_2OF2 |
  e_smod_3TOI |
  e_smod_2TOF |

enum EPR_ScalingMethod

Enumerator:

  e_smid_non |
  e_smid_lin |
  e_smid_log |