Tips for Improved Handling of JPSS VIIRS Imagery in AWIPS

v1.2, August 10, 2023

Introduction

Since July 12, 2023, AWIPS has been receiving Visible Infrared Imaging Radiometer Suite (VIIRS) imagery from NOAA-21, the newest satellite in the Joint Polar Satellite System (JPSS). Full configurations for NOAA-21 VIIRS imagery will be included in the next TOWR-S RPM bundle (v24), available in Oct. 2023.

But AWIPS users need not wait until then. Here are some configuration changes that AWIPS sites can apply right away to improve the handling of VIIRS imagery from NOAA-21 (and other JPSS satellites). These steps assume your site has TOWR-S RPM v23 installed (released Feb 2023).

1. Update CAVE menu entries for VIIRS Imagery

NOAA-21 VIIRS imagery in AWIPS uses the same WMO headers as S-NPP VIIRS imagery: so AWIPS has no way to tell them apart. Thus, any menu entry for S-NPP VIIRS imagery will in fact display VIIRS imagery from both S-NPP and NOAA-21. To avoid any confusion in the menu entries, first open a CAVE session and go to the Localization Perspective and select CAVE->Menus->npp. Then copy nppMenuItems.xml to a site localization. Edit the menuText of this file to read JPSS Polar (S-NPP, NOAA-20, NOAA-21) as shown here:

<?xml version="1.0" encoding="ISO-8859-1" standalone="no"?>

<!--

This_software_was_developed_and_/_or_modified_by_Raytheon_Company, pursuant_to_Contract_DG133W-05-CQ-1067_with_the_US_Government.

U.S._EXPORT_CONTROLLED_TECHNICAL_DATA This_software_product_contains_export-restricted_data_whose export/transfer/disclosure_is_restricted_by_U.S._law._Dissemination to_non-U.S._persons_whether_in_the_United_States_or_abroad_requires an_export_license_or_other_authorization.

Contractor_Name:________Raytheon_Company

Contractor_Address:_____6825_Pine_Street,_Suite_340

________________________Mail_Stop_B8

________________________Omaha,_NE_68106

________________________402.291.0100

See_the_AWIPS_II_Master_Rights_File_("Master_Rights_File.pdf")_for further_licensing_information.

-->

<!--

This is an absolute override file, indicating that a higher priority version of the file will completely replace a lower priority version of the file.

-->

<menuTemplate xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance">

<contribute xsi:type="subMenu" id="NPPProducts"

menuText="JPSS Polar (S-NPP, NOAA-20, NOAA-21)">

<contribute xsi:type="separator" id="Imagery"

visible="false" />

<contribute xsi:type="titleItem" id="SoundingsTitle"

titleText="------ Soundings ------" />

<contribute xsi:type="separator" id="Soundings"

visible="false" />

</contribute>

</menuTemplate>

Next, from the Localization perspective, select CAVE->Menus->npp->viirs and open the site version of viirsBundleItems_nccCombine.xml. Or, in a terminal from dv1, edit the file /awips2/edex/data/utility/cave_static/site/XYZ/menus/npp/viirs/viirs/viirsBundleItems_nccCombine.xml (where XYZ is your site identifier).

In this file, replace all 4 instances of the string

S-NPP and NOAA-20 NCC

with

VIIRS Day-Night Band NCC

Finally, from the Localization perspective, select CAVE->Menus->npp->viirs and open the site version of the file viirs/viirsMenuItems.xml. Or, in a terminal from dv1, edit the file /awips2/edex/data/utility/cave_static/site/XYZ/menus/npp/viirs/viirs/viirsMenuItems.xml (where XYZ is your site identifier).

In this file, on or near line 52, replace the string

S-NPP and NOAA-20 NCC

with

VIIRS Day-Night Band NCC

Optionally, starting on or near line 57 of this file, use <!-- and --> brackets to comment out any unwanted menu items (<contribute> elements) specific to S-NPP or NOAA-20. This will simplify the menu structure.

After editing these files, restart CAVE to see the new menu entries. They should resemble the following. (This example retains entries for S-NPP/NOAA-21 Alaska and NOAA-20 Alaska.)

 

2. Remove overlaps between satellite swaths displayed in CAVE

By default, CAVE shows VIIRS imagery granules in a fairly long time interval. This produces displays where swaths from NOAA-20, NOAA-21, and S-NPP overlap quite a bit, as seen below.

For a cleaner, non-overlapping display of these swaths, from the Localization perspective, select CAVE->bundles->npp->viirs and open the site version of viirsDayNightBandImagery.xml. Or, in a terminal from dv1, edit the file /awips2/edex/data/utility/cave_static/site/XYZ/bundles/npp/viirs/viirsDayNightBandImagery.xml (where XYZ is your site identifier).

In this file, on or near line 39, change

${groupTimeRange;15}

to

${groupTimeRange;0}

Then restart CAVE. This should produce views like the following:

 

3. Avoid granule geolocation errors

Due to a bug in the AWIPS Java code, EDEX geolocates a few VIIRS granules each day (from any of the JPSS satellites) a half- or quarter- orbit away from where they should be –e.g., granules showing Puerto Rico display over Australia, or vice-versa.

Until this bug gets fixed, AWIPS sites can avoid most of these geolocation errors by configuring their incoming SBN feed to receive VIIRS imagery for only one of (a) Alaska, (b) CONUS + Puerto Rico, or (c) Pacific. To do this, sites with operational AWIPS systems should follow steps A - E below. (For developmental/standalone systems, see the steps farther below, “Stand-Alone / Developmental AWIPS Systems.”)

Operational AWIPS Systems

A.     Edit the dv1 pqact.conf.xyz (where xyz is your three-letter site-id, lower case). The entries/updates are listed below.

Edit pqact.conf.xyz on dv1 and add ONE of the following entries (for desired geographic region), replacing <TAB> with literal keyboard TABs (a template in VLab w/these entries is included at this link):

sudo -u ldm vi /usr/local/ldm/etc/pqact.conf.xyz

where xyz is your lower-case site ID (permissions will be retained as ldm:fxalpha).

Add one of:

#New NPP/VIIRS data Alaska

NOTHER <TAB> ^(TIP[AB]..) (KNES) (..)(..)(..)

<TAB> FILE <TAB> -overwrite -log -close -edex

/data_store/sat/(\3:yyyy)(\3:mm)\3/\(4)/VIIRS/\1_\2_\3\4\5_(seq).%Y%m%d%H

or

#New NPP/VIIRS data CONUS + Puerto Rico

NOTHER <TAB> ^(TIP[CDPQ]..) (KNES) (..)(..)(..)

<TAB> FILE <TAB> -overwrite -log -close -edex

/data_store/sat/(\3:yyyy)(\3:mm)\3/\(4)/VIIRS/\1_\2_\3\4\5_(seq).%Y%m%d%H

or

#New NPP/VIIRS data Pacific

NOTHER <TAB> ^(TIP[HI]..) (KNES) (..)(..)(..)

<TAB> FILE <TAB> -overwrite -log -close -edex /data_store/sat/(\3:yyyy)(\3:mm)\3/\(4)/VIIRS/\1_\2_\3\4\5_(seq).%Y%m%d%H

B.     On dv1, check the syntax of the pqact.conf.xyz:

sudo -u ldm chmod 644 /usr/local/ldm/etc/pqact.conf.xyz

sudo scp /usr/local/ldm/etc/pqact.conf.xyz cpv1:/usr/local/ldm/etc

Even though the “config_awips2.sh ldm XYZ” localization checks the syntax of the pqact.conf.xyz before it pushes it to the CPs, it is recommended to run the “ldmadmin pqactcheck -p etc/pqact.conf.xyz” (as shown below) to verify the file/s are correct after any edits, first. Unfortunately, the “ldmadmin” tool is not installed on dv1, so you must log in to the CP to do this and run it on a local copy of pqact.conf.xyz, there.

Now go back over to cpv1:

cd /usr/local/ldm

sudo -i -u ldm /usr/local/ldm/bin/ldmadmin pqactcheck -p etc/pqact.conf.xyz

C.     On dv1, update pqact.conf.exclude to exclude entries that have been modified/updated in the pqact.conf.xyz (above).

The entry to exclude should be exactly as it appears in the dv1 file: /usr/local/ldm/etc/pqact.conf.base.conus (this file is also mirrored on the cpv1 in cpv1:/usr/local/ldm/etc/pqact.conf.base.conus). It is pictured here:

This entry will be updated in cpv1 pqact.conf by the expressions added above in Step A, in the dv1:/usr/local/ldm/etc/pqact.conf.xyz, and we therefore configure this base entry to be excluded in this step.

Update your pqact.conf.exclude file on dv1:

Entries for the pqact.conf.exclude are in this template file in VLab. w/proper spacing/tabs included (please make sure your template file does not have a blank space at the top as an earlier Vlab template contained).

sudo -u ldm vi /usr/local/ldm/etc/pqact.conf.exclude

Add the following; remember it must have the exact spacing and tabs as found in the pqact.conf.base.conus template as described above

#New NPP/VIIRS

NOTHER <TAB> ^(TIP...) (KNES) (..)(..)(..)

<TAB> FILE <TAB> -overwrite -log -close -edex

/data_store/sat/(\3:yyyy)(\3:mm)\3/\(4)/VIIRS/\1_\2_\3\4\5_(seq).%Y%m%d%H

D.     On dv1, run the LDM task to create the pqact.conf (where it will reside on cpv1 in /usr/local/ldm/etc/ upon completion).

This AWIPS LDM localization script is config_awips2.sh on dv1:

sudo /data/fxa/sdc/config_awips2.sh ldm XYZ

(where XYZ is your site in all capital letters)

LDM will be restarted in this step.

E.     Log into cpv1 and inspect /usr/local/ldm/etc/pqact.conf and pqact.conf.priority

a.  Check that the TIP entry you made in Step A appears in the cpv1 pqact.conf and that there are no duplicates:

b.  In cpv1:/usr/local/ldm/etc/pqact.conf.priority, make sure the following pattern (pictured below) are NOT present. Search for the pattern TIP. You should not have any of these patterns in the file for NPP/VIIRS data, specifically:

If the above pattern does still appear in your pqact.conf.priority, this indicates the contents of the dv1:/usr/local/ldm/etc/pqact.conf.exclude were not matched against the base template when config_awips2.sh was run. Refer back to Step C above. If that is the case, ensure your dv1:/usr/local/ldm/etc/pqact.conf.exclude does not have an empty line at the top of the template. Ensure there are empty lines between new pqact entries in the exclude file (w/the exception of the top line). It’s important that the expression pictured above is not in cpv1:/usr/local/ldm/etc/pqact.conf.priority because it will be read when LDM runs along with contents of pqact.conf, and could result in duplicate ingest of VIIRS granules.

Stop Here. Update is complete

Henceforth AWIPS EDEX should correctly geolocate all new VIIRS granules for the CONUS, Puerto Rico, and Alaska regions, and most granules for the Pacific region. (A few Pacific-region granules will continue to be displaced – from the northern Pacific to the southern Pacific, or vice-versa.)

 

Stand-Alone / Developmental AWIPS Systems only:

First save /usr/local/ldm/etc/pqact.conf as /usr/local/ldm/etc/pqact.conf.orig, then edit /usr/local/ldm/etc/pqact.conf. On or near line 665, replace the first period (".") character (immediately after "TIP"),

NOTHER<TAB>^(TIP...) (KNES) (..)(..)(..)

with one of the following region-specific patterns:

NOTHER<TAB>^(TIP[AB]..) (KNES) (..)(..)(..)           (for Alaska)

NOTHER<TAB>^(TIP[CDPQ]..) (KNES) (..)(..)(..)        (for CONUS + Puerto Rico)

NOTHER<TAB>^(TIP[HI]..) (KNES) (..)(..)(..)           (for Pacific)

(Be sure to keep the actual <TAB> character where indicated - do not replace it with space characters.)

Then restart LDM. Henceforth AWIPS EDEX should correctly geolocate all new VIIRS granules for the CONUS, Puerto Rico, and Alaska regions, and most granules for the Pacific region. (A few Pacific-region granules will continue to be displaced – from the northern Pacific to the southern Pacific, or vice-versa.)