Snow Cover Science

Processing Algorithm
(SNOWCOV_SPA)
User's Guide

Version 1.5.08.04

August 2014

GODDARD SPACE FLIGHT CENTER

GREENBELT, MARYLAND
 Snow Cover Science Processing Algorithm
SNOWCOV_SPA
General
The NASA Goddard Space Flight Center’s (GSFC) Direct Readout Laboratory (DRL), Code
606.3 developed this software for the International Polar Orbiter Processing Package
(IPOPP). IPOPP maximizes the utility of Earth science data for making real-time decisions
by giving fast access to instrument data and derivative products from the Suomi National
Polar-orbiting Partnership (SNPP), Aqua, and Terra missions and, in the future, the Joint
Polar Satellite System (JPSS) mission.

Users must agree to all terms and conditions in the Software Usage Agreement on the DRL
Web Portal before downloading this software.

Software and documentation published on the DRL Web Portal may occasionally be
updated or modified. The most current versions of DRL software are available at the DRL
Web Portal:

http://directreadout.sci.gsfc.nasa.gov/?id=software

Questions relating to the contents or status of this software and its documentation should be
addressed to the DRL via the Contact DRL mechanism at the DRL Web Portal:

http://directreadout.sci.gsfc.nasa.gov/?id=dspContent&cid=66

Algorithm Wrapper Concept

The DRL has developed an algorithm wrapper to provide a common command and
execution interface to encapsulate multi-discipline, multi-mission science processing
algorithms. The wrapper also provides a structured, standardized technique for packaging
new or updated algorithms with minimal effort.

A Science Processing Algorithm (SPA) is defined as a wrapper and its contained algorithm.
SPAs will function in a standalone, cross-platform environment to serve the needs of the
broad Direct Readout community. Detailed information about SPAs and other DRL
technologies is available at the DRL Web Portal.

Software Description
This software package contains the Visible Infrared Imaging Radiometer Suite (VIIRS) Snow
Cover Science Processing Algorithm (SNOWCOV_SPA). The Snow Cover algorithm takes
as input the VIIRS I1, I2, I3, I5, M15, and M16 band Sensor Data Record (SDR) products;
the VIIRS M-Band Terrain-Corrected Geolocation product; the VIIRS I-Band Terrain-
Corrected Geolocation product; the VIIRS Cloud Mask Intermediate Product (IP); and the
VIIRS Aerosol Optical Thickness IP and produces the mission-compliant Snow Binary Map
Environmental Data Record (EDR) and Snow Fraction EDR. The SPA functions in two
modes: Standalone, or as an IPOPP plug-in.

SNOWCOV_SPA Page 1 August 2014

Software Version
Version 1.3 of the DRL algorithm wrapper was used to package the SPA described in this
document. The SnowCov algorithm has been ported from the Interface Data Processing
Segment (IDPS) OPS Version 1.5.08.04.

Enhancements to this SPA include:

 algorithm updated to version 1.5.08.04;
 capability to process compressed and/or chunked HDF5 input files;
 updated Lookup Tables (LUTs).

This software will execute on a 64-bit computer, and has been tested with the following
operating systems:
a) Fedora 18 X86_64;
b) CentOS Linux 6.4 X86_64;
c) OpenSUSE Linux 12.1 X86_64;
d) Kubuntu 13.04 X86_64.

Credits
The SnowCov algorithm was provided to the DRL by the JPSS Mission. This algorithm was
ported to run outside of the IDPS by the DRL in collaboration with the Land Product
Evaluation and Algorithm Test Element (LPEATE).

Prerequisites
To run this package, you must have the Java Development Kit (JDK) or Java Runtime
Engine (JRE) (Java 1.6.0_25 or higher) installed on your computer, and have the Java
installation bin/ subdirectory in your PATH environment variable. This package contains 64-
bit binaries statically pre-compiled on an x86-compatible 64-bit computer running under
Fedora 14, using gcc 4.5.1.

Program Inputs and Outputs

The SPA uses the following inputs:
a) VIIRS I1, I2, I3, I5, M15, and M16 band SDR products;
b) VIIRS M-Band Terrain-Corrected Geolocation product;
c) VIIRS I-Band Terrain-Corrected Geolocation product;
d) VIIRS Cloud Mask IP;
e) VIIRS Aerosol Optical Thickness IP;

The SPA produces the mission-compliant Snow Binary Map EDR and Snow Fraction EDR
as outputs.

SNOWCOV_SPA Page 2 August 2014

Installation and Configuration

Installing as a Standalone Application:

Download the SNOWCOV_1.5.08.04_SPA_1.3.tar.gz and
SNOWCOV_1.5.08.04_SPA_1.3_testdata.tar.gz (optional) files into the same directory.

Decompress and un-archive the SNOWCOV_1.5.08.04_SPA_1.3.tar.gz and

SNOWCOV_1.5.08.04_SPA_1.3_testdata.tar.gz (optional) files:

$ tar -xzf SNOWCOV_1.5.08.04_SPA_1.3.tar.gz

$ tar -xzf SNOWCOV_1.5.08.04_SPA_1.3_testdata.tar.gz

This will create the following subdirectories:

SPA
SnowCov
algorithm
ancillary
station
testdata
testscripts
wrapper

Installing into an IPOPP Framework: This SPA can also be installed dynamically into an
IPOPP framework to automate production of SNOWCOV_SPA data products. The SPA
installation process will install SPA station(s) into IPOPP. An SPA station is an IPOPP agent
that provides the mechanism necessary for running an SPA automatically within the IPOPP
framework. Once this SPA is installed, users must enable the station(s) corresponding to
this SPA along with any other pre-requisite station(s). Instructions for installing an SPA and
enabling its stations are contained in the IPOPP User’s Guide (available on the DRL Web
Portal). The SPA stations associated with this SPA are listed in Appendix A.

Software Package Testing and Validation

The testscripts subdirectory contains test scripts that can be used to verify that your current
installation of the SPA is working properly, as described below. Note that the optional
SNOWCOV_1.5.08.04_SPA_1.3_testdata.tar.gz file is required to execute these testing
procedures.

Step 1: cd into the testscripts directory.

Step 2: There is a script named run-SnowCov inside the testscripts directory.
To run the SnowCov algorithm, use

$./run-SnowCov

A successful execution usually requires about 1 minute, depending on the speed of your
computer. If everything is working properly, the scripts will terminate with a message such
as:

SNOWCOV_SPA Page 3 August 2014

Output viirs.vscd is /home/ipopp/drl/SPA/SnowCov/testdata/output/VSCDO_npp_d20130323_t1851552_e1853194.h5
Output viirs.vscm is /home/ipopp/drl/SPA/SnowCov/testdata/output/VSCMO_npp_d20130323_t1851552_e1853194.h5

You can cd to the output directory to verify that the science products exist. Test output
product(s) are available for comparison in the testdata/output directory. These test output
product(s) were generated on a 64-bit PC architecture computer running Fedora 14. The
output products serve as an indicator of expected program output. Use a comparison utility
(such as diff, h5diff, etc.) to compare your output product(s) to those provided in the
testdata/output directory. Locally generated files may differ slightly from the provided output
files because of differences in machine architecture or operating systems.

If there is a problem and the code terminates abnormally, the problem can be identified
using the log files. Log files are automatically generated within the directory used for
execution. They start with stdfile* and errfile*. Other log and intermediate files may be
generated automatically within the directory used for execution. They are useful for
traceability and debugging purposes. However it is strongly recommended that users clean
up log files and intermediate files left behind in the run directory before initiating a fresh
execution of the SPA. Intermediate files from a previous run may affect a successive run
and produce ambiguous results. Please report any errors that cannot be fixed to the DRL.

Program Operation
In order to run the package using your own input data, you can either use the run scripts
within the wrapper subdirectories, or modify the test scripts within the testscripts
subdirectory.

To Use the Run Scripts

Identify the 'run' scripts: The wrapper directory within this package contains one
subdirectory named SnowCov. The subdirectory contains an executable called 'run'.
Execute 'run' within the correct wrapper subdirectory to generate the corresponding product.
For instance, the 'run' within wrapper/SnowCov is used for creating Snow Cover outputs.
Note that to execute 'run', you need to have java on your path.

Specify input parameters using <label value> pairs: To execute the 'run' scripts, you
must supply the required input and output parameters. Input and output parameters are
usually file paths or other values (e.g., an automatic search flag). Each parameter is
specified on the command line by a <label value> pair. Labels are simply predefined names
for parameters. Each label must be followed by its actual value. Each process has its own
set of <label value> pairs that must be specified in order for it to execute. Some of these
pairs are optional, meaning the process would still be able to execute even if that parameter
is not supplied. The two types of <label value> pairs that the SNOWCOV_SPA uses are:
a) Input file label/values. These are input file paths. Values are absolute or relative
paths to the corresponding input file.
b) Output file label/values. These are output files that are produced by the SPA. Values
are absolute or relative paths of the files you want to generate.

SNOWCOV_SPA Page 4 August 2014

The following tables contain labels, and their descriptions, required by the
SNOWCOV_SPA.

Input File Labels Description Data Source

viiirs.gmtco VIIRS M-Band terrain corrected 1. The C-SDR_SPA and VIIRS-SDR

Geolocation input HDF5 file path SPAs can be used to create these
VIIRS SDR products.
viirs.gitco VIIRS I-Band terrain corrected
2. Real time VIIRS SDR products over the
Geolocation input HDF5 file path eastern US region are available from
the DRL ftp site at:
viirs.svi01 VIIRS Imagery Resolution Band I1 ftp://is.sci.gsfc.nasa.gov/gsfcdata/npp/vi
input HDF5 file path irs/level1/<SVxxx|GxxxO>
_npp_dyyyymmdd_thhmmssS_ehhmm
viirs.svi02 VIIRS Imagery Resolution Band I2 ssS*.h5
input HDF5 file path Where yyyy, mm, dd represents the
year, month, and date for the start of
the swath; the first hh, mm, ss, S
viirs.svi03 VIIRS Imagery Resolution Band I3
represents the hour, minutes, seconds,
input HDF5 file path and 10th of a second for the start of the
swath and the second hh, mm, ss, S
viirs.svi05 VIIRS Imagery Resolution Band I5 represents the end time of the swath.
input HDF5 file path
3. VIIRS SDR products for other locations
viirs.svm15 VIIRS Moderate Resolution Band and times are available for download at
M15 input HDF5 file path www.class.noaa.gov

viirs.svm16 VIIRS Moderate Resolution Band

M16 input HDF5 file path

viirs.aotip VIIRS Aerosol Optical Thickness 1. The Aerosol_SPA can be used to

(AOT) IP input HDF5 file path create this product.

2. Real time AOT IP products over the

eastern US region are available from
the DRL ftp site at:
ftp://is.sci.gsfc.nasa.gov/gsfcdata/npp/vi
irs/level2/IVAOT
_npp_dyyyymmdd_thhmmssS_ehhmm
ssS*.h5
Where yyyy, mm, dd represents the
year, month, and date for the start of
the swath; the first hh, mm, ss, S
represents the hour, minutes, seconds,
and 10th of a second for the start of the
swath and the second hh, mm, ss, S
represents the end time of the swath.

viirs.cmip VIIRS Cloud Mask IP input HDF5 1. The Cloudmask_SPA can be used to
file path create this product.

2. Real time Cloud Mask IP products over

the eastern US region are available
from the DRL ftp site at:
ftp://is.sci.gsfc.nasa.gov/gsfcdata/npp/vi
irs/level2/IICMO
_npp_dyyyymmdd_thhmmssS_ehhmm
ssS*.h5

SNOWCOV_SPA Page 5 August 2014

Input File Labels Description Data Source

Where yyyy, mm, dd represents the

year, month, and date for the start of
the swath; the first hh, mm, ss, S
represents the hour, minutes, seconds,
and 10th of a second for the start of the
swath and the second hh, mm, ss, S
represents the end time of the swath.

3. CloudMask IP products for other

locations and times are available for
download at www.class.noaa.gov

Output File Labels Description Destination (when SPA is installed in IPOPP)

viirs.vscm VIIRS Snow Binary Map EDR /raid/pub/gsfcdata/npp/viirs/level2/VSCMO_npp_

output HDF5 file path dyyyymmdd_thhmmssS_ehhmmssS*.hdf

viirs.vscd VIIRS Snow Fraction EDR /raid/pub/gsfcdata/npp/viirs/level2/VSCDO_npp_

output HDF5 file path dyyyymmdd_thhmmssS_ehhmmssS*.hdf

Execute the 'run': The following script shows an example of command line to run the
SnowCov algorithm from the testscripts directory:
$ ../wrapper/SnowCov/run \
viirs.gmtco \
../testdata/input/GMTCO_npp_d20130323_t1851552_e1853194_b07270_c20130329144438416689_noaa_ops.h5 \
viirs.gitco \
../testdata/input/GITCO_npp_d20130323_t1851552_e1853194_b07270_c20130329144559539969_noaa_ops.h5 \
viirs.svi01 \
../testdata/input/SVI01_npp_d20130323_t1851552_e1853194_b07270_c20130329144457901126_noaa_ops.h5 \
viirs.svi02 \
../testdata/input/SVI02_npp_d20130323_t1851552_e1853194_b07270_c20130329144508343727_noaa_ops.h5 \
viirs.svi03 \
../testdata/input/SVI03_npp_d20130323_t1851552_e1853194_b07270_c20130329144453693755_noaa_ops.h5 \
viirs.svi05 \
../testdata/input/SVI05_npp_d20130323_t1851552_e1853194_b07270_c20130329144537193540_noaa_ops.h5 \
viirs.svm15 \
../testdata/input/SVM15_npp_d20130323_t1851552_e1853194_b07270_c20130329144411111248_noaa_ops.h5 \
viirs.svm16 \
../testdata/input/SVM16_npp_d20130323_t1851552_e1853194_b07270_c20130329144517993558_noaa_ops.h5 \
viirs.cmip \
../testdata/input/IICMO_npp_d20130323_t1851552_e1853194_b07270_c20130618184731407557_noaa_ops.h5 \
viirs.aotip ../testdata/input/IVAOT_npp_d20130323_t1851552_e1853194.h5 \
viirs.vscd ../testdata/output/VSCDO_npp_d20130323_t1851552_e1853194.h5 \
viirs.vscm ../testdata/output/VSCMO_npp_d20130323_t1851552_e1853194.h5

A successful execution usually requires about 1 minute per VIIRS granule (1 granule = 48
scans), depending on the speed of your computer. If execution fails, you will see an error
message indicating the cause of failure (e.g., a file cannot be found, or a label cannot be
recognized). Correct it and run again. If the problem has some other cause, it can be
identified using the log files. Log files are automatically generated within the directory used
for execution. They start with stdfile* and errfile* and can be deleted after execution. Other
log and intermediate files may be generated automatically within the directory used for
execution. They are useful for traceability and debugging purposes. However it is strongly

SNOWCOV_SPA Page 6 August 2014

recommended that users clean up log files and intermediate files left behind in the run
directory before initiating a fresh execution of the SPA. Intermediate files from a previous
run may affect a successive run and produce ambiguous results. The 'run' can be executed
from any directory the user chooses. This can be done by prefixing it with the file path for
the 'run' script.

NOTES:
1. The data products generated by this SPA may be visualized with the DRL's
H2G_SPA (Hierarchical Data Format [HDF] to Georeferenced Tagged Image File
Format [GeoTIFF] Converter Science Processing Algorithm). H2G is designed
specifically for Direct Readout applications to create geolocated GeoTIFF images,
jpeg browse images, and png browse images for parameter datasets in SNPP
products and EOS products. H2G_SPA and its User Guide are available for
download from the DRL web-portal. Please refer to Appendix A for information on
enabling image production for this SPA in IPOPP.

To Use the Scripts in the testscripts Directory

One simple way to run the algorithms from the directory of your choice using your own data
is to copy the run-SnowCov.sh script from the testscripts directory to the selected directory.
Change the values of the variables like WRAPPERHOME, INPUTHOME and
OUTPUTHOME to reflect the file paths of the wrapper directories and the input/output file
paths. Then modify the input/output file name variables. Run the script to process your
data.

SNOWCOV_SPA Page 7 August 2014

 Appendix A
SPA Stations
Installation of this SPA in IPOPP mode will make the SPA stations listed in Table A-1
available to IPOPP. These stations along with any other pre-requisite stations (listed in
Table A-2) will need to be enabled to allow IPOPP to automate production of the VIIRS
Snow Cover data products. Further, users who wish to generate image products from the
data products generated by this SPA will need to enable the image-generating stations
listed in Table A-3. The SPAs containing the pre-requisite and the image-generating
stations listed in Tables A-2 and A-3 can be downloaded from the DRL Web Portal, in case
they are not already available in your IPOPP installation. Details about these other SPAs are
available in the respective SPA User’s Guides. Please refer to the IPOPP User’s Guide for
instructions on how to install an SPA in IPOPP and enable the corresponding stations.

Table A-1. SPA Stations

SPA stations for this SPA Data Products produced

SnowCov VIIRS Snow Binary Map EDR (Daytime only
product)
VIIRS Snow Fraction EDR (Daytime only
product)

Table A-2. Pre-requisite Stations

Pre-requisite SPA stations SPA in which they are available

VIIRS-SDR or VIIRS_C-SDR VIIRS-SDR_SPA or C-SDR_SPA
CloudMask Cloudmask_SPA
Aerosol Aerosol_SPA

NOTE: The stations VIIRS-SDR and VIIRS_C-SDR must never be run simultaneously.

Table A-3. Image-generating Stations

Image-generating stations SPA in which they are available

vsnowh5-geotiff H2G_SPA
NOTE: Please refer to the H2G_SPA User’s Guide for more details about the image
products, including their locations and filename patterns when they are generated in IPOPP.

SNOWCOV_SPA Page A-1 August 2014