| ENVISAT Product Reader API for C |
|
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 Mon Aug 2 15:24:00 2010
ENVISAT Product Reader C API
Written by
Brockmann Consult,
© 2002
