Requirement	Toolbar and User Interface
Section	3.2.5.1
JIRA Task	EIR-71 - Getting issue details... STATUS

Reviewed For	Date
Conventional spacing between sections	2016-08-31

Introduction

This section describes the Epi Map module window, the Toolbar, and the other controls that allow the user to interact with the module. When selected from the main menu, Epi Map opens a full-screen window, with a Mercator projection of a satellite map of the world consuming the majority of the display. There is a vertically oriented Toolbar, similar to that of the Visual Dashboard, consisting of a blue strip containing five icons in the opening window and expanding to as many as seven icons as data layers are added. These icons provide access to the major functions of the module, allowing the user to open and save map files; load base maps and data layers; and save maps as images, toggle the legend display, and create time-lapse maps using time-stamped subject data. On the map itself, at the upper left, are controls for zooming, scrolling, and changing orientation. At the upper right are buttons for switching between satellite and political/street maps, or no background map (blank). At the lower right are scale bars and an indicator for true North. At the bottom is the Map Layers tab; this will be discussed in the Base Maps and Data Layers section.

Overview

The Toolbar, located at the left margin of the Epi Map window, can display a total of seven (7) icons that enable the user to open and save maps files, save raw images of the current map, add base and data layers, toggle the map legend display, and create a time-lapse display showing how data changes over time. The number and identity of the icons depends on the data being displayed. Icons 1 - 5 are present by default when the program is initiated.

Icons

Icon ID ^[4]	Icon Number			Title	Description
Icon ID ^[4]	^[1]	^[2]	^[3]	Title	Description
1	1	1	1	Open	Opens a previously saved map.
2	2	2	2	Save	Saves the current map.
3	3	3	3	Save as Image	Saves the current map as an image.
4	4	4	4	Add Data Layer	Adds a data layer to the map.
5	5	5	5	Add Base Layer	Adds a base layer to the map.
6			6	Create Time Lapse	Create a time-lapse display with case clusters on the map.
7		6	7	Hide/Show Legend	Hide or show the map legend/key of the layers on the map.

Notes:

Default configuration of Toolbar icons on program initiation, before data or base layers have been added. Total icons: 5.
After the addition of a data layer, the Hide/Show Legend icon (ID = 7) appears, enabling the user to toggle the presence of the Map Legend. Hide/Show Legend is always the bottom-most icon on the list.
The time-lapse feature of Epi Maps functions with case-cluster data; the Create Time Lapse icon (ID = 6) is only present when case-cluster data are available as a map layer. It is positioned after the five default icons but before the Legend icon. Because case-cluster is a data layer, icons 6 and 7 always appear together.
The icons have been given position-based ID numbers to facilitate the discussion of their Functional Requirements, in the following section.

Functional Requirements

The icons on the Toolbar shall enable the user to:

open an Epi Info™ 7 map file (.map7), replacing the following data or parameters with those from the file:
1. all data layers,
2. all base layers,
3. the status of the Map Legend (opened or closed),
4. the chosen background map (satellite, streets, or blank),
5. the status of the scale bar (hidden or displayed),
6. the status of the Auto Adjust Color feature (enabled or disabled),
7. the zoom level,
8. the azimuth of the view (the view's orientation with respect to true North)^[1], and
9. the center coordinate of the view;
save the current map to an Epi Map file, including:
1. all data layers,
2. all base layers,
3. the status of the Map Legend (opened or closed),
4. the chosen background map (satellite, streets, or blank),
5. the status of the scale bar (hidden or displayed),
6. the status of the Auto Adjust Color feature (enabled or disabled),
7. the zoom level,
8. the azimuth of the view (the view's orientation with respect to true North)^[1], and
9. the center coordinate of the view;
save the current view of the Epi Map as a bit-mapped .png file;
add to the current map one of the following four Data Layer types^[2]:
1. Choropleth,
2. Dot Density,
3. Case Cluster, and
4. Spot Map;
add to the current map a Base Layer derived from one of the following data sources^[3]:
1. a local Shapefile,
2. a remote KML/KMZ file, and
3. a remote Map Server;
create a time lapse display and histogram based on a Case Cluster Data Layer with a temporal variable;
toggle the display of the Map Legend, located in the lower left corner of the map and consisting of:
1. color gradients for Choropleth quantiles,
2. color and shape indicators for Spot Map features,
3. color and shape indicators for Case Cluster maps, and
4. dot colors for Dot Density maps.

Notes:

Note that the view's azimuth is not reset to that of the map file. Maps of non-polar regions are normally oriented so that "up" corresponds to due North, an azimuth or bearing of 0.0º. If the current view of Epi Map is rotated to an arbitrary heading, say 270º or due west, a different map opened from a file using icon 1 will be rotated to reflect the previous map's orientation-- it, too, will be oriented with west in the "up" direction. If a map is saved with an arbitrary orientation, when it is loaded, it will always be rendered according to the azimuth of the map view immediately before its file was opened.
The requirements for creating the four types of Data Layers are described in detail in Section 3.2.5.3, Map Layers.
The requirements for creating Base Layers are described in detail in Section 3.2.5.3, Map Layers.

Map Tools

Overview

Overlapping the map display, there are a number of indicators and controls that help the user manipulate the map and view the information contained in the base and data layers. At the upper left are the controls for scrolling in the cardinal directions, rotating the orientation of the map, reestablishing "up" as North, zoom control and zoom-out-to-full-extent. At the upper right, the user can switch between a satellite image and a political/street map background, or select "Blank" to have no background map. At the lower right is a compass-like indicator for true North and a scale to estimate distance. At bottom center is the tab to raise, lower and configure Map Layers. Finally, the Map Legend is located at the lower left of the map and is only visible when Map Layers have been configured and enabled using Icon 7.

Functional Requirements

The map display has the following Map Tools that enable the user to complete the listed tasks:

Zoom control slider:
1. Moving the slider bar up and down shall increase or decrease the zoom level in proportion to the amount of movement on the bar.
2. The arrow button at the top of the slider shall increase the linear resolution by a factor of ~2.
3. The arrow button at the bottom of the slider shall decrease the linear resolution by a factor of ~0.5.
Combination N-S-E-W scroll and azimuth control ring:
1. The arrow buttons at 3, 6, 9, and 12-o'clock shall scroll the map in the cardinal directions (E, S, W, N, respectively).
2. The curved sections between the arrows shall control the orientation of the map. Starting with the map in the default "up" = North orientation, dragging the ring in the clockwise direction moves the top of the view progressively westward (from a bearing of 360º toward 270º).
3. At the bottom of the ring, toward the left, is a button that shall reset the orientation of the map to "up" = North.
4. At the bottom of the right, toward the right, is a button that shall zoom out the map to its largest extent. The map is centered, approximately, on the prime meridian (0º longitude), extending from the left from the International Date Line (≈180º W) to the International Date Line in the east (≈180º E) on the right. The map is a Mercator projection covering from approximately 75º N latitude to 75º S latitude.
Compass:
1. A circular indicator with pointer directed to a large "N" shall display the direction toward true North, regardless of how the map orientation may have been changed with the azimuth control ring (2b).
Scale:
1. A scale shall consist of a horizontal line segment with hatch marks (up and down) at the left end plus two additional marks to the right, indicating distance in metric units (top mark: meters and kilometers), and English units (bottom mark: feet and miles).
Map Layers: see Section 3.2.5.3, Map Layers.
Map Legend:
1. Choropleth:
2. Dot Density, Case Cluster, and Spot Maps:
Background map selector:
1. shall allow the user to select between:
  1. satellite imagery,
  2. a map of political boundaries with light topographic shading at low resolution and road/street maps at high resolution, or
  3. a uniform white background (suitable for use with shapefiles, KML/KMZ data, and other maps created from raw coordinates.
2. To the right of the map selector controls is an icon consisting of a square with an arrow pointing outward through the upper-right corner. This enables the user to switch to "full-screen" mode, enlarging the window, if not already full-screen, and removing the operating system window borders and controls. In this mode, the icon changes to a box inside a box; clicking on it will restore the window to its previous state.

Mouse Functionality

Overview

In addition to the mouse-activated icons in the Toolbar and the Map Tools discussed previously, the computer mouse has several other functions in the map display. The user may use the mouse to scroll the display in any direction with a left-button click-and-drag gesture. The mouse wheel may be used to zoom the map in and out, with each increment being approximately equal to that produced by the zoom buttons located at either end of the zoom slider bar (see Requirement 1b, under Map Tools, above). Clicking the right mouse button also accesses a menu that enables the user to toggle the scale bar; delete all map layers; and place markers, zones, and labels directly on the map.

Functional Requirements

When the mouse pointer is in the map display, in a region not occupied by Map Tools, activation of the following controls shall enable the user to accomplish the following tasks:

left mouse button:
1. a click-hold-and-drag gesture shall scroll the map in the direction of mouse movement
mouse wheel:
1. rotating the wheel forward shall change the zoom level by a factor of ~2 (doubling linear dimensions) per increment.
2. rotating the wheel rearward shall change the zoom level by a factor of ~0.5 (halving linear dimensions) per increment.
right mouse button; a click shall reveal a menu with the following options:
1. selecting add marker shall bring up a panel^[1] with menus to select:
  1. marker shape:
    1. circle,
    2. square,
    3. diamond,
    4. cross, and
    5. triangle;
  2. marker size, 10 - 50 points;
  3. marker color:
    1. choose from 48 basic colors,
    2. 16 custom colors, or
    3. define a custom color using:
      1. hue, saturation, and luminosity (each parameter, 0 - 255);
      2. red, green, blue (each parameter, 0 - 255);
      3. a color selection square (hue × saturation) plus luminosity slider.
2. selecting add zone shall bring up a panel^[1] with menus to select:
  1. zone radius (text entry field),
  2. zone units:
    1. kilometer,
    2. meter,
    3. mile,
    4. yard, and
    5. foot;
  3. zone color (see options for marker color in 3.a.iii).
3. selecting add label shall bring up a panel^[1] with a field and menus to select:
  1. label text (text entry field),
  2. label font style (text field populated by Microsoft font chooser UI, activated by button labeled "Font"),
  3. label color (see options for marker color in 3.a.iii).
4. selecting scale bar shall toggle a checkbox to the left of the menu item and the presence of the scale bar in the lower right corner of the map display.
5. selecting remove all layers shall remove all base layers and map layers from the map display and the Map Layers tab.

Notes:

After parameters are selected, the feature shall be added as a "layer" in the Map Layers tab.

Future Development

Overview

At present, there is no way to edit base maps after they have been assigned to a map layer. For example, there is no way to change the selected feature in a base layer that uses a map server and provides multiple options under the Select Feature menu. The user must delete the layer and start over to make this change.

When zooming or scrolling a map with a complex base layer, it can take a long time (minutes) before the base layer features are drawn in the newly exposed areas. During this time, there are no cues to indicate that the system is still waiting for data; the user can continue to zoom and scroll and may assume that there are no features of the base layer's type in the area of interest. The user needs an indicator to show that there is additional data coming that has yet to appear on the map. A progress bar indicating the amount of map data loaded versus the amount remaining would be ideal; an animated circular arrow, gear or stopwatch that indicates that the loading process is in progress and incomplete would be sufficient.

Epi Map does not allow the user to manually interrogate map features for the corresponding form data; this is an important deficit to address. For example, it is possible implement software to use the mouse to select data points in a spot map or case-cluster layer and retrieve the corresponding information for the record(s). Data points can be selected in a number of ways: individual records can be retrieved by clicking on individual spots on a spot map; single or multiple records can be retrieved by clicking on case-cluster spots; and multiple locations can be selected using the Ctrl-Click convention (clicking on multiple objects while the Ctrl key is pressed). Multiple selection can also be accomplished by defining an area on the map, such as a rectangle or circle, positioned and dimensioned using a click-and-drag gesture. With choropleth and dot density maps, the shapes are already defined; clicking inside the shape retrieves all the records in that geographical area. Once the data are selected, there needs to be a mechanism to transfer the records to Classic Analysis or Visual Dashboard for further analysis.

Like Visual Dashboard, Epi Map does not always work properly when its window is reduced from full-screen mode. This is most evident in the configuration panels for tools accessed through icons on the Toolbar. The problem is intermittent, but the "Ok" and "Cancel" buttons frequently fall outside the view of the window when the vertical dimension is reduced. No scroll bars are enabled in this situation, which would ordinarily allow those buttons to be brought into view and used.

Functional Requirements

Epi Maps shall enable the user to:

change the feature type displayed by a base layer that gets its data from a map server.
determine when the process of loading map data is ongoing and when it is complete (in the context of zooming and scrolling).
use the mouse to select data spots on the map and retrieve form data for the corresponding record.
export data records selected in Epi Map to Classic Analysis or Visual Dashboard for further analysis.
see all interface components for layer configuration and map display, regardless of the size of the Epi Map window, by defining component positions relative to the proximal window edge or edges, or by using vertical and horizontal scroll bars.

Browser not supported