ENVISAT Product Reader API for C

epr_api.h
Go to the documentation of this file.
1 /*
2  * $Id: epr_api.h,v 1.3 2009-03-27 10:25:54 sabine Exp $
3  *
4  * Copyright (C) 2002 by Brockmann Consult (info@brockmann-consult.de)
5  *
6  * This program is free software; you can redistribute it and/or modify it
7  * under the terms of the GNU General Public License as published by the
8  * Free Software Foundation. This program is distributed in the hope it will
9  * be useful, but WITHOUT ANY WARRANTY; without even the implied warranty
10  * of MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.
11  * See the GNU General Public License for more details.
12  *
13  * You should have received a copy of the GNU General Public License
14  * along with this program; if not, write to the Free Software
15  * Foundation, Inc., 59 Temple Place - Suite 330, Boston, MA 02111-1307, USA.
16  */
17 
18 #ifndef EPR_API_H_INCL
19 #define EPR_API_H_INCL
20 
21 
22 #ifdef __cplusplus
23 extern "C"
24 {
25 #endif
26 
27 /* to make the FILE structure available */
28 #include <stdio.h>
29 
30 /* to make dynamic arrays available*/
31 #include "epr_ptrarray.h"
32 
33 #define EPR_PRODUCT_API_NAME_STR "ENVISAT Product Reader API"
34 #define EPR_PRODUCT_API_VERSION_STR "2.2"
35 
36 /* needed by Doxygen */
46 {
60  e_tid_int = 6,
71 };
72 
73 
79 {
80  /* Not an error */
82 
83  /* Low level errors */
91 
92  /* I/O errors */
99 
100  /* API related errors */
115 
116  /* Bitmask term errors */
118 
119 
120  /* DDDB errors */
122 };
123 
124 
130 {
135 };
136 
138 {
144 };
145 
147 {
151 };
152 
153 struct EPR_ProductId;
154 struct EPR_DatasetId;
155 struct EPR_BandId;
156 struct EPR_Record;
157 struct EPR_RecordInfo;
158 struct EPR_Field;
159 struct EPR_FieldInfo;
160 struct EPR_ProductInfo;
161 struct EPR_DSD;
162 struct EPR_Raster;
163 struct EPR_DatasetRef;
164 struct EPR_Flag;
165 struct EPR_BandId;
166 struct EPR_ParamElem;
167 struct EPR_Time;
168 
176 typedef struct EPR_BandId EPR_SBandId;
177 typedef struct EPR_Record EPR_SRecord;
178 typedef struct EPR_RecordInfo EPR_SRecordInfo;
179 typedef struct EPR_Field EPR_SField;
180 typedef struct EPR_FieldInfo EPR_SFieldInfo;
181 typedef struct EPR_DSD EPR_SDSD;
182 typedef struct EPR_Raster EPR_SRaster;
183 typedef struct EPR_FlagDef EPR_SFlagDef;
184 typedef struct EPR_ParamElem EPR_SParamElem;
185 typedef struct EPR_Time EPR_STime;
187 typedef struct EPR_BitmaskTerm EPR_SBitmaskTerm;
188 typedef struct EPR_FlagSet EPR_SFlagSet;
189 typedef void (*EPR_FErrHandler)(EPR_EErrCode err_code, const char* err_message);
190 typedef void (*EPR_FLogHandler)(EPR_ELogLevel log_level, const char* log_message);
191 
192 
193 typedef int epr_boolean;
194 typedef unsigned char uchar;
195 typedef unsigned short ushort;
196 typedef unsigned int uint;
197 typedef unsigned long ulong;
198 
199 
200 typedef int EPR_Magic;
201 
202 #define EPR_MAGIC_PRODUCT_ID 0xCAFFEE64
203 #define EPR_MAGIC_DATASET_ID 0xEFEABDCA
204 #define EPR_MAGIC_BAND_ID 0xFEC21ABD
205 #define EPR_MAGIC_RECORD 0x7BABACAE
206 #define EPR_MAGIC_FIELD 0xBA0BABBA
207 #define EPR_MAGIC_RASTER 0x0BABA0EB
208 #define EPR_MAGIC_FLAG_DEF 0xCABA11AD
209 
210 #define TRUE 1
211 #define FALSE 0
212 
213 #define EPR_PRODUCT_ID_STRLEN 48
214 
215 
216 /*************************************************************************/
217 /******************************** STRUCTURES *****************************/
218 /*************************************************************************/
219 
228 {
233  EPR_Magic magic;
234 
238  char* file_path;
239 
244  FILE* istream;
245 
249  uint tot_size;
250 
255 
260 
270 
275 
280 
285  EPR_SPtrArray* dsd_array;
286 
296  EPR_SPtrArray* record_info_cache;
297 
304  EPR_SPtrArray* param_table;
305 
309  EPR_SPtrArray* dataset_ids;
310 
314  EPR_SPtrArray* band_ids;
315 
320 };
321 
322 
323 
324 
338 {
343  EPR_Magic magic;
344 
349 
353  char* dsd_name;
354 
358  const EPR_SDSD* dsd;
359 
364 
368  const struct RecordDescriptor* record_descriptor;
369 
374 
375 
379  char* description;
380 };
381 
382 
390 struct EPR_DSD
391 {
396  EPR_Magic magic;
397 
401  int index;
402 
406  char* ds_name;
407 
411  char* ds_type;
412 
416  char* filename;
417 
421  uint ds_offset;
422 
426  uint ds_size;
427 
431  uint num_dsr;
432 
436  uint dsr_size;
437 };
438 
439 
448 {
453  EPR_Magic magic;
454 
459 
466 
472 };
473 
481 struct EPR_Field
482 {
487  EPR_Magic magic;
488 
494 
515  void* elems;
516 };
517 
524 {
529  EPR_Magic magic;
530 
535  EPR_EDataTypeId data_type;
536 
540  uint elem_size;
541 
546 
551 
556 
561 
567 
573 
578  void* buffer;
579 };
580 
581 
597 {
599  int field_index; /* -1 if not used */
600  int elem_index; /* -1 if not used */
601 };
602 
608 {
613  EPR_Magic magic;
614 
618  char* name;
619 
623  uint bit_mask;
624 
628  char* description;
629 };
630 
631 
644 {
649  EPR_Magic magic;
650 
655 
660  char* band_name;
661 
666 
674 
684  EPR_ESampleModel sample_model;
685 
693  EPR_EDataTypeId data_type;
694 
703  EPR_EScalingMethod scaling_method;
704 
715 
727 
731  char* bm_expr;
732 
738  EPR_SPtrArray* flag_coding;
739 
743  char* unit;
744 
748  char* description;
749 
755  epr_boolean lines_mirrored;
756 };
757 
764 struct EPR_Time
765 {
766  int days;
767  uint seconds;
769 };
770 
771 
772 
773 /*************************************************************************/
774 /********************************* FUNCTIONS *****************************/
775 /*************************************************************************/
776 
777 /*
778  * ============================ (1) Initialisation ==========================
779  */
780 
801 int epr_init_api(EPR_ELogLevel log_level,
802  EPR_FLogHandler log_handler,
803  EPR_FErrHandler err_handler);
804 
805 
812 void epr_close_api();
816 /*
817  * ============================ (2) Logging ============================
818  */
819 
835 int epr_set_log_level(EPR_ELogLevel log_level);
836 
846 void epr_set_log_handler(EPR_FLogHandler log_handler);
847 
856 void epr_log_message(EPR_ELogLevel log_level, const char* log_message);
857 
860 /*
861  * ========================= (3) Error Handling ==========================
862  */
863 
875 void epr_set_err_handler(EPR_FErrHandler err_handler);
876 
883 EPR_EErrCode epr_get_last_err_code();
884 
891 const char* epr_get_last_err_message();
892 
898 void epr_clear_err();
899 
902 /*
903  * ========================== (4) Input / Output ============================
904  */
905 
911 /*
912  * ======================= (4.1) Product File Access ==========================
913  */
914 
933 EPR_SProductId* epr_open_product(const char* product_file_path);
934 
942 int epr_close_product(EPR_SProductId* product_id);
947 /*
948  * ================= (4.2) Writing to a file or standard output =================
949  */
950 
977 void epr_print_record(const EPR_SRecord* record, FILE* ostream);
978 void epr_print_field(const EPR_SField* field, FILE* ostream);
979 void epr_print_element(const EPR_SRecord* record, uint field_index, uint element_index, FILE* ostream);
980 void epr_dump_record(const EPR_SRecord* record);
981 void epr_dump_field(const EPR_SField* field);
982 void epr_dump_element(const EPR_SRecord* record, uint field_index, uint element_index);
985 /*
986  * ======================= (5) Basic Data Access =========================
987  */
988 
1001 uint epr_get_scene_width(const EPR_SProductId* product_id);
1002 
1010 uint epr_get_scene_height(const EPR_SProductId* product_id);
1011 
1014 /*
1015  * ============================ (5.1) Dataset ==============================
1016  */
1017 
1030 uint epr_get_num_datasets(EPR_SProductId* product_id);
1031 
1040 EPR_SDatasetId* epr_get_dataset_id_at(EPR_SProductId* product_id, uint index);
1041 
1049 EPR_SDatasetId* epr_get_dataset_id(EPR_SProductId* product_id, const char* dataset_name);
1050 
1057 const char* epr_get_dataset_name(EPR_SDatasetId* dataset_id);
1058 
1065 const char* epr_get_dsd_name(const EPR_SDatasetId* dataset_id);
1066 
1073 EPR_SRecord* epr_get_mph(const EPR_SProductId* product_id);
1074 
1081 EPR_SRecord* epr_get_sph(const EPR_SProductId* product_id);
1082 
1089 const EPR_SDSD* epr_get_dsd(const EPR_SDatasetId* dataset_id);
1090 
1097 uint epr_get_num_records(const EPR_SDatasetId* dataset_id);
1098 
1099 
1100 uint epr_get_num_dsds(const EPR_SProductId* product_id);
1101 EPR_SDSD* epr_get_dsd_at(const EPR_SProductId* product_id, uint dsd_index);
1102 
1105 /*
1106  * ================================= (5.2) Records ============================
1107  */
1108 
1124 
1144  uint record_index,
1145  EPR_SRecord* record);
1146 
1154 void epr_free_record(EPR_SRecord* record);
1155 
1158 /*
1159  * =========================== (5.3) Field Access =============================
1160  */
1161 
1178 const EPR_SField* epr_get_field(const EPR_SRecord* record, const char* field_name);
1179 
1186 uint epr_get_num_fields(const EPR_SRecord* record);
1187 
1196 const EPR_SField* epr_get_field_at(const EPR_SRecord* record, uint field_index);
1197 
1204 const char* epr_get_field_unit(const EPR_SField* field);
1205 
1213 const char* epr_get_field_description(const EPR_SField* field);
1214 
1222 uint epr_get_field_num_elems(const EPR_SField* field);
1223 
1231 const char* epr_get_field_name(const EPR_SField* field);
1232 
1240 EPR_EDataTypeId epr_get_field_type(const EPR_SField* field);
1241 
1244 /*
1245  * ========================= (5.4) Single Element Access =========================
1246  */
1247 
1263 char epr_get_field_elem_as_char(const EPR_SField* field, uint elem_index);
1264 uchar epr_get_field_elem_as_uchar(const EPR_SField* field, uint elem_index);
1265 short epr_get_field_elem_as_short(const EPR_SField* field, uint elem_index);
1266 ushort epr_get_field_elem_as_ushort(const EPR_SField* field, uint elem_index);
1267 int epr_get_field_elem_as_int(const EPR_SField* field, uint elem_index);
1268 uint epr_get_field_elem_as_uint(const EPR_SField* field, uint elem_index);
1269 float epr_get_field_elem_as_float(const EPR_SField* field, uint elem_index);
1270 double epr_get_field_elem_as_double(const EPR_SField* field, uint elem_index);
1271 const EPR_STime* epr_get_field_elem_as_mjd(const EPR_SField* field);
1272 const char* epr_get_field_elem_as_str(const EPR_SField* field);
1275 /*
1276  * =========================== (5.5) Array Element Access =============================
1277  */
1278 
1291 const char* epr_get_field_elems_char(const EPR_SField* field);
1292 const uchar* epr_get_field_elems_uchar(const EPR_SField* field);
1293 const short* epr_get_field_elems_short(const EPR_SField* field);
1294 const ushort* epr_get_field_elems_ushort(const EPR_SField* field);
1295 const int* epr_get_field_elems_int(const EPR_SField* field);
1296 const uint* epr_get_field_elems_uint(const EPR_SField* field);
1297 const float* epr_get_field_elems_float(const EPR_SField* field);
1298 const double* epr_get_field_elems_double(const EPR_SField* field);
1317 uint epr_copy_field_elems_as_ints(const EPR_SField* field, int* buffer, uint num_elems);
1318 uint epr_copy_field_elems_as_uints(const EPR_SField* field, uint* buffer, uint num_elems);
1319 uint epr_copy_field_elems_as_floats(const EPR_SField* field, float* buffer, uint num_elems);
1320 uint epr_copy_field_elems_as_doubles(const EPR_SField* field, double* buffer, uint num_elems);
1325 /*
1326  * ======================== (6) Geophysical Data Access =========================
1327  */
1328 
1336 /*
1337  * ================================== (6.1) Raster ===============================
1338  */
1339 
1381  uint source_width,
1382  uint source_height,
1383  uint source_step_x,
1384  uint source_step_y);
1385 
1398 EPR_SRaster* epr_create_raster(EPR_EDataTypeId data_type,
1399  uint source_width,
1400  uint source_height,
1401  uint source_step_x,
1402  uint source_step_y);
1403 
1404 
1415 EPR_SRaster* epr_create_bitmask_raster(uint source_width,
1416  uint source_height,
1417  uint source_step_x,
1418  uint source_step_y);
1419 
1437 int epr_read_band_raster(EPR_SBandId* band_id,
1438  int offset_x,
1439  int offset_y,
1440  EPR_SRaster* raster);
1441 
1442 
1446 uint epr_get_raster_elem_size(const EPR_SRaster* raster);
1447 
1451 void* epr_get_raster_elem_addr(const EPR_SRaster* raster, uint offset);
1452 
1456 void* epr_get_raster_pixel_addr(const EPR_SRaster* raster, uint x, uint y);
1457 
1461 void* epr_get_raster_line_addr(const EPR_SRaster* raster, uint y);
1462 
1463 
1471 uint epr_get_raster_width(EPR_SRaster* raster);
1472 
1480 uint epr_get_raster_height(EPR_SRaster* raster);
1481 
1482 
1483 
1490 uint epr_get_num_bands(EPR_SProductId* product_id);
1491 
1500 EPR_SBandId* epr_get_band_id_at(EPR_SProductId* product_id, uint index);
1501 
1509 EPR_SBandId* epr_get_band_id(EPR_SProductId* product_id, const char* band_name);
1510 
1517 const char* epr_get_band_name(EPR_SBandId* band_id);
1518 
1524 void epr_free_raster(EPR_SRaster* raster);
1525 
1528 /*
1529  * ============================ (6.2) Single Pixel Access ========================
1530  */
1531 
1548 uint epr_get_pixel_as_uint(const EPR_SRaster* raster, int x, int y);
1549 int epr_get_pixel_as_int(const EPR_SRaster* raster, int x, int y);
1550 float epr_get_pixel_as_float(const EPR_SRaster* raster, int x, int y);
1551 double epr_get_pixel_as_double(const EPR_SRaster* raster, int x, int y);
1554 /*
1555  * ================================= (7) Bitmasks ==========================
1556  */
1557 
1583 int epr_read_bitmask_raster(EPR_SProductId* product_id,
1584  const char* bm_expr,
1585  int offset_x,
1586  int offset_y,
1587  EPR_SRaster* raster);
1588 
1591 /*
1592  * ================================= (8) Utility functions ==========================
1593  */
1594 
1603 uint epr_get_data_type_size(EPR_EDataTypeId data_type_id);
1604 
1608 const char* epr_data_type_id_to_str(EPR_EDataTypeId data_type_id);
1609 
1612 #ifdef __cplusplus
1613 } /* extern "C" */
1614 #endif
1615 #endif /* #ifndef EPR_API_H_INCL */

Generated on Sat Mar 22 2014 03:42:25

ENVISAT Product Reader C API

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