YEA Atmosphere Panel: Satellite Sky Tiles and Forecast Integration

Document ID: CNL-SP-2026-027 Version: 0.9 Date: February 27, 2026 Author: Michael P. Hamilton, Ph.D.

AI Assistance Disclosure: This specification was developed through structured dialogue between the author and Claude (Anthropic, Claude Opus 4.6). The author conceived the architectural vision during a walking conversation (Sandwalk session, February 27, 2026); Claude contributed technical research on NASA GIBS data services, synthesized the panel card structure, and drafted the specification text. The author takes full responsibility for the content, accuracy, and design decisions.

Abstract

This specification defines the Atmosphere panel for Your Ecological Address (YEA), a new fifth panel in the field guide drawer sequence that presents satellite-derived sky conditions and forecast trajectories for any queried coordinate on Earth. The panel introduces two data cards — Sky Now (geostationary satellite crop) and Forecast Arc (Open-Meteo atmospheric trajectory) — and integrates with an existing Three.js globe widget displaying daily VIIRS true-color Earth composites. The design shifts satellite cloud imagery from a decorative globe overlay to a scientifically grounded, place-specific atmospheric observation instrument. Data sources include NASA GIBS WMTS tiles from GOES-East, GOES-West, and Himawari-8 geostationary satellites (10-minute temporal resolution, cached hourly on Galatea), the existing Open-Meteo forecast and historical APIs, and the daily VIIRS NOAA-20 true-color archive maintained since June 2025. A third card, Climate Envelope, is architecturally anticipated for future implementation using Open-Meteo's Climate Change API with CMIP6 projections.

1. Introduction

1.1 Context

YEA's field guide presents ecological information in a sequence of panels, each representing a domain of place-based knowledge: Identity, Physical Place, Ecological Setting, and Living Systems. These panels integrate over 15 API data sources spanning geology, climate, biodiversity, and land cover. Current weather data is served via Weather Underground personal weather stations and Open-Meteo modeled conditions, presented as a Current Conditions card within the Physical Place panel.

The atmosphere — the air between the rock and the life — mediates nearly every ecological process at a site: solar radiation drives photosynthesis, cloud cover modulates temperature extremes, precipitation determines water availability, and weather fronts trigger phenological events. Despite this central role, YEA currently treats atmospheric data as a supporting detail rather than a first-class observational domain.

1.2 Design Origin

A prior implementation (Phase 6, YEA3D workplan) attempted to visualize atmosphere by extracting clouds from daily VIIRS composites and draping them as a transparent PNG on the Mapbox globe. This approach suffered from three fundamental limitations: the extraction algorithm (brightness + saturation thresholding) confused clouds with snow, ice, and bright desert; the Mapbox image source on globe projection introduced a 10–15° northward latitude shift; and the visual result resembled, in the author's assessment, "frosting splattered on the globe" rather than a convincing atmospheric layer.

The present specification abandons the globe overlay approach entirely. Instead, satellite imagery is reframed as a place-specific observational tool — a small tile crop from geostationary orbit showing the sky above a specific ground point, paired with forecast data that provides temporal context and ecological interpretation.

1.3 Objectives

1. Establish a new Atmosphere panel (fifth in the drawer sequence) with two initial data cards
2. Deliver near-real-time satellite sky imagery at the place level via GOES/Himawari geostationary data
3. Reframe Open-Meteo forecast data as atmospheric trajectory with ecological interpretation
4. Simplify the existing VIIRS fetcher by removing cloud extraction and serving full true-color composites to a dedicated Three.js globe widget
5. Architect the panel to accommodate a future Climate Envelope card (CMIP6 projections)

2. Panel Architecture

2.1 Position in Drawer Sequence

Identity → Physical Place → Atmosphere → Ecological Setting → Living Systems

The Atmosphere panel sits between Physical Place (geology, terrain, soils, land cover) and Ecological Setting (ecoregion, vegetation community, climate classification). This position reflects the causal chain: the physical substrate determines what atmospheric patterns occur (orographic lift, rain shadows, coastal fog), and those atmospheric patterns in turn determine what ecological communities can persist.

2.2 Card Structure

Cards 1 and 2 are specified for initial implementation. Card 3 is architecturally anticipated; its detailed specification will be a separate document.

2.3 Companion Widget: VIIRS Globe

A Three.js globe widget displays the daily VIIRS true-color Earth composite (8K equirectangular JPEG) as a textured sphere with atmospheric limb glow. This widget provides planetary-scale atmospheric context — the user sees the full Earth as photographed from space today, with clouds as part of the natural image rather than an extracted overlay. The widget may be embedded as an interactive thumbnail in the Atmosphere panel header or accessed as a standalone view.

The existing LCARS Planetary Observation System implementation (operational since June 2025 at MacroNexus/Active/LCARS-ALPHA-v3/widgets/planetary-explorer/) serves as the proof-of-concept codebase for adaptation.

3. Card 1: Sky Now

3.1 Concept

A small satellite image crop (~300 km radius) centered on the queried coordinate, showing the sky above the place as seen from geostationary orbit. During local daytime, the Red Visible band provides an intuitive photographic view — white clouds against dark land and ocean. At night, the Clean Infrared band (10.3 µm, Band 13) shows cloud structure by thermal signature — cold high clouds appear bright, warm clear surface appears dark.

3.2 Data Source

NASA Global Imagery Browse Services (GIBS) provides pre-tiled geostationary satellite imagery via OGC Web Map Tile Service (WMTS) and Web Map Service (WMS).

Satellites and coverage:

Coverage gap: Europe, Africa, and western Asia are not covered by these three geostationary platforms. Meteosat (EUMETSAT) covers this region but uses a different access model. For YEA's initial implementation, the gap is acceptable — the majority of current Nature Places are in the Western Hemisphere. Meteosat integration is deferred to a future revision.

Available bands:

The Red Visible and Clean Infrared bands are selected for implementation. Air Mass RGB is deferred (scientifically rich but visually abstract for a general audience).

3.3 GIBS Access Pattern

WMTS REST endpoint:

https://gibs.earthdata.nasa.gov/wmts/epsg4326/best/{LayerIdentifier}/default/{Time}/{TileMatrixSet}/{ZoomLevel}/{TileRow}/{TileCol}.jpg

WMS endpoint (for bounding-box crops):

https://gibs.earthdata.nasa.gov/wms/epsg4326/best/wms.cgi
  ?SERVICE=WMS
  &REQUEST=GetMap
  &VERSION=1.1.1
  &LAYERS={LayerIdentifier}
  &FORMAT=image/jpeg
  &WIDTH=512
  &HEIGHT=512
  &SRS=EPSG:4326
  &BBOX={lon-delta},{lat-delta},{lon+delta},{lat+delta}
  &TIME={YYYY-MM-DDTHH:MM:SSZ}

No authentication or API key is required. NASA GIBS is a free, open-access public service. Attribution is required (see Section 8).

3.4 Band Selection Logic

The fetcher determines which band to serve based on solar position at the place coordinate:

solar_altitude = compute_solar_altitude(lat, lon, utc_time)

if solar_altitude > 10°:
    band = Red Visible
elif solar_altitude > -6°:
    band = Red Visible (twilight, may be dim)
else:
    band = Clean Infrared

Solar altitude is computed from standard astronomical equations using latitude, longitude, day of year, and UTC time. The 10° threshold ensures adequate solar illumination for meaningful visible imagery. Below -6° (civil twilight), the infrared band is used exclusively.

3.5 Computed Metrics

From the retrieved tile crop, the following metrics are derived:

Cloud fraction: Percentage of tile pixels classified as cloud. For the Red Visible band, cloud pixels are identified by high brightness (reflectance > threshold). For Clean Infrared, cloud pixels are identified by low brightness temperature (< threshold, indicating cold cloud tops).

Estimated solar attenuation: Fraction of direct solar radiation blocked by cloud cover, derived from cloud fraction and estimated cloud optical depth. Simplified model: attenuation = cloud_fraction × 0.7 (thin clouds transmit ~30% of direct radiation on average).

Cloud top temperature (infrared only): Mean brightness temperature of cloud-classified pixels, providing an estimate of cloud altitude. Colder tops indicate higher, thicker clouds with greater precipitation potential.

3.6 Card UI

The card displays:

1. Satellite tile image — 512×512 px crop, centered on place coordinate, ~300 km radius
2. Band indicator — "Visible" or "Infrared" with satellite name (e.g., "GOES-East Visible")
3. Timestamp — UTC and local time of the satellite observation
4. Cloud fraction — Percentage, with qualitative label (Clear / Partly Cloudy / Mostly Cloudy / Overcast)
5. Solar radiation estimate — Qualitative impact on incoming shortwave (Full / Reduced / Minimal)
6. Ecological one-liner — Brief interpretive text connecting sky condition to ecology at this place

Example ecological one-liners:

• "Clear sky — full solar heating of canopy, high evapotranspiration demand"
• "Solid stratus deck — diffuse light only, suppressed surface temperature"
• "Convective cells building — afternoon precipitation likely, typical for subtropical summer"
• "Marine layer present — fog drip contributing to canopy moisture interception"

3.7 Card Source Line

NASA GIBS · GOES-East Red Visible · 2026-02-27 18:20 UTC

4. Card 2: Forecast Arc

4.1 Concept

A 72-hour atmospheric trajectory anchored to the queried coordinate, presenting the forecast not as a weather report but as an ecological process driver. The card reframes existing Open-Meteo forecast data — already available in the YEA data pipeline — into a temporal view of the sky over the place.

4.2 Data Source

Open-Meteo Forecast API (existing integration, customer API key):

https://customer-api.open-meteo.com/v1/forecast
  ?latitude={lat}&longitude={lon}
  &hourly=cloud_cover,precipitation_probability,precipitation,
          pressure_msl,wind_speed_10m,wind_direction_10m,
          shortwave_radiation,direct_radiation,diffuse_radiation,
          temperature_2m,relative_humidity_2m,
          sunshine_duration
  &daily=sunrise,sunset,daylight_duration,
         precipitation_sum,precipitation_hours,
         shortwave_radiation_sum
  &temperature_unit=fahrenheit
  &wind_speed_unit=mph
  &timezone=auto
  &forecast_days=3
  &apikey={OPEN_METEO_API_KEY}

4.3 Card UI Components

4.3.1 Sky Timeline (72-hour sparkline)

A compact area chart showing cloud cover percentage (0–100%) over the next 72 hours. Color-coded: clear (warm amber), partly cloudy (muted), overcast (cool gray). Precipitation probability overlaid as a secondary line or bar. Sunrise/sunset markers as vertical lines delineating day/night periods.

4.3.2 Pressure Trend

Current surface pressure (hPa/mb) with directional arrow and rate of change. Rising pressure indicates clearing, high-pressure ridge building. Falling pressure indicates approaching system, increasing cloud and precipitation probability. Ecological significance: pressure changes correlate with frontal passage, wind shifts, and rapid weather transitions that trigger animal behavior changes (bird migration movements, insect emergence, barometric-sensitive species activity).

4.3.3 Solar Radiation Budget

Total incoming shortwave radiation (W/m²) for today vs. clear-sky potential. Expressed as a percentage: "68% of potential solar radiation reaching surface." This directly quantifies the ecological impact of cloud cover on photosynthetically active radiation (PAR), canopy energy balance, and soil heating.

4.3.4 Ecological Interpretation

A 2–3 sentence narrative connecting the forecast arc to ecological processes at this specific place. Generated by the existing Claude Haiku narrative engine using the forecast data and place context (ecoregion, vegetation type, season, latitude).

Example:

"A Pacific frontal system arrives tonight with 15–20 mm precipitation over 12 hours, followed by clearing and a pressure rise through Saturday. For this mixed-conifer forest at 1,400 m elevation, this late-February rain event falls within the spring moisture recharge window — soil moisture will peak as the growing season approaches. Expect increased amphibian surface activity during the rain event."

4.4 Card Source Line

Open-Meteo Forecast · 72-hr from 2026-02-27 06:00 PST · ECMWF IFS

5. Card 3: Climate Envelope (Future)

5.1 Concept

A 30-year climate trajectory at the queried coordinate using CMIP6 ensemble model projections via the Open-Meteo Climate Change API. This card answers: "What will the atmospheric regime at this place look like in 2055?"

5.2 Deferred

Detailed specification deferred to a separate document. The Atmosphere panel layout and data model should reserve space for a third card. Key data dimensions to anticipate: temperature envelope shift, precipitation regime change, growing season extension/contraction, extreme heat days, frost-free period, and aridity index trajectory.

5.3 Open-Meteo Climate Change API

Endpoint: https://climate-api.open-meteo.com/v1/climate

Provides daily or monthly climate projections from multiple CMIP6 models (EC-Earth3, MPI-ESM, FGOALS, etc.) under SSP scenarios (SSP2-4.5, SSP3-7.0, SSP5-8.5). Free tier available; customer API key extends rate limits.

6. VIIRS Globe Widget

6.1 Simplified Fetcher

The existing viirs_earth_fetcher.py (v2.0) on Galatea is simplified by removing the cloud extraction pipeline:

Removed:

• extract_clouds() function
• _fast_blur() function
• Cloud brightness/saturation thresholding constants
• Transparent PNG generation
• latest_clouds.png symlink

Retained:

• 8K equirectangular JPEG fetch from NASA GIBS WMS
• VIIRS NOAA-20 → VIIRS Suomi NPP → MODIS Terra layer fallback
• Date-based archive to /Archive/Media_Files/Images/NASA/HighRes/{year}/{month}/
• latest_earth.jpg symlink to YEA serving directory
• Logging infrastructure
• launchd schedule (daily at 08:15)

New symlink:

clouds/latest_earth.jpg → /Archive/.../earth_8k_{date}.jpg

The fetcher becomes v3.0 — a clean JPEG fetch-and-archive with no image processing.

6.2 Three.js Globe Widget

Adapted from the LCARS Planetary Observation System proof-of-concept (MacroNexus/Active/LCARS-ALPHA-v3/widgets/planetary-explorer/).

Core implementation:

• Three.js sphere geometry with latest_earth.jpg as diffuse texture
• Atmospheric limb glow via custom shader or second transparent sphere with Fresnel-based opacity
• Slow rotation (configurable speed, default ~0.05°/frame)
• Mouse/touch drag to rotate manually
• Scroll to zoom
• Coordinate display on hover (lat/lon from raycasting)

Integration with Atmosphere panel:

• Clicking a point on the Three.js globe could trigger a YEA query at that coordinate
• When a place is queried, the globe rotates to center that coordinate
• The Sky Now tile crop region could be indicated on the globe as a small highlighted square

Embedding options (to be determined during implementation):

• Small interactive thumbnail (~200 px) in the Atmosphere panel header, expandable to full view
• Separate "Globe" view accessible from the toolbar, alongside the Mapbox 3D view
• Dedicated panel or modal overlay

6.3 Archive Value

The daily VIIRS archive (operational since June 2025, ~270 days, ~1.9 GB as of February 2026) provides historical Earth portraits for temporal animation. Future integration with the snapshots/temporal analysis system (see YEA3D Workplan Phase 8) could animate the globe through weeks or months of composites, visualizing weather system progression at planetary scale.

7. Data Pipeline Architecture

7.1 GOES Sky Tile Fetcher (New)

Script: goes_sky_fetcher.py Location: Galatea Schedule: launchd daemon, every 60 minutes Language: Python 3

Pipeline per execution:

1. Query yea_places table for all places with status = 'published' and valid coordinates
2. For each place: a. Determine nearest geostationary satellite (GOES-East, GOES-West, or Himawari) based on longitude b. Compute solar altitude at place coordinate for current UTC time c. Select band (Red Visible if solar altitude > 10°, Clean Infrared otherwise) d. Construct GIBS WMS request for 512×512 crop at ~300 km radius around coordinate e. Fetch tile image f. Compute cloud fraction and solar attenuation metrics g. Cache tile image and metrics to local filesystem
3. Write manifest JSON with per-place metadata (satellite, band, timestamp, metrics)

Cache structure:

/Library/WebServer/Documents/Canemah/projects/yea3d/atmosphere/
  ├── manifest.json                    # all places, current state
  ├── tiles/
  │   ├── {place_slug}_sky.jpg        # most recent tile
  │   ├── {place_slug}_meta.json      # metrics for this place
  │   └── ...
  └── archive/                         # optional historical tiles
      └── {YYYY-MM-DD}/
          └── {place_slug}_{HH}00.jpg

Database dependency: Read-only access to yea_places table (coordinates, slug, status). Connection via mysqli to the YEA database on Galatea.

7.2 VIIRS Fetcher (Simplified)

Script: viirs_earth_fetcher.py v3.0 Schedule: Existing launchd daemon, daily at 08:15 Change: Remove cloud extraction; retain JPEG fetch and archive only.

7.3 Atmosphere API Endpoint (New)

File: api/atmosphere.php Actions:

The sky action reads from the cached tiles and manifest. The forecast action proxies the Open-Meteo Forecast API with the atmospheric-specific parameter set. The globe action returns metadata for the Three.js widget.

7.4 Frontend Integration

New files:

• fg-atmosphere.js — FG module for Atmosphere panel rendering, card templates, sparkline charts
• Panel CSS additions to panels.css or fieldguide.css

Modified files:

• fg-config.js — Remove VIIRS cloud layer source and cloud-layer map layer; remove FG.cloudsVisible, FG.toggleClouds(), FG._cloudOpacityForZoom(); remove clouds toggle button wiring
• index.php — Remove clouds toggle button from toolbar; add Atmosphere panel markup to drawer; add fg-atmosphere.js script include
• layout.css — Remove cloud toggle button styles

8. Attribution and Compliance

8.1 NASA GIBS

Required acknowledgment per NASA GIBS usage guidelines:

We acknowledge the use of imagery provided by services from NASA's Global Imagery Browse Services (GIBS), part of NASA's Earth Science Data and Information System (ESDIS).

Display in the Sky Now card source line and on the Sources page (sources.php).

8.2 Open-Meteo

Existing attribution arrangement. Open-Meteo has donated 60 days of customer API access to support YEA development. Attribution in Forecast Arc card source line and Sources page.

8.3 NOAA / JMA

GOES satellite data is produced by NOAA. Himawari data is produced by the Japan Meteorological Agency (JMA) and provided to NOAA through a data-sharing agreement. Appropriate credit on the Sources page.

9. Implementation Sequence

Steps 1–2 can proceed immediately as cleanup. Steps 3–5 establish the data pipeline. Steps 6–8 build the frontend. Step 7 can proceed in parallel with steps 3–6.

10. Limitations

1. Geostationary coverage gap: Europe, Africa, and western Asia lack coverage from GOES and Himawari. Approximately 30% of Earth's land surface is in this gap. Meteosat integration is deferred.

2. Visible band daytime only: The Red Visible band requires solar illumination. Nighttime and high-latitude winter conditions fall back to infrared, which is less intuitive for general audiences.

3. Cloud fraction is approximate: Automated cloud classification from a single spectral band is inherently imprecise. Snow/ice confusion in infrared; bright desert confusion in visible. Metrics should be presented as estimates, not measurements.

4. Hourly cache latency: The GOES source updates every 10 minutes, but the Galatea cache refreshes hourly. Sky conditions can change significantly in 60 minutes, particularly for convective environments. The cache frequency may be increased for specific places or weather events in future iterations.

5. Ecological interpretation is AI-generated: The one-liner interpretations and forecast narratives are produced by Claude Haiku and should be understood as informed synthesis, not ground-truth ecological assessment.

11. Relationship to Other YEA Components

Replaces: Phase 6 VIIRS cloud layer overlay on Mapbox globe (removed).

Extends: Current Conditions card (Weather Underground + Open-Meteo) in the Physical Place panel. The Current Conditions card retains its current role for ground-level weather. The Atmosphere panel provides the overhead satellite view and forecast trajectory that contextualizes those ground conditions.

Informs: AI narrative engine. The Atmosphere panel data (cloud fraction, forecast arc, pressure trend) becomes available as context for the Naturalist persona's place narratives, enriching ecological interpretation.

Anticipates: Train a Naturalist longitudinal monitoring system (Sandwalk concept, February 27, 2026). Sky condition snapshots stored over time at bookmarked Nature Places would reveal atmospheric patterns — seasonal fog frequency, storm system tracks, clear-sky windows — as ecological data rather than weather noise.

Document History

End of Specification