# 1 "orb.c"
# 1 "<built-in>"
# 1 "<command line>"
# 1 "orb.c"
# 773 "orb.c"
=pod

=head1 NAME

orb.gex - GrADS Extension Library for Satellite Orbit Masking

=head1 SYNOPSIS

=head3 GrADS Commands:

=over 4

=item

run B<set_orb> I<PARAM> I<VALUE> - Set internal parameters

=item

run B<orb_track> I<SATELLITE> - Plot satellite orbits

=back

=head3 GrADS Function:

=over 4

=item

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

=back

=head1 DESCRIPTION

This library provides GrADS extensions (I<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 I<t>, satellite orbits can be simulated for the
interval from I<t-0.5> to I<t+0.5>. During this period the satellite
describe a ground track which can be plotted with the command
B<orb_track>. With function B<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.

=head1 EXAMPLES

=head2 Plotting orbits

=over 4

One can plot lines depicting the satellite ground track with the B<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

=back

=head2 Masking variables according to satelite orbits

=over 4

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 I<t>, the
satellite ground track is computed from I<t-0.5> to I<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.

=back

=head1 COMANDS PROVIDED

=head2 B<set_orb> I<PARAM> VALUE

=over 4

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

=over 8

=item B<set_orb> I<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.

=item B<set_orb> I<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 I<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

=item B<set_orb> I<IHALO> LEFT[,RIGHT]

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

=item B<set_orb> I<JHALO> BELOW[,ABOVE]

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

=item B<set_orb> I<HALO> LEFT[,RIGHT]

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

=back

=back


=head2 B<orb_track> I<SATELLITE>

=over 4

This command plots the ground track for a given satellite. For a
given GrADS time index I<t>, the satellite ground track is computed
from I<t-0.5> to I<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.

=over 8

=item I<SATELLITE>

Currently the following NASA EOS satellites are supported

=over 4

=item * Aqua

=item * Terra

=item * Aura

=item * Calipso

=item * CloudSat

=back

=back

=back


=head1 FUNCTIONS PROVIDED

=head2 B<orb_mask>(I<EXPR,SAT[,SWATH_WIDTH|SWATH_LEFT,SWATH_RIGHT[,dS]]>)

=over 4

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

=over 8

=item I<EXPR>

GrADS expressions to be masked

=item I<SAT>

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

=item I<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).

=item I<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).

=item I<dS>

Swath resolution, in kilometers. Default is 10 km.

=back

=back


=head1 SEE ALSO

=over 4

=item *

L<http:

=item *

L<http:
OpenGrADS Cookbooks

=item *

L<http:

=item *

L<http:

=back

=head1 AUTHORS

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


=head1 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.

=cut
