orb.gex - GrADS Extension Library for Satellite Orbit Masking

- NAME
- SYNOPSIS

- GrADS Commands:
- GrADS Function:

- DESCRIPTION
- EXAMPLES

- Plotting orbits
- Masking variables according to satelite orbits

- COMANDS PROVIDED

- set_orb PARAM VALUE
- orb_track SATELLITE

- FUNCTIONS PROVIDED

- orb_mask(EXPR,SAT[,SWATH_WIDTH|SWATH_LEFT,SWATH_RIGHT[,dS]])

- SEE ALSO
- AUTHORS
- COPYRIGHT

# NAME

orb.gex - GrADS Extension Library for Satellite Orbit Masking

# SYNOPSIS

### GrADS Commands:

  run set_orb PARAM VALUE - Set internal parameters

  run orb_track SATELLITE - Plot satellite orbits

### GrADS Function:

  display orb_mask(EXPR,SAT[,SWATH_WIDTH|SWATH_LEFT,SWATH_RIGHT[,dS]]) - Mask EXPR according to orbit

# DESCRIPTION

This library provides GrADS extensions (gex) for simulating satellite orbits and masking gridded variables according to these orbits. The calculation in this extension is meant to be a simulation of the satellite orbit and should not be used for forecasting real satellite overpasses. This calculation is not based on realtime Two-line Element (TLE) data.

GrADS datasets are given on a constant time interval. For a given GrADS time index t, satellite orbits can be simulated for the interval from t-0.5 to t+0.5. During this period the satellite describe a ground track which can be plotted with the command orb_track. With function orb_mask() one can mask gridded variables by setting to undefined those gridpoints which were not visited by the satellite, with the possibility of specifying the swath width and halo gridpoints.

When combined with a compression algorithm (such as in GRIB), satellite masked variables can use considerabily less storage space.

# EXAMPLES

## Plotting orbits

One can plot lines depicting the satellite ground track with the orb_track command:

     ga-> open model
     ga-> d ts
     ga-> orb_track aqua

Instead of lines, one can also use marks to plot the ground track,

     ga-> set_orb mark 6
     ga-> orb_track aqua

## Masking variables according to satelite orbits

This example shows how to set to undefined all grid points which have not been visited by the satellite. For a given GrADS time index t, the satellite ground track is computed from t-0.5 to t+0.5 and this simulated ground track is used to mask a variable:

     ga-> open model
     ga-> define xts = re(ts,0.5) # higher resolution version
     ga-> set gxout grfill

     ga-> d orb_mask(xts,aqua)

By default, the variable is masked according to the satellite ground track. However, it is also possible to specify the swath width (in km),

     ga-> d orb_mask(xts,aqua,300)

You can also specify a halo, that is, additional gridpoints around the mask:

     ga-> set_orb halo 2
     ga-> d orb_mask(xts,aqua)

Halos are useful for interpolating gridded values to observation locations.

# COMANDS PROVIDED

## set_orb PARAM VALUE

This command can be use to set several internal paramers, namely

set_orb DT TIMESTEP_IN_SECS

  Specify the timestep in seconds used to simulate the ground track. For example, a timestep of 60 seconds will cause of the (longitude,latitude) of the ground track to be computed every minute.

set_orb MARK MARK_TYPE

  Specify the the type of mark used to plot the ground track. By default, MARK_TYPE=-1, and straight lines are used to plot the ground track. Other possibles values for MARK_TYPE are:

        1 - plus sign
        2 - open circle (default)
        3 - closed circle
        4 - open square
        5 - closed square
        6 - multiplication sign
        7 - open diamond
        8 - open triangle
        9 - closed triangle
       10 - open circle with vertical bar
       11 - closed circle with vertical bar

set_orb IHALO LEFT[,RIGHT]

  Specify the number of zonal gridpoints to extend an orbital mask with. The parameter LEFT is the number of gridpoints west of the mask, while RIGHT is the number of gridpoints east of the mask. When RIGHT is missing it is set the same as LEFT.

set_orb JHALO BELOW[,ABOVE]

  Specify the number of meridional gridpoints to extend an orbital mask with. The parameter BELOW is the number of gridpoints south of the mask, while ABOVE is the number of gridpoints to the north of the mask. When ABOVE is missing it is set the same as BELOW.

set_orb HALO LEFT[,RIGHT]

  Specify the number of meridional and zonal gridpoints to extend an orbital mask with. The parameter LEFT is the number of gridpoints to the west/south of the mask, while RIGHT is the number of gridpoints to the east/north of the mask. When RIGHT is missing it is set the same as LEFT.

## orb_track SATELLITE

This command plots the ground track for a given satellite. For a given GrADS time index t, the satellite ground track is computed from t-0.5 to t+0.5. This ground track is meant to be a simulation of the satellite orbit and should not be used for forecasting real satellite overpasses. This calculation is not based on realtime Two-line Element (TLE) data.

SATELLITE

  Currently the following NASA EOS satellites are supported

- Aqua
- Terra
- Aura
- Calipso
- CloudSat

# FUNCTIONS PROVIDED

## orb_mask(EXPR,SAT[,SWATH_WIDTH|SWATH_LEFT,SWATH_RIGHT[,dS]])

This function masks out those grind points which have not been visited by the satellite from grads time index t-0.5 to time index t+0.5. On can optionally specify a swath width.

EXPR

  GrADS expressions to be masked

SAT

  Satellite name (Aqua, Terra, Aura, Calipso, CloudSat)

SWATH_WIDTH

  Width of the swath in kilometers, centered around the ground track. This gives SWATH_WIDTH/2 kilometers to the left/right of the ground track. Default is 0 (no swath).

SWATH_LEFT,SWATH_RIGHT

  Width of the swath in kilometers to the left and right of the satellite ground track. Default is 0 (no swath).

dS

  Swath resolution, in kilometers. Default is 10 km.

# SEE ALSO

- http://opengrads.org/ - OpenGrADS Home Page

- http://cookbooks.opengrads.org/index.php - OpenGrADS Cookbooks

- http://opengrads.org/wiki/index.php - OpenGrADS User Defined Extensions

- http://www.iges.org/grads/ - Official GrADS Home Page

# AUTHORS

Arlindo da Silva (dasilva@opengrads.org) and Arif Albayrak.

# COPYRIGHT

This extension has been placed in the public domain.

This is free software; see the source for copying conditions. There is NO warranty; not even for MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.

orb.gex - GrADS Extension Library for Satellite Orbit Masking