ENVISAT Product Reader API for C

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

Generated on Wed May 4 2011 16:55:54

ENVISAT Product Reader C API

Written by Brockmann Consult, © 2002     Brockmann Consult      Eropean Space Agency