==========================================================================
                Help notes for modis_L0_to_L1A_GEO.csh
==========================================================================

Usage: modis_L0_to_L1A_GEO.csh MODIS_L0_PDS_file [OPTIONS]

Options: 

  -b                        Use base of input filename for output filenames
                            (without -b, output filenames are automatically determined)
  -o L1A_file               Output MODIS L1A HDF filename
  -g GEO_file               Output MODIS GEO HDF filename
  -n next_granule_filename  Next L0 granule (for geolocation of last scan; sets stopnudge=0)
  -a1 attitude_file1        Input attitude file 1 (chronological)
  -a2 attitude_file2        Input attitude file 2 (chronological)
  -e1 ephemeris_file1       Input ephemeris file 1 (chronological)
  -e2 ephemeris_file2       Input ephemeris file 2 (chronological)
  -disable-definitive       Disable use of definitive attitude/ephemeris
  -disable-definitive-ftp   Disable auto-downloading of definitive attitude/ephemeris
  -disable-predicted        Disable use of real-time attitude/ephemeris
  -disable-predicted-ftp    Disable auto-downloading of real-time attitude/ephemeris
  -disable-curl             Disable use of curl for ftp'ing predicted attitude/ephemeris lists
  -disable-utcpole_leapsec  Disable auto-downloading of utcpole.dat and leapsec.dat
  -verbose-ftp              Enable verbose auto-download messages
  -disable-fix_L0           Disable use of l0fix_modis utility for corrupt or wrong-sized packets
  -disable-dem              Disable terrain elevation correction
  -startnudge n             Level-0 start-time offset (seconds)
  -stopnudge n              Level-0 stop-time offset (seconds)
  -geocheck_threshold n     % of geo-populated pixels required to pass geocheck validation test
  -satellite aqua           Only required if filename is not a*, A*, MOD00.P*, or P1540064*
  -satellite terra          Only required if filename is not t*, T*, MOD00.A*, or P0420064*
  -save-log                 Save the Level 1A and geolocation processing log files

==========================================================================

The modis_L0_to_L1A_GEO.csh wrapper script creates a MODIS formatted Aqua
or Terra Level 1A and Geolocation file from a Production Data Set (PDS)
formatted MODIS Level 0 file. Unless the "-satellite" option is specified,
the input filename must match one of the following patterns in order for
the platform to be determined:

  -Aqua L0 filenames: a*, A*, MOD00.P*, P1540064*
  -Terra L0 filenames: t*, T*, MOD00.A*, or P0420064*

If no output filenames are specified, the filenames will be constructed
using the AYYYYDDDHHMMSS or TYYYYDDDHHMMSS prefix format reflecting the
calculated pass start time. In this case, the Level 1A and Geolocation
filenames will be given ".L1A_LAC" and ".GEO" suffixes respectively.
Default Level 1A and Geolocation file output directories can be optionally
defined by setting the MODIS_L1A and MODIS_GEO environment variables.

In order to successfully create a Geolocation file from a Level 1A file,
corresponding attitude and ephemeris files are required (unless the Terra
embedded Onboard (TONS) real-time attitude/ephemeris is being used). These
files can be created locally with the GBAD processor, or can be manually
downloaded, though it is recommended to simply allow MODISL1DB to
automatically fetch the required files via its built-in wget program.
To learn how to manually retrieve these files, please consult the SeaDAS
Ancillary Data Info page:

http://oceancolor.gsfc.nasa.gov/seadas/doc/toplevel/anc_info.html#ATTEPH

If neither the -disable-definitive nor -disable-predicted options are set
when running modis_L0_to_L1A_GEO.csh, MODISL1DB will first attempt to use
definitive data, and will then fall back on real-time data if definitive
isn't available.

NOTE: Two MODIS ancillary data files utcpole.dat and leapsec.dat reside in
the $SEADAS/var/modis/ directory and must be kept up-to-date. Though
this script will automatically download them if they're over 14 days old,
it is still suggested that they be updated on a weekly basis by running
the modis_update_utcpole_leapsec.csh script as a cron job. To quantify the
errors caused by not updating these files (called "latency") Peter
Noerdlinger has prepared an excellent document:

http://newsroom.gsfc.nasa.gov/sdptoolkit/latency.html

The utcpole.dat and leapsec.dat files are available here:

ftp://oceans.gsfc.nasa.gov/COMMON/utcpole.dat
ftp://oceans.gsfc.nasa.gov/COMMON/leapsec.dat

==========================================================================

======================================
Explanation of command line arguments:
======================================

MODIS_L0_PDS_file (required)
Input MODIS Aqua/Terra L0 file for generating the L1A and GEO file.

-b (optional)
Use the base of the input L0 filename (up to first ".") for naming the
output filenames. This allows for filename bases to now be kept identical
through the processing chain instead of the seconds potentially changing.

-o L1A_file (optional)
Output filename for the MODIS L1A HDF file.

-g GEO_file (optional)
Output filename for the MODIS GEO HDF file.

-n next_granule_filename (optional)
Next L0 granule filename. This option allows geolocation of the input
L0 file's last scanline, and automatically sets stopnudge to 0.

-a1 attitude_file1 (optional)
Input attitude file 1 (chronologically before attitude_file2)

-a2 attitude_file2 (optional)
Input attitude file 2 (chronologically after attitude_file1)

-e1 ephemeris_file1 (optional)
Input ephemeris file 1 (chronologically before ephemeris_file2)

-e2 ephemeris_file2 (optional)
Input ephemeris file 2 (chronologically after ephemeris_file1)

-disable-definitive (optional)
Disable use of definitive attitude/ephemeris to generate the geolocation
file. If both definitive and real-time attitude/ephemeris options are
enabled, MODISL1DB will first attempt to use definitive, and then
fall back on real-time.

-disable-definitive-ftp (optional)
Disable automatic downloading of the required definitive files.

-disable-predicted (optional)
Disable use of real-time attitude/ephemeris to generate the geolocation
file. If both definitive and real-time attitude/ephemeris options are
enabled, MODISL1DB will first attempt to use definitive, and then
fallback on real-time.

-disable-predicted-ftp (optional)
Disable automatic downloading of the required real-time files. This option
applies only to Aqua, as Terra's non-definitive attitude/ephemeris is
embedded in the L0 data file.

-disable-curl (optional)
Disable use of the curl ftp client used in the predicted attitude/ephemeris
download process. curl requires fewer connections to the ftp server and so
is recommended as a firewall may limit the number of connections per IP.
Though used by default, if curl doesn't exist in the user's path, the
script will fall back to wget.

-disable-utcpole_leapsec (optional)
Disable automatic downloading of the utcpole.dat and leapsec.dat files if
they're not found on the user's local hard disk or if they're more than 14
days old.

-verbose-ftp (optional)
Enable verbose wget output messages from attempted attitude/ephemeris
downloads.

-disable-fix_L0 (optional)
Disable automatic use of the l0fix_modis utility if a corrupt or wrong-
sized Level 0 packet is detected by the l0cnst_write_modis binary, while
attempting to generate the constructor file. If this option is used and
such an error is detected, processing will stop. Otherwise, an attempt will
be made to create a new Level 0 file with the problem packet(s) removed,
and if successful processing will proceed.

-disable-dem (optional)
Disable terrain elevation correction (including processing over land and
lakes.) If terrain elevation correction is enabled and no MODIS DEM files
exist in $SDSDATA/modis/dem/, terrain elevation correction will be
automatically disabled and processing will continue. (MODIS DEM files are
available in the seadas_dem_modis.tar.gz distribution file.)

-startnudge n (optional) (default=10)
Specifies the Level-0 start-time offset (seconds). This is the number of
seconds of data to remove from the beginning of the L0 file to avoid
geolocation problems due to unavailable leading packets. Partial scan
lines will not be retained.

-stopnudge n (optional) (default=10)
Specifies the Level-0 stop-time offset (seconds). This is the number of
seconds of data to remove from the end of the L0 file to avoid geolocation
problems due to unavailable trailing packets. Partial scan will not be
retained.

-geocheck_threshold n (optional) (default=95)
Specifies the percent of geo-populated pixels required to pass the
geocheck validation test. The geocheck validation test calculates the
percentage of pixels that were not successfully geolocated, and if this
percentage is less than geocheck_threshold, the processing will assume
failure and will not delete temporary processing and log files.

-satellite aqua/terra (may be required)
Only required if filename does not match one of the patterns specified
above for determination of the platform.

-save-log (optional)
Saves the Level 1A and geolocation processing LogStatus files. (All logs
are deleted by default if processing completes without a fatal error.)

==========================================================================