Table of Contents

1 INTRODUCTION History of GloVis Installation Guide Caveat Installation First Steps 2 HARDWARE REQUIREMENTS Java Applet Web Pages Ingest Overview 3 OBTAINING THE GLOVIS SOURCE CODE GloVis Distribution Website Registration for Download Access Downloading the Source Code Package 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 1 1 2 3 4 4 4 5 5 6 6 6 6 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 Release 8.0+ Notice 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

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

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

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
9 DISCLAIMER 10 ACRONYMS 11 APPENDIX A. Signing Your Java Applet B. Address Search

28 28 28 28 29
30 31 33 33 36

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 Earth Explorer; 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 previous search and order tools utilized. 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 the original Landsat 7 ETM+ as well as ASTER Level-1B VNIR and Level-1B TIR; Landsat 7 ETM+ SLC-off; Landsat 4/5 TM; Landsat Orthorectified ETM+, Pansharpened ETM+, TM and MSS; Landsat 1-3 and 4/5 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, do 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 inline 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, 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, it requires any web browser with support for Java 6 (plug-in version 1.6 Update 10 or higher) but the most recent version is strongly recommended. Java is built into many browsers and can be added to other browsers by downloading, installing, and enabling a plug-in. To get the JRE, go to <http://java.com/> and select the Free Java Download link. On the developer's side, it requires any recent Java Software Development Kit (SDK), 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 things 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 distribution website. The distribution website is accessible from the GloVis homepage <http://glovis.usgs.gov/>; click on Download Source Code in the blue navigation bar at the bottom of the page. To view and utilize the functionality of the GloVis distribution website, you need to be running a current generation browser with support for CSS and JavaScript.

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. We only wish to collect this information from our external users in order to enable us to contact you with news about the software if needed and for our own statistical purposes. 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 the raw 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 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 files associated with each scene from the GloVis inventory for your state in order to build your browse inventory.

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 8_0 with the version you are installing): > tar zxf source_with_doc_glovis_8_0.tar.gz The code will be in a directory named similar to glovis_8_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.

If you do want the features available in the File menu, you must create a Java security certificate (use keytool) and use the same parameters for your public key on the Java applet side ( 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) Remove the WorldBoundariesBlack.gif image from the GIFS macro and World5Minute.jpg from the JPGS macro since you will not be needing these images

12

Preparing for Installation (cont)

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, an ftp location to retrieve the files from, 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 webpages 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)

Release 8.0+ Notice

The 8.0+ release of GloVis contains some major changes. We have updated the Java applet code to use Java 1.6 (also called Java 6). This means the end-user of the application is required to have a Java 6 or higher plug-in (1.6+) in order to use the application. There is a capability built into the website to detect the users Java plug-in version and redirect the user to webpage informing them 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. 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 the 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 (we use GD 1.41) 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/> 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 packages gd-1.8.4-12 and gd-devel-1.8.4-12) 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 NCSA site via ftp: <ftp://ftp.ncsa.uiuc.edu/HDF/HDF/HDF4.1r5>. 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.remotesensing.org/gdal/>. Version 1.2.1 is the version tested with the GloVis code.

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_8_0/path_to_file/filename modified_glovis_8_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/ Setting up Apache on Linux: http://www.linuxgazette.com/issue12/server.html

Programming Information
About Environment Variables: http://www.iu.hio.no/~mark/unix/unix.html#SEC27 Perl Documentation: http://perldoc.perl.org/ Javal: http://java.com/ jQuery JavaScript library: http://jquery.com

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

Documentation and Support (cont)

Example StateView Websites

AlaskaView: http://glovis.gina.alaska.edu TexVis: http://glovis.texasview.org

29

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.

30

10. Acronyms
ALI ASTER CSS DAAC EO-1 EROS ETM+ FTP GIF GloVis GLIS GOTS JPEG Advanced Land Imager Advanced Spaceborne Thermal Emission and Reflection Radiometer Cascading Style Sheets Distributed Active Archive Center Earth Observing-1 Earth Resources Observation Systems Enhanced Thematic Mapper+ File Transfer Protocol Graphic Interchange Format Global Visualization Viewer Global Land Information System Government Off-The-Shelf Joint Photographic Experts Group

JRE
LDCM MODIS MRLC MSS

Java Runtime Environment

Landsat Data Continuity Mission Moderate Resolution Imaging Spectroradiometer Multi-Resolution Land Characteristics Consortium Multispectral Scanner

31

Acronyms (cont)
NAPP NASA NDVI NCSA National Aerial Photography Program National Aeronautics and Space Administration Normalized Difference Vegetation Index The National Center for Supercomputing Applications

NHAP
POC SLC SSI TOC URL US USGS VNIR WRS

National High Altitude Photography

Point of Contact Scan-Line Corrector Server-Side Include Table of Contents Uniform Resource Locator United States [of America] United States Geological Survey Visible and Near-Infrared Worldwide Reference System

32

11. Appendix
A. Signing Your Java Applet
If you wish to support the functions of the GloVis applet that arent normally allowed by applets (the File menu, which has functions to write files to the users hard drive), here is some more information about how to sign the applet to allow users to give permission for the applet to have functionality that Java normally wouldnt permit. Following is details of how we setup the Java key, how to use it, and other factors you might want to consider. Review the Securing Java 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) for Symantec csr: keytool -certreq -alias $(GV_JAVASEC_ALIAS) \ -storepass $(GV_JAVASEC_PASSWORD) -keystore javakey -file csrFile # target to import the certificate from Symantec into the key file importcsr: keytool -importcert -alias $(GV_JAVASEC_ALIAS) \ -storepass $(GV_JAVASEC_PASSWORD) -keystore javakey -file cert.cer

33

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 Symantec (formerly VeriSign) if you intend to get a certificate. The file created by this step is something you use when filling out the web form to purchase the certificate from Symantec. If you don't get a certificate, the security warning shown says the publisher hasn't been verified - but it doesn't limit the functionality available in the applet. Having the certificate and showing the authenticity verified by statement basically to give users a comfort factor. The importcsr target takes the certificate purchased from Symantec and adds it to the javakey file. The targets use a number of environment variables, discussed here: GV_JAVASEC_ALIAS GV_JAVASEC_PASSW ORD GV_JAVASEC_NAME we just set that to "glovis" the password for the keystore; make it whatever you want 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 basically the name of the javakey file when it is installed. We set this to ~/glovis_build/bin/javakey

GV_JAVASEC_KEYST ORE

34

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. It 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. There isn't anything special you need to do in the code to use the features that are normally not allowed by applets. If you have created a javakey file and signed the applet with it, the applet will see that and automatically provide the user the additional functionality if they accepted it (by accepting the certificate that pops up when they first visit the site).

35

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. Beginning with 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.

36