VIIRS Active Fires Science

Processing Algorithm
(VIIRS-AF_SPA)
User's Guide

Version 1.3.6

December 2018

GODDARD SPACE FLIGHT CENTER

GREENBELT, MARYLAND
 VIIRS Active Fires Science Processing Algorithm
VIIRS-AF_SPA
General
The NASA Goddard Space Flight Center’s (GSFC) Direct Readout Laboratory (DRL), Code
619.1, developed this software for the International Planetary Observation 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 NOAA-
20 [Joint Polar Satellite System (JPSS)], Suomi National Polar-orbiting Partnership (SNPP),
Aqua, and Terra missions.

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:

https://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:

https://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)
Active Fires Science Processing Algorithm (VIIRS-AF_SPA). The SPA supports both the
SNPP and NOAA-20 (JPSS-1) missions; it can process VIIRS inputs from either spacecraft.
This algorithm primarily uses brightness temperatures derived from bands M13 and M15 to
detect fires. VIIRS bands M5, M7, M11, and M16 are used to reject false alarms and to
mask clouds. The algorithm takes as input VIIRS Science Data Record (SDR) files, along
with the associated geolocation file, and identifies active fires. The outputs are a two-
dimensional fire mask in Hierarchical Data Format (HDF) and a firelocation text file. The
SPA functions in two modes: Standalone, or as an IPOPP plug-in.

VIIRS-AF_SPA Page 1 December 2018

Software Version
Version 1.7 of the DRL algorithm wrapper was used to package the SPA described in this
document. The SPA uses version 1.3.6 of the VIIRS-AF algorithm.

Enhancements to this SPA include support for NOAA-20 (JPSS-1) VIIRS data processing.
The NOAA-20 algorithm is an Engineering Version.

This software will execute on a 64-bit computer. This software has been tested on a
computer with 32GB of RAM and a CentOS Linux 7 X86_64 operating system.

Copyright 1999-2007, United States Government as represented by the Administrator for

the National Aeronautics and Space Administration. All Rights Reserved.

Credits
The VIIRS-AF algorithm was co-developed by the Land Science Team and the DRL at
NASA/GSFC, under the guidance of the International Land Direct Readout Coordinating
Committee (ILDRCC).

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. Also, the VIIRS-AF_SPA requires at least 2 GB of memory to
run successfully, although more is recommended for improved performance.

Program Inputs and Outputs

See the Program Operation subsection.

Installation and Configuration

NOTE: Due to limited resources, as well as the many variables that impact scientific integrity
and algorithm stability, the DRL will soon no longer support the Standalone Mode for SPA
processing. We strongly encourage you now to run SPAs in IPOPP Mode exclusively, that
is, from within the IPOPP processing framework. IPOPP will autonomously:
 discover and register raw sensor data;
 retrieve ancillaries from the DRL’s real-time and archived ancillary repositories;
 register ancillaries in its Ancillary File Cache;
 schedule SPA executions;
 fulfill science data/ancillary requests from SPAs;
 generate science data products; and

VIIRS-AF_SPA Page 2 December 2018

  manage the IPOPP file system.

Installing into an IPOPP Framework: This SPA can also be installed dynamically into an
IPOPP framework to automate production of VIIRS Active Fires Level2 HDF file and VIIRS
Fire Location text file products. The SPA installation process will install SPA service(s) into
IPOPP. An SPA service 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 service(s) corresponding to this SPA along with any other
prerequisite service(s). Instructions for installing an SPA and enabling its services are
contained in the IPOPP User’s Guide (available on the DRL Web Portal).The SPA services
associated with this SPA are listed in Appendix A.

Installing as a Standalone Application:

NOTE: If you have a previous version of this SPA installed, delete the SPA/VIIRS-AF
directory before decompressing and un-archiving the new SPA tar file.

Download the VIIRS-AF_1.3.6_SPA_1.7.tar.gz and VIIRS-

AF_1.3.6_SPA_1.7_testdata.tar.gz (optional) files into the same directory.

Decompress and un-archive VIIRS-AF_1.3.6_SPA_1.7.tar.gz and VIIRS-

AF_1.3.6_SPA_1.7_testdata.tar.gz (optional) files:

$ tar -xzf VIIRS-AF_1.3.6_SPA_1.7.tar.gz

$ tar -xzf VIIRS-AF_1.3.6_SPA_1.7_testdata.tar.gz

This will create the following subdirectories:

SPA
VIIRS-AF
algorithm
ancillary
station
testdata
testscripts
wrapper

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 VIIRS-
AF_1.3.6_SPA_1.7_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-vaf.sh inside the testscripts directory.

To run the VIIRS-AF algorithm, use

VIIRS-AF_SPA Page 3 December 2018

 $ ./run-vaf.sh

A successful execution usually requires approximately one minute or more, depending on

the speed of your computer. If everything is working properly, the scripts will terminate with
a message such as:

Output viirs.ActiveFires is /home/ipopp/drl/SPA/VIIRS-AF/testdata/output/NPP_VIIRS-AF.hdf

Output viirs.FireLoc is /home/ipopp/drl/SPA/VIIRS-AF/testdata/output/FireLoc.txt

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, hdiff, 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 VIIRS-AF. 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/VIIRS-AF is used for creating VIIRS-AF 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 VIIRS-AF_SPA uses are:

VIIRS-AF_SPA Page 4 December 2018

 a) Input file labels/values. These are input file paths. Values are absolute or relative
paths to the corresponding input file.
b) Output file labels/values. These are output files that are produced by the SPA. Values
are absolute or relative paths of the files you want to generate.

The following tables contain labels, and their descriptions, required by the VIIRS-AF_SPA.

Input File Labels Description Source

viirs.gmtco VIIRS MOD Terrain-Corrected

1. The C-SDR_SPA can be used to create
Geolocation input HDF file path
these products.
viirs.svm05 VIIRS 750m M5 band SDR input 2. Real time products over the eastern US
HDF file path region are available from the DRL ftp site
at:
viirs.svm07 VIIRS 750m M7 band SDR input
SNPP:
HDF file path
ftp://is.sci.gsfc.nasa.gov/gsfcdata/npp/viirs/l
viirs.svm11 VIIRS 750m M11 band SDR input evel1/<GMTCO|SVMxx>_npp
HDF file path _dyyyyMMdd_thhmmssS_ehhmmssS*.h5

viirs.svm13 VIIRS 750m M13 band SDR input NOAA-20:

HDF file path ftp://is.sci.gsfc.nasa.gov/gsfcdata/jpss1/viir
s/level1/<GMTCO|SVMxx>_j01
viirs.svm15 VIIRS 750m M15 band SDR input _dyyyyMMdd_thhmmssS_ehhmmssS*.h5
HDF file path

viirs.svm16 VIIRS 750m M16 band SDR input Where yyyy, MM, dd represents the year,
HDF file path month, and day of month 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. (xx = 05, 07, 11, 13, 15,
16)
3. Products for other locations and times are
available for download at
www.class.noaa.gov

Output File Labels Description Output Format Description

viirs.ActiveFires VIIRS Active Fires Level2 HDF See Notes below

file path (VAF)

viirs.FireLoc VIIRS Fire Location text file path

Execute the 'run': The following is an example of the command line to run the VIIRS-AF
algorithm from the testscripts directory:

VIIRS-AF_SPA Page 5 December 2018

$ ../wrapper/VIIRS-AF/run \
viirs.gmtco ../testdata/input/GMTCO_npp_d20140901_t1738560_e1740201_b14746_c20140908200702642321_noaa_ops.h5 \
viirs.svm05 ../testdata/input/SVM05_npp_d20140901_t1738560_e1740201_b14746_c20140908200735223402_noaa_ops.h5 \
viirs.svm07 ../testdata/input/SVM07_npp_d20140901_t1738560_e1740201_b14746_c20140908200729256422_noaa_ops.h5 \
viirs.svm11 ../testdata/input/SVM11_npp_d20140901_t1738560_e1740201_b14746_c20140908200858348915_noaa_ops.h5 \
viirs.svm13 ../testdata/input/SVM13_npp_d20140901_t1738560_e1740201_b14746_c20140908200931364181_noaa_ops.h5 \
viirs.svm15 ../testdata/input/SVM15_npp_d20140901_t1738560_e1740201_b14746_c20140908200911898965_noaa_ops.h5 \
viirs.svm16 ../testdata/input/SVM16_npp_d20140901_t1738560_e1740201_b14746_c20140908200729274370_noaa_ops.h5 \
viirs.ActiveFires ../testdata/output/NPP_VIIRS-AF.hdf \
viirs.FireLoc ../testdata/output/FireLoc.txt

A successful execution usually requires approximately one minute or more, depending on

the speed of your computer and the size of the input. 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
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 Fire Location text file contains information about each fire pixel detected by the
SPA. Each line represents one fire pixel and has the following seven columns,
separated by commas:
o Column 1: Fire Pixel Latitude
o Column 2: Fire Pixel Longitude
o Column 3: M13 Brightness Temperature
o Column 4: Along scan pixel dimension (km)
o Column 5: Along track pixel dimension (km)
o Column 6: Fire Detection Confidence (0-100)
o Column 7: Fire Radiative Power (FRP)
Please note that the Fire Location text file is not generated if no fire pixels are
detected for the datasets processed. When running in standalone mode, the VIIRS-
AF_SPA will terminate with a message similar to the following when no Fire Location
text file is generated:
Output viirs.ActiveFires is /home/ipopp/drl/SPA/VIIRS-AF/testdata/output/NPP_VIIRS-AF.hdf
Output viirs.FireLoc is null
2. The data products generated by this SPA may be visualized with the DRL's

VIIRS-AF_SPA Page 6 December 2018

 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,
NOAA-20 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-vaf.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.

VIIRS-AF_SPA Page 7 December 2018

 Appendix A
SPA Services

Installation of this SPA in IPOPP mode will make the SPA services listed in Table A-1
available to IPOPP. These services along with any other prerequisite services (listed in
Table A-2) will need to be enabled to allow IPOPP to automate production of the VIIRS-
AF_SPA data products. Furthermore, users who wish to generate image products from the
data products generated by this SPA will need to enable the image-generating services
listed in Table A-3. The SPAs containing the prerequisite and the image-generating services
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 services.

Table A-1. SPA Services

Services for this Data Products Produced

SPA
VIIRS-AF1
Product Name Destination
(when installed in IPOPP)
VIIRS Active Fires Level2 HDF File $HOME/drl/data/pub/gsfcdata/<missio
ndir>/viirs/level2/VAF_ppp_dyyyyMMd
d_thhmmssS_ehhmmssS*.h52
VIIRS Fire Location Text File $HOME/drl/data/pub/gsfcdata/<missio
ndir>/viirs/level2/FireLoc_ppp_dyyyyM
Mdd_thhmmssS_ehhmmssS*.txt2
1
The SPA service(s) for SNPP processing is available on the “SNPP-VIIRS” tab of the
IPOPP dashboard, while the corresponding SPA service for NOAA-20 processing is
available on the “JPSS-1-VIIRS” tab.
2
Where yyyy, MM, dd represents the year, month and day of month for 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. . ‘ppp’
is the spacecraft field and is either ‘npp’ for SNPP or ‘j01’ for NOAA-20. <missiondir> is the
mission specific directory. It is ‘npp’ for SNPP and ‘jpss1’ for NOAA-20.

VIIRS-AF_SPA Page A-1 December 2018

 Table A-2. Prerequisite SPA Services

Prerequisite SPA Services SPA in which they are available

VIIRS_C-SDR C-SDR_SPA

Table A-3. Image-generating SPA Services

Image-generating SPA Services SPA in which they are available

viirsaf-geotiff H2G_SPA
vcviirsfire-geotiff H2G_SPA

NOTES:
1. 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.
2. The vcviirsfire-geotiff service additionally needs CVIIRS_SPA to be installed and the
“CVIIRS” SPA service enabled in IPOPP in order to run. CVIIRS_SPA is available for
download from the DRL Web Portal in case it is not already available in your IPOPP
installation.

3. The SPA service(s) for SNPP processing is available on the “SNPP-VIIRS” tab of the
IPOPP dashboard, while the corresponding SPA service for NOAA-20 processing is
available on the “JPSS-1-VIIRS” tab.

VIIRS-AF_SPA Page A-2 December 2018