CISN Display Settings Manual
(for Version 1.7)






Introduction

     This manual describes the configuration settings for the CISN Display program.  These settings are accessible via the "Settings", "Tools | Settings" and "Tools | Audible-Visible Alarm Regions" menu items.



Settings Dialog Window

     Clicking on the "Settings" item in the "Tools" menu brings up the "Settings" dialog window.  The window contains several "tabbed" panels, one of which may be selected at a time.  These tabs and their items are described in the sections below.

At the bottom of the window are the following buttons:



"Alarm" Tab

     The items on this tab configure the operation of the audible and visible alarms that are triggered in response to seismic events that meet the alarm criteria.  These items apply to events that happen anywhere on the map.  Note that "alarm regions" may be configured to also trigger alarms; see the "Audible-Visible Alarm Regions" Dialog Window section for details.  An alarm is triggered if the criteria configured on this tab is met or if the alarm criteria from any of the Audible-Visible Alarm Regions is met.
     Note:  Events first need to pass the "filter" settings (configured via the "Filters" Tab) to be able to trigger alarms.
     The following items define the "audible-visible" alarm settings:

Enable audible alarms:  If this checkbox item is selected, a sound will be played when an "audible-visible" alarm is triggered.  The alarm duration and interval items described below will affect how long and how often the alarm sound is played.

Enable visual alarmsIf this checkbox item is selected, the program's display screen will flash when an "audible-visible" alarm is triggered.  The alarm duration and interval items described below will affect how long and how often the screen is flashed.

Minimum magnitude for alarm:  Sets the minimum-magnitude criteria value for the alarm.  The magnitude of an earthquake event must be at this value or greater for the alarm to be triggered.  This is a floating-point value.  Note that the other alarm criteria items on this tab must also be satisfied for the alarm to be triggered.

Minimum depth for alarm:  Sets the minimum-depth criteria value for the alarm, in kilometers.  The depth of an earthquake event must be at this value or higher for the alarm to be triggered.  This is a floating-point value.  Note that the other alarm criteria items on this tab must also be satisfied for the alarm to be triggered.

Maximum depth for alarm:  Sets the maximum-depth criteria value for the alarm, in kilometers.  If this value is greater than zero then the depth of an earthquake event must be at this value or lower for the alarm to be triggered.  If this value is zero then this alarm criteria item will not be used.  This is a floating-point value.  Note that the other alarm criteria items on this tab must also be satisfied for the alarm to be triggered.

Maximum event age (hours)Sets the maximum-event-age criteria value for the alarm.  If this value is greater than zero then the number of hours passed since the event-time of an earthquake event must be at this value or lower for the alarm to be triggered.  If this value is zero then this alarm criteria item will not be used, allowing events of any age to trigger the alarm.  This is a floating-point value.  Note that the other alarm criteria items on this tab must also be satisfied for the alarm to be triggered.

Only verified events trigger alarmWhen this checkbox item is selected, only "verified" events (those that have been reviewed) will be allowed to trigger the alarm.

Alarm duration (seconds):  Sets the total number of seconds that the alarm will last.  During this time the alarm sound will be played repeatedly (and the screen flashed).  Setting this item to zero will configure the alarm sound to be played once (and the screen flashed once).

Alarm interval (seconds):  Sets the number of seconds that will pass between the repeated playing of the alarm sound (and flashing of the screen).  Setting this item to zero will configure the alarm to be played once.

Audible-visible alarm regions:  The "Modify Regions" button brings up the "Audible-Visible Alarm Regions" dialog window, which is used to specify regions of interest for deciding which events will trigger alarms.  See the "Audible-Visible Alarm Regions" Dialog Window section for details.

     After the alarm has been triggered, it may be shut off manually by using the "Tools | Stop Audible-Visible Alarm" menu item or by pressing the "Esc" key.  The alarm may be tested by using the "Tools | Test Audible-Visible Alarm" menu item or by pressing "A" while holding the "Alt" key.



"ShakeMap" Tab

     The items on this tab configure how ShakeMaps are downloaded and displayed.

Auto-popup ShakeMaps in browser:  Selecting this checkbox enables the automatic display of the web pages for newly-arrived ShakeMaps in a popped-up web-browser window.  See the "Web Browser Notes" section for more information related to this setting.

Max popup ShakeMaps age (hours):  Sets the maximum age (in hours) for ShakeMaps to be automatically displayed in a popped-up web-browser window. 
The age is measured from the time that the ShakeMap-product message was generated on the server.  Setting this item to zero will allow ShakeMaps of any age to be automatically displayed in a popped-up web-browser window.

Auto-display ShakeMaps on map:  Selecting this checkbox enables the automatic download and display of ShakeMaps onto the map display.

Auto-center ShakeMap when auto-displayed:  When this checkbox is selected and a ShakeMap is automatically displayed on the map, the map will be centered onto the event associated with the ShakeMap.

Max ShakeMaps display age (hours):  Sets the maximum age (in hours) for ShakeMaps to be automatically displayed onto the map.  The age is measured from the time that the ShakeMap-product message was generated on the server. 
Setting this item to zero will allow ShakeMaps of any age to be automatically displayed onto the map.

Max time to show ShakeMaps (hours):  Sets the maximum age (in hours) that a ShakeMap will be shown on the map before being automatically removed. 
The age is measured from the time that the ShakeMap is downloaded and displayed on the map.  Setting this item to zero will disable the automatic removal of ShakeMaps from the map.

# of days to keep ShakeMap files
Sets the number of days that downloaded ShakeMap files will be kept.  ShakeMap files older than the specified number of days will be automatically deleted.  These files are downloaded whenever a ShakeMap is displayed on the map, and they are kept in the directory specified by the "ShakeMap files directory" setting.  The age of the files is measured from the time that the ShakeMap was displayed.  Setting this item to zero will disable the automatic removal of ShakeMap files (never delete).

ShakeMap files directory
:  Sets the name of the subdirectory used to store downloaded ShakeMap data files.

Ignore ShakeMaps below magnitude:  ShakeMaps associated with events whose magnitude is below this value will never be automatically downloaded and displayed onto the map display.

Always display ShakeMaps magnitude:  ShakeMaps associated with events whose magnitude is at or above this value will always be automatically downloaded and displayed onto the map display (as long as the ShakeMap is not older than the "Max ShakeMaps display age" setting).  See the "Rules for Automatic Download and Display of ShakeMaps" section below for more information on how this setting is used.

Adjacent distance limit:  When the distance between two ShakeMaps is less than or equal to this value then the two ShakeMaps are considered to be "adjacent" or "in the same area".  The distance is measured between the locations of ShakeMaps' associated events.  See the "Rules for Automatic Download and Display of ShakeMaps" section below for more information on how this setting is used.

Hide adjacent smaller ShakeMaps:  When this checkbox is selected, smaller ShakeMaps that are adjacent to larger ShakeMaps will (in many cases) be hidden.  When this happens, the hidden ShakeMap will still have an entry under the "Layers" menu.  See the "Rules for Automatic Download and Display of ShakeMaps" section below for more information on how this setting is used.

Put larger ShakeMaps on top:  If this checkbox is selected then when a new ShakeMap is added, the new ShakeMap is placed below any currently-loaded ShakeMaps whose "magnitude" is greater than the new ShakeMap.  (The "magnitude" of the ShakeMap is the magnitude of its associated event.)  If this checkbox is not selected then new ShakeMaps are placed above all currently-loaded ShakeMaps.  Note that the relative positions of the ShakeMap layers may also be moved via the "Layers | Edit Layers" menu item.

Autodownload Hazus files:  If this checkbox is selected then when a new ShakeMap is available, if the magnitude of the event associated with the ShakeMap is greater than or equal to 5.0 the program will attempt to download the set of "HAZUS" data files for the event.  If the files are available and the download is successful then the files will be placed into the subdirectory defined by the "Hazus files directory" settings.

Hazus files directory:  Sets the name of the subdirectory used to store downloaded HAZUS data files.

Place ShakeMap layers before:  Sets the name of the layer before which ShakeMap layers should be placed.  When a new ShakeMap is added it is placed before the specified layer, resulting in it (and all the layers below) being displayed underneath the ShakeMap.  If this setting and the "Place ShakeMap Layers after" setting both contain layer names, this setting will take precedence.  Note that the positions of the ShakeMap layers may be moved via the "Layers | Edit Layers" menu item.

Place ShakeMap layers after:  Sets the name of the layer after which ShakeMap layers should be placed.  When a new ShakeMap is added it is placed after the specified layer, resulting in it (and all the layers above) being displayed on top of the ShakeMap.  If this setting and the "Place ShakeMap Layers before" setting both contain layer names, the "Place ShakeMap Layers before" setting will take precedence.  Note that the relative positions of the ShakeMap layers may also be moved via the "Layers | Edit Layers" menu item.

Show detailed ShakeMap legend:  When this checkbox is selected, the "detailed" version of the ShakeMap legend (shown via the "View | Show ShakeMap Legend" menu item) is used; otherwise the "basic" version of the legend is used.

--------

Rules for Automatic Download and Display of ShakeMaps:

The tag names below are used in the rule-descriptions that follow:

    displayShakeMapsMag  : "Always display ShakeMaps magnitude"
    adjacentShakeMapDist  : "Adjacent distance limit"
    hideAdjShakeMapsFlag : "Hide adjacent smaller ShakeMaps"

1. When a new ShakeMap is available, if 'hideAdjShakeMapsFlag'==false then the new ShakeMap is automatically downloaded & displayed and no other ShakeMaps are modified.  Otherwise:

2. If no other ShakeMaps are located within 'adjacentShakeMapDist' miles of the new ShakeMap's location then the new ShakeMap is automatically downloaded & displayed.  (The distance between ShakeMaps is measured between the locations of ShakeMaps' associated events.)  Otherwise:

3. If the new ShakeMap has a magnitude at or above the 'displayShakeMapsMag' value or is the highest-magnitude ShakeMap in the area then the new ShakeMap is automatically downloaded & displayed.  (Being equal to the highest-magnitude ShakeMap is treated the same as being the highest.)  After that, any of the smaller ShakeMaps in the area with a magnitude smaller than the 'displayShakeMapsMag' value are hidden (but their layers remain in the "Layers" menu).

4. If the new ShakeMap has a magnitude below the 'displayShakeMapsMag' value and is not the highest-magnitude ShakeMap in the area then the new ShakeMap is downloaded and placed into the "Layers" menu but it is not displayed on the map.  (Being equal to the highest-magnitude ShakeMap is treated the same as being the highest.)



"Display" Tab

     The items on this tab define a set of display and view parameters.

Display time zone:  This combo-box selects the time zone used on the display.

Locale name:  Selects the name of the locale to be used by the program when displaying information.  If "Default" is selected then the default locale for the Java installation will be used.

Measurement units:  Selects the measurement units for the distance values shown in the event-information panel at the bottom of the screen and on the map-scale bar.  If "Default" is selected then 'Miles' will be used in the "United States" locale and 'KM' will be used in other locales.

Symbol pixels per magnitude:  Configures the size of the earthquake-event symbols shown on the map as a floating-point ratio of screen pixels to earthquake-event magnitude.

Reset-View center latitude:  Sets the latitude value (in decimal degrees) used by the "Reset View" button and view-menu item.  This value may also be set via the "View | Save Current Map View" menu item.

Reset-View center longitude:  Sets the longitude value (in decimal degrees) used by the "Reset View" button and view-menu item.  This value may also be set via the "View | Save Current Map View" menu item.

Reset-View map zoom-scale:  Sets the map zoom-scale value used by the "Reset View" and "Reset Zoom" buttons and view-menu items.  This value may also be set via the "View | Save Current Map View" menu item.

Reset view after inactivity (secs):  Sets a time value such that if the display has been inactive (with no map or event changes) for the given number of seconds then the map position and zoom-scale will be set to the Reset-View values.  If this setting is zero then its functionality will be disabled.

Banner graphic file:  Clicking on this button will display a file-chooser browser that may be used to modify the graphic for the banner shown above the map.  The name of the current banner-graphic file is displayed on the button.



"Config" Tab

     The items on this tab define a set of general configuration parameters.

Audible beep on new events:  When this checkbox is selected, a "beep" will be sounded when a new event arrives.

Max loaded-events age (days):  Sets the maximum age (in days) for events that are held in the program's memory.  Events older than this age will be removed from the display.  (The events may still be available in the program's local archive.)  The age is measured from the event-time for the events and is specified as a floating-point value (which must be greater than zero).

Max event-archive age (days):  Sets the maximum age (in days) for event messages that are held in the program's local (file-based) archive.  Event messages older than this age will be removed from the archive.  The age is measured from the time that the event messages were generated on the server and is specified as an integer value (which must be greater than zero).

Launch browser command prefix:  Sets the prefix string for the operating system command used to launch a web browser.  Leaving the two "Launch browser command" items blank will configure the program to automatically determine the proper operating system command to use, which works well on most systems.  See the "Web Browser Notes" section for more information related to this setting.

Launch browser command suffix:  Sets the suffix string for the operating system command used to launch a web browser.  Leaving the two "Launch browser command" items blank will configure the program to automatically determine the proper operating system command to use, which works well on most systems.  See the "Web Browser Notes" section for more information related to this setting.

Remote-layers location:  Specifies the web page that will be shown in the viewer displayed when the "Remote" button on the "Add Layer" dialog window is pressed.  If this setting is empty then the "Remote" button will not be shown.

USGS event page prefix:  Specifies the web-address prefix used with the "Show USGS Event Page" event-menu and products-menu items.  If this setting is empty then the menu items will not be shown.

USGS ShakeMap page prefix:  Specifies the web-address prefix used with the "View Intensity Webpage" item on the ShakeMap-button menu.  If this setting is empty then the URL specified in the ShakeMap-product message will be used.

USGS ShakeMap page suffix:  Specifies the web-address suffix used with the "View Intensity Webpage" item on the ShakeMap-button menu.

Product button1 product type:  This combo-box may be used to select the function performed by the top "product" button that appears on the event information panel shown below the map.  Available selections include "Info" (to configure the button to bring up an event information window), "Products" (to configure the button to bring up a menu showing available event products, if any are available) and "<none>" (for no button).  The other available selections correspond to various product types that may be associated with events.  When the button is configured for one of these product types and the product is available for the event displayed in the information panel, the button will appear.

Product button2 product type:  This combo-box may be used to select the function performed by the middle "product" button that appears on the event information panel shown below the map.  See the description for "Product button1 product type" for more information.

Product button3 product type:  This combo-box may be used to select the function performed by the bottom "product" button that appears on the event information panel shown below the map.  See the description for "Product button1 product type" for more information.




"AutoSelect" Tab

Auto-select new events:  When this checkbox is selected and a new event arrives with an event-time newer than the "Max auto-select age" value, the newly-arrived event will become the selected event.  The map may also be centered on the event -- see the "Center map on auto-selected events" and "Center if away from middle (%)" settings below.

Max auto-select age (hours):  Sets the maximum age (in hours) for newly-arrived events to be auto-selected.  The age is measured from the event-time for the event.  Setting this item to zero will allow all newly-arrived events to be auto-selected (assuming that the "Auto-selected new events" checkbox is selected).

Center map on auto-selected events:  When this checkbox is selected and an event is auto-selected, the map will be centered on the event if the event's location passes the "Center if away from middle (%)" setting (see below).  When this checkbox is not selected, the map will not be centered on the event.

Center if away from middle (%):  When an event is auto-selected and the "Center map on auto-selected events" checkbox is selected, the map will be centered on the event only if the event's location is further away from the map's middle point than the given percentage value.  For example, if this value is set to 50, then the map would only be centered on the event if the event's location is (roughly) closer to the map's edge than its middle point.  A higher value would allow the event's location to be closer to the map's edge without centering on the event, whereas a value of zero would result in the map always being centered on the event.  A value greater than 50 helps prevent the display from getting bogged down with map redraws when events are arriving at a fast pace (i.e., during an event "swarm").  Note that this setting does not apply to events that trigger an alarm -- the map will always be centered on them if they are auto-selected and the "Center map on auto-selected events" checkbox is selected.

Suppress auto-select after manual (secs):  Sets the amount of time (in seconds) that the auto-selection of events will be suppressed (disabled) after the selected event is "manually" changed by the user.  The selected event is "manually" changed by clicking on the right-side events list, using the up/down arrow or PgUp/PgDn/Home/End keys, right-clicking near an event symbol on the map display, or via the "Event" menu.  While auto-selection is suppressed, new events are still received and added to the display.  This is a floating-point value.

Drill-down zoom-scale enabled:  When this checkbox is selected, the map display will be zoomed-in when a ShakeMap arrives or when a new earthquake event arrives with a magnitude greater than or equal to the "Drill-down events minimum magnitude" value.  The map will be set to the zoom-scale specified by the "Drill-down zoom-scale value".

Drill-down events minimum magnitude:  When the "Drill-down zoom-scale enabled" checkbox is enabled and a new earthquake event arrives with a magnitude greater than or equal to the specified value, the map display will be set to the zoom-scale specified by the "Drill-down zoom-scale value".

Drill-down zoom-scale valueWhen the "Drill-down zoom-scale enabled" checkbox is enabled and a ShakeMap arrives or a new earthquake event arrives with a magnitude greater than or equal to the "Drill-down events minimum magnitude" value, the map display will be set to the specified zoom-scale value.



"Filters" Tab

     The items on this tab define the event filter that is used to select which events are shown on the program's display.  For an event to be shown, it must satisfy all of the enabled filter items.  A list of events that have been filtered out may be viewed using the 'View' | 'Filtered-Out Events' menu item.

Minimum event magnitude displayed:  Only earthquake events with a magnitude of this value or greater will be displayed.  Setting this item to zero will disable it (allowing events of any magnitude to be displayed).  If this item is set to a non-zero value and a given earthquake event does not have a magnitude value then the event will not be displayed.

Maximum event age displayed (days):  Only events that are newer than this age (in days) will be displayed.  The age is measured from the event-time for the event and is specified as a floating-point value.  Setting this item to zero will disable it (allowing events of any age to be displayed).

Keep events from these data sources:  This item contains a comma-separated list of data-source specifiers (i.e. "CI, NC"), and only events with matching data-source specifiers will be displayed.  If this item is set to an asterisk ("*") then events from all data sources will be displayed (except those dropped via the "Drop events from these data sources" item).  If this item contains data-source specifiers then they will override any matching specifiers in the "Drop events from these data sources" item.  This item defaults to the known set of data-source specifiers, and if it is cleared then that set of specifiers will be re-entered into the item.  The data-source specifiers are not case-sensitive.

Drop events from these data sourcesThis item may contain a comma-separated list of data-source specifiers (i.e. "CI, NC"), and events with matching data-source specifiers will not be displayed (as long as the "Keep events from these data sources" item does not contain matching specifiers).  If this item is blank then it will have no effect on filtering.  The data-source specifiers are not case-sensitive.

Minimum event latitude displayed:  Events with a latitude less than this item's value will not be displayed.  The value is specified in decimal degrees.  If both this and the "Maximum event latitude displayed" item are zero then events of any latitude will be displayed.

Maximum event latitude displayedEvents with a latitude greater than this item's value will not be displayed.  The value is specified in decimal degrees.  If both this and the "Minimum event latitude displayed" item are zero then events of any latitude will be displayed.

Minimum event longitude displayedEvents with a longitude less than this item's value will not be displayed.  The value is specified in decimal degrees.  If both this and the "Maximum event longitude displayed" item are zero then events of any longitude will be displayed.

Maximum event longitude displayedEvents with a longitude greater than this item's value will not be displayed.  The value is specified in decimal degrees.  If both this and the "Minimum event longitude displayed" item are zero then events of any longitude will be displayed.

Minimum event depth (km) displayed:  Only earthquake events with a depth (in kilometers) of this item's value or greater will be displayed.  Setting this item to zero will disable itIf this item is set to a non-zero value and a given earthquake event does not have a depth value then the event will not be displayed.

Maximum event depth (km) displayed:  Earthquake events with a depth (in kilometers) greater than this item's value will not be displayed.  Setting this item to zero will disable itEarthquake events that do not have a depth value will be unaffected by this item.

Maximum event magnitude error displayed:  Earthquake events with a magnitude error greater than this item's value will not be displayed.  Setting this item to zero will disable itEarthquake events that do not have a magnitude-error value will be unaffected by this item.

Maximum event horizontal error displayed:  Earthquake events with a horizontal error (in kilometers) greater than this item's value will not be displayed.  Setting this item to zero will disable itEarthquake events that do not have a horizontal-error value will be unaffected by this item.

Maximum event vertical error displayed:  Earthquake events with a vertical error (in kilometers) greater than this item's value will not be displayed.  Setting this item to zero will disable itEarthquake events that do not have a vertical-error value will be unaffected by this item.

Maximum event standard error displayed:  Earthquake events with an RMS-time standard error (in seconds) greater than this item's value will not be displayed.  Setting this item to zero will disable itEarthquake events that do not have a standard-error value will be unaffected by this item.

Maximum event azimuthal gap displayed:  Earthquake events with an azimuthal gap (in degrees) greater than this item's value will not be displayed.  Setting this item to zero will disable itEarthquake events that do not have an azimuthal gap value will be unaffected by this item.

Minimum event number of phases displayed:  Only earthquake events where the number of phases is at this item's value or greater will be displayed.  Setting this item to zero will disable itIf this item is set to a non-zero value and a given earthquake event does not have a number-of-phases value then the event will not be displayed.

Drop events with invalid data values:  When this checkbox is selected, only events with valid data values will be displayed.  The following data values are range-checked:  eventTime:  1970 < t < (currentTime+100yrs), lat:  -360 < l < 360, lon:  -360 < l < 360, mag:  -100 < m < 100.  When this checkbox is not selected, the data-values checks are not performed.



"Colors" Tab

     The items on this tab define the colors used on the program's display.  Each color item has a "color" button labeled with the name or numeric-hex value for the color.  When a "color" button is pressed, it brings up a "Select Color" dialog window that may used to select a color using various methods.  In addition to the red, green and blue attributes of the color, its "alpha" value may also be set, where an "alpha" value of 0 means fully transparent and an "alpha" value of 255 means fully opaque.  Note that lowering the "alpha" value below 255 on any of the "background" color items is not recommended, as this may cause intermittent "ghosting" effects on the display.

Map background color:  The map background color, shown as the "water" areas on the map.

Banner background color:  The background color for the program "banner" graphic shown above the map.

Info panel background color:  The background color for the event information panel shown below the map.

Info panel prompt color:  The color for the "prompt" text items on the event information panel shown below the map.  (For example, "Event ID".)

Info panel data colorThe color for the "data" text items on the event information panel shown below the map.  (For example, the event-ID value.)

Info panel buttons color:  The color for the text-labels on the buttons on the event information panel shown below the map.

Legend background color:  The background color for the map legend.

Legend foreground color:  The color for the text on the map legend.

Event list background color:  The background color for non-selected events on the event list shown to the right of the map.
Event list foreground colorThe text color for non-selected, non-verified events on the event list shown to the right of the map.

Event list select background colorThe background color for the currently-selected event on the event list shown to the right of the map.

Event list select foreground color:  The text color for the currently-selected (non-verified) event on the event list shown to the right of the map.

Verified event colorThe text color for verified events on the event list shown to the right of the map.

Settings summary background colorThe background color for the optional settings-summary panel shown at the bottom of the display.  This panel may be shown or hidden via the "View | Show Settings Summary" menu item.

Settings summary prompt colorThe color for the "prompt" text items on the optional settings-summary panel shown at the bottom of the display.  This panel may be shown or hidden via the "View | Show Settings Summary" menu item.

Settings summary data colorThe color for the "data" text items on the optional settings-summary panel shown at the bottom of the display.  This panel may be shown or hidden via the "View | Show Settings Summary" menu item.




"Event Colors" Tab

Event age >= 0 hours color:  The color for event symbols on the map that represent events that are less than one hour old.

Event age >= 1 hour colorThe color for event symbols on the map that represent events that are at least one hour old but less than one day old.

Event age >= 1 day colorThe color for event symbols on the map that represent events that are at least one day old but less than two days old.

Event age >= 2 days colorThe color for event symbols on the map that represent events that are at least two days old but less than three days old.

Event age >= 3 days colorThe color for event symbols on the map that represent events that are at least three days old but less than four days old.

Event age >= 4 days colorThe color for event symbols on the map that represent events that are at least four days old but less than five days old.

Event age >= 5 days colorThe color for event symbols on the map that represent events that are at least five days old but less than six days old.

Event age >= 6 days colorThe color for event symbols on the map that represent events that are at least six days old but less than seven days old.

Event age >= 7 days colorThe color for event symbols on the map that represent events that are at least seven days old.

Selected symbol color:  The color for the event symbol on the map corresponding to the currently-selected event.  Setting the "alpha" value for this color to zero will leave the symbol for the currently-selected event unchanged.

CUBE/REDI color scheme:  Selecting this radio-button will set the "Event age" and "Selected symbol color" items to the factory-default values for the CUBE/REDI color scheme.

Simpson-map color schemeSelecting this radio-button will set the "Event age" and "Selected symbol color" items to the factory-default values for the Simpson-map color scheme.



"Connection" Tab

     The items on this tab define the parameters used for the connection to the server.

Server host address:  Sets the host-address value for the server.  The value may be in name (i.e. "www.caltech.edu") or numeric-IP (i.e. "131.215.220.4") form.  If the server-host-address value is empty and the "Enable fail-over to alternate servers" checkbox is selected then one of the alternate servers will be chosen at random and used as the server.

Server port number:  Sets the port-number value for the server.

Server LoginClicking on this button will display a Login-Information window that may be used to enter or modify the username and password used to validate the connection to the server.  This window is also displayed when the program fails to connect because the username/password combination is not accepted by the server.  For login username/password help, contact your system administrator or the CISN Display helpdesk representative at one of the CISN member organizations.

Max secs for server alive msgs:  Sets the maximum number of seconds that this program will wait for a server "alive" message before determining that the message has been missed.  The server will transmit one "alive" message every ten seconds.  When server "alive" messages have been missed and the number of seconds elapsed since the last-received server "alive" message exceeds the "Server connection timeout" value, the program will attempt to reestablish its connection to the server.  Setting this item to zero will disable alive-message checking.

Server connection timeout (seconds):  Sets the number of seconds that this program will wait, after server "alive" messages have been missed, before attempting to reestablish its connection to the server.  Setting this item to zero will configure the program to never attempt to reestablish its server connection.

Max connection-retry wait (minutes):  Sets the maximum number of minutes that this program will wait between consecutive attempts to reestablish its connection to its server (or alternate servers).  After each consecutive failed connection attempt, the amount of wait-time before the next attempt will be doubled (which helps to reduce network traffic during lengthy outages).  This item establishes a maximum wait-time.

Enable fail-over to alternate servers:  When this checkbox item is selected and a connection to the current server cannot be established, a connection to an alternate server will be attempted.  This program maintains a list of alternate servers in its configuration, and also fetches a new list each time it connects to a server.

Max event from server age (days)Sets the maximum age (in days) for event messages that are fetched from the server.  The age is measured from the time that the event messages were generated on the server and is specified as a floating-point value.  Setting this item to zero will disable the fetching of previously-sent messages from the server.  Note that event messages generated on the server after the time specified by this maximum-age limit may reference events that occurred before the time specified by this maximum-age limit.



"Email" Tab

     The items on this tab configure how email is sent to alert recipients.  The "Recipients" tab is used to configure the individual alert recipients.  The emails may be generated using a "long" or a "short" format.

'From' real-name for messages:  The "real" name that will appear in the "From:" field of sent alert email messages.

'From' email-address for messages:  The email address that will appear in the "From:" field of sent alert email messages.  For the sending of email messages to succeed, this setting must contain a valid email address.

Address of SMTP server for sending:  The address of the SMTP email server to be used for sending email alert messages.  For the sending of email messages to succeed, this setting must contain the address of an SMTP email server that will accept send-mail requests from the machine on which the program is running.

Maximum number of send-mail retries:  Sets the maximum number of times the program will attempt to send an alert email message after all previous attempts have failed.

Local time zone for messages:  Selects the "local" time zone to be used in alert email messages.  In "long"-format alert messages, both the "local" and the GMT event times are given.  If the "Use GMT for date/times in short messages" checkbox is not selected then the specified "local" time zone will be used in the "short"-format messages.

Use GMT for date/times in short messages:  When this checkbox is selected, the date/time shown in "short"-format alert email messages will use the GMT time zone.  When this checkbox is not selected, the messages will use the "local" time zone (specified via the "Local time zone for messages" setting).



"Recipients" Tab

     The "Recipients" tab is used to configure alert recipients that receive messages via email.  (The "Email" tab configures how the email is sent.)  On this tab is a list containing an entry for each email alert recipient that has been setup, and the following buttons (which act upon the currently-selected recipient entry):

Double-clicking on an existing recipient entry will display the "edit" dialog window for that recipient.

     When a newly-received event message meets the configured criteria for a recipient's email alarm, a "New-Event" alert email is sent to the recipient's email address.  When an update message for the same event is received, an "Update" alert email is sent (even if the update modifies the event so as to make it no longer meet the recipient's criteria).  If a delete message is received for the event, a "Cancel" alert email is sent.




Recipient Configuration

     The "Recipent Configuration" window allows information for an email alert recipient to be entered and edited.  All of the items in the "Recipent Configuration" window apply only to the one recipient.  The window contains two "tabbed" panels, one of which may be selected at a time.  These tabs and their items are described below.

At the bottom of the window are the following buttons:


Recipient Configuration "General" tab:

     The items on this tab configure the general operation of the email alert recipient.

Recipient name:  The name to be associated with the recipient.

Email address(es):  One or more email addresses for the recipient.

Enable sending emails to this recipient:  When this checkbox is selected, the recipient is enabled and may be sent alert email messages.  When this checkbox is not selected, the recipient will never be sent alert email messages.

Use "long" email message formatWhen this checkbox is selected, the alert email messages sent to the recipient will use the "long" format, which provides detailed information about the event.  When this checkbox is not selected, the alert email messages sent to the recipient will use the "short" format, which provides a concise description (suitable for pagers).

Email this recipient when audible-visible alarm triggered:  When this checkbox is selected (and the "Enable sending emails to this recipient" checkbox is selected), and an "audible-visible" alarm occurs, the recipient will be sent an alert email message.  When this checkbox is not selected, "audible-visible" alarms will have no effect on this recipient.  The "audible-visible" alarm settings are configured via the "Alarm" tab on the main Settings window and via the "Audible-Visible Alarm Regions" Dialog Window.  Note that if this checkbox is selected and the "Enable audible alarms" and "Enable visible alarms" checkboxes on the "Alarm" tab are not selected, the recipient will still be sent an alert email message if an event occurs that satisfies the "audible-visible" alarm criteria.


Recipient Configuration "Email Alarms" tab:

     The items on this tab configure the "alarm" criteria used to determine which events will trigger alert email messages.  These items apply to events that happen anywhere on the map.  Note that "alarm regions" may be configured for the recipient and the "region" settings may also trigger alarms; see the "Email Alarm Regions for recipient" Dialog Window section for details.  An email alarm is triggered if the criteria configured on this tab is met or if the alarm criteria from any of the recipient regions is met.  The following items define the email alarm settings for the recipient:

Minimum magnitude for alarm:  Sets the minimum-magnitude criteria value for the email alarm.  The magnitude of an earthquake event must be at this value or greater for the alarm to be triggered.  This is a floating-point value.  Note that the other alarm criteria items on this tab must also be satisfied for the alarm to be triggered.

Minimum depth for alarm:  Sets the minimum-depth criteria value for the email alarm, in kilometers.  The depth of an earthquake event must be at this value or higher for the alarm to be triggered.  This is a floating-point value.  Note that the other alarm criteria items on this tab must also be satisfied for the alarm to be triggered.

Maximum depth for alarm:  Sets the maximum-depth criteria value for the email alarm, in kilometers.  If this value is greater than zero then the depth of an earthquake event must be at this value or lower for the alarm to be triggered.  If this value is zero then this alarm criteria item will not be used.  This is a floating-point value.  Note that the other alarm criteria items on this tab must also be satisfied for the alarm to be triggered.

Maximum event age (hours)Sets the maximum-event-age criteria value for the email alarm.  If this value is greater than zero then the number of hours passed since the event-time of an event must be at this value or lower for the alarm to be triggered.  If this value is zero then this alarm criteria item will not be used, allowing events of any age to trigger the alarm.  This is a floating-point value.  Note that the other alarm criteria items on this tab must also be satisfied for the alarm to be triggered.

Only verified events trigger alarmWhen this checkbox item is selected, only "verified" events (those that have been reviewed) will be allowed to trigger the email alarm.



"Email Alarm Regions for recipient" Dialog Window

     Clicking on the "Regions" button on "Recipients" tab brings up the "Email Alarm Regions" dialog window for the currently-selected recipient entry in the "Email Alert Recipients" list.  This dialog window may be used to specify regions of interest for deciding which events will trigger recipient alarms, resulting in alert email messages.  An email alarm is triggered if the alarm criteria from any of the recipient regions is met or if the criteria configured on the "Email Alarms" tab for the recipient is met.
     The items on this dialog window are very similar to those on the "Audible-Visible Alarm Regions" Dialog Window.



"Add/Edit Region for recipient" Dialog Window

     Clicking on one of the right-side "add" or "edit" buttons on the "Email Alarm Regions for recipient" dialog window will bring up a dialog window that may be used to add or edit an alarm region.
     The items on this dialog window are very similar to those on the "Add/Edit Circle/Polygon Region" Dialog Window
.



"Audible-Visible Alarm Regions" Dialog Window

     Clicking on the "Modify Regions" button on the "Alarm" Settings tab or on the "Audible-Visible Alarm Regions" item in the "Tools" menu brings up the "Audible-Visible Alarm Regions" dialog window.  This dialog window is used to specify regions of interest for deciding which events will trigger alarms.  An alarm is triggered if the alarm criteria from any of the Audible-Visible Alarm Regions is met or if the criteria configured on the "Alarm" tab on the main Settings window is met.
     Note:  Events first need to pass the "filter" settings
(configured via the "Filters" Tab) to be able to trigger alarms.  The Audible-Visible Alarm Regions are used configure which events will trigger audible and visible alarms, whereas the Email Alarm Regions for recipients are used to configure which events will trigger email alert messages.
     The polygons and circles that make up the regions may be displayed via a map layer named "Alarm Regions", which is listed in the "Layers" menu.  When this map layer is enabled, the polygons and circles are shown on the map.  They may be hidden by unselecting the "Alarm Regions" entry in the "Layers" menu.  When adding or editing alarm regions it is recommended that the
"Alarm Regions" layer be enabled.  Whether or not it is enabled has no effect on how the alarms are triggered.

     The "Audible-Visible Alarm Regions" dialog window displays a list of entries, one for each currently-configured region.  An entry may be selected by clicking on it, and the following right-side buttons are available:

Double-clicking on an existing alarm-regions entry will display the edit-regions dialog window for that entry.

     At the bottom of the dialog window are the following buttons:



"Add/Edit Circle/Polygon Region" Dialog Window

     Clicking on one of the right-side "add" or "edit" buttons on the "Audible-Visible Alarm Regions" dialog window will bring up a dialog window that may be used to add or edit an alarm region.  This dialog window is located at the top-right portion of the screen, and while it is displayed, alarm regions may be defined by clicking on the map.  After each mouse click, the corresponding numeric values will be entered into the "Region data" field on the dialog window.
     The following items are available:

Name of region: A name value to be associated with the region.

Minimum magnitude for alarm:  Sets the minimum-magnitude alarm criteria value for the region.  The magnitude of an earthquake event must be at this value or greater for the alarm to be triggered.  This is a floating-point value.  Note that the other alarm criteria items for this region must also be satisfied for the alarm to be triggered.

Minimum depth for alarm:  Sets the minimum-depth criteria value for the alarm, in kilometers.  The depth of an earthquake event must be at this value or higher for the alarm to be triggered.  This is a floating-point value.  Note that the other alarm criteria items for this region must also be satisfied for the alarm to be triggered.

Maximum depth for alarm:  Sets the maximum-depth criteria value for the alarm, in kilometers.  If this value is greater than zero then the depth of an earthquake event must be at this value or lower for the alarm to be triggered.  If this value is zero then this alarm criteria item will not be used.  This is a floating-point value.  Note that the other alarm criteria items for this region must also be satisfied for the alarm to be triggered.

Maximum event age (hours)Sets the maximum-event-age criteria value for the alarm.  If this value is greater than zero then the number of hours passed since the event-time of an event must be at this value or lower for the alarm to be triggered.  If this value is zero then this alarm criteria item will be not be used, allowing events of any age to trigger the alarm.  This is a floating-point value.  Note that the other alarm criteria items for this region must also be satisfied for the alarm to be triggered.

Only verified events trigger alarmWhen this checkbox item is selected, only "verified" events (those that have been reviewed) will be allowed to trigger the alarm.

Enable audible alarms:  If this checkbox item is selected, a sound will be played when an alarm is triggered via this region.  The alarm duration and interval items on the "Alarm" tab will affect how long and how often the alarm sound is played.

Enable visual alarmsIf this checkbox item is selected, the program's display screen will flash when an alarm is triggered via this region.  The alarm duration and interval items on the "Alarm" tab will affect how long and how often the screen is flashed.

Region data:  The geographical data values for the region.  The values may be entered in manually or by clicking on points on the map display.
     For circle regions, the data values consist of a latitude, longitude and radius (in miles) with the following format:  "(lat lon) radius".  A circle region may be defined by two mouse clicks on the map display, with the first one specifying the center and the second one specifying the radius of the circle.  When clicking on the map to define a circle region, any existing region-data values will be replaced.
     For polygon regions, the data values consist of 3 or more latitude/longitude points with the following format:  "(lat lon)", with each point-entry on a separate line.  The polygon region may be defined by clicking points on the map display.  The latitude-longitude values for each clicked-on point will be added after any current values.  When clicking points to define a polygon, the shape does not need to be "closed" because a line will automatically be assumed between the first and last points.

At the bottom of the window are the following buttons:




Web Browser Notes

     When the "Auto-popup ShakeMaps in browser" checkbox on the "ShakeMap" tab is selected, the program will show the web page for newly-arrived ShakeMaps in a web browser window.  On many machines, if the web browser was previously displaying a page, the ShakeMap page will be displayed instead.
     There are several ways in which this behavior can be changed.  The program can be prevented from automatically requesting the display of web pages for ShakeMaps by clearing the "Auto-popup ShakeMaps in browser" checkbox.
     Another approach is to make the requested web page appear in a new browser window, and there are a couple of ways to make this happen.
     The web browser can be configured to show requested web pages in a new browser window (or tab).  This may be done in Internet Explorer (v6) by hitting the "Tools" | "Internet Options" menu item, going to the "Advanced" tab, to the "Browsing" section, and then turning off the "Reuse windows for launching shortcuts" checkbox.
     For web browsers that display web pages on multiple tabs (like Firefox), there is usually a setting to enable opening "links from other applications" in a new tab or a new window.
     It is also possible to change how the program launches the browser to make the requested web pages appear in a new window.  On the "Config" tab, the "Launch browser command prefix" may be setup to directly launch the web browser program.  On most Windows machines, entering  "C:\Program Files\Internet Explorer\iexplore.exe" will result in a new browser window being launched every time.
     The results of the configuration change may be tested by hitting the "Help" | "About" menu item and clicking on the "CISN" text in the middle.  If a web page was already being displayed in a browser then the "CISN" web page should appear in a new browser window.



Configuration and Launch Files

     The configuration settings for the CISN Display program are stored in the "conf/QWClientConfig.xml" file in XML format.  The contents of this file are overwritten anytime the settings are modified.

     If the program is not installed under the user-home directory, the program will store its write-access (configuration, storage and log) files in a directory under the user-home directory.  For example, on a Windows Vista system, if the program is installed in the "C:\Program Files\CISN_Display" directory, the write-access files will be stored in a "C:\Users\username\.cisndisplay\client##########" directory.  The current directory in use is displayed at the bottom of the "Help" | "About" window (as "WorkDir:").

     The program should not be launched by simply clicking on the "QWClient.jar" file or directly with the "java" command because the program will not have enough memory to operate (resulting in an "OutOfMemory" error).  The program should be launched via the icon or executable file created by the GUI installer or via the "runClient" script/batch file (the script will need to be marked "executable").  These provide the necessary "-Xmx" parameter to increase the maximum-memory-heap-size value.




Libraries

     The following open-source libraries are used by this program:

     See the files in "doc/libdocs" in the installation directory of this program for the licensing information for these libraries.



See Also

"Event Viewer" program Settings Manual



8/14/2013 - Eric Thomas / Kevin Frechette, Instrumental Software Technologies, Inc. - www.isti.com

ISTI

EDC