Pileus Git - ~andy/rsl/blob - dorade.h

   1 /*
   2     NASA/TRMM, Code 910.1.
   3     This is the TRMM Office Radar Software Library.
   4     Copyright (C) 1996-1999
   5             John H. Merritt
   6             Space Applications Corporation
   7             Vienna, Virginia
   8
   9     This library is free software; you can redistribute it and/or
  10     modify it under the terms of the GNU Library General Public
  11     License as published by the Free Software Foundation; either
  12     version 2 of the License, or (at your option) any later version.
  13
  14     This library is distributed in the hope that it will be useful,
  15     but WITHOUT ANY WARRANTY; without even the implied warranty of
  16     MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the GNU
  17     Library General Public License for more details.
  18
  19     You should have received a copy of the GNU Library General Public
  20     License along with this library; if not, write to the Free
  21     Software Foundation, Inc., 675 Mass Ave, Cambridge, MA 02139, USA.
  22 */
  23 #ifndef _dorade_
  24 #define _dorade_
  25 #include <stdio.h>
  26
  27 typedef struct {
  28   char code[4];
  29   int  len;
  30   char *comment; /* 0..len-1 of comments (N bytes ASCII, N%4==0 */
  31 } Comment_block;
  32
  33 typedef struct {
  34   char  code[4];          /* Code identifier for the volume descriptor. (4 ASCII "VOLD") */
  35   int   len;              /* Length of the volume descriptor. (4 byte int) */
  36   short version;          /* Version number of the format. (2 byte int) */
  37   short volume_number;    /* Volume number from the begining of the data set. (2 byte int) */
  38   int   max_bytes;        /* Maximum number of bytes in a data record. (4 byte int) */
  39   char  project_name[20]; /* Project name. (20 ASCII) */
  40   short year;             /* Year YYYY e.g. 1999 (2 byte int) */
  41   short month;            /* Month 1-12 (2 byte int) */
  42   short day;              /* Day   1-31 (2 byte int) */
  43   short hour;             /* Hour  1-23 (2 byte int) */
  44   short minute;           /* Minute 0-59 (2 byte int) */
  45   short second;           /* Second 0-59 (2 byte int) */
  46   char  flight_num[8];    /* Flight number (8 ASCII) for airborne raar or IOP number
  47                              for ground based radars. */
  48   char  facility_name[8]; /* Generation facility. (8 ASCII) */
  49   short gen_year;         /* Generation year YYYY. (2 byte int) */
  50   short gen_month;        /* Generation month 1-12. (2 byte int) */
  51   short gen_day;          /* Generation day   1-31. (2 byte int) */
  52   short nsensors;         /* Number of sennsor descriptors to follow. (2 byte int) */
  53 } Volume_desc;
  54
  55 typedef struct {
  56   char  code[4];       /* Code identifier for the radar descriptor. (4 ASCII "RADD") */
  57   int   len;           /* Length of the radar descriptor. (4 byte int) */
  58   char  radar_name[8]; /* Radar name. (8 ASCII) */
  59   float radar_constant;/* Radar constant. */
  60   float peak_power;    /* Nominal Peak power. [kw] */
  61   float noise_power;   /* Nominal Noise power. [dBm] */
  62   float rcvr_gain;     /* Receiver gain. [dB] */
  63   float ant_gain;      /* Antenna gain. [dB] */
  64   float radar_system_gain;     /* [dB] */
  65   float horizontal_beam_width; /* [deg] */
  66   float vertical_beam_width;   /* [deg] */
  67   short radar_type;            /* 0--Ground
  68                                   1--Airborne fore
  69                                   2--Airborne aft
  70                                   3--Airborne tail
  71                                   4--Airborne lower fuselage
  72                                   5--Shipborne
  73                                */
  74   short scan_mode;             /* 0--Calibration
  75                                   1--PPI (Constant elevation)
  76                                   2--Coplane
  77                                   3--RHI (Constant azimuth)
  78                                   4--Vertical pointing
  79                                   5--Target (Stationary, not vertical pointing)
  80                                   6--Manual
  81                                   7--Idle (out of control)
  82                                   8--Surveillance
  83                                   9--Vertical sweep (rotation axis parallels the fuselage)
  84                                */
  85   float scan_rate;             /* Nominal scan rate. [deg/sec] */
  86   float start_angle;           /* Nominal start angle. [deg] */
  87   float stop_angle;            /* Nominal stop angle. [deg] */
  88   short nparam_desc;           /* Total number of parameter descriptors for this radar. (2 byte int) */
  89   short ndesc;                 /* Total number of descriptors for this radar. (2 byte int) */
  90   short compress_code;         /* Data compression format code. (2 byte int):
  91                                   0--no compression
  92                                   1--data compression (compression algorithm described
  93                                      in the ASCII file athe the begining of the file.
  94                                */
  95   short compress_algo;         /* Data reduction algorithm:
  96                                   0--No data reduction.
  97                                   1--Data recorded between two rotation angles.
  98                                   2--Data recorded between two concentic angles.
  99                                   3--Data recorded between two altitudes.
 100                                   4-N--Other types of data reduction.
 101                                */
 102   float data_reduction_param1; /* Data reduction specific parameter #1
 103                                   1--Smallest positive angle [deg].
 104                                   2--Inner circle diameter [km].
 105                                   3--Minimum altitude [km].
 106                                   4-N--Will be defined if other types created.
 107                                */
 108   float data_reduction_param2; /* Data reduction specific parameter #2
 109                                   1--Largest positive angle [deg].
 110                                   2--Outer circle diameter [km].
 111                                   3--Maximum altitude [km].
 112                                   4-N--Will be defined if other types created.
 113                                */
 114   float longitude;             /* Radar longitude [deg].  If airborne, airport longitude. */
 115   float latitude;              /* Radar latitude [deg].   If airborne, airport latitude. */
 116   float altitude;              /* Radar altitude of mean sea level (msl) [km].
 117                                   If airborne, airport altitude. */
 118   float unambiguous_velocity;  /* Effective unambiguous velocity [m/s]. */
 119   float unambiguous_range;     /* Effective unambiguous range [km]. */
 120   short nfreq;                 /* Number of freqencies transmitted (2 byte int). */
 121   short npulse_periods;        /* Number of different inter-pulse periods (IPP's) transmitted.
 122                                   (2 byte int). */
 123   float freq[5];               /* Frequency 1..5 [GHz] (float) */
 124   float period[5];             /* Interpulse Period (IPP) 1..5 [ms] (float) */
 125 } Radar_desc;
 126
 127 typedef struct {
 128   char  code[4];       /* Code identifier. (4 ASCII "PARM") */
 129   int   len;           /* Length of this descriptor. */
 130   char  name[8];       /* Name of the parameter. */
 131   char  description[40]; /* Description of the parameter. */
 132   char  units[8];      /* Units (8 ASCII) */
 133   short ipp;           /* Inter-pulse periods.
 134                           Bit 0 set to 1 indicates IPP#1 is used in this parameter.
 135                           Similiarly for bits 1,2,3 and 4 and IPP's 2,3,4 and 5.
 136                        */
 137   short xmit_freq;     /* Transmittd frequencies.
 138                           Bit 0 set to 1 indicates Frequency#1 is used in this parameter.
 139                           Similiarly for bits 1,2,3 and 4 and Frequencies 2,3,4 and 5.
 140                        */
 141   float rcvr_bandwidth;/* [MHz] */
 142   short pulse_width;   /* [m] */
 143   short polarization;  /* 0--Horizontal
 144                           1--Vertical
 145                           2--Circular, Right handed
 146                           3--Elliptical
 147                           4--Circular, Left handed
 148                           5--Dual polarization
 149                        */
 150   short nsamp_in_dwell_time; /* Number of samples in dwell time. */
 151   short parameter_type;    /* 1--8  bit integer
 152                               2--16 bit integer
 153                               3--32 bit integer
 154                               4--floating point (32 bit IEEE)
 155                            */
 156   char  threshold_field[8];
 157   float threshold_value;   /* Units depend on the threshold field. */
 158   float scale_factor;      /* Scale factor. */
 159   float offset_factor;     /* meteorological val = (recorded val - offset factor) / scale factor */
 160   int   missing_data_flag; /* Deleted or missing data flag.  256for bytes, -999 for all others. */
 161 } Parameter_desc;
 162
 163 typedef struct {
 164   char  code[4];     /* Code identifier. (4 ASCII "CELV") */
 165   int   len;         /* Length of this descriptor. */
 166   int   ncells;      /* Number of cells definced in this vector. */
 167   float *range_cell; /* Range to cell n [m] (0..ncells-1) */
 168 } Cell_range_vector;
 169
 170 typedef struct {
 171   char  code[4];           /* Code identifier. (4 ASCII "CFAC") */
 172   int   len;               /* Length of this descriptor. */
 173   float azimuth;           /* Correction for azimuth [deg]. */
 174   float elevation;         /* Correction for elevation [deg]. */
 175   float range;             /* Correction for range delay [m]. */
 176   float longitude;         /* Correction for radar longitude [deg]. */
 177   float latitude;          /* Correction for radar latitude  [deg]. */
 178   float altitude;          /* Correction for radar pressure altitude (msl) [km]. */
 179   float height;            /* Correction for radar altitude above ground (agl) [km]. */
 180   float speed_east_west;   /* Correction for radar platform ground speed E->W [m/s]. */
 181   float speed_north_south; /* Correction for radar platform ground spedd N->S [m/s]. */
 182   float vertical_velocity; /* Correction for radar platform vertical velocity [m/s]. */
 183   float heading;           /* Correction for radar platform heading [deg]. */
 184   float roll;              /* Correction for radar platform roll [deg]. */
 185   float pitch;             /* Correction for radar platform pitch [deg]. */
 186   float drift;             /* Correction for radar platform drift [deg]. */
 187   float rotation_angle;    /* Correction for radar rotation angle [deg]. */
 188   float tilt_angle;        /* Correction for radar tilt angle [deg]. */
 189 } Correction_factor_desc;
 190
 191 typedef struct {
 192   char  code[4];       /* Code identifier. (4 ASCII "SWIB") */
 193   int   len;           /* Length of this descriptor. */
 194   char  radar_name[8]; /* Radar name. */
 195   int   sweep_num;     /* Sweep number from beginning of volume. */
 196   int   nrays;         /* Number of rays recorded in this sweep. */
 197   float start_angle;   /* True start angle [deg]. */
 198   float stop_angle;    /* True stop  angle [deg]. */
 199   float fixed_angle;   /* Fixed angle [deg]. */
 200   int   filter_flag;   /* Filter flag:
 201                           0--No filtering in use.
 202                           1--ON (Algorithm described in ASCII file at beginning of the file.)
 203                        */
 204 } Sweep_info;
 205
 206 typedef struct {
 207   char  code[4];   /* Code identifier. (4 ASCII "RYIB") */
 208   int   len;       /* Length of this descriptor. */
 209   int   sweep_num;
 210   int   jday;      /* Julian day.  (from beginning of year :-) */
 211   short hour;      /* Hour 0-23. */
 212   short minute;    /* Minute 0-59. */
 213   short second;    /* Second 0-59. */
 214   short msec;      /* Millisecond. */
 215   float azimuth;   /* [deg] */
 216   float elevation; /* [deg] */
 217   float peak_power;/* Peak transmitted power [kw] */
 218   float scan_rate; /* [deg/sec]. */
 219   int   status;    /* Ray status:
 220                       0--Normal
 221                       1--Transition (antenna repositioning)
 222                       2--Bad
 223                       3--Questionable
 224                    */
 225 } Ray_info;
 226
 227 typedef struct {       /* Especially for moving radars. */
 228   char  code[4];       /* Code identifier. (4 ASCII "ASIB") */
 229   int   len;           /* Length of this descriptor. */
 230   float longitude;     /* Radar longitude [deg]. */
 231   float latitude;      /* Radar latitude [deg]. */
 232   float altitude;      /* Radar pressure altitude (msl) [km]. */
 233   float height;        /* Radar above ground altitude (agl) [km]. */
 234   float ew_speed;      /* Platform ground speed (E (positive) or W) [m/s]. */
 235   float ns_speed;      /* Platform ground speed (N (positive) or S) [m/s]. */
 236   float v_speed;       /* Platform vertical velocity [m/s]. */
 237   float heading;       /* Platform heading [deg]. */
 238   float roll;          /* Platform roll    [deg]. */
 239   float pitch;         /* Platform pitch   [deg]. */
 240   float drift;         /* Platform drift   [deg]. */
 241   float rotation;      /* Platform rotation angle [deg]. */
 242   float tilt;          /* Platform tilt    [deg]. */
 243   float ew_wind_speed; /* Horizontal wind speed at radar (toward East positive) [m/s]. */
 244   float ns_wind_speed; /* Horizontal wind speed at radar (toward North positive) [m/s]. */
 245   float v_wind_speed;  /* Vertical wind speed at radar (up is positive) [m/s]. */
 246   float heading_rate;  /* Heading change rate [deg/sec]. */
 247   float pitch_rate;    /* Pitch change rate [deg/sec]. */
 248 } Platform_info;
 249
 250 typedef struct {
 251   char  code[4];   /* Code identifier. (4 ASCII "RDAT") */
 252   int   len;       /* Length of this descriptor. */
 253   char  name[8];   /* Name of parameter.  (See name in  'parameter descriptor'). */
 254   char *data;      /* Length as described in Parameter_desc. */
 255 } Parameter_data;
 256
 257 /* Higher level objects */
 258 typedef struct {
 259   Radar_desc              *radar_desc;
 260   int                      nparam;
 261   Parameter_desc         **p_desc;     /* 0..nparam-1 */
 262   Cell_range_vector       *cell_range_vector;
 263   Correction_factor_desc  *correction_factor_desc;
 264 } Sensor_desc;
 265
 266 typedef struct {
 267   Ray_info        *ray_info;
 268   Platform_info   *platform_info;
 269   int             nparam;
 270   int            *data_len;        /* 0..nparam-1
 271                                     * Length of *parameter_data[i] in bytes.
 272                                     * This is length of data portion.
 273                                     */
 274   int            *word_size;       /* 0..nparam-1
 275                                     * Size of each word in *parameter_data[i].
 276                                     */
 277   Parameter_data **parameter_data; /* 0..nparam-1 */
 278 } Data_ray;
 279
 280 typedef struct {
 281   Sweep_info *s_info;
 282   int        nrays;
 283   Data_ray  **data_ray; /* 0..nrays-1 */
 284 } Sweep_record;
 285
 286 /* PROTOTYPES */
 287 Comment_block *dorade_read_comment_block(FILE *in);
 288
 289 Volume_desc    *dorade_read_volume_desc    (FILE *in);
 290
 291 /* Sensor descriptor routines. */
 292 Radar_desc     *dorade_read_radar_desc     (FILE *in);
 293 Parameter_desc *dorade_read_parameter_desc (FILE *in);
 294 Cell_range_vector      *dorade_read_cell_range_vector     (FILE *in);
 295 Correction_factor_desc *dorade_read_correction_factor_desc(FILE *in);
 296 Sensor_desc            *dorade_read_sensor (FILE *in);
 297
 298 Sweep_info *dorade_read_sweep_info(FILE *in);
 299 Sweep_record *dorade_read_sweep(FILE *fp, Sensor_desc **sd);
 300
 301 /* Data Ray routines. */
 302
 303 Ray_info       *dorade_read_ray_info      (FILE *in);
 304 Platform_info  *dorade_read_platform_info (FILE *in);
 305 Parameter_data *dorade_read_parameter_data(FILE *in);
 306 Data_ray       *dorade_read_ray           (FILE *in);
 307
 308 /* Memory management routines. */
 309 void dorade_free_sweep(Sweep_record *s);
 310 void dorade_free_data_ray(Data_ray *r);
 311
 312 /* Print routines. */
 313 void dorade_print_sweep_info(Sweep_info *d);
 314 void dorade_print_ray_info(Ray_info *d);
 315 void dorade_print_platform_info(Platform_info *d);
 316 void dorade_print_correction_factor_desc(Correction_factor_desc *d);
 317 void dorade_print_cell_range_vector(Cell_range_vector *d);
 318 void dorade_print_parameter_desc(Parameter_desc *d);
 319 void dorade_print_radar_desc(Radar_desc *d);
 320 void dorade_print_volume_desc(Volume_desc *d);
 321 void dorade_print_comment_block(Comment_block *cb);
 322 void dorade_print_sensor(Sensor_desc *s);
 323
 324 #endif