sdata.h
Go to the documentation of this file.
1 /*
2  * Copyright 2016 CNRS & Universite Lille 1. All rights reserved.
3  *
4  * Licensed under the GRASP Open Source License V1.0 (see LICENSE file)
5  */
6 
13 #ifndef SDATA_H
14 #define SDATA_H
15 
16 #include <grasp/utils.h>
17 #include "../../grasp_input.h"
18 #include "../../util/grasp_box.h"
19 #include "../../../global/grasp_retrieval_meas_type.h"
20 #include "../../util/grasp_driver_settings.h"
21 #include "mod_par_inv.inc"
22 #include "mod_par_OS.inc"
23 #include <time.h>
24 #include "grasp_input_driver_sdata_error_codes.h"
25 
26 typedef struct SDATA_HANDLE_ SDATA_HANDLE;
27 typedef struct SDATA_RECORD_ SDATA_RECORD;
28 
29 
30 #define SDATA_MAX_NWL _KWM /* maximal number of wavelengths */
31 #define SDATA_MAX_NBVM _NBVM /* maximal number of geometries */
32 #define SDATA_MAX_KNBVM _KNBVM /* maximum between _NBVM and _KVERTM */
33 #define SDATA_MAX_NX _KIX
34 #define SDATA_MAX_NY _KIY
35 #define SDATA_MAX_NSURF _KSURF
36 #define SDATA_MAX_NIP _KIP
37 #define SDATA_MAX_KVERTM _KVERTM /* maximal number of vertical measurements */
38 
39 typedef struct SDATA_TIMESTAMP_ {
40  /* all the fields below are redundant, and are different expressions (or parts) of the same timestamp.
41  * They are provided here as a convenience for the user and also for control.
42  * Some fields may be removed in more mature versions of the project.
43  */
44  char str_date_time[20 + 1]; /* format YYYY-MM-DDThh:mm:ssZ */
45  time_t unix_time; /* representation of the timestamp in number of seconds since the Unix Epoch */
46  long index_of_day; /* representation of the timestamp in number of days since the Unix Epoch (starts at 0) */
47 } SDATA_TIMESTAMP;
48 
49 typedef struct SDATA_TIME_LIMITS_ {
50  SDATA_TIMESTAMP first_record;
51  SDATA_TIMESTAMP last_record;
52 } SDATA_TIME_LIMITS;
53 
54 typedef struct SDATA_HEADER_ {
55  char format_version[31 + 1];
56  int nx;
57  int ny;
58  int nrecords; /* number of records (one record is a SDATA_RECORD object). One record may contain several pixels with the same time index (it). */
59  int npixels; /* total number of pixels (SDATA_PIXEL objects) in the SDATA file (sum of the pixels of all the records) */
60  int xmin, xmax; /* x-range of the pixels available in the SDATA */
61  int ymin, ymax; /* y-range of the pixels available in the SDATA */
62  SDATA_TIME_LIMITS time_limits;
63 } SDATA_HEADER;
64 
65 typedef struct SDATA_PIXEL_ {
66 
67  int ix; /* relative coordinate in the SDATA segment, in the range [1..nx] */
68  int iy; /* relative coordinate in the SDATA segment, in the range [1..ny] */
69  int it; /* index of observation (the record number to which the pixel belongs in the SDATA file) */
70  time_t unix_time; /* derived from the SDATA_RECORD the pixel belongs to */
71  long index_of_day; /* representation of the timestamp in number of days since the Unix Epoch (starts at 0) */
72  int cloud_flag;
73  int irow; /* coordinate of the pixel in the satellite grid */
74  int icol; /* coordinate of the pixel in the satellite grid */
75  double latitude;
76  double longitude;
77  double hgr; /* height of the ground */
78  double hobs; /* height of the observation (same as hgr_km for AERONET, different for satellites) */
79  double land_percent; /* between 0. and 100. */
80  int num_wavelengths;
81 
82  int nsurf; /* derived from the SDATA_RECORD the pixel belongs to */
83  int ifgas; /* derived from the SDATA_RECORD the pixel belongs to */
84 
85  int num_hvp; /* number of valid values for hvp */
86  double hvp[SDATA_MAX_KVERTM]; /* heights for vertical profile */
87 
88  /* spectral properties */
89  double wavelengths[SDATA_MAX_NWL];
90  int num_meas_types[SDATA_MAX_NWL];
91  int num_valid_meas[SDATA_MAX_NWL][SDATA_MAX_NIP];
92  int meas_types[SDATA_MAX_NWL][SDATA_MAX_NIP];
93  double thetas[SDATA_MAX_NWL]; /* solar zenith angle (aka sza) */
94  double thetav[SDATA_MAX_NWL][SDATA_MAX_NIP][SDATA_MAX_KNBVM]; /* view zenith angle (aka vza) */
95  double dphi[SDATA_MAX_NWL][SDATA_MAX_NIP][SDATA_MAX_KNBVM]; /* relative azimuth angle, dphi = phis - phiv (aka raa) */
96  double groundpar[SDATA_MAX_NWL][SDATA_MAX_NSURF]; /* only the first nsurf indices of MAX_NSURF are valid */
97  double gaspar[SDATA_MAX_NWL];
98  int ifcov[SDATA_MAX_NWL][SDATA_MAX_NIP]; /* presence (0 - 1) of covariant matrix in input data */
99  double cmtrx[SDATA_MAX_NWL][SDATA_MAX_NIP][SDATA_MAX_KNBVM]; /* diagonal of covariant matrix */
100  int ifmp[SDATA_MAX_NWL][SDATA_MAX_NIP]; /* presence (0 - 1) of molecular profile in input data */
101  double mprof[SDATA_MAX_NWL][SDATA_MAX_NIP][SDATA_MAX_KVERTM]; /* vertical profile of Rayleigh Backscattering */
102 
103  double tod[SDATA_MAX_NWL][SDATA_MAX_NBVM]; /* optical thickness (meas_type = 11) */
104  double aod[SDATA_MAX_NWL][SDATA_MAX_NBVM]; /* optical thickness (meas_type = 12) */
105  double aaod[SDATA_MAX_NWL][SDATA_MAX_NBVM]; /* optical thickness (meas_type = 13) */
106  double htod[SDATA_MAX_NWL][SDATA_MAX_NBVM]; /* optical thickness (meas_type = 13) */
107  double p11[SDATA_MAX_NWL][SDATA_MAX_NBVM]; /* p11 phase matrix element (meas_type = 21) */
108  double p12[SDATA_MAX_NWL][SDATA_MAX_NBVM]; /* p12 phase matrix element (meas_type = 22) */
109  double p22[SDATA_MAX_NWL][SDATA_MAX_NBVM]; /* p22 phase matrix element (meas_type = 23) */
110  double p33[SDATA_MAX_NWL][SDATA_MAX_NBVM]; /* p33 phase matrix element (meas_type = 24) */
111  double p34[SDATA_MAX_NWL][SDATA_MAX_NBVM]; /* p34 phase matrix element (meas_type = 25) */
112  double p44[SDATA_MAX_NWL][SDATA_MAX_NBVM]; /* p44 phase matrix element (meas_type = 26) */
113  double p11_rel_ang[SDATA_MAX_NWL][SDATA_MAX_NBVM]; /* p44 phase matrix element (meas_type = 27) */
114  double p12_rel[SDATA_MAX_NWL][SDATA_MAX_NBVM]; /* p44 phase matrix element (meas_type = 28) */
115 
116  double LS[SDATA_MAX_NWL][SDATA_MAX_KVERTM]; /* lidar signal (meas_type = 31) */
117  double RL[SDATA_MAX_NWL][SDATA_MAX_KVERTM]; /* Raman lidar signal (meas_type = 32) */
118  double DPAR[SDATA_MAX_NWL][SDATA_MAX_KVERTM]; /* Parallel polarized lidar (meas_type = 33) */
119  double DPER[SDATA_MAX_NWL][SDATA_MAX_KVERTM]; /* Cross polarized lidar (meas_type = 34) */
120  double DP[SDATA_MAX_NWL][SDATA_MAX_KVERTM]; /* depolarization ratio (meas_type = 35) */
121  double VEXT[SDATA_MAX_NWL][SDATA_MAX_KVERTM]; /* Vertical extinction (meas_type = 36) */
122  double VBS[SDATA_MAX_NWL][SDATA_MAX_KVERTM]; /* Vertical backscatter (meas_type = 39) */
123  double I[SDATA_MAX_NWL][SDATA_MAX_NBVM]; /* I Stokes Parameter (meas_type = 41) */
124  double Q[SDATA_MAX_NWL][SDATA_MAX_NBVM]; /* Q Stokes Parameter (meas_type = 42) */
125  double U[SDATA_MAX_NWL][SDATA_MAX_NBVM]; /* U Stokes Parameter (meas_type = 43) */
126  double P[SDATA_MAX_NWL][SDATA_MAX_NBVM]; /* Polarization sqrt(Q*Q + U*U) (meas_type = 44) */
127  double I_rel_sum[SDATA_MAX_NWL][SDATA_MAX_NBVM]; /* Polarization sqrt(Q*Q + U*U) (meas_type = 45) */
128  double P_rel[SDATA_MAX_NWL][SDATA_MAX_NBVM]; /* Polarization sqrt(Q*Q + U*U) (meas_type = 46) */
129 
130  double p11_intd[SDATA_MAX_NWL][SDATA_MAX_NBVM]; /* p11 integrated phase matrix element (meas_type = 51) */
131  double p11_intd_cut_off_1[SDATA_MAX_NWL][SDATA_MAX_NBVM]; /* p11 integrated phase matrix element (meas_type = 52) */
132  double p11_intd_cut_off_2[SDATA_MAX_NWL][SDATA_MAX_NBVM]; /* p11 integrated phase matrix element (meas_type = 53) */
133  double p11_intd_cut_off_3[SDATA_MAX_NWL][SDATA_MAX_NBVM]; /* p11 integrated phase matrix element (meas_type = 54) */
134  double p11_intd_cut_off_4[SDATA_MAX_NWL][SDATA_MAX_NBVM]; /* p11 integrated phase matrix element (meas_type = 55) */
135 
136 } SDATA_PIXEL;
137 
138 extern const char *sdata_str_meas_types(int meas_type);
139 extern int sdata_open(const char *file_name, SDATA_HANDLE **ihandle);
140 extern const char *sdata_get_file_name(const SDATA_HANDLE *handle);
141 extern int sdata_get_header(const SDATA_HANDLE *handle, SDATA_HEADER *header);
142 extern void sdata_print_header(FILE *output_stream, const char *label, const SDATA_HEADER *header);
143 extern void sdata_print_pixel(FILE *output_stream, const char *label, const SDATA_PIXEL *pixel);
144 extern int sdata_close(SDATA_HANDLE *handle);
145 extern int sdata_dump_file(FILE *output_stream, const char *sdata_file);
146 extern void sdata_dump_record(FILE *output_stream, SDATA_RECORD *record);
147 extern void sdata_dump_pixel(FILE *output_stream, const SDATA_PIXEL *pixel);
148 extern void sdata_dump_header(FILE *output_stream, const SDATA_HEADER *header);
149 extern int sdata_load_box(SDATA_HANDLE *handle, const grasp_driver_settings_t *user_settings, grasp_box_t **ibox);
150 extern void sdata_set_error_stream(FILE *stream);
151 extern void sdata_set_debug_stream(FILE *stream);
152 extern FILE *sdata_get_error_stream(void);
153 extern FILE *sdata_get_debug_stream(void);
154 
155 #endif /* SDATA_H */
grasp_driver_settings_t_
Definition: grasp_driver_settings.h:21
SDATA_TIMESTAMP_
Definition: sdata.h:39
SDATA_HEADER_::ny
int ny
Definition: sdata.h:57
SDATA_TIME_LIMITS_::last_record
SDATA_TIMESTAMP last_record
Definition: sdata.h:51
SDATA_PIXEL
struct SDATA_PIXEL_ SDATA_PIXEL
SDATA_HEADER_::nrecords
int nrecords
Definition: sdata.h:58
sdata_get_error_stream
FILE * sdata_get_error_stream(void)
Definition: sdata.c:147
SDATA_PIXEL_::latitude
double latitude
Definition: sdata.h:75
sdata_set_debug_stream
void sdata_set_debug_stream(FILE *stream)
Definition: sdata.c:142
SDATA_HEADER_::ymax
int ymax
Definition: sdata.h:61
SDATA_PIXEL_::thetas
double thetas[SDATA_MAX_NWL]
Definition: sdata.h:93
SDATA_PIXEL_::htod
double htod[SDATA_MAX_NWL][SDATA_MAX_NBVM]
Definition: sdata.h:106
SDATA_PIXEL_::aaod
double aaod[SDATA_MAX_NWL][SDATA_MAX_NBVM]
Definition: sdata.h:105
SDATA_PIXEL_::ix
int ix
Definition: sdata.h:67
SDATA_PIXEL_::mprof
double mprof[SDATA_MAX_NWL][SDATA_MAX_NIP][SDATA_MAX_KVERTM]
Definition: sdata.h:101
SDATA_RECORD_
Definition: sdata-impl.h:61
sdata_get_file_name
const char * sdata_get_file_name(const SDATA_HANDLE *handle)
Definition: sdata.c:541
SDATA_PIXEL_::cloud_flag
int cloud_flag
Definition: sdata.h:72
SDATA_MAX_NWL
#define SDATA_MAX_NWL
Definition: sdata.h:30
SDATA_PIXEL_::p33
double p33[SDATA_MAX_NWL][SDATA_MAX_NBVM]
Definition: sdata.h:110
sdata_get_header
int sdata_get_header(const SDATA_HANDLE *handle, SDATA_HEADER *header)
Definition: sdata.c:530
SDATA_PIXEL_::meas_types
int meas_types[SDATA_MAX_NWL][SDATA_MAX_NIP]
Definition: sdata.h:92
sdata_close
int sdata_close(SDATA_HANDLE *handle)
Definition: sdata.c:2048
SDATA_PIXEL_::RL
double RL[SDATA_MAX_NWL][SDATA_MAX_KVERTM]
Definition: sdata.h:117
SDATA_TIME_LIMITS
struct SDATA_TIME_LIMITS_ SDATA_TIME_LIMITS
SDATA_PIXEL_::P
double P[SDATA_MAX_NWL][SDATA_MAX_NBVM]
Definition: sdata.h:126
SDATA_PIXEL_::it
int it
Definition: sdata.h:69
SDATA_PIXEL_::p11_intd_cut_off_4
double p11_intd_cut_off_4[SDATA_MAX_NWL][SDATA_MAX_NBVM]
Definition: sdata.h:134
SDATA_PIXEL_::unix_time
time_t unix_time
Definition: sdata.h:70
SDATA_PIXEL_::hgr
double hgr
Definition: sdata.h:77
SDATA_PIXEL_::index_of_day
long index_of_day
Definition: sdata.h:71
SDATA_HEADER_::ymin
int ymin
Definition: sdata.h:61
SDATA_PIXEL_::p11_rel_ang
double p11_rel_ang[SDATA_MAX_NWL][SDATA_MAX_NBVM]
Definition: sdata.h:113
SDATA_PIXEL_::LS
double LS[SDATA_MAX_NWL][SDATA_MAX_KVERTM]
Definition: sdata.h:116
SDATA_PIXEL_::thetav
double thetav[SDATA_MAX_NWL][SDATA_MAX_NIP][SDATA_MAX_KNBVM]
Definition: sdata.h:94
SDATA_PIXEL_::P_rel
double P_rel[SDATA_MAX_NWL][SDATA_MAX_NBVM]
Definition: sdata.h:128
SDATA_PIXEL_::num_wavelengths
int num_wavelengths
Definition: sdata.h:80
SDATA_PIXEL_::p11
double p11[SDATA_MAX_NWL][SDATA_MAX_NBVM]
Definition: sdata.h:107
sdata_get_debug_stream
FILE * sdata_get_debug_stream(void)
Definition: sdata.c:156
SDATA_PIXEL_::Q
double Q[SDATA_MAX_NWL][SDATA_MAX_NBVM]
Definition: sdata.h:124
SDATA_PIXEL_::irow
int irow
Definition: sdata.h:73
SDATA_PIXEL_::DP
double DP[SDATA_MAX_NWL][SDATA_MAX_KVERTM]
Definition: sdata.h:120
SDATA_PIXEL_::wavelengths
double wavelengths[SDATA_MAX_NWL]
Definition: sdata.h:89
SDATA_PIXEL_::VEXT
double VEXT[SDATA_MAX_NWL][SDATA_MAX_KVERTM]
Definition: sdata.h:121
SDATA_PIXEL_::hobs
double hobs
Definition: sdata.h:78
SDATA_PIXEL_::ifmp
int ifmp[SDATA_MAX_NWL][SDATA_MAX_NIP]
Definition: sdata.h:100
SDATA_PIXEL_::aod
double aod[SDATA_MAX_NWL][SDATA_MAX_NBVM]
Definition: sdata.h:104
sdata_print_pixel
void sdata_print_pixel(FILE *output_stream, const char *label, const SDATA_PIXEL *pixel)
Definition: sdata.c:685
SDATA_PIXEL_::DPER
double DPER[SDATA_MAX_NWL][SDATA_MAX_KVERTM]
Definition: sdata.h:119
SDATA_PIXEL_::VBS
double VBS[SDATA_MAX_NWL][SDATA_MAX_KVERTM]
Definition: sdata.h:122
SDATA_PIXEL_::gaspar
double gaspar[SDATA_MAX_NWL]
Definition: sdata.h:97
SDATA_PIXEL_::icol
int icol
Definition: sdata.h:74
SDATA_PIXEL_::U
double U[SDATA_MAX_NWL][SDATA_MAX_NBVM]
Definition: sdata.h:125
SDATA_PIXEL_::num_valid_meas
int num_valid_meas[SDATA_MAX_NWL][SDATA_MAX_NIP]
Definition: sdata.h:91
grasp_input_driver_sdata_error_codes.h
SDATA_PIXEL_::tod
double tod[SDATA_MAX_NWL][SDATA_MAX_NBVM]
Definition: sdata.h:103
SDATA_PIXEL_::num_hvp
int num_hvp
Definition: sdata.h:85
sdata_dump_pixel
void sdata_dump_pixel(FILE *output_stream, const SDATA_PIXEL *pixel)
Definition: sdata.c:2089
SDATA_HEADER_::npixels
int npixels
Definition: sdata.h:59
sdata_open
int sdata_open(const char *file_name, SDATA_HANDLE **ihandle)
Definition: sdata.c:417
SDATA_PIXEL_::iy
int iy
Definition: sdata.h:68
SDATA_PIXEL_::ifgas
int ifgas
Definition: sdata.h:83
SDATA_PIXEL_::p11_intd_cut_off_2
double p11_intd_cut_off_2[SDATA_MAX_NWL][SDATA_MAX_NBVM]
Definition: sdata.h:132
SDATA_MAX_NBVM
#define SDATA_MAX_NBVM
Definition: sdata.h:31
sdata_print_header
void sdata_print_header(FILE *output_stream, const char *label, const SDATA_HEADER *header)
Definition: sdata.c:562
sdata_str_meas_types
const char * sdata_str_meas_types(int meas_type)
Definition: sdata.c:62
SDATA_HEADER_::xmin
int xmin
Definition: sdata.h:60
SDATA_PIXEL_::num_meas_types
int num_meas_types[SDATA_MAX_NWL]
Definition: sdata.h:90
sdata_dump_file
int sdata_dump_file(FILE *output_stream, const char *sdata_file)
Definition: sdata.c:2397
SDATA_HEADER_::time_limits
SDATA_TIME_LIMITS time_limits
Definition: sdata.h:62
SDATA_HEADER
struct SDATA_HEADER_ SDATA_HEADER
SDATA_PIXEL_::p12_rel
double p12_rel[SDATA_MAX_NWL][SDATA_MAX_NBVM]
Definition: sdata.h:114
sdata_dump_record
void sdata_dump_record(FILE *output_stream, SDATA_RECORD *record)
Definition: sdata.c:2077
SDATA_TIMESTAMP_::index_of_day
long index_of_day
Definition: sdata.h:46
SDATA_TIME_LIMITS_::first_record
SDATA_TIMESTAMP first_record
Definition: sdata.h:50
SDATA_PIXEL_::I_rel_sum
double I_rel_sum[SDATA_MAX_NWL][SDATA_MAX_NBVM]
Definition: sdata.h:127
SDATA_TIMESTAMP_::unix_time
time_t unix_time
Definition: sdata.h:45
SDATA_PIXEL_::land_percent
double land_percent
Definition: sdata.h:79
SDATA_PIXEL_::nsurf
int nsurf
Definition: sdata.h:82
SDATA_MAX_NIP
#define SDATA_MAX_NIP
Definition: sdata.h:36
SDATA_HEADER_::format_version
char format_version[31+1]
Definition: sdata.h:55
sdata_dump_header
void sdata_dump_header(FILE *output_stream, const SDATA_HEADER *header)
Definition: sdata.c:551
SDATA_PIXEL_::ifcov
int ifcov[SDATA_MAX_NWL][SDATA_MAX_NIP]
Definition: sdata.h:98
SDATA_TIME_LIMITS_
Definition: sdata.h:49
sdata_set_error_stream
void sdata_set_error_stream(FILE *stream)
Definition: sdata.c:129
SDATA_PIXEL_::longitude
double longitude
Definition: sdata.h:76
SDATA_PIXEL_::p22
double p22[SDATA_MAX_NWL][SDATA_MAX_NBVM]
Definition: sdata.h:109
SDATA_PIXEL_::hvp
double hvp[SDATA_MAX_KVERTM]
Definition: sdata.h:86
SDATA_PIXEL_::p11_intd_cut_off_3
double p11_intd_cut_off_3[SDATA_MAX_NWL][SDATA_MAX_NBVM]
Definition: sdata.h:133
SDATA_PIXEL_
Definition: sdata.h:65
SDATA_HANDLE_
Definition: sdata-impl.h:52
SDATA_TIMESTAMP_::str_date_time
char str_date_time[20+1]
Definition: sdata.h:44
SDATA_PIXEL_::I
double I[SDATA_MAX_NWL][SDATA_MAX_NBVM]
Definition: sdata.h:123
SDATA_MAX_KNBVM
#define SDATA_MAX_KNBVM
Definition: sdata.h:32
SDATA_PIXEL_::p11_intd
double p11_intd[SDATA_MAX_NWL][SDATA_MAX_NBVM]
Definition: sdata.h:130
SDATA_HEADER_::xmax
int xmax
Definition: sdata.h:60
SDATA_PIXEL_::p44
double p44[SDATA_MAX_NWL][SDATA_MAX_NBVM]
Definition: sdata.h:112
SDATA_MAX_KVERTM
#define SDATA_MAX_KVERTM
Definition: sdata.h:37
SDATA_PIXEL_::groundpar
double groundpar[SDATA_MAX_NWL][SDATA_MAX_NSURF]
Definition: sdata.h:96
SDATA_PIXEL_::cmtrx
double cmtrx[SDATA_MAX_NWL][SDATA_MAX_NIP][SDATA_MAX_KNBVM]
Definition: sdata.h:99
grasp_box_t_
Definition: grasp_box.c:29
SDATA_MAX_NSURF
#define SDATA_MAX_NSURF
Definition: sdata.h:35
SDATA_HEADER_::nx
int nx
Definition: sdata.h:56
SDATA_HEADER_
Definition: sdata.h:54
sdata_load_box
int sdata_load_box(SDATA_HANDLE *handle, const grasp_driver_settings_t *user_settings, grasp_box_t **ibox)
Definition: sdata.c:2536
SDATA_PIXEL_::dphi
double dphi[SDATA_MAX_NWL][SDATA_MAX_NIP][SDATA_MAX_KNBVM]
Definition: sdata.h:95
SDATA_PIXEL_::p12
double p12[SDATA_MAX_NWL][SDATA_MAX_NBVM]
Definition: sdata.h:108
SDATA_PIXEL_::DPAR
double DPAR[SDATA_MAX_NWL][SDATA_MAX_KVERTM]
Definition: sdata.h:118
SDATA_PIXEL_::p34
double p34[SDATA_MAX_NWL][SDATA_MAX_NBVM]
Definition: sdata.h:111
SDATA_TIMESTAMP
struct SDATA_TIMESTAMP_ SDATA_TIMESTAMP
SDATA_PIXEL_::p11_intd_cut_off_1
double p11_intd_cut_off_1[SDATA_MAX_NWL][SDATA_MAX_NBVM]
Definition: sdata.h:131