Users Guide to RSL.

What is RSL good for?

Below, is a table listing the input/output routines supplied in RSL. You will notice that there are only two output routines. RSL, by design, is not a format converter, but, a library to facilitate reading and manipulation of RADAR data. Output for UF and HDF are supplied because of the popularity of those two formats.
 

Data format	Input routine	Output routine
HDF 1B-51 and 1C-51	RSL_hdf_to_radar	RSL_radar_to_hdf
Lassen (Darwin)	RSL_lassen_to_radar	None
WSR-88d (Nexrad)	RSL_wsr88d_to_radar	None
UF (Universal Format from NCAR)	RSL_uf_to_radar	RSL_radar_to_uf
SIGMET (Version 1)	RSL_nsig_to_radar	None
SIGMET (Version 2)	RSL_nsig2_to_radar	None
McGill	RSL_mcgill_to_radar	None
TOGA	RSL_toga_to_radar	None
RAPIC (Berrimah)	RSL_rapic_to_radar	None
RADTEC (SPANDAR)	RSL_radtec_to_radar	None
EDGE	RSL_edge_to_radar	None

RSL is designed to provide you with a uniform data structure so that you can design RADAR independent science applications. You no longer need to wrestle over the input data format and have a different version of your algorithm for each different RADAR format you may need to analyze.

This paper presents RSL from a science application developer's point of view. It will present some of the more useful routines and which fields in the Radar structure that will be important to you and it will attempt to cover some of the programming pitfalls associated with RSL usage. One of the most difficult hurdles to overcome is that RSL makes extensive use of pointer syntax. You will find yourself becoming expert with C pointers. However, the design of RSL makes it possible to use C pointers painlessly.

Ok, I have some data, how do I look at it?

RSL_anyformat_to_radar
RSL_load_refl_color_table
RSL_volume_to_gif

The C program you need is incredibly short. It illustrates how to ingest radar data and create a GIF image of the DZ (reflectivity) field:

#include "rsl.h"
void main(int argc, char **argv)
{
  Radar *radar;
  radar = RSL_anyformat_to_radar("radar.dat", NULL);
  RSL_load_refl_color_table();
  RSL_volume_to_gif(radar->v[DZ_INDEX], "dz_sweep", 400, 400, 200.0);
}

#include "rsl.h"

is required when using the RSL. It defines important constants and declares all the RSL functions that your application may need.

The line:

Radar *radar;

The line:

radar = RSL_anyformat_to_radar("radar.dat", NULL);

Note: RSL_anyformat_to_radar can't handle every radar format for which there is an RSL ingest routine. But, it does a good job at recognizing most formats. Currently, TOGA and MCGILL files cannot be automatically detected. In those cases, use: RSL_toga_to_radar and RSL_mcgill_to_radar.

While basic image generation is provided in RSL, it is never intended to be anything more than a diagnostic tool. Several assumptions are made, but, the image generation functions provided are useful. This is what the last two lines illustrate. First you must define a color table. That is done with:

RSL_load_refl_color_table();

RSL_volume_to_gif(radar->v[DZ_INDEX], "dz_sweep", 400, 400, 200.0);

Making images of velocity data, VR_INDEX, involves two more steps that are not very obvious. Because of the limited range of the values presented in velocity data, you must re-bin the data. Do that with any one of the following:

RSL_rebin_velocity_sweep,
RSL_rebin_velocity_volume

RSL_load_vel_color_table();

Whoopty doo, I really wanted to examine the values.

The Radar structure

• Radar header.
• Array of pointers to Volumes.

Radar *radar;
radar->h.member;

if (radar->v[XZ_INDEX]) /* XZ exists */

There are basically two methods for indexing the array of pointers to Volumes:

• Use the index name, eg. CZ_INDEX or its value.
• Use a variable that ranges from 0 to radar->h.nvolumes-1.

Example 1:

Radar *radar;
Volume *volume;

volume = radar->v[CZ_INDEX];
if (volume != NULL) {
   /* Do something with volume. */
}

Radar *radar;
Volume *volume;
int i;

for (i=0; i<radar->h.nvolumes) {
   volume = radar->v[i];
   if (volume == NULL) continue; /* skip this NULL volume */
   /* Do something with volume. */
}

radar->v[DZ_INDEX]
radar->v[VR_INDEX]

Each field type encountered has a specific index within the radar->v array of pointers to Volumes. The field type indexes are hard-coded and are defined to be specific numbers starting at 0. Hard-coded field type indexes simplifies the syntax for accessing volumes. When there is no volume for a particular field type, the volume pointer is NULL. This is ok, as NULL is a perfectly acceptable, albeit useless, volume. Here is a table of all the field type indexes used in RSL.
 

INDEX NAME	Value	Description
DZ_INDEX	0	Reflectivity (dBZ)
VR_INDEX	1	Radial Velocity (m/s)
SW_INDEX	2	Spectral Width (m2/s2)
CZ_INDEX	3	QC Reflectivity (dBZ)
ZT_INDEX	4	Total Reflectivity (dBZ)
DR_INDEX	5	Differential reflectivity
LR_INDEX	6	Another differential refl.
ZD_INDEX	7	Reflectivity Depolarization Ratio  ZDR = 10log(ZH/ZV) (dB)
DM_INDEX	8	Received power (dBm)
RH_INDEX	9	Rho: Correlation coefficient
PH_INDEX	10	Phi (MCTEX parameter)
XZ_INDEX	11	X-band reflectivity
CR_INDEX	12	Corrected DR reflectivity (differential).
MZ_INDEX	13	DZ mask volume for HDF 1C-51 product.
MR_INDEX	14	DR mask volume for HDF 1C-51 product.
ZE_INDEX	15	Edited reflectivity.
VE_INDEX	16	Edited velocity.
KD_INDEX	17	KDP (unknown) for MCTEX data.
TI_INDEX	18	TIME (unknown) for MCTEX data.

The Volume structure

The organization of the Volume structure closely resembles the organization of the Radar structure. It, too, is compose of two parts:

• Volume header.
• Array of pointers to Sweeps.

Volume *volume;
volume->h.member;

There are two methods to accessing sweeps:

• Use a loop index that ranges from 0 to volume->h.nsweeps-1.
• Use RSL_get_sweep or other similiar RSL sweep retieval functions.

Example 1:

Volume *volume;
Sweep *sweep;
int i;

/* Assume a non-NULL volume at this point. */
for (i=0; i<volume->h.nsweeps; i++) {
   sweep = volume->sweep[i];
   if (sweep == NULL) continue; /* Skip NULL sweeps. */
   /* Do something with this sweep. */
   printf("Sweep %d elevation is %f\n", i, sweep->h.elev);
}

Volume *volume;
Sweep *sweep;
float elev;

/* No assumption about volume, it *can* be NULL! */
/* That's because RSL_get_sweep checks it. */
elev = 2.0;
sweep = RSL_get_sweep(volume, elev);
if (sweep != NULL)
   printf("Sweep %d elevation is %f\n", i, sweep->h.elev);

The Sweep structure

• Sweep header.
• Array of pointers to Rays.

Sweep *sweep;
sweep->h.member;

There are two methods to accessing rays:

• Use a loop index that ranges from 0 to sweep->h.nrays-1.
• Use RSL_get_ray or other similiar RSL ray retieval functions.

Example 1:

Sweep *sweep;
Ray *ray;
int i;

/* Assume a non-NULL sweep at this point. */
for (i=0; i<sweep->h.nrays; i++) {
   ray = sweep->ray[i];
   if (ray == NULL) continue; /* Skip NULL rays. */
   /* Do something with this ray. */
   printf("Ray %d azimuth is %f\n", i, ray->h.azimuth);
}

Volume *volume;
Ray *ray;
float elev, azimuth;

/* No assumption about volume, it *can* be NULL! */
/* That's because RSL_get_ray checks it. */
elev = 2.0;
azimuth = 30.2;
ray = RSL_get_ray(volume, elev, azimuth);
if (ray != NULL)
   printf("Ray %d elevation is %f, azimuth is %f\n", i, ray->h.elev, ray->h.azimuth);

The Ray structure

• Ray header.
• Array of field type measurements. These are not pointers. It is an array of values.

Ray *ray;
ray->h.member;

There are two methods to accessing the data:

• Use a loop index that ranges from 0 to ray->h.nbins-1 calling the ray->h.f function.
• Use RSL_get_value or other similiar RSL get value functions.

Example 1:

Ray *ray;
int i;
float x;

/* Assume a non-NULL ray at this point. */
for (i=0; i<ray->h.nbins; i++) {
   x = ray->h.f(ray->range[i]);
   /* Do something with this floating point value 'x'. */
   printf("BIN %d value is %f\n", i, x);
}

Volume *volume;
float x;
float elev, azimuth, range;

/* No assumption about volume, it *can* be NULL! */
/* That's because RSL_get_value checks it. */
elev = 2.0;
azimuth = 30.2;
range = 87.3; /* KM */
x = RSL_get_value(volume, elev, azimuth, range);

No assumptions as to the validity of the data.

Pitfalls when using RSL in an application.

1. Not checking for NULL. It is very important to check for NULL pointers. In the RSL context, NULL is a perfectly valid ray, sweep or volume. Blindly assuming that a volume, sweep, or ray exists is asking for trouble. When using an RSL interface routine, a routine that is prefixed with RSL_, you don't have to worry too much about passing null pointers. RSL routines check their arguments.
2. Not checking for NULL, when passing a volume, sweep, or ray pointer into a routine. Check for NULL immediately.
3. Not using the value for radar->h.nvolumes, volume->h.nsweeps, sweep->h.nray. They represent the maximum index possible and not the actual number of non-NULL structures. Remember a NULL sweep, in RSL, is a valid sweep; you just can't do anything with it. If you want to know how many non-NULL volumes you have, you'll have to count them yourself. Do that by looping from 0 to radar->h.nvolumes - 1.
4. Not using the value for radar->h.nvolumes, volume->h.nsweeps, sweep->h.nrays, and ray->h.nbins for the current object. Never assume that the values are constant throughout the radar structure. They constantly change. For instance, the number of bins may decrease as the sweep elevation increases.
5. Not converting the data in the Radar, Volume, Sweep, Ray, (really the Ray) to floating point before comparing with anything, including comparing it with BADVAL, RFVAL, APFLAG, NOECHO. Do this conversion with the h.f(c), where c is ray->range[i] and is of type Range. For example:

 

 

x = ray->h.f(ray->range[ibin]);

6. Not converting a floating point number to internal storage with h.invf(x), where x is of type float, before filling the range array. For example:

 

 

ray->range[ibin] = ray->h.invf(x);

7. Forgetting to load a color table before calling an image generation function. If you don't load a color table, your images will be black.
8. Not rebinning the velocity data before making velocity images. The default color table is setup to cover the range of -nyquist to +nyquist.