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.
 */

#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  uchar;
typedef unsigned short ushort;
typedef unsigned int   uint;
typedef unsigned long  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 TRUE   1
#define FALSE  0

#define EPR_PRODUCT_ID_STRLEN    48


/*************************************************************************/
/******************************** STRUCTURES *****************************/
/*************************************************************************/

struct EPR_ProductId
{
    EPR_Magic magic;

    char* file_path;

    FILE* istream;

    uint  tot_size;

    uint  scene_width;

    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;

    uint ds_offset;

    uint ds_size;

    uint num_dsr;

    uint dsr_size;
};


struct EPR_Record
{
    EPR_Magic magic;

    EPR_SRecordInfo* info;

    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;

    uint elem_size;

    uint source_width;

    uint source_height;

    uint source_step_x;

    uint source_step_y;

    uint raster_width;

    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;

    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;
    uint seconds;
    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(void);
/*
 * ============================ (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(void);

const char* epr_get_last_err_message(void);

void epr_clear_err(void);

/*
 * ========================== (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, 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);
/*
 * ======================= (5) Basic Data Access =========================
 */

uint epr_get_scene_width(const EPR_SProductId* product_id);

uint epr_get_scene_height(const EPR_SProductId* product_id);

/*
 * ============================ (5.1) Dataset ==============================
 */

uint epr_get_num_datasets(EPR_SProductId* product_id);

EPR_SDatasetId* epr_get_dataset_id_at(EPR_SProductId* product_id, 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);

uint epr_get_num_records(const EPR_SDatasetId* 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);

/*
 * ================================= (5.2) Records ============================
 */

EPR_SRecord* epr_create_record(EPR_SDatasetId* dataset_id);

EPR_SRecord* epr_read_record(EPR_SDatasetId* dataset_id,
                             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);

uint epr_get_num_fields(const EPR_SRecord* record);

const EPR_SField* epr_get_field_at(const EPR_SRecord* record, uint field_index);

const char* epr_get_field_unit(const EPR_SField* field);

const char* epr_get_field_description(const EPR_SField* field);

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, 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);
/*
 * =========================== (5.5) Array Element Access =============================
 */

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);
/*
 * ======================== (6) Geophysical Data Access =========================
 */

/*
 * ================================== (6.1) Raster ===============================
 */

EPR_SRaster* epr_create_compatible_raster(EPR_SBandId* band_id,
                                          uint source_width,
                                          uint source_height,
                                          uint source_step_x,
                                          uint source_step_y);

EPR_SRaster* epr_create_raster(EPR_EDataTypeId data_type,
                               uint source_width,
                               uint source_height,
                               uint source_step_x,
                               uint source_step_y);


EPR_SRaster* epr_create_bitmask_raster(uint source_width,
                                       uint source_height,
                                       uint source_step_x,
                                       uint source_step_y);

int epr_read_band_raster(EPR_SBandId* band_id,
                         int offset_x,
                         int offset_y,
                         EPR_SRaster* raster);


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);

uint epr_get_raster_height(EPR_SRaster* raster);



uint epr_get_num_bands(EPR_SProductId* product_id);

EPR_SBandId* epr_get_band_id_at(EPR_SProductId* product_id, 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 ========================
 */

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 ==========================
 */

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 */