Table of Contents

1 INTRODUCTION
History of GloVis
Installation Guide Caveat
Installation First Steps

1
1
2
3

2 HARDWARE REQUIREMENTS
Java Applet
Web Pages
Ingest
Overview

4
4
4
5
5

3 OBTAINING THE GLOVIS SOURCE CODE

GloVis Distribution Website
Registration for Download Access
Downloading the Source Code Package

6
6
6
6

4 PREPARING FOR INSTALLATION

Application and Data Overview
Decompressing the Source Code Package
Web Server Notes
Defining Environment Variables
Environment Variables for Advanced Installs
Linking in Your Data Inventories
Creating the State Locator Map
cont

7
7
8
8
9
10
11
12

ii

Table of Contents: Sec 4-6 of 11 (cont)

4 PREPARING FOR INSTALLATION (cont)
Processing Data Orders
Trimming the Sensor Menu
About Default Linework
Additional Modifications/Notes
Minimum Java Version
5 BUILDING AND INSTALLATION
Build the Installation Directory Tree
Building and Installing the Application
Building for Using GloVis Data Files
Building for Processing Your Data Files
Install Validation

Downloading GloVis Browse Image Data

Downloading Default NDVI Data
Downloading Default Linework
System-Specific Notes
Solaris

External Tools
Applet Tools
Ingest Processing Tools
Map Layer Tools

6 WRAPPING THINGS UP
Viewing Your StateView Website
Feedback of Code Changes/Bug Reporting

13
14
14
15
16
17
17
18
18
18
18
19
20
21
21
21
22
22
23
23
24
24
24

iii

Table of Contents: Sec 7-11 of 11 (cont)

7 UPGRADE INSTALLS
Upgrading the Code
Building and Installing for an Upgrade
Releasing an Upgrade Installation

25
25
26
27

8 DOCUMENTATION AND SUPPORT

System Information
Programming Information
General Satellite Data Information
Example StateView Websites

28
28
28
28
29

9 DISCLAIMER

29

10 ACRONYMS

30

11 APPENDIX
A. Signing Your Java Applet
B. Address Search

32
33
35

iv

1. Introduction
History of GloVis
The Global Visualization Viewer (GloVis) application was originally conceptualized and prototyped
at the USGS National Center for EROS in response to a need to strive beyond the typical
metadata query capabilities of GLIS or EarthExplorer; to provide the additional infrastructure of a
visual remote sensed data search and order client. This client would be driven by visual queries,
versus the traditional metadata-driven searches of previous search and order tools. GloVis was
prototyped with Landsat 7 ETM+ data initially and was received positively by the USGS
AmericaView program customer. The USGS requirements were documented at that point and the
prototype began to take shape. The next two releases focused on code cleanup, and the GloVis
project was brought to official status.
Landsat 7 ETM+ data has become just the tip of the iceberg; many more remotely sensed data
collections have been added as the application has transitioned from prototype to official
development. Through the joint efforts of AmericaView and the NASA Distributed Active Archive
Center (DAAC), access to the ASTER Level-2 VNIR browse dataset was added next. As the
notoriety of the application increased, the tool was quickly adopted by users as a reliable search
and order interface, and is now widely used. Excitement surrounding the ability to quickly locate
and view browse imagery and easily select interesting scenes for ordering has led to requests for
many additional remote sensed datasets to be added to the tool. The ASTER Level-2 VNIR
browse were later replaced with Level-1B VNIR browse, and GloVis now contains those datasets
as well as ASTER TIR; Landsat 7 ETM+ SLC-off; Landsat 4-5 TM; Landsat 1-3 and 4-5 MSS;
Landsat Orthorectified ETM+, Pansharpened ETM+, TM and MSS; MRLC 2001 Terrain Corrected,
and 2001 Reflectance Adjusted collections; Earth Observing-1 (EO-1) ALI and Hyperion data;
NAPP and NHAP aerial photography; MODIS grid datasets; and the list of datasets keeps
growing.

The most recent addition is Landsat 8, released in 2013. Landsat 8 continues more than 40 years
of coverage of the earths land surfaces.

Introduction: History of GloVis (cont)

Since its inception, GloVis has expanded from a small user base to now providing scientists,
cooperators, researchers, and external public parties with a quick and easy method to select and
order various flavors of remotely sensed data. AmericaView, NASA, and USGS requirements have
been combined in a software package that allows access to a variety of collections of remotely
sensed browse imagery through quick and reliable access to state satellite imagery holdings. A
large number of external users have now downloaded and adapted the source code for a variety of
uses beyond these original intentions. The tool is, quite simply, a unique advancement for the
remote sensing community and has become, for countless users, an indispensable method of
acquiring and/or distributing remotely sensed data.

Installation Guide Caveat

Even though this guide specifically discusses using the GloVis source code to build a StateView
website for AmericaView member states, it is generally applicable to an install of the source code
to accomplish other data distribution projects as well. It is left to the user to apply this document to
their specific situation.

Introduction (cont)

Installation First Steps

It is suggested you familiarize yourself with the GloVis application before you begin the process of
adapting and building it for a StateView website. Browse the datasets available, submit test orders,
and familiarize yourself with the applications features with the current GloVis application online at
<http://glovis.usgs.gov/>. You may also wish to review the Quick Start Guide, which can be
accessed from the link on the GloVis homepage. This will not only allow you to ensure the
functionality of the application is in line with the data distribution system you are wishing to provide,
but will also assist in comprehension of this document.
Another thing you will want to do before beginning the process of creating a StateView website is
to begin collecting a list of your states satellite image data holdings you wish to distribute via your
StateView website application. Sometimes this is the most time consuming step, so get this
information collected as soon as possible to streamline the process so youll have your data ready
to link into the application when youre done building it. The information you will need about the
data in your states archive to pull the necessary files from the GloVis server is the instrument the
data was collected with, the path and row each scene is in, and the acquisition date of each scene,
though you may choose to store more details about the data for your own purposes. More
information about retrieving browse data from the GloVis server is given in Building and
Installation: Downloading GloVis Browse Image Data.

2. Hardware Requirements
GloVis is actually split into several parts: the java applet that presents the data to the user along
with the web pages associated with the applet, and the ingest code to convert the imagery into the
format required for the applet. Each of these parts have separate requirements, as will be
described next.

Java Applet
On the user's side, GloVis requires any web browser with support for Java 8 or higher but the
most recent version is strongly recommended. To get plug-ins or add-ons for your browsers,
sometimes called the Java Runtime Environment (JRE), go to <http://java.com/> and select the
Free Java Download link.
On the developer's side, GloVis requires the Java SE Development Kit (JDK), which is available
from Oracle at <http://java.com/>.

Web Pages
Requires a web server to serve up the pages. At EROS, we run Apache on a Linux server. The
web pages have a few features in them that depend on Apache functionality and configuration
options. But it would probably be relatively easy to eliminate those and run it on any web server.
The size of the server depends on how many simultaneous users you expect at once.
Enough disk space to hold your data.

Hardware Requirements (cont)

Ingest
The ingest software has only been run on Linux. But it should be fairly easy to adapt to nearly any
type of Unix without much (if any) work. However, you'd need to customize the ingest software for
your data.
Note that most states do not run the ingest code and instead download the processed browse
scenes associated with their data from the GloVis inventory. More information about this option is
available in Preparing for Installation: Application and Data Overview.

Overview
In general, many parts of the software build process assume it is running on some flavor of Unix.
Adapting it to work on a Windows box would require a lot of work. In a nutshell, the system
requirements for ingesting and serving web pages is any moderately sized PC running a version of
Linux. But it would take very little work to adapt it to some other flavor of Unix if you want.
A note about your network connection; if this is to be a publicly available web site, obviously the
better your connection the more your users will like it.

3. Obtaining the GloVis Source Code

GloVis Distribution Website
The GloVis application source code is government off-the-shelf (GOTS), which is public domain
and is made available for download on the GloVis website <http://glovis.usgs.gov/>; click on
Download Source Code in the blue navigation bar at the bottom of the page.

Registration for Download Access

Users are required to register for access to the download portion of the distribution site. Be
assured your personal information is not distributed in any form. It is helpful if users make an effort
to keep their profile information as up-to-date as possible. Each time you visit the site, please take
a moment to review your profile information and update it if necessary. Your registration information
is the same EarthExplorer registration you use for ordering and downloading imagery.

Downloading the Source Code Package

From the download page, click the Begin Download link to retrieve the source code archive file and
the supporting release notes and installation documentation.
Note that the installation document in the distribution source code is a very brief list of the steps
outlined in this Guide, and likely will not suffice for StateView installs, unless the install is being
done by an experienced computer programmer.

4. Preparing for Installation

Application and Data Overview
The GloVis application code consists of two major pieces data ingest to get the data processed
to the correct format and organized in a local inventory, and the java applet and web pages used to
view the data. Most states setting up a StateView website will only need to be concerned with
installing the Java applet. The ingest processing can be replaced by running a script to download
the processed data files from the GloVis inventory. More information about downloading the
browse scene data is provided in Building and Installation: Downloading GloVis Browse Image
Data.
The GloVis ingest process consists of retrieving a browse file for a scene from a server housing the
browse inventory, reprocessing the browse to the projection used by the GloVis display, and
creating the associated metadata and Table of Contents (TOC) files from the scenes metadata
retrieved from a database, which completes the data inventory. Once again, most states will not
need to process their own data in this manner, but if you do, the ingest process is closely coded to
the specifics of the systems at EROS that GloVis interfaces with and will likely require major
changes. This document will not go into the details of modifying the ingest code.
The Java applet is the web interface used to display the browse images representative of the data
in your inventory and allows the user to select and order the scenes they are interested in.
So, the basics of getting a StateView website up and running are: retrieve and decompress the
source code, build and install the Java applet, and download the browse images and metadata
files associated with each scene from the GloVis inventory for your state.

Preparing for Installation (cont)

Decompressing the Source Code Package

Once the source code archive file has been retrieved from the
distribution site to the desired system of installation, select a
location to decompress the source code.

Decompress the source code archive file with the following

command (replace 9_0 with the version you are installing):
> tar zxf source_with_doc_glovis_9_0.tar.gz
The code will be in a directory named similar to glovis_9_0
(depending to which version you are installing); well just use the
directory name of glovis in this document.

The source code is now ready for customizing for your specific installation.

Web Server Notes

The applications homepage uses Server-Side Includes (SSIs) to pull in some of the components
of the page from other files. You will either need to ensure your web server is configured to enable
SSIs or rework the pages (glovis/web/mainpage/*) to not use them.

Preparing for Installation (cont)

Defining Environment Variables

GloVis depends on a number of environment variables for building as well as for ingest processing.
It will be necessary for you to define some of these variables, depending on which portions of the
GloVis code you are utilizing. The definition of these variables is done in two shell scripts that are in
the glovis/env directory: glovis_env.[csh/sh] and glovis_config.[csh/sh]. Two versions of each script
is provided for the different shells users may be running. You will only need to keep and update the
scripts for the shell you are running.
The glovis_env script defines the variables that are used to build and install the software. Most of
the variables are based on the value of the GV_HOME variable. In fact, most users will need to
modify the definition of the GV_HOME and GV_INVENTORY variables only, since the remaining
variables are based on these.
When the glovis_env script is executed, GV_HOME can be set with an input value, provided as a
command line parameter; its value will default to $HOME/glovis_build if not specified, which you
may also wish to modify. GV_HOME should reflect where you wish to install the application; this
should point to a build location where the compiled pieces of the application will be installed,
under the web servers root html directory. Additional notes about command-line parameters to the
script are provided in the header block of the script. It is purely preference whether you
permanently modify the value of GV_HOME directly in the glovis_env script or whether you set it
via the command line parameter to the script each time you are building the code.

Preparing for Installation (cont)

Environment Variables for Advanced Installs

Most of the environment variables in the glovis_config script are not needed for external users,
unless you plan to ingest your own data, create custom linework files, or build any capabilities that
depend on the Java security model. If you plan to acquire the appropriate browse scenes,
metadata, TOC files, and linework directly from the GloVis inventory, then you do not need to
define the first block of environment variables in the glovis_config script.
The second block of variables are used to build features of the application that depend on Java
security features. If you do not create a Java security certificate and setup this block of
environment variables prior to building this portion of the code, the File menu will not be included in
your application. The File menu contains features to download browse image data directly from the
applet to the users computer and functionality to save/load your scene list. Users may also receive
Java security warnings or may be blocked from running the applet.
If you do plan to sign your applet, you must create a Java security certificate (using keytool) and
use the same parameters for your public key on the Java applet side (using jarsigner). A link to
learn more about these tools is provided in Documentation and Support: Programmer Information.
Weve also provided information on how we go about signing the applet in Appendix A. Signing
Your Java Applet. Signing your applet using a certificate from a recognized Certificate Authority will
also reduce the number of warnings users see when accessing your site.
If you determine you need to define any of the variables from the glovis_config file, the easiest
thing to do would be to add the needed variables to the glovis_env, assigning them appropriate
values according to the comment provided for each. Two separate scripts to define these variables
is not necessary for your purposes, so just combine the variable definitions into a single script. We
have two scripts to keep system-sensitive information out of the source code package we distribute
to the public.

10

Preparing for Installation (cont)

Linking in Your Data Inventories

The install procedure will create some symbolic links in the $(GV_HTML)/ImgViewer directory that
may need modifying. GloVis stores its image data on a different system disk than the application
code is installed on so the imagery is on a disk large enough. We then link the location of the
imagery and linework to the application with these symbolic links. Symbolic links for each sensor's
inventory directory and for the linework directory (more information about the linework is available
in Preparing for Installation: About Default Linework) will be created in $(GV_HTML)/ImgViewer
and will point to default locations. Review what these get set to after installation and modify if
necessary. To modify the symbolic links permanently, modify the glovis_env script to set
GV_INVENTORY to the directory that contains your browse data inventories. This will only work if
your inventories are structured similar to:
$(GV_INVENTORY)/l5
$(GV_INVENTORY)/l7
$)GV_INVENTORY)/linework
etc
You may also wish to not use symbolic links and have the data directories directly under
$(GV_HTML)/ImgViewer; this is a valid solution and in this case GV_INVENTORY should be
defined in the glovis_env script as $(GV_HTML)/ImgViewer. If you do not use symbolic links, you
also need to remove the creation of these links from the install target of
glovis/web/ImgViewer/Makefile. This means to remove the lines similar to this:
@if [ ! -L $(INST_DIR)/l7 -a ! -d $(INST_DIR)/l7 ] ; then \
ln -sf $(GV_INVENTORY)/l7 $(INST_DIR)/l7 ; fi

11

Preparing for Installation (cont)

Creating the State Locator Map

To replace the world map GloVis uses for the navigation locator map with your state map, you will
first need a state image that is in the geographic projection. This image can be any size; we
suggest it be around 180x150 pixels. It can be any image format supported by Java; GIF or JPEG
would be good choices. To update the applet to use your state map, follow these steps:
Put the state map image file in the glovis/web/ImgViewer/graphics directory
Warning: dont use an image with transparency, as this will cause problems with the
diamond locator icon displaying properly
Modify the glovis/web/ImgViewer/LocatorMapConfig.java file to specify the name of the state
image file to use for the locator map and define the images size and geo-location information

Set IMAGE_WIDTH and IMAGE_HEIGHT variables to the size of your state map image
Set the LEFT_LON, RIGHT_LON, TOP_LAT, BOTTOM_LAT variables to reflect the
geographic extents of the image (Note: for the US, the longitude values will be negative)
Set the MAP_IMAGE variable to the name of your image
Set the ENFORCE_GEOGRAPHIC_BUMPER variable to true to reflect the geographic
extents of the image.
If you want to overlay on your state image with boundaries (e.g. county boundaries), set
the BOUNDARY_IMAGE variable to the name of your boundary image file. This image
must be the same size as the map image and also must be in the geographic projection
and must be a transparent GIF to overlay the state map properly. Otherwise set
BOUNDARY_IMAGE= and USE_BOUNDARY_IMAGE to false
Update the Makefile in the glovis/web/ImgViewer directory

Add your image file name(s) to the appropriate macro in the file (e.g. under GIFS, JPGS,
or create a new one if necessary)

12

Preparing for Installation (cont)

Remove the WorldBoundariesBlack.gif image from the GIFS macro and World5Minute.jpg from
the JPGS macro since you will not need these images
For completeness, you may also remove the World5Minute.jpg and WorldBoundariesBlack.gif
images from the glovis/web/ImgViewer/graphics directory, since you will not use them

Processing Data Orders

Once a user of your StateView website is done selecting the imagery that is interesting to them
and they wish to obtain the original data files, the application needs to provide some method to get
that data to the user or to fulfill an order. GloVis handles orders by passing the user on to our
one of our ordering systems at EROS. We use a variable-encoded URL string that passes the
information about the scenes they are ordering to the order system. You may devise a similar
system, though you will more likely send the user to a webpage that lists links to the data files they
selected for manual download, or even send an email to a designated party that will fulfill the order
using another method.
There are a number of ways to fulfill a data order. Exactly how this is accomplished is left up to
each individual state. Refer to the Documentation and Support: Contact Personnel section for a
contact that can help you with the ordering procedure setup if you need. As a starting point, the
glovis/web/ImgViewer/Sensor.java file contains the routine that defines how to handle a data order.

13

Preparing for Installation (cont)

Trimming the Sensor Menu

You can easily remove sensors you dont have data for from the Sensor menu by modifying a
source code file to tell it not to add those sensors to the menu list.
Open the file glovis/web/ImgViewer/GloVis.Properties

Each of the variables represents one of the sensor menu items

Any parameter set to enabled (as is the default for all) will be added to the Collection menu
Any parameter set to view only will be added to the menu but the Send to Cart button at the
bottom of the Scene List will be absent
Any parameter set to hidden will not be shown in the Collection menu

About Default Linework

User-specified map layer displays are available in GloVis, including general layers available to all
datasets, like political boundaries; roads; water; U.S. cities; north arrow; and grid centers (WRS in
most cases). Layers specific to certain datasets may exist as well. The code within GloVis preprocesses these layers specifically for the projection we use for our map displays (Lambert
Azimuthal Equal Area for most datasets).

If you wish to use the linework files that are utilized by GloVis, you may download them from the
GloVis website by running a script distributed with the source code. This is explained further in
Building and Installation: Downloading Default Linework.
The default configuration distributed with the source code will not display linework upon starting the
GloVis application. Linework must be selectively turned on with application menus. To change the
initial display defaults:
Open the file glovis/web/ImgViewer/MapLayersConfig.java
Set each of the variables representing the linework map overlay items to either true or false to
have it appear (or not) upon starting the application.

14

Preparing for Installation (cont)

Additional Modifications/Notes
There a number of additional changes you will surely need to make to the overall look of the web
pages and applet to identify the application as your states StateView website. You may want to
initially build and install the default pages, then review them to identify where additional updates
are needed. Keep a list of all the files you modify in the code and additional files you add to the
codebase (new images, etc); this will be handy if you ever wish to upgrade to a new GloVis
version. Some suggested additional information that you will likely want to change includes:
Create a custom header banner, image map, and footer for the homepage
(glovis/web/mainpage/index.shtml or glovis/web/includes/headerinclude.html,
header_glovisb2.html, footer.shtml)
Customize the navigation bars on the homepage
Trim the sensor list on the homepage to only contain the data you are distributing
Various Makefiles may need review and updates for your replacement files
Modify glovis/web/ImgViewer/Sensor.java to reference your local archive
Modify glovis/web/ImgViewer/GloVis.Properties according to your installed datasets

15

Preparing for Installation (cont)

Minimum Java Version

Beginning with Release 8.0, among other changes, we updated the Java applet code to use Java
1.6 (also called Java 6). The website detects the users Java plug-in version and provides an error
message or redirects to a web page advising the user to update to the latest version of the Java
plug-in. The 8.15 release of GloVis started using the Deployment Toolkit script, deployJava.js, with
a minimum Java version of 1.6.0_10.
Beginning with Release 8.19.3, GloVis requires the end-user to have a Java 7 or higher plug-in or
add-on enabled in their browser.
Beginning with Release 9.4.2, GloVis requires the end-user to have a Java 8 or higher plug-in or
ad-on enabled in their browser.
Updating the Java plug-in notices may include updates in the following files in the
glovis/web/mainpage directory:
index.shtml
glovisImageViewer.js

16

5. Building and Installation

Building the Installation Directory Tree
Building and installation of the code depends on a location to be defined to install to and a certain
directory structure to exist there as well. The install will copy the built components of the application
to a released location, that you have defined with the GV_HOME environment variable. This will be
a location under the web servers root directory so it is viewable on the internet. Work with your
system administrator to establish appropriate permissions on that directory.
Now that we have identified the directory to install the application to, we must create the directory
structure the application will be built into. The script we will create this directory structure with is
glovis/env/make_directories.csh. You will want to modify this file slightly to remove creation of
directories that you will not need. This includes removing essentially the last half of the file that
makes the directories needed for the GloVis distribution website.
The process to make this directory tree depends on variables defined in the environment scripts,
so at this point well need to source those scripts to setup those variables.
Change directories into the glovis/env directory if you are not there already
Execute source glovis_env.csh to setup the environment variables (remember to provide an input
argument if you wish to override the default location for the GV_HOME variable)
Execute source make_directories.csh to build the installation directory tree structure
To review the directories created, execute ls $GV_HOME. You will see the next level of
directories that were created, as well as the $(GV_HOME) directory, and this will be where the
built application files get installed

17

Building and Installation (cont)

Building and Installing the Application

Building for Using GloVis Data Files:
Most StateView developers will retrieve each scenes preprocessed browse image data and
associated files from the GloVis inventory, rather than create these files themselves. When you are
not ingesting your own data, you only need to build certain portions of the GloVis code.
By using the following command when in the top-level directory of the source code, you will avoid
building those portions of the code that are only needed to process your own data. This command
will compile and install your code, using your predefined environment variables:
make website (errors should be analyzed and resolved before moving on to the next step)
Not building those unneeded portions of the code will not only reduce the total build time and the
disk used by your installed application, but will also prevent potential build errors that you might
spend time resolving that are not even applicable to the parts of the software you will be using.
Basically, building only the parts of the code you will actually be using is pretty smart!
Building for Processing Your Data Files:
If you do plan on processing your own source data to create the browse and ancillary files, execute
make from the command line in the root directory of your source code to compile the full GloVis
codebase. Errors should be analyzed and resolved before moving to the next step. Refer to the
Documentation and Support section for links to online information that may be helpful and a list of
contacts that may be able to help you work through errors encountered during the build process
that you were unable to resolve yourself. When the errors have been resolved from the previous
step, execute make install from the command line in the root glovis directory to install the code.
Install Validation:
You can verify the install worked properly by listing the directory contents of any subdirectory of
$(GV_HOME) and making sure there are files in the directory. If you need to make modifications to
the source code after youve executed the initial build and install, execute make clean in the root
glovis directory before you rebuild the code.

18

Building and Installation (cont)

Downloading GloVis Browse Image Data

When you have completed installation of the application, you will want to link browse scene data to
it so there is something to look at. A script is available in the source code package that will enable
a user to easily download all relevant browse data for the scenes for your state. The script is
located in the source code at glovis/coop_utils/download_usgs_scenes.pl. At this point, the script
supports retrieving the browse image data and associated files for Landsat 4/5 TM, Landsat 7
ETM+ (SLC-off and SLC-on), ASTER, MODIS, and Landsat Orthorectified. It would probably be
any easy procedure to expand the datasets retrieved by the script if you wish to retrieve browse for
additional GloVis datasets. Refer to the scripts header block for information on how to run it.
Since there may be a time when you want or need to re-pull the browse data for your scenes from
the GloVis server, you may wish to save the details of each scene you retrieve the browse for in a
text file that can be passed to the download script on input. An example scene list file is in the code
at glovis/coop_utils/ak_scenes.txt.
The data downloaded by the script will be retrieved to a directory structure organized by a grid
overlaid on the globe. For most datasets GloVis supports at this time, that grid is either the WRS-1
or WRS-2 grid. The directory structure is, thus, organized by path and row cells. For example, if we
are talking about the P30/R29 grid cell for Landsat 7 ETM+, this is referring to the location on the
earth covered by WRS-2 Path 30, Row 29, and the directory in the GloVis inventory would look like
$(GV_INVENTORY)/l7/p030/r029. Under this grid cell directory, a subdirectory will exist for each
year you download scenes from. So, the files associated with a Landsat 7 ETM+ scene in this grid
cell acquired in 2002 will be retrieved to $(GV_INVENTORY)/l7/p030/r029/y2002. Not all datasets
follow this exact directory structure format, but most are very close to this.
The download_usgs_scenes.pl script will retrieve the following files for each scene:

The (reduced resolution) browse image file (Level 0 for some datasets, Level 1 for others)
A <filename>.meta file that contains selected metadata for the scene
cont (next page)

19

Building and Installation: Downloading GloVis Browse Image Data (cont)

At least 2 reprojected browse image files one reprojected to the map projection used by the
applet at the original resolution and one or more reprojected to the map projection used by the
applet at differing resolutions for various views of the data in the applet
For each reprojected browse image the scene has, an associated <filename>.geoinfo file that
contains some general metadata about the scene as well as some specific information regarding
resolution and projection for the associated reprojected version of the browse image
You will also get a TOC file for each grid cell (e.g. from our previous example, a TOC file would
exist at $(GV_INVENTORY)/l7/p030/r029/TOC). The TOC file is basically a catalog of the scenes
in that grid cell. It contains information including the number of scenes in the cell, various metadata
that is used by the applet when the user is defining date limits and cloud cover percentages, etc.
The exact format of each datasets TOC files is fully described in the datasets inventory description
document in the glovis/documentation directory. Each time you use download_usgs_scenes.pl,
that script will add an entry to the appropriate TOC file for the new scene data you download.

Downloading Default NDVI data

Note: The modifications described below are to add the NDVI Graph feature to your GloVis
application. If you do not want a NDVI Graph option, you can stop reading this section now, as no
code modifications are necessary to omit this feature.
When you build and install the GloVis source code package, the install procedure will look at your
build directory tree for the NDVI data directory. If the data directory is found in the expected
location, a link will be added to the GloVis applications Tools menu to allow your users to access
the NDVI data. Otherwise, there will be no NDVI Graph option displayed in your GloVis application
(since it does not exist).

20

Building and Installation: Downloading NDVI Data (cont)

If you are interested in having the NDVI Graph option available you will need to run the following command
from your command line to get the NDVI source files.
cd $(GV_HTML)/ImgViewer
wget -q -np -nH --cut-dirs=2 -A.gz -r http://glovis.usgs.gov/ImgViewer/NDVI/
After you have downloaded the NDVI directory, you will have to create the NDVI directory; since this is an
optional feature of GloVis, the make_directories script will not create this directory for you automatically). The
GloVis build should now create the link to the NDVI data under the Tools menu.
Downloading Default Linework
Yet another script has been distributed with the GloVis source code for StateView developers. This one
allows you to easily retrieve the linework that GloVis uses, if you are interested in the overlays. The script is at
glovis/coop_utils/download_usgs_linework.pl. It will download the full set of linework files to the local directory
at $(GV_HTML)/ImgViewer/linework. More information about the script is provided in the header of the file.
System-Specific Notes
If you have additional notes for this list that may be useful for others to be aware of, please email it to
custserv@usgs.gov.
Solaris:
test -L doesnt work, so remove references to this from the Makefiles

21

Building and Installation (cont)

External Tools
For the most part, installing a StateView website will not require the use of any external tools since
most of the ones GloVis uses are only needed for ingesting data.
Applet Tools:
There are two tools, though, that are needed to display the Landsat-7 ETM+ SLC-off browse scenes,
so everyone planning to distribute SLC-off data will need these. The libgd is available in the base
install of Red Hat and probably most other Linux distributions. Some care must be taken though, to
make sure the libgd and the Perl GD library you will also need are compatible. We are actually using
a fairly old version of Perl GD since Red Hat was shipping a relatively old version of libgd. If you
decide to use a different version of either of these tools, make sure it is compatible with the version of
the other tool you are using. (Make sure you setup your environment variables properly with the
glovis_env script before executing these installs.)
Perl GD module
Create a new directory to retrieve the module to (lets use perl_gd here)
Download the Perl GD module from CPAN.org at the following location:
<http://www.cpan.org/modules/by-module/GD/> or read the GD documentation at the
following location: <https://metacpan.org/pod/GD>

Move the appropriate archive file into your perl_gd directory

Copy the Makefile file from glovis/coop_utils/perl_gd to your perl_gd directory (if you use a
different GD version than we do you will have to modify this file slightly to change the file
and directory names; you will also have to make sure the version of libgd you are using is
compatible with your GD module)
Go into your perl_gd directory and execute make to build and install the library (answer the
prompts for types to install support for as follows. JPEG: y, FreeType: y, XPM: y, GIF: n)
Verify the install worked by executing ls $GV_HTML/ImgViewer/perllib/i386-linux-threadmulti; you should see a GD.pm file and a few other related files
libgd, which is used by the Perl GD module. We use the default libgd shipped with Red Hat, so we
will not go into install details here

22

Building and Installation: External Tools (cont)

Ingest Processing Tools:
If you are going to ingest your own data, there are a few more external tools required. The binary
executables created from building these tools all need to be installed in the $(GV_BIN) directory.
Details of building and installing these tools will not be provided here since most users will not need
them anyway, but we still want to mention them:

netpbm, for manipulating imagery

It is usually part of the standard install on Linux systems. If netpbm is not installed on your
system, it can be found online at <http://netpbm.sourceforge.net/>.
IJG JPEG library
It is also usually part of the standard install on Linux systems, but if you need to install it manually,
you will need to retrieve the archive file jpegsrc.v6b.tar.gz from <http://www.ijg.org/>.
HDF4 library, for the hdf2jpeg utility it creates
It can be found online at various download sites. Make sure you get the HDF4 library, not a more
recent version. It is available on the HDF Group web site:
<http://www.hdfgroup.org/products/hdf4/>.
Map Layer Tools:
There is one external tool required for ingesting original Protected Areas ESRI shapefiles to
produce the GloVis compatible map layer files. Nothing more will be mentioned about this here
since, again, most users will not care to build this advanced layer.
The GDAL library
It can be found online at the following link: <http://www.gdal.org/>.

23

6. Wrapping Things Up
Viewing Your StateView Website
You now should have the applet and web pages for the application tailored, built, and installed; the
browse scene data for the scenes purchased by your state should be downloaded to your local
inventory; and the linework files should be copied to your local system, if you have chosen to
incorporate these into your StateView instance. With these steps complete, you now can type the
location of your website into a current generation browsers URL field and view your states
remotely sensed image data browse inventory with your new StateView application.
The homepage of the website is the glovis/web/index.shtml file. After installing the application, you
will need to use a web address similar to this to view your homepage:
http://www.<your_host.domain>/<stateview>/. You may wish to have your system administrator
setup an alias for your website so you can have an address more like this:
http://<stateview.your_host.domain>. Your administrator may have to add index.shtml to the list of
index files the web server looks for.

Feedback of Code Changes/Bug Reporting

If you make significant changes to the code to allow easier setup for a StateView site, or if you
create or modify any of the existing scripts for retrieving data from the GloVis server in ways that
may be useful to other StateView developers, please send these changes back to the GloVis
development team. We will review your code in consideration of adding it to our codebase in order
to assist other states in setting up their StateView site. Email your code updates/additions to
custserv@usgs.gov; please include at least a brief description of what you changed or added and
how it assists in a StateView implementation.
Please report bugs and documentation updates to custserv@usgs.gov also.

24

7. Upgrade Installs
Once you have your StateView website created and a new version of GloVis is released, it may be
a daunting task to upgrade your code. This task can be accomplished actually, if you follow the
proper steps. First, review the release notes for the new version and see if you are even interested
in incorporating the updates into your StateView instance. If you do wish to install the new version,
follow the instructions provided below.

Upgrading the Code

Start by downloading and decompressing the new GloVis codebase package, following the same
steps as you have previously, outlined in Obtaining the GloVis Source Code: Downloading the
Source Code Package and Preparing for Installation: Decompressing the Source Code Package
Create patch files for the files youve made updates to by comparing the differences between
your modified files and the contents of each of those files in the new codebase.
For each file youve modified in the source code, execute a command like this:
diff u glovis_9_0/path_to_file/filename modified_glovis_9_0/path_to_file/filename >
filename.patch This creates what is called a patch file that you can use to easily apply the
same changes to the new version of this file in the new releases source code (obviously,
use the proper version numbers for the code packages you are working with).

Put all the patch files in a common location for ease of use
The remaining steps in Preparing for Installation, that you executed with your previous install, can
be replaced by simply applying your patch files to the files in the new source code. The basic
command to apply a patch is patch < path_to_patch/filename.patch (you have to be at the same
directory level to apply the patch as you were when you created it). Any conflicts with the patches
need to be resolved before moving on.
Any new files you created will need to by copied from your old source code to the appropriate
location in the new releases source code directory tree (new images, etc.).

25

Upgrade Installs (cont)

Building and Installing for an Upgrade

To allow for a seamless cut-over to your new version, you initially will want to install the new code
in a new location; then you can move it to the live location after its installed correctly and youve
verified the install worked correctly.

Were basically going to start at Building and Installation: Build the Installation Directory Tree and
do the build and install the same as if this was a first-time install, but use a different location to
install the application at. When you source the glovis_env script, just provide a new location to
install this version of the application to (i.e. glovis_build_new).
When you have the code built and installed, you need to get your scene data and the linework
installed in this new location too. In most cases you can use the same data you already have for
each scene and for the linework. If you have your data directories located outside the install
directory structure and use symlinks to link it in, your links should already be made if you have
creating them worked into your build process correctly. If you keep the data directly under the
$(GV_HTML)/ImgViewer directory, you can just copy each entire data inventory structure from your
old install (e.g. cp R glovis_build/ImgViewer/l7 $(GV_HTML)/ImgViewer, assuming your
environment variables are setup for your new install still). Do this for each dataset you support as
well as for the linework.
Occasionally, metadata file contents and/or the browse imagery itself gets modified, so be careful
when reading the release notes to determine if you can use the same data files for each dataset
and the linework or if you will need to re-pull the any files from the GloVis server. If you do need to
re-pull any data, you can just re-execute the process to do this outlined in Building and Installation:
Downloading GloVis Browse Image Data and/or Building and Installation: Downloading Default
Linework to get the new data.

Typically, we will not upgrade to new versions of the external tools GloVis relies on, so you usually
will not have to update those, though you still will need to install the necessary external tools into
the new applications build directory tree, as you did previously, if you needed any of them.

26

Upgrade Installs: Building and Installing For an Upgrade (cont)

Releasing an Upgrade Installation

Before you release your new StateView application, you should take time to review and test it in a
web browser to make sure the updates worked correctly. If everything is in working order, you can
now cut-over to the new version.

Move your existing StateView build directory tree to a backup location (e.g. mv glovis_build
glovis_build_old) in case the new application is found to have problems, then you can just move
this back where it was until the new versions issues are resolved and you can re-release it.
Move the new version to the live location (e.g. mv glovis_build_new glovis_build)
As soon as you move your current version out of the way, move the new one in as quickly as
possible to minimize the time your site is unavailable.

27

8. Documentation and Support

System Information
About Linux:
http://www.linux.org/
http://www.linuxjournal.com

Programming Information
Java:
http://java.com/
http://www.oracle.com/technetwork/java/javase/documentation/index.html
jQuery JavaScript library:
http://jquery.com
Oracle Tools for Java Platform Security (signing your Java applet):
http://docs.oracle.com/javase/8/docs/technotes/guides/security/SecurityToolsSummary.html
http://docs.oracle.com/javase/tutorial/deployment/jar/signing.html
http://java.com/en/download/help/appsecuritydialogs.xml
Perl Documentation:
http://perldoc.perl.org/

General Satellite Data Information

About the Worldwide Reference System (WRS):
http://landsat.usgs.gov/worldwide_reference_system_WRS.php
EROS Public Website:
http://eros.usgs.gov

28

9. Disclaimer
The GloVis source code is provided "As Is", without a warranty or support of any kind. The
software is Government Off-The-Shelf (GOTS), public-domain; it is available to any government,
public, or private institution. Occasionally, limited support will be considered for agencies with
whom we have cooperative agreements or mutual goals.

29

10. Acronyms
ALI

Advanced Land Imager

ASTER

Advanced Spaceborne Thermal Emission and Reflection Radiometer

CSS

Cascading Style Sheets

DAAC

Distributed Active Archive Center

EO-1

Earth Observing-1

EROS

Earth Resources Observation & Science

ETM+

Enhanced Thematic Mapper+

GIF

Graphic Interchange Format

GloVis

Global Visualization Viewer

GLIS

Global Land Information System

GOTS

Government Off-The-Shelf

JDK

Java SE Developer Kit

JPEG

Joint Photographic Experts Group

JRE

Java Runtime Environment

LDCM

Landsat Data Continuity Mission

MODIS

Moderate Resolution Imaging Spectroradiometer

MRLC

Multi-Resolution Land Characteristics Consortium

MSS

Multispectral Scanner

30

Acronyms (cont)
NAPP

National Aerial Photography Program

NASA

National Aeronautics and Space Administration

NDVI

Normalized Difference Vegetation Index

NCSA

The National Center for Supercomputing Applications

NHAP

National High Altitude Photography

OLI

Operational Land Imager

POC

Point of Contact

SLC

Scan-Line Corrector

SSI

Server-Side Include

TIRS

Thermal Infrared Sensor

TOC

Table of Contents

URL

Uniform Resource Locator

US

United States [of America]

USGS

United States Geological Survey

VNIR

Visible and Near-Infrared

WRS

Worldwide Reference System

31

11. Appendix
A. Signing Your Java Applet
If you wish to sign your applet, we have provided some example code. Following are details of how
GloVis sets up the Java key, how to use it, and other factors you might want to consider.
Review the Java security tutorials on the Oracle documentation website if you need help
understanding Java security. The link is given in the Documentation and Support: Programming
Information section.
Here are the targets in a Makefile we use to build the Java key used to sign the applet:
# target to make a Java security key
javakey:
keytool -alias $(GV_JAVASEC_ALIAS) -storepass $(GV_JAVASEC_PASSWORD) \
-keypass $(GV_JAVASEC_PASSWORD) -genkeypair -keyalg RSA -sigalg MD5withRSA \
-keystore javakey -keysize 2048 -dname "$(GV_JAVASEC_NAME)"
# target to make a Java security certificate signing request (CSR) using a local file called csrFile
csr:
keytool -certreq -alias $(GV_JAVASEC_ALIAS) \
-storepass $(GV_JAVASEC_PASSWORD) -keystore javakey -file csrFile
# target to import the certificate from the Certificate Authority data
# from a local file called cert.cer into the key file
importcsr:
keytool -importcert -alias $(GV_JAVASEC_ALIAS) \
-storepass $(GV_JAVASEC_PASSWORD) -keystore javakey -file cert.cer

32

Appendix A. Signing Your Java Applet (cont)

The javakey target builds the javakey file used to sign the applet.
The csr target is used to build the file that needs to be given to the Certificate Authority. The file
created by this step is something you use when filling out the request to purchase the certificate.
If you don't get a certificate and sign your applet, users may be blocked from running your applet.
The importcsr target takes the certificate purchased from the Certificate Authority and adds it to
the javakey file.
The targets use a number of environment variables, discussed here:

GV_JAVASEC_ALIAS

we just set that to "glovis"

GV_JAVASEC_PASSW
ORD

the password for the keystore; make it whatever you want

GV_JAVASEC_NAME

information shown when the security popup is shown in the applet.

We have it set to:
"CN=USGS, OU=National Center\, EROS, O=USGS, L=Sioux
Falls, ST=SD, C=US
but you'll want to tailor it for your site

GV_JAVASEC_KEYST
ORE

basically the name of the javakey file when it is installed. We set

this to ~/glovis_build/bin/javakey

33

Appendix A. Signing Your Java Applet (cont)

Then, in the glovis/web/ImgViewer/Makefile, it reads:
default : java2ImgViewer.jar sign
java2ImgViewer.jar: geocodeGoogle $(CLASSES)
jar cmf java_manifest java2ImgViewer.jar *.class
.java.class:
javac -Xlint:deprecation $<
sign:
@if [ -n "$(GV_JAVASEC_KEYSTORE)" -a -n "$(GV_JAVASEC_PASSWORD)" -a \
-n "$(GV_JAVASEC_ALIAS)" -a -e $(GV_JAVASEC_KEYSTORE) ] ; then \
jarsigner -keystore $(GV_JAVASEC_KEYSTORE) \
-storepass $(GV_JAVASEC_PASSWORD) java2ImgViewer.jar $(GV_JAVASEC_ALIAS); fi
This command in the sign target is the main part of interest:
jarsigner -keystore $(GV_JAVASEC_KEYSTORE) \
-storepass $(GV_JAVASEC_PASSWORD) java2ImgViewer.jar $(GV_JAVASEC_ALIAS)
The command actually signs the jar file with the javakey file created above. Note that the "if" part
of that target allows you to build the web site without creating the javakey file. The if condition
isn't needed unless you want to detect when the javakey file is available to be used for signing. The
environment variables used in this Makefile for signing the applet need to have the same values
that they had when you created the javakey file.
As of Java 7 Update 51, the Java client installed in the users browser has to see the Permissions
attribute in the manifest or it will not run the applet. Our java_manifest file is included in the
codebase; you will want to modify it for your installation.

34

Appendix B. Address Search

In version 7.10, a feature was added under the Map Layers menu to allow searching for addresses
and places; this feature made use of the Google Maps Geocoding API. Since version 8.11, GloVis
uses a Google Maps API for Business license. To include this feature in your installation, you will
need to create a Google account of your own. Information can be found at
<http://developers.google.com/maps> including terms of use.
Once you have an account set up, create a file named geocodeGoogle.pm. This module must
contain a method called geocode that is exported; this method takes an address entered by the
user, invokes the Google Geocoding API, and returns a string with results in the format:
Found:lng:lat:formatted_address::lng:lat:formatted_address
Or
Error:your_error_message
The ProcessResults class in SearchForAddressDialog.java contains more examples of the
expected format for lookup results. Please refer to Googles documentation for examples of
implementing the geocoding functionality.
Install the geocodeGoogle.pm file in the $GV_HTML/ImgViewer/.security directory and rebuild the
software. The Search for Address option will not be available under the Map Layers menu until this
is done.
As an alternative to using Google for address lookup, you may use another geocoding service. In
SearchForAddressDialog.java, modify the callGeocodingCgi method to invoke a different script, or
implement some other lookup functionality directly in the Java class. Also, the
AddressSearchMapLayer class requires a file called searchenabled to determine whether to
display the Address Search Result option in the Map Layers menu. The Makefile manages this
file based on the presence of an installed geocodeGoogle.pm file, so modify the Makefile if your
implementation differs.

35