epr_api.h

Go to the documentation of this file.

/*
 * $Id: epr_api.h,v 1.3 2009-03-27 10:25:54 sabine Exp $
 *
 * Copyright (C) 2002 by Brockmann Consult (info@brockmann-consult.de)
 *
 * This program is free software; you can redistribute it and/or modify it
 * under the terms of the GNU General Public License as published by the
 * Free Software Foundation. This program is distributed in the hope it will
 * be useful, but WITHOUT ANY WARRANTY; without even the implied warranty
 * of MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.
 * See the GNU General Public License for more details.
 *
 * You should have received a copy of the GNU General Public License
 * along with this program; if not, write to the Free Software
 * Foundation, Inc., 59 Temple Place - Suite 330, Boston, MA  02111-1307, USA.
 */
#pragma GCC diagnostic ignored "-Wpadded"
#ifndef EPR_API_H_INCL
#define EPR_API_H_INCL
 
 
#ifdef __cplusplus
extern "C" {
#endif
 
/* to make the FILE structure available */
#include <stdio.h>
 
/* to make dynamic arrays available*/
#include "epr_ptrarray.h"
 
#define EPR_PRODUCT_API_NAME_STR         "ENVISAT Product Reader API"
#define EPR_PRODUCT_API_VERSION_STR      "2.3"
 
/* needed by Doxygen */
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
};
 
enum EPR_ErrCode {
    /* Not an error */
    e_err_none = 0,
 
    /* Low level errors */
    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,
 
    /* I/O errors */
    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,
 
    /* API related errors */
    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,
 
    /* Bitmask term errors */
    e_err_flag_not_found = 301,
 
 
    /* DDDB errors */
    e_err_invalid_ddbb_format = 402
};
 
enum EPR_LogLevel {
    e_log_debug = -1,
    e_log_info = 0,
    e_log_warning = 1,
    e_log_error = 2
};
 
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
};
 
struct EPR_ProductId;
struct EPR_DatasetId;
struct EPR_BandId;
struct EPR_Record;
struct EPR_RecordInfo;
struct EPR_Field;
struct EPR_FieldInfo;
struct EPR_ProductInfo;
struct EPR_DSD;
struct EPR_Raster;
struct EPR_DatasetRef;
struct EPR_Flag;
struct EPR_BandId;
struct EPR_ParamElem;
struct EPR_Time;
 
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 epr_uchar;
typedef unsigned short epr_ushort;
typedef unsigned int epr_uint;
typedef unsigned long epr_ulong;
 
 
typedef int EPR_Magic;
 
#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 EPR_TRUE   1
#define EPR_FALSE  0
 
#define EPR_PRODUCT_ID_STRLEN    48
 
 
/*************************************************************************/
/******************************** STRUCTURES *****************************/
/*************************************************************************/
 
struct EPR_ProductId {
    EPR_Magic magic;
 
    char* file_path;
 
    FILE* istream;
 
    epr_uint tot_size;
 
    epr_uint scene_width;
 
    epr_uint scene_height;
 
    char id_string[EPR_PRODUCT_ID_STRLEN + 1];
 
    EPR_SRecord* mph_record;
 
    EPR_SRecord* sph_record;
 
    EPR_SPtrArray* dsd_array;
 
    EPR_SPtrArray* record_info_cache;
 
    EPR_SPtrArray* param_table;
 
    EPR_SPtrArray* dataset_ids;
 
    EPR_SPtrArray* band_ids;
 
    int meris_iodd_version;
};
 
struct EPR_DatasetId {
    EPR_Magic magic;
 
    EPR_SProductId* product_id;
 
    char* dsd_name;
 
    const EPR_SDSD* dsd;
 
    char* dataset_name;
 
    const struct RecordDescriptor* record_descriptor;
 
    EPR_SRecordInfo* record_info;
 
 
    char* description;
};
 
struct EPR_DSD {
    EPR_Magic magic;
 
    int index;
 
    char* ds_name;
 
    char* ds_type;
 
    char* filename;
 
    epr_uint ds_offset;
 
    epr_uint ds_size;
 
    epr_uint num_dsr;
 
    epr_uint dsr_size;
};
 
struct EPR_Record {
    EPR_Magic magic;
 
    EPR_SRecordInfo* info;
 
    epr_uint num_fields;
 
    EPR_SField** fields;
};
 
struct EPR_Field {
    EPR_Magic magic;
 
    EPR_SFieldInfo* info;
 
    void* elems;
};
 
struct EPR_Raster {
    EPR_Magic magic;
 
    EPR_EDataTypeId data_type;
 
    epr_uint elem_size;
 
    epr_uint source_width;
 
    epr_uint source_height;
 
    epr_uint source_step_x;
 
    epr_uint source_step_y;
 
    epr_uint raster_width;
 
    epr_uint raster_height;
 
    void* buffer;
};
 
struct EPR_DatasetRef {
    EPR_SDatasetId* dataset_id;
    int field_index; /* -1 if not used */
    int elem_index; /* -1 if not used */
};
 
struct EPR_FlagDef {
    EPR_Magic magic;
 
    char* name;
 
    epr_uint bit_mask;
 
    char* description;
};
 
struct EPR_BandId {
    EPR_Magic magic;
 
    EPR_SProductId* product_id;
 
    char* band_name;
 
    int spectr_band_index;
 
    EPR_SDatasetRef dataset_ref;
 
    EPR_ESampleModel sample_model;
 
    EPR_EDataTypeId data_type;
 
    EPR_EScalingMethod scaling_method;
 
    float scaling_offset;
 
    float scaling_factor;
 
    char* bm_expr;
 
    EPR_SPtrArray* flag_coding;
 
    char* unit;
 
    char* description;
 
    epr_boolean lines_mirrored;
};
 
struct EPR_Time {
    int days;
    epr_uint seconds;
    epr_uint microseconds;
};
 
 
 
/*************************************************************************/
/********************************* FUNCTIONS *****************************/
/*************************************************************************/
 
/*
 * ============================ (1) Initialisation ==========================
 */
 
int epr_init_api(EPR_ELogLevel log_level,
        EPR_FLogHandler log_handler,
        EPR_FErrHandler err_handler);
 
 
void epr_close_api();
/*
 * ============================ (2) Logging ============================
 */
 
int epr_set_log_level(EPR_ELogLevel log_level);
 
void epr_set_log_handler(EPR_FLogHandler log_handler);
 
void epr_log_message(EPR_ELogLevel log_level, const char* log_message);
 
/*
 * ========================= (3) Error Handling ==========================
 */
 
void epr_set_err_handler(EPR_FErrHandler err_handler);
 
EPR_EErrCode epr_get_last_err_code();
 
const char* epr_get_last_err_message();
 
void epr_clear_err();
 
/*
 * ========================== (4) Input / Output ============================
 */
 
/*
 * ======================= (4.1) Product File Access ==========================
 */
 
EPR_SProductId* epr_open_product(const char* product_file_path);
 
int epr_close_product(EPR_SProductId* product_id);
/*
 * ================= (4.2) Writing to a file or standard output =================
 */
 
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, epr_uint field_index, epr_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, epr_uint field_index, epr_uint element_index);
/*
 * ======================= (5) Basic Data Access =========================
 */
 
epr_uint epr_get_scene_width(const EPR_SProductId* product_id);
 
epr_uint epr_get_scene_height(const EPR_SProductId* product_id);
 
/*
 * ============================ (5.1) Dataset ==============================
 */
 
epr_uint epr_get_num_datasets(EPR_SProductId* product_id);
 
EPR_SDatasetId* epr_get_dataset_id_at(EPR_SProductId* product_id, epr_uint index);
 
EPR_SDatasetId* epr_get_dataset_id(EPR_SProductId* product_id, const char* dataset_name);
 
const char* epr_get_dataset_name(EPR_SDatasetId* dataset_id);
 
const char* epr_get_dsd_name(const EPR_SDatasetId* dataset_id);
 
EPR_SRecord* epr_get_mph(const EPR_SProductId* product_id);
 
EPR_SRecord* epr_get_sph(const EPR_SProductId* product_id);
 
const EPR_SDSD* epr_get_dsd(const EPR_SDatasetId* dataset_id);
 
epr_uint epr_get_num_records(const EPR_SDatasetId* dataset_id);
 
 
epr_uint epr_get_num_dsds(const EPR_SProductId* product_id);
EPR_SDSD* epr_get_dsd_at(const EPR_SProductId* product_id, epr_uint dsd_index);
 
/*
 * ================================= (5.2) Records ============================
 */
 
EPR_SRecord* epr_create_record(EPR_SDatasetId* dataset_id);
 
EPR_SRecord* epr_read_record(EPR_SDatasetId* dataset_id,
        epr_uint record_index,
        EPR_SRecord* record);
 
void epr_free_record(EPR_SRecord* record);
 
/*
 * =========================== (5.3) Field Access =============================
 */
 
const EPR_SField* epr_get_field(const EPR_SRecord* record, const char* field_name);
 
epr_uint epr_get_num_fields(const EPR_SRecord* record);
 
const EPR_SField* epr_get_field_at(const EPR_SRecord* record, epr_uint field_index);
 
const char* epr_get_field_unit(const EPR_SField* field);
 
const char* epr_get_field_description(const EPR_SField* field);
 
epr_uint epr_get_field_num_elems(const EPR_SField* field);
 
const char* epr_get_field_name(const EPR_SField* field);
 
EPR_EDataTypeId epr_get_field_type(const EPR_SField* field);
 
/*
 * ========================= (5.4) Single Element Access =========================
 */
 
char epr_get_field_elem_as_char(const EPR_SField* field, epr_uint elem_index);
epr_uchar epr_get_field_elem_as_uchar(const EPR_SField* field, epr_uint elem_index);
short epr_get_field_elem_as_short(const EPR_SField* field, epr_uint elem_index);
epr_ushort epr_get_field_elem_as_ushort(const EPR_SField* field, epr_uint elem_index);
int epr_get_field_elem_as_int(const EPR_SField* field, epr_uint elem_index);
epr_uint epr_get_field_elem_as_uint(const EPR_SField* field, epr_uint elem_index);
float epr_get_field_elem_as_float(const EPR_SField* field, epr_uint elem_index);
double epr_get_field_elem_as_double(const EPR_SField* field, epr_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);
/*
 * =========================== (5.5) Array Element Access =============================
 */
 
const char* epr_get_field_elems_char(const EPR_SField* field);
const epr_uchar* epr_get_field_elems_uchar(const EPR_SField* field);
const short* epr_get_field_elems_short(const EPR_SField* field);
const epr_ushort* epr_get_field_elems_ushort(const EPR_SField* field);
const int* epr_get_field_elems_int(const EPR_SField* field);
const epr_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);
epr_uint epr_copy_field_elems_as_ints(const EPR_SField* field, int* buffer, epr_uint num_elems);
epr_uint epr_copy_field_elems_as_uints(const EPR_SField* field, epr_uint* buffer, epr_uint num_elems);
epr_uint epr_copy_field_elems_as_floats(const EPR_SField* field, float* buffer, epr_uint num_elems);
epr_uint epr_copy_field_elems_as_doubles(const EPR_SField* field, double* buffer, epr_uint num_elems);
/*
 * ======================== (6) Geophysical Data Access =========================
 */
 
/*
 * ================================== (6.1) Raster ===============================
 */
 
EPR_SRaster* epr_create_compatible_raster(EPR_SBandId* band_id,
        epr_uint source_width,
        epr_uint source_height,
        epr_uint source_step_x,
        epr_uint source_step_y);
 
EPR_SRaster* epr_create_raster(EPR_EDataTypeId data_type,
        epr_uint source_width,
        epr_uint source_height,
        epr_uint source_step_x,
        epr_uint source_step_y);
 
 
EPR_SRaster* epr_create_bitmask_raster(epr_uint source_width,
        epr_uint source_height,
        epr_uint source_step_x,
        epr_uint source_step_y);
 
int epr_read_band_raster(EPR_SBandId* band_id,
        int offset_x,
        int offset_y,
        EPR_SRaster* raster);
 
 
epr_uint epr_get_raster_elem_size(const EPR_SRaster* raster);
 
void* epr_get_raster_elem_addr(const EPR_SRaster* raster, epr_uint offset);
 
void* epr_get_raster_pixel_addr(const EPR_SRaster* raster, epr_uint x, epr_uint y);
 
void* epr_get_raster_line_addr(const EPR_SRaster* raster, epr_uint y);
 
 
epr_uint epr_get_raster_width(EPR_SRaster* raster);
 
epr_uint epr_get_raster_height(EPR_SRaster* raster);
 
 
 
epr_uint epr_get_num_bands(EPR_SProductId* product_id);
 
EPR_SBandId* epr_get_band_id_at(EPR_SProductId* product_id, epr_uint index);
 
EPR_SBandId* epr_get_band_id(EPR_SProductId* product_id, const char* band_name);
 
const char* epr_get_band_name(EPR_SBandId* band_id);
 
void epr_free_raster(EPR_SRaster* raster);
 
/*
 * ============================ (6.2) Single Pixel Access ========================
 */
 
epr_uint epr_get_pixel_as_uint(const EPR_SRaster* raster, int x, int y);
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);
/*
 * ================================= (7) Bitmasks ==========================
 */
 
int epr_read_bitmask_raster(EPR_SProductId* product_id,
        const char* bm_expr,
        int offset_x,
        int offset_y,
        EPR_SRaster* raster);
 
/*
 * ================================= (8) Utility functions ==========================
 */
 
epr_uint epr_get_data_type_size(EPR_EDataTypeId data_type_id);
 
const char* epr_data_type_id_to_str(EPR_EDataTypeId data_type_id);
 
#ifdef __cplusplus
} /* extern "C" */
#endif
#endif /* #ifndef EPR_API_H_INCL */