EarthAtlas Web Mapping Application
Help and Instructions

The EarthAtlas (v.1) Web mapping application is being developed by the Water Systems Analysis Group (WSAG) at the University of New Hampshire. It is designed to allow a user to access and interact with a variety of data and model output for Earth system data layers related to water (natural and human) and any other information needed to our projects.

The EarthAtlas system is built with two major pieces:

The OpenLayers API (v6.4.3) which is an Open Source initiative for dynamic mapping in compliance with OGC standards and protocols and
The University of New Hampshire Rapid Integrated Mapping System (RIMS) for geospatial data management, manipulation, and visualization functions.

EarthAtlas is a front end RIMS application (E-RIMS) serving its own full featured Web portal and a number of WSAG project-focused pages. These project-focused pages are specifically customized to meet the goals of each research project. The latter includes banner, styles, map views, mapping tools and functionality, dataset selection, etc.

The overall primary purpose and functionality of the EarthAtlas is dynamically (no preprocessing requited) displaying maps of

Raster and Vector Polygon Datasets (spatial coverages of observational or modeled data)
Point Datasets (station and site data)

which are listed in the RIMS dataset metadata Database (DB) also called the Magic Table (MT). It contains information on dataset files location and structure, time series, units, projection, default styling, etc. So adding a new record (dataset) into MT immediately makes it searchable by the RIMS tools and available for RIMS WMS and WFS clients, e.g. EarthAtlas.

The informational overlays such as coastlines, country/administrative borders/labels, OSM and Bing street and satellite maps, etc. are served as geospatial reference only and, thus, not available for RIMS tools, e.g. data query, calculations, etc.

2. Map Navigation and View Controls

2.1. Basic Navigation

Basic navigation and view controls are those from the OpenLayers which include -

Zoom using-

Mouse wheel
Mouse double click
Zoom controls in the upper left corner of the map window -

Keyboard Shift + Mouse drag -

Zoom out to Full Extent of the map using “Full Zoom” control -

Pan using -

Mouse drag on the map
Mouse drag of selection area in the overview map. The overview map control is located in the lower left corner of the main map -

Rotate map using -

Keyboard Shift + Alt + Mouse drag
If maps gets rotated a rotation reset control appears in the upper right corner of the map -

Rotate map to North -

Keyboard key “n” or “N”
Rotate Map to North control located in the upper right corner of the Map view (available in Polar projection only) -

2.2. Map View History

Each time map view changes with user zoom/pan/rotate actions or a new dataset gets loaded or modified (e.g. time series date, resample method, etc.) the new view gets recorded to the Map View History sequence, so that the user can navigate back and forth using history controls located in the upper right corner of the Map view -

Note, the Map View History gets reset, if map Projection changes.

2.3. Overview Map

Overview map control is located in the lower left corner of the Map view and it allows to see and drag/move the dashed rectangle of the present location of the view within the larger extent which is particular useful in high zoom levels (closeup views) -

Closed Overview Control

Opened Overview Control

2.4. Map Attributions

Map attribution control is located in the lower right corner of the Map view and it allows to see ownership of the map tile server and the map information for the dataset presently being displayed. The attribution control can be opened or closed by the user at any time -

2.5. Map Scale

Map scale is located in the lower right corner of the Map view -

2.6. Coordinates of the Mouse Position

Coordinates of the mouse position on the map are displayed in the upper right corner of the Map view in decimal arc degree units of the Geographical projection -

2.7. Changing Map Projection

Map projection choices and selector are located at the upper right corner of the Web page -

A user can switch map projection by clicking to the selector text box with the projection name (three projection choices are shown in the illustration above with current one highlighted) and the map with displayed data on it will be re-built for the closest spatial extent in the new chosen projection. Map view history and the dual layer tool will be reset though.

3. Raster and Vector Polygon Datasets

Raster and Vector Polygon Datasets are dynamically served by RIMS WMS based on their metadata stored in the RIMS DB that is also called the Magic Table (MT). Each dataset record in the MT contains information on the data file(s) location and structure, units and unit conversion on-the-fly, projection, map styling, map options, original source reference, download link, etc. The raster/polygon dataset that is displayed in the map view of the EarthAtlas is considered the Main Data Layer (MDL) and it retains focus of all RIMS tools, such as information table with the dataset title, legend, units, resample, dynamic styling, cell value query, time series graphing, etc. which is illustrated here -

There are three different ways to load Main Data Layer (MDL) to be displayed in the Map view area of the EarthAtlas using -

“Raster and Polygon Data” menu
Dataset Search/Query Tool from metadata DB sources -

Global MT (default)
Local MT by providing a file path to it

Direct input of dataset ID
Direct input of dataset metadata from *.init file

These methods are explained in the sections below.

3.1. Loading Maps Using Dataset Menu

Most relevant datasets for the project site that uses EarthAtlas Web engine are included to the pre-built dataset cascading menu here -

3.2. Loading Maps Using Search/Query Tool

Presently WSAG metadata DB (Global MT) has over 26,000 active and about the same number of archived dataset records. It is impossible to add even a small fraction of those into the dataset menu described above. So, the EarthAtlas has a dataset search/query tool that can be called from clicking on “Dataset Search” tab for the Global MT in the Data Menu here -

→

The search can take one or two search strings or regular expressions with logical or/and conditions and any combination of four record fields to search, e.g. “Name”, “Data ID/Code”, etc. Search results indicate time series type (if any) and dates range. In addition it can also display “Status” (check for file existence” and “Extents” that are displayed in Geographical projection coordinates and grid cell size information. Example of search results is illustrated below -

Note, the search results in the blue font are actually links to display this dataset as the Main Data Layer in the Map view window.

The local metadata DB with a file path to it that is entered to the “Dataset DB” input field can be searched/queried using the same tool, but invoked by clicking “Search DB” button next to it -

3.3. Loading Maps Using Direct Input of the dataset ID

If a user has the dataset ID, it can be used to load MDL to the EarthAtlas by adding it to the “Dataset ID” input form and clicking “Update Map” button as illustrated here -

This will load a dataset from the Global MT database. In case the dataset ID is from the local DB, the “Dataset DB” input form has to have a valid path to it -

3.4. Loading Maps Using Direct Input of the dataset metadata *.init file path

A record of RIMS dataset metadata can be saved to an *.init file that has a nesting structure of Key => Value pairs with are quite similar to JSON format, but in Perl language. Loading such record into the EarthAtlas results has a similar action as reading it from the Global or local metadata DB. The metadata *.init file path has to be entered to the “Dataset ID” input form while leaving the “Dataset DB” input empty as shown below -

3.5. Resample Option for the Main Data Layer

Two resample methods are available for mapping a given main data layer. While a Bilinear resampling makes gradual transition of map colors on the map and so avoiding “blockiness” of map views, it does not represent the actual values in the original data cells. Often a researched needs to see actual extents of each original data grid cell that is available with the Nearest Neighbour resampling method, e.g. for hurricane Irma over Florida on September 10, 2017 -

Bilinear resampling Nearest Neighbour resampling

The default resampling method for a given dataset is controlled by an entry in the dataset metadata, so if the user wants to keep his/her preferable method while loading other datasets, it can be preserved by checking “Lock” input checkbox next to the form of map resample method -.

3.6. Dynamic Styling Option for the Main Data Layer

The default color palette as well as data value range over the span of palette colors can be dynamically set by a user to have a better view of the data in certain situations, e.g. while viewing a close-up area on the map with a small variability of data values as compared to the variability in the Global view. Dynamic Styling Option has four input fields -

Color Palette. Clicking on it displays a drop-down menu with graphical color bar images of available palettes.

See table of all palette choices below.
Min - minimum data value for the palette color range.
Max - maximum data value for the palette color range.
Log scale - a choice using a logarithmic scale of data values for the palette color range. It is quite useful for datasets with a range of data values with many orders of magnitude such as population, river flow (discharge), etc.

Note, non-default style stays retained for the next dataset displayed on the map. So, a user must explicitly Reset it in order to return to the default data styling.

Table of Color Palettes

#	Color Palette	Name
1		Grey Scale
2		BlueWhiteRed
3		DarkBlue
4		DarkGreen
5		DarkOrange
6		DarkRed
7		Green
8		GreenRed
9		OrangeYellow
10		PaleRGB
11		RainbowBR
12		Rainbow
13		RainbowRB
14		RedGreen
15		RedOrange
16		RedWhiteBlue
17		ROYG
18		SST
19		TanBrown
20		WhGrRed
21		WhiteRainbowBR
22		WhiteRedBlueGreen
23		WhiteRedBlue
24		YellowGreen
25		YellowWhiteBlue
26		Random

3.7. Dual Layer Tool

The Dial Layer Tool allows to view two datasets simultaneously by changing transparency of the top layer. It can be opened by clicking the “Dual Layer Tool” button in the upper right corner of the area above map -

The Main Data Layer (MDL) is always the top layer, and the bottom layer is usually the previous layer that had been loaded to the Map view unless it is locked -

In addition to the option to lock bottom layer there are two more controls in the tool-

A slider to change opacity of the Top layer, and
Button to Swap top and bottom layer which can be needed, for instance, to check a data value for the map pixel of interest (see next section)

3.8. i-Tool

The i-Tool allows to retrieve a data value of the MDL over the map pixel of interest. It can be activated (and de-activated) by clicking on the i-Tool control in the upper right corner of the Map view -

When i-Tool gets activated, clicking on the map starts a data query of the MDL for the clicked pixel (see illustration above). The map Pixel Data Query popup indicates click point -

Coordinates in Geographical projection
Country
Watershed
Data value
Case of MDL is not time series dataset -
Link to display MDL data aggregation values for spatial polygons which intersect with this point coordinates. Note, this polygon aggregations have to be pre-processed and linked to the source MDL dataset. When the link “Polygon Data” is clicked, the popup expands with additional polygon aggregation data -
Case of MDL is time series dataset -
A “Link to TS data graph for this pixel and from/to dates” is displayed at the bottom of the Pixel Data Query popup -

Clicking on this link opens the time series graph in the browser child window described below.

3.9. Time Series Graph Window

The Time Series Graph Window always displays data for the MDL dataset, if the latter is actually time series (excludes yearly climatology since those are one layer TS). The sequence of actions to build a time series graph for MDL pixel point is -

Activate i-Tool (see the first illustration above in this section).
Choose time series temporal resolution (e.g. yearly) and range of dates for the graph in the Time Series Control (described in detail in the next section).
Mouse click on the map at the location (point) of interest. This will bring up the Pixel Data Query popup.
Click on the link to TS data graph (see illustration just above). This will bring up the Time Series Graph Window where the graph is displayed and additional graphing options are provided.

This is summarized in the illustration below -

The Time Series Graph Window has following options -

Display available polygon aggregations for this MDL dataset over which the coordinate point intersects. E.g. in the illustration above there are two aggregations available -

Watershed: Suwannee as the click point is right over it, and
Country: United States

Clicking on the “United States” link brings up the graph of average annual temperatures for the US -

Note, There is an additional link in the “Polygon” in red font that displays a graph of average temperature for all countries combined.

“Date Offset” and “Step” input allows filtering graph data points in the time series sequence. E.g. this feature is specifically useful for displaying graph for a certain month in the monthly time series. Since offset indexing is zero based, the month of December needs to be offset of 11 and step of 12 as shown here -

“Plot Sigma” (standard deviation) of temporal aggregation MDL time series, e.g. yearly data that had been aggregated from original source of daily data. See yellow lines on the graph -

Additional options are to save Graphics and/or Graphics Data using buttons right above the graph.

3.10. Time Series Control

The Time Series Control (TSC) is displayed in the upper left corner of the Map view, only if the MDL dataset is time series (TS) -

Folded TSC Unfolded TSC

The data of TS is displayed right above TSC - see circled date in the left illustration above. And the TSC starts in folded format (left illustration above) for the purpose of not obstructing the Map view. When unfolded, it has 3 sections -

Date Chooser that lists only dates available in the MDL time series. These may not be consequent dates since missing date layers are not getting listed or it could be 5- or 10-day composites of, say, NASA Satellite images. “Previous” and “Next” buttons allow switching to available adjacent dates.in one click, otherwise the user has to click “Get Single Image” after choosing the wanted date to be loaded to the Map view.
The purpose of “Graph data dates” is setting a range of TS dates to be plotted from the pixel data query i-Tool and Time Series Graph Window (see 2 previous sections). The selected date range can also be used to build map mpeg animations (TBD).
Temporal Resolution Chooser is at the bottom of the TSC window. It allows to choose a different temporal resolution of the MDL dataset, if those are available. The unavailable TS resolutions are greyed out and radio button controls are disabled. Clicking on active temporal resolution radio buttons starts loading selected TS to the MDL and updating the TSC.

The Date Chooser and Graph Data Dates sections of TSC are displayed for all TS types (temporal resolutions) except Yearly Climatology since it does not have dates to choose from.

4. Point Datasets (Station and Site Data)

Similarly to Raster layers described above, the Point datasets can be dynamically added to the EarthAtlas WFS from the Point metadata DB which we also call the Magic Table (MT). The metadata record in the DB for a given point dataset includes information about the data file location of data DB (MS Access, SQL, etc.), dataset title, project, credit reference, OL symbol style, etc. Adding or updating a new record in the DB makes it immediately available for mapping in the EarthAtlas.

4.1. Loading Point Datasets Using Search/Query Tool

A list of site select default point data datasets specific to each project can be added to the Map page initial loading. These are available for viewing as the map page starts. Loading addition point datasets at any time can be done using the same Search/Query Tool we had described for Raster datasets above. It opens from the menu above the Map view with the only difference that the “Point Data” radio button must be selected -

→

Search results show the dataset point symbol, name, and the number of points it contains. Clicking on the dataset name (in blue) opens it up on the Map view -

4.2. Loading Point Datasets Using Direct Input of the dataset ID

This loading option is essentially very much the same as for the Raster datasets described in this section above with the only difference that the “Point Data” checkbox has to be checked -

4.3. Point Datasets Control

The Point Datasets Control (PDC) is located in the upper left corner of the Map view with the green shaded control expand button -

Folded PDC

Unfolded PDC

As you can see in the illustration above of the unfolded PDC, it has four columns -

Display checkboxes that allows to show or hide the point symbols on the Map view
Graphical point symbols (“Sym”)
Name of the datasets, and
Remove (“Rm”) checkboxes that permanently remove the dataset from the PDC list. These can be added later using point dataset search tool or direct input described in the previous two sections.

4.4. Interacting with Point Sites

Pointing the mouse over a site symbol displays a tooltip with the site Name -

And clicking on it opens the site Web page in a new browser tab. E.g. -

5. Overlays

Presently the EarthAtlas offers a choice of 6 overlays with background transparency over the Main Data Layer (MDL) -

The first three are grouped and only one of them can be selected/used at a time -

Administrative borders and coastline. Country borders and labels are displayed at low zoom levels, and State/Provinces and their labels are displayed at higher zoom levels.
Microsoft Bing maps where one of the three layers can be chosen at a time -

Roads
Aerial/Satellite
Aerial/Satellite with labels

Open Street Maps (OSM)

Bing and OSM maps have opacity slider controls that get activated by clicking on the Bing or OSM blue links/buttons -

Note, clinking on the Bing blue link also offers a choice of aforementioned Road, Aerial, or Aerial with labels layers.

Other overlay choices include -

Rivers and Lakes with labels
STN Rivers (Simulated Topological Networks) which are commonly used for streamflow routing in hydrological modeling
Graticule grid that is shown on default for the Polar projection.

The checkbox selectors next to each overlay name are turning them on or off.

6. Data Calculator

The data calculator is a powerful tool to perform a variety of algebraical, statistical, logical, etc. operations over a single or a number of single layer and/or time series gridded datasets. This tools can be activated by clicking on “The Map Data Calculator” bar just below the Map view -

Detailed instructions for using the Data Calculator are available in the link here -
Data Calculator Instructions

7. User Vector Polygons Tool

This tool allows a user to draw and modify vector polygons on the EarthAtlas map and use those in the Data Calculator (see section above) perform a variety of algebraical, statistical, logical, etc. operations over area in these polygons with any RIMS mounted gridded or vector datasets. This tools can be activated by clicking on “The Vector Polygon Tools” bar just below the Map view -

Vector polygons can be created and added to the maps by two different methods -

Drawing by a user with polygon vortices or free-hand lines.
Server selection of the river network upstream area from a user map-click location.

7.1. Drawing and Modifying

Checking the “Polygon” radio button activates the polygon drawing tool, and pressing ESC keyboard key deactivates it. There are two ways to create polygon shapes -

Sequential clicking on the map creates polygon vortices (or vertices) until the starting vortex is clicked, and double-click closes the polygon.
Freehand drawing by moving the mouse pointer around while pressing the SHIFT keyboard key.

Notes:

Press ESC key to stop drawing action and/or deactivate the polygon draw functions.
Press u keyboard key to undo/remove last drawn polygon vortex.
Additional Help instructions are available in the pop-up window by clicking the button.

Modifying already drawn polygons can be done at any time by checking the “Polygon” or “Modify Polygons” (see “Advanced Controls” below) radio buttons to activate the polygon functions. A user can move the mouse over the polygon lines and vortices to add or drag them to new locations.

Resulting polygons may look something like this -

7.2. River Upstream Area

Checking the “Upstream” radio button activates the River Upstream tool, and clicking on the map will trigger the map server to locate the river network upstream area from the clicking location. Note that the upstream point will be searched from the click location by the maximum upstream area value within the search distance selected in the drop-down menu to the right from the “Upstream” radio button -

The resulting upstream area vector polygon may look like this -

7.3. Advanced Controls

Clicking the “More Controls” button unfolds Advanced Control options -

There are four tools becomes available for the user -

“Densify All” button - When this button is clicked, it automatically inserts additional vortices along the edges of the straight polygon lines. This process increases the number of points that define the polygon, allowing for a more precise representation of its shape. By adding these extra vortices, the polygon's geometry can be more accurately adjusted and maintained across different map projections or transformations. This is especially useful when dealing with complex or straight-edged polygons, ensuring that their shape remains consistent and true to the original in various viewpoints or coordinate systems.
“Clear All Polygons” button - Removes all polygons and upstream areas from the map.
“Modify Polygons” radio button - When checked it activates polygon modifying functions such as adding or removing vortices and dragging them to other locations.
“Select Polygons” radio button - When checked, clicking to the polygon area or borders selects the polygon for two possible actions: (1) Delete, if pressed the Delete key on the keybouard; and (2) Densify, if letter d on the keyboard (see item # 1 above for the action details).

There is also the “List of User Selected Polygons” button that triggers displaying/hiding of the user polygon list, and polygon data download option in GeoJSON or ESRI Shapefile formats -

where check-boxes on the left show or hide the given polygons, and the check-boxes on the right do cause removal of them from the map.

7.4. Use of Polygons in the “Data Calculator”

User polygons can be used in the “Data Calculator” equations with the symbols indicated in the “List of User Selected Polygons” under the “Symbols” column. Clicking on the symbol will paste it to the equation entry form of the Data Calculator Tool. Examples using those polygons in the calculations are given in the “Data Calculator” Help document (there is a link to it in the calculator toolbox).

Questions and comments are welcome - alex.proussevitch@unh.edu

Written by Alex Prusevich
Edited by Richard Lammers, Alexander Shiklomanov, and Stanley Glidden

EarthAtlas Web Mapping ApplicationHelp and Instructions

1. Introduction