MADIS Surface Observations – User Guide Version 4.0

================================================================================
1. APPLICATION OVERVIEW
================================================================================
The MADIS Surface Display is a web application that presents real-time surface 
meteorological observations across an interactive ESRI Map interface. 

The MADIS meteorological surface data-set includes reports from many observing
networks run by different providers.

The small colored markers on the map represent weather observing stations. 
The color of each marker corresponds to the current observation value of the 
selected display variable (defaulting to "Air Temp (T)").


================================================================================
2. QUICK NAVIGATION & LIVE STATUS BAR
================================================================================
- Panning & Zooming:
    • Click and drag the map to pan across regions.
    • Use your mouse scroll wheel to adjust zoom levels.

- Basemap Switcher:
    • Use the basemap icon in the top-right corner to switch basemap layers 
      (e.g., USGS National Map).

- Live Status Bar (Bottom of Screen):
    • Local & UTC Clocks: Displays live local and UTC system time.
    • Obs Displayed: Shows visible vs. total loaded stations (e.g., 250 / 1000).
    • Data Loaded: Shows the UTC timestamp of the currently loaded batch.
    • Cursor Lat / Lon: Tracks cursor location across the map in real time.


================================================================================
3. LOCATION & STATION SEARCH
================================================================================
- Station ID Search ("Station ID" Input):
    • Enter a Station ID (e.g., KDEN or SCFM:MESONET) and click "Find ID" 
      (or press Enter).
    • The map zooms directly to the station and opens its details.

- Address Search ("Enter city or zip code..." Input):
    • Enter a city name, address, or 5-digit zip code and click "Go".
    • The map re-centers and zooms to the target area.


================================================================================
4. TOOLBAR CONTROLS & PANELS
================================================================================
Variables Button (Display Settings Panel):
  - Display Variable: Choose the weather variable (Air Temp, Wind Barbs, 
    Altimeter, Dewpoint, Relative Humidity, Precip, Visibility, etc.).
  - Unit System: Switch between Native (K, m/s), Metric (°C, km/h), 
    and English (°F, mph).
  - Display Style: Choose Colored Symbols or direct Text Values on the map.
  - Max Visible Stations: Performance slider (25 to 10,000) controlling 
    plotted station density.
  - Observation Filters (Min/Max): Hide stations reporting outside a specified 
    numeric range.
  - Hide Failed QC: Checkbox to automatically hide stations failing QC 
    checks (Flags X, Q, B).
  - Show QC Ring / Halo: Toggle the color-coded QC outer border around 
    station markers.
  - Color Scale Range: Set custom Min/Max range for the map gradient scale.
  - Marker Size: Adjust station point size (4px to 40px).

Datasets Button (Data Networks Panel):
  - Select All Button: Enables all provider data networks.
  - Clear All Button: Deselects all data networks.
  - Network Checkboxes: Expand categories to enable/disable specific data 
    providers.

Requested Hours Dropdown:
  - Query time window options: Last 1 Hour, Last 2 Hours, or Last 4 Hours.

Refresh Data Button:
  - Re-queries the backend database and updates map markers instantly.

FeedBack Button:
  - Opens support contacts (madis-support@noaa.gov).

Doc Button:
  - Opens this documentation window.


================================================================================
5. QUALITY CONTROL (QC) COLOR LEGEND
================================================================================
Station markers display an outer border/halo reflecting Quality Control status:

  ● Green  (Pass)          - Passed all QC checks (Flags V, G)
  ● Magenta (Partial Pass) - Passed basic Level 1/2 QC (Flags S, C)
  ● White  (Unverified)    - No QC performed / Unverified (Flags Z, T)
  ● Black  (Failed)        - Failed QC checks (Flags X, Q, B)


================================================================================
6. INTERACTIVE MOUSE ACTIONS & TIMINGS
================================================================================
1. Hover (Mouse Move)
Triggered by: Moving the cursor across the map.
What it does:
  - Tracks cursor Latitude & Longitude in the status bar.
  - Performs a hit test to detect station markers.
  - Pulls station observations from browser memory and renders a pop-up 
    tooltip table with weather values and QC flags.
Expected Delay:
  - Showing Tooltip: Near-Instantaneous (< 50ms, zero network calls).
  - Hiding Tooltip: 500ms grace period after moving off the marker.

2. Left Click
Triggered by: Clicking directly on a station marker.
What it does:
  - Opens the station detail popup window.
  - Fetches the last 48 hours (2880 minutes) of historical data for that site.
  - Generates an interactive Chart.js line graph for the chosen variable.
Expected Delay:
  - Opening Popup: Instantaneous.
  - Drawing Chart: ~200ms - 2s (Network & DB dependent).

3. Right Click
Triggered by: Right-clicking anywhere on the map interface.
What it does:
  - Standard browser context menu is disabled (e.preventDefault) to prevent 
    interference with map interactions.
Expected Delay:
  - Instantaneous (0ms).


================================================================================
7. Functions and Features no longer available
================================================================================
  - User Profiles
  - Overlays
  - Auto Update
  - Site Lookup
  - ESS Variable Names
  - Data Downloads


================================================================================
8. Functions Location Moved
================================================================================

  - Variable Unit Selction moved to Variable Button
  - Variable Progressive Discloure moved to Variable Button 
  - Variable Display Type moved to Variable Button 
  - Variable Color Scale Range moved to Variable Button 


================================================================================
9. Known Changes
================================================================================

  - Chart is plotted latest time to oldest time