ENVISAT Product Reader C API: Main Page

ENVISAT Product Reader API for C |

- Main Page
- Modules
- Data Structures
- Files

- File List
- Globals

# epr_api.h

Go to the documentation of this file.

    00001 /*
    00002  * $Id: epr_api.h,v 1.3 2009-03-27 10:25:54 sabine Exp $
    00003  *
    00004  * Copyright (C) 2002 by Brockmann Consult (info@brockmann-consult.de)
    00005  *
    00006  * This program is free software; you can redistribute it and/or modify it
    00007  * under the terms of the GNU General Public License as published by the
    00008  * Free Software Foundation. This program is distributed in the hope it will
    00009  * be useful, but WITHOUT ANY WARRANTY; without even the implied warranty
    00010  * of MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.
    00011  * See the GNU General Public License for more details.
    00012  *
    00013  * You should have received a copy of the GNU General Public License
    00014  * along with this program; if not, write to the Free Software
    00015  * Foundation, Inc., 59 Temple Place - Suite 330, Boston, MA  02111-1307, USA.
    00016  */
    00017
    00018 #ifndef EPR_API_H_INCL
    00019 #define EPR_API_H_INCL
    00020
    00021
    00022 #ifdef __cplusplus
    00023 extern "C"
    00024 {
    00025 #endif
    00026
    00027 /* to make the FILE structure available */
    00028 #include <stdio.h>
    00029
    00030 /* to make dynamic arrays available*/
    00031 #include "epr_ptrarray.h"
    00032
    00033 #define EPR_PRODUCT_API_NAME_STR         "ENVISAT Product Reader API"
    00034 #define EPR_PRODUCT_API_VERSION_STR      "2.2"
    00035
    00036 /* needed by Doxygen */
    00045 enum EPR_DataTypeId
    00046 {
    00048     e_tid_unknown = 0,
    00050     e_tid_uchar   = 1,
    00052     e_tid_char    = 2,
    00054     e_tid_ushort  = 3,
    00056     e_tid_short   = 4,
    00058     e_tid_uint    = 5,
    00060     e_tid_int     = 6,
    00062     e_tid_float   = 7,
    00064     e_tid_double  = 8,
    00066     e_tid_string  = 11,
    00068     e_tid_spare  = 13,
    00070     e_tid_time    = 21
    00071 };
    00072
    00073
    00078 enum EPR_ErrCode
    00079 {
    00080     /* Not an error */
    00081     e_err_none                 =    0,
    00082
    00083     /* Low level errors */
    00084     e_err_null_pointer         =    1,
    00085     e_err_illegal_arg          =    2,
    00086     e_err_illegal_state        =    3,
    00087     e_err_out_of_memory        =    4,
    00088     e_err_index_out_of_range   =    5,
    00089     e_err_illegal_conversion   =        6,
    00090     e_err_illegal_data_type        =    7,
    00091
    00092     /* I/O errors */
    00093     e_err_file_not_found       =  101,
    00094     e_err_file_access_denied   =  102,
    00095     e_err_file_read_error      =  103,
    00096     e_err_file_write_error     =  104,
    00097     e_err_file_open_failed     =  105,
    00098     e_err_file_close_failed    =  106,
    00099
    00100     /* API related errors */
    00101     e_err_api_not_initialized  =  201,
    00102     e_err_invalid_product_id   =  203,
    00103     e_err_invalid_record           =  204,
    00104     e_err_invalid_band             =  205,
    00105     e_err_invalid_raster       =  206,
    00106     e_err_invalid_dataset_name =  207,
    00107     e_err_invalid_field_name   =  208,
    00108         e_err_invalid_record_name  =  209,
    00109         e_err_invalid_product_name =  210,
    00110     e_err_invalid_band_name    =  211,
    00111         e_err_invalid_data_format  =  212,
    00112         e_err_invalid_value        =  213,
    00113         e_err_invalid_keyword_name =  214,
    00114         e_err_unknown_endian_order =  216,
    00115
    00116     /* Bitmask term errors */
    00117         e_err_flag_not_found       =  301,
    00118
    00119
    00120     /* DDDB errors */
    00121     e_err_invalid_ddbb_format  =  402
    00122 };
    00123
    00124
    00129 enum EPR_LogLevel
    00130 {
    00131     e_log_debug   = -1,
    00132     e_log_info    =  0,
    00133     e_log_warning =  1,
    00134     e_log_error   =  2
    00135 };
    00136
    00137 enum EPR_SampleModel
    00138 {
    00139     e_smod_1OF1 = 0,
    00140     e_smod_1OF2 = 1,
    00141     e_smod_2OF2 = 2,
    00142     e_smod_3TOI = 3,
    00143     e_smod_2TOF = 4
    00144 };
    00145
    00146 enum EPR_ScalingMethod
    00147 {
    00148     e_smid_non = 0,
    00149     e_smid_lin = 1,
    00150     e_smid_log = 2
    00151 };
    00152
    00153 struct EPR_ProductId;
    00154 struct EPR_DatasetId;
    00155 struct EPR_BandId;
    00156 struct EPR_Record;
    00157 struct EPR_RecordInfo;
    00158 struct EPR_Field;
    00159 struct EPR_FieldInfo;
    00160 struct EPR_ProductInfo;
    00161 struct EPR_DSD;
    00162 struct EPR_Raster;
    00163 struct EPR_DatasetRef;
    00164 struct EPR_Flag;
    00165 struct EPR_BandId;
    00166 struct EPR_ParamElem;
    00167 struct EPR_Time;
    00168
    00169 typedef enum   EPR_DataTypeId      EPR_EDataTypeId;
    00170 typedef enum   EPR_ErrCode         EPR_EErrCode;
    00171 typedef enum   EPR_LogLevel        EPR_ELogLevel;
    00172 typedef enum   EPR_SampleModel     EPR_ESampleModel;
    00173 typedef enum   EPR_ScalingMethod   EPR_EScalingMethod;
    00174 typedef struct EPR_ProductId       EPR_SProductId;
    00175 typedef struct EPR_DatasetId       EPR_SDatasetId;
    00176 typedef struct EPR_BandId                  EPR_SBandId;
    00177 typedef struct EPR_Record          EPR_SRecord;
    00178 typedef struct EPR_RecordInfo      EPR_SRecordInfo;
    00179 typedef struct EPR_Field           EPR_SField;
    00180 typedef struct EPR_FieldInfo       EPR_SFieldInfo;
    00181 typedef struct EPR_DSD             EPR_SDSD;
    00182 typedef struct EPR_Raster          EPR_SRaster;
    00183 typedef struct EPR_FlagDef         EPR_SFlagDef;
    00184 typedef struct EPR_ParamElem       EPR_SParamElem;
    00185 typedef struct EPR_Time            EPR_STime;
    00186 typedef struct EPR_DatasetRef      EPR_SDatasetRef;
    00187 typedef struct EPR_BitmaskTerm     EPR_SBitmaskTerm;
    00188 typedef struct EPR_FlagSet         EPR_SFlagSet;
    00189 typedef void (*EPR_FErrHandler)(EPR_EErrCode err_code, const char* err_message);
    00190 typedef void (*EPR_FLogHandler)(EPR_ELogLevel log_level, const char* log_message);
    00191
    00192
    00193 typedef int            epr_boolean;
    00194 typedef unsigned char  uchar;
    00195 typedef unsigned short ushort;
    00196 typedef unsigned int   uint;
    00197 typedef unsigned long  ulong;
    00198
    00199
    00200 typedef int EPR_Magic;
    00201
    00202 #define EPR_MAGIC_PRODUCT_ID     0xCAFFEE64
    00203 #define EPR_MAGIC_DATASET_ID     0xEFEABDCA
    00204 #define EPR_MAGIC_BAND_ID        0xFEC21ABD
    00205 #define EPR_MAGIC_RECORD         0x7BABACAE
    00206 #define EPR_MAGIC_FIELD          0xBA0BABBA
    00207 #define EPR_MAGIC_RASTER         0x0BABA0EB
    00208 #define EPR_MAGIC_FLAG_DEF       0xCABA11AD
    00209
    00210 #define TRUE   1
    00211 #define FALSE  0
    00212
    00213 #define EPR_PRODUCT_ID_STRLEN    48
    00214
    00215
    00216 /*************************************************************************/
    00217 /******************************** STRUCTURES *****************************/
    00218 /*************************************************************************/
    00219
    00227 struct EPR_ProductId
    00228 {
    00233     EPR_Magic magic;
    00234
    00238     char* file_path;
    00239
    00244     FILE* istream;
    00245
    00249     uint  tot_size;
    00250
    00254     uint  scene_width;
    00255
    00259     uint  scene_height;
    00260
    00269     char id_string[EPR_PRODUCT_ID_STRLEN + 1];
    00270
    00274     EPR_SRecord* mph_record;
    00275
    00279     EPR_SRecord* sph_record;
    00280
    00285     EPR_SPtrArray* dsd_array;
    00286
    00296     EPR_SPtrArray* record_info_cache;
    00297
    00304     EPR_SPtrArray* param_table;
    00305
    00309     EPR_SPtrArray* dataset_ids;
    00310
    00314     EPR_SPtrArray* band_ids;
    00315
    00319         int meris_iodd_version;
    00320 };
    00321
    00322
    00323
    00324
    00337 struct EPR_DatasetId
    00338 {
    00343     EPR_Magic magic;
    00344
    00348     EPR_SProductId* product_id;
    00349
    00353     char* dsd_name;
    00354
    00358     const EPR_SDSD* dsd;
    00359
    00363     char* dataset_name;
    00364
    00368         const struct RecordDescriptor* record_descriptor;
    00369
    00373     EPR_SRecordInfo* record_info;
    00374
    00375
    00379     char* description;
    00380 };
    00381
    00382
    00390 struct EPR_DSD
    00391 {
    00396     EPR_Magic magic;
    00397
    00401     int index;
    00402
    00406     char* ds_name;
    00407
    00411     char* ds_type;
    00412
    00416     char* filename;
    00417
    00421     uint ds_offset;
    00422
    00426     uint ds_size;
    00427
    00431     uint num_dsr;
    00432
    00436     uint dsr_size;
    00437 };
    00438
    00439
    00447 struct EPR_Record
    00448 {
    00453     EPR_Magic magic;
    00454
    00458     EPR_SRecordInfo* info;
    00459
    00465     uint num_fields;
    00466
    00471     EPR_SField** fields;
    00472 };
    00473
    00481 struct EPR_Field
    00482 {
    00487     EPR_Magic magic;
    00488
    00493     EPR_SFieldInfo* info;
    00494
    00515     void* elems;
    00516 };
    00517
    00523 struct EPR_Raster
    00524 {
    00529     EPR_Magic magic;
    00530
    00535     EPR_EDataTypeId data_type;
    00536
    00540     uint elem_size;
    00541
    00545     uint source_width;
    00546
    00550     uint source_height;
    00551
    00555     uint source_step_x;
    00556
    00560     uint source_step_y;
    00561
    00566     uint raster_width;
    00567
    00572     uint raster_height;
    00573
    00578     void* buffer;
    00579 };
    00580
    00581
    00596 struct EPR_DatasetRef
    00597 {
    00598     EPR_SDatasetId* dataset_id;
    00599     int             field_index; /* -1 if not used */
    00600     int             elem_index;  /* -1 if not used */
    00601 };
    00602
    00607 struct EPR_FlagDef
    00608 {
    00613     EPR_Magic magic;
    00614
    00618     char* name;
    00619
    00623     uint bit_mask;
    00624
    00628     char* description;
    00629 };
    00630
    00631
    00643 struct EPR_BandId
    00644 {
    00649     EPR_Magic magic;
    00650
    00654     EPR_SProductId* product_id;
    00655
    00660     char* band_name;
    00661
    00665     int spectr_band_index;
    00666
    00673      EPR_SDatasetRef dataset_ref;
    00674
    00684      EPR_ESampleModel sample_model;
    00685
    00693      EPR_EDataTypeId data_type;
    00694
    00703      EPR_EScalingMethod scaling_method;
    00704
    00714      float scaling_offset;
    00715
    00726      float scaling_factor;
    00727
    00731      char* bm_expr;
    00732
    00738     EPR_SPtrArray* flag_coding;
    00739
    00743     char* unit;
    00744
    00748     char* description;
    00749
    00755     epr_boolean lines_mirrored;
    00756 };
    00757
    00764 struct EPR_Time
    00765 {
    00766     int  days;
    00767     uint seconds;
    00768     uint microseconds;
    00769 };
    00770
    00771
    00772
    00773 /*************************************************************************/
    00774 /********************************* FUNCTIONS *****************************/
    00775 /*************************************************************************/
    00776
    00777 /*
    00778  * ============================ (1) Initialisation ==========================
    00779  */
    00780
    00801 int epr_init_api(EPR_ELogLevel   log_level,
    00802                  EPR_FLogHandler log_handler,
    00803                  EPR_FErrHandler err_handler);
    00804
    00805
    00812 void epr_close_api();
    00816 /*
    00817  * ============================ (2) Logging ============================
    00818  */
    00819
    00835 int epr_set_log_level(EPR_ELogLevel log_level);
    00836
    00846 void epr_set_log_handler(EPR_FLogHandler log_handler);
    00847
    00856 void epr_log_message(EPR_ELogLevel log_level, const char* log_message);
    00857
    00860 /*
    00861  * ========================= (3) Error Handling ==========================
    00862  */
    00863
    00875 void epr_set_err_handler(EPR_FErrHandler err_handler);
    00876
    00883 EPR_EErrCode epr_get_last_err_code();
    00884
    00891 const char* epr_get_last_err_message();
    00892
    00898 void epr_clear_err();
    00899
    00902 /*
    00903  * ========================== (4) Input / Output ============================
    00904  */
    00905
    00911 /*
    00912  * ======================= (4.1) Product File Access ==========================
    00913  */
    00914
    00933 EPR_SProductId* epr_open_product(const char* product_file_path);
    00934
    00942 int epr_close_product(EPR_SProductId* product_id);
    00947 /*
    00948  * ================= (4.2) Writing to a file or standard output =================
    00949  */
    00950
    00977 void epr_print_record(const EPR_SRecord* record, FILE* ostream);
    00978 void epr_print_field(const EPR_SField* field, FILE* ostream);
    00979 void epr_print_element(const EPR_SRecord* record, uint field_index, uint element_index, FILE* ostream);
    00980 void epr_dump_record(const EPR_SRecord* record);
    00981 void epr_dump_field(const EPR_SField* field);
    00982 void epr_dump_element(const EPR_SRecord* record, uint field_index, uint element_index);
    00985 /*
    00986  * ======================= (5) Basic Data Access =========================
    00987  */
    00988
    01001 uint epr_get_scene_width(const EPR_SProductId* product_id);
    01002
    01010 uint epr_get_scene_height(const EPR_SProductId* product_id);
    01011
    01014 /*
    01015  * ============================ (5.1) Dataset ==============================
    01016  */
    01017
    01030 uint epr_get_num_datasets(EPR_SProductId* product_id);
    01031
    01040 EPR_SDatasetId* epr_get_dataset_id_at(EPR_SProductId* product_id, uint index);
    01041
    01049 EPR_SDatasetId* epr_get_dataset_id(EPR_SProductId* product_id, const char* dataset_name);
    01050
    01057 const char* epr_get_dataset_name(EPR_SDatasetId* dataset_id);
    01058
    01065 const char* epr_get_dsd_name(const EPR_SDatasetId* dataset_id);
    01066
    01073 EPR_SRecord* epr_get_mph(const EPR_SProductId* product_id);
    01074
    01081 EPR_SRecord* epr_get_sph(const EPR_SProductId* product_id);
    01082
    01089 const EPR_SDSD* epr_get_dsd(const EPR_SDatasetId* dataset_id);
    01090
    01097 uint epr_get_num_records(const EPR_SDatasetId* dataset_id);
    01098
    01099
    01100 uint epr_get_num_dsds(const EPR_SProductId* product_id);
    01101 EPR_SDSD* epr_get_dsd_at(const EPR_SProductId* product_id, uint dsd_index);
    01102
    01105 /*
    01106  * ================================= (5.2) Records ============================
    01107  */
    01108
    01123 EPR_SRecord* epr_create_record(EPR_SDatasetId* dataset_id);
    01124
    01143 EPR_SRecord* epr_read_record(EPR_SDatasetId* dataset_id,
    01144                              uint record_index,
    01145                              EPR_SRecord* record);
    01146
    01154 void epr_free_record(EPR_SRecord* record);
    01155
    01158 /*
    01159  * =========================== (5.3) Field Access =============================
    01160  */
    01161
    01178 const EPR_SField* epr_get_field(const EPR_SRecord* record, const char* field_name);
    01179
    01186 uint epr_get_num_fields(const EPR_SRecord* record);
    01187
    01196 const EPR_SField* epr_get_field_at(const EPR_SRecord* record, uint field_index);
    01197
    01204 const char* epr_get_field_unit(const EPR_SField* field);
    01205
    01213 const char* epr_get_field_description(const EPR_SField* field);
    01214
    01222 uint epr_get_field_num_elems(const EPR_SField* field);
    01223
    01231 const char* epr_get_field_name(const EPR_SField* field);
    01232
    01240 EPR_EDataTypeId epr_get_field_type(const EPR_SField* field);
    01241
    01244 /*
    01245  * ========================= (5.4) Single Element Access =========================
    01246  */
    01247
    01263 char epr_get_field_elem_as_char(const EPR_SField* field, uint elem_index);
    01264 uchar epr_get_field_elem_as_uchar(const EPR_SField* field, uint elem_index);
    01265 short epr_get_field_elem_as_short(const EPR_SField* field, uint elem_index);
    01266 ushort epr_get_field_elem_as_ushort(const EPR_SField* field, uint elem_index);
    01267 int epr_get_field_elem_as_int(const EPR_SField* field, uint elem_index);
    01268 uint epr_get_field_elem_as_uint(const EPR_SField* field, uint elem_index);
    01269 float epr_get_field_elem_as_float(const EPR_SField* field, uint elem_index);
    01270 double epr_get_field_elem_as_double(const EPR_SField* field, uint elem_index);
    01271 const EPR_STime* epr_get_field_elem_as_mjd(const EPR_SField* field);
    01272 const char* epr_get_field_elem_as_str(const EPR_SField* field);
    01275 /*
    01276  * =========================== (5.5) Array Element Access =============================
    01277  */
    01278
    01291 const char* epr_get_field_elems_char(const EPR_SField* field);
    01292 const uchar* epr_get_field_elems_uchar(const EPR_SField* field);
    01293 const short* epr_get_field_elems_short(const EPR_SField* field);
    01294 const ushort* epr_get_field_elems_ushort(const EPR_SField* field);
    01295 const int* epr_get_field_elems_int(const EPR_SField* field);
    01296 const uint* epr_get_field_elems_uint(const EPR_SField* field);
    01297 const float* epr_get_field_elems_float(const EPR_SField* field);
    01298 const double* epr_get_field_elems_double(const EPR_SField* field);
    01317 uint epr_copy_field_elems_as_ints(const EPR_SField* field, int* buffer, uint num_elems);
    01318 uint epr_copy_field_elems_as_uints(const EPR_SField* field, uint* buffer, uint num_elems);
    01319 uint epr_copy_field_elems_as_floats(const EPR_SField* field, float* buffer, uint num_elems);
    01320 uint epr_copy_field_elems_as_doubles(const EPR_SField* field, double* buffer, uint num_elems);
    01325 /*
    01326  * ======================== (6) Geophysical Data Access =========================
    01327  */
    01328
    01336 /*
    01337  * ================================== (6.1) Raster ===============================
    01338  */
    01339
    01380 EPR_SRaster* epr_create_compatible_raster(EPR_SBandId* band_id,
    01381                                           uint source_width,
    01382                                           uint source_height,
    01383                                           uint source_step_x,
    01384                                           uint source_step_y);
    01385
    01398 EPR_SRaster* epr_create_raster(EPR_EDataTypeId data_type,
    01399                                uint source_width,
    01400                                uint source_height,
    01401                                uint source_step_x,
    01402                                uint source_step_y);
    01403
    01404
    01415 EPR_SRaster* epr_create_bitmask_raster(uint source_width,
    01416                                        uint source_height,
    01417                                        uint source_step_x,
    01418                                        uint source_step_y);
    01419
    01437 int epr_read_band_raster(EPR_SBandId* band_id,
    01438                          int offset_x,
    01439                          int offset_y,
    01440                          EPR_SRaster* raster);
    01441
    01442
    01446 uint epr_get_raster_elem_size(const EPR_SRaster* raster);
    01447
    01451 void* epr_get_raster_elem_addr(const EPR_SRaster* raster, uint offset);
    01452
    01456 void* epr_get_raster_pixel_addr(const EPR_SRaster* raster, uint x, uint y);
    01457
    01461 void* epr_get_raster_line_addr(const EPR_SRaster* raster, uint y);
    01462
    01463
    01471 uint epr_get_raster_width(EPR_SRaster* raster);
    01472
    01480 uint epr_get_raster_height(EPR_SRaster* raster);
    01481
    01482
    01483
    01490 uint epr_get_num_bands(EPR_SProductId* product_id);
    01491
    01500 EPR_SBandId* epr_get_band_id_at(EPR_SProductId* product_id, uint index);
    01501
    01509 EPR_SBandId* epr_get_band_id(EPR_SProductId* product_id, const char* band_name);
    01510
    01517 const char* epr_get_band_name(EPR_SBandId* band_id);
    01518
    01524 void epr_free_raster(EPR_SRaster* raster);
    01525
    01528 /*
    01529  * ============================ (6.2) Single Pixel Access ========================
    01530  */
    01531
    01548 uint epr_get_pixel_as_uint(const EPR_SRaster* raster, int x, int y);
    01549 int epr_get_pixel_as_int(const EPR_SRaster* raster, int x, int y);
    01550 float epr_get_pixel_as_float(const EPR_SRaster* raster, int x, int y);
    01551 double epr_get_pixel_as_double(const EPR_SRaster* raster, int x, int y);
    01554 /*
    01555  * ================================= (7) Bitmasks ==========================
    01556  */
    01557
    01583 int epr_read_bitmask_raster(EPR_SProductId* product_id,
    01584                             const char* bm_expr,
    01585                             int offset_x,
    01586                             int offset_y,
    01587                             EPR_SRaster* raster);
    01588
    01591 /*
    01592  * ================================= (8) Utility functions ==========================
    01593  */
    01594
    01603 uint epr_get_data_type_size(EPR_EDataTypeId data_type_id);
    01604
    01608 const char* epr_data_type_id_to_str(EPR_EDataTypeId data_type_id);
    01609
    01612 #ifdef __cplusplus
    01613 } /* extern "C" */
    01614 #endif
    01615 #endif /* #ifndef EPR_API_H_INCL */