feat(globe): add real-time solar day/night terminator and shading

Author: KOUSTAV2409

Globe.qml

@@ -34,7 +34,15 @@ Item {
   property color textColor: "#f3f4f5"
   property string fontFamily: "monospace"
 
+  property bool showTerminator: true
+  property var subsolarPoint: RadioModel.subsolarPoint(new Date())
+  property color nightColor: "#040608"
+  property real nightOpacity: 0.44
+  property color terminatorColor: accentColor
+  property real terminatorOpacity: 0.45
+
   property var hoveredStation: null
+
   property real hoverX: 0
   property real hoverY: 0
   property var highlightedStation: null
@@ -428,6 +436,90 @@ Item {
     }
   }
 
+  function paintSolarTerminator(ctx, centreX, centreY, globeRadius) {
+    if (!subsolarPoint) return
+    var sLat = Number(subsolarPoint.latitude) * Math.PI / 180
+    var sLon = Number(subsolarPoint.longitude) * Math.PI / 180
+    var cosSLat = Math.cos(sLat)
+    var sx = cosSLat * Math.cos(sLon)
+    var sy = cosSLat * Math.sin(sLon)
+    var sz = Math.sin(sLat)
+
+    var latitude = centreLatitude * Math.PI / 180
+    var longitude = centreLongitude * Math.PI / 180
+    var sinLatitude = Math.sin(latitude)
+    var cosLatitude = Math.cos(latitude)
+    var sinLongitude = Math.sin(longitude)
+    var cosLongitude = Math.cos(longitude)
+
+    var horizontal = sx * cosLongitude + sy * sinLongitude
+    var sCamX = sy * cosLongitude - sx * sinLongitude
+    var sCamY = cosLatitude * sz - sinLatitude * horizontal
+    var sCamZ = sinLatitude * sz + cosLatitude * horizontal
+
+    var inPlaneLen = Math.hypot(sCamX, sCamY)
+
+    if (inPlaneLen < 1e-4) {
+      if (sCamZ < 0) {
+        ctx.beginPath()
+        ctx.arc(centreX, centreY, globeRadius, 0, Math.PI * 2)
+        ctx.fillStyle = withAlpha(nightColor, nightOpacity)
+        ctx.fill()
+      }
+      return
+    }
+
+    var sunAngleMath = Math.atan2(sCamY, sCamX)
+    var sunAngleScreen = Math.atan2(-sCamY, sCamX)
+    var cosSun = Math.cos(sunAngleMath)
+    var sinSun = Math.sin(sunAngleMath)
+
+    var steps = 64
+    var ellipsePoints = []
+    for (var i = 0; i <= steps; i++) {
+      var t = -Math.PI / 2 + (i / steps) * Math.PI
+      var v = Math.sin(t)
+      var u = -sCamZ * Math.cos(t)
+
+      var x = u * cosSun - v * sinSun
+      var y = u * sinSun + v * cosSun
+
+      var sxScreen = centreX + x * globeRadius
+      var syScreen = centreY - y * globeRadius
+      ellipsePoints.push({ x: sxScreen, y: syScreen })
+    }
+
+    var angleStartScreen = Math.atan2(ellipsePoints[0].y - centreY, ellipsePoints[0].x - centreX)
+    var angleEndScreen = Math.atan2(ellipsePoints[steps].y - centreY, ellipsePoints[steps].x - centreX)
+
+    var awayFromSun = (sunAngleScreen + Math.PI * 3) % (Math.PI * 2)
+    var angleEndWrapped = (angleEndScreen + Math.PI * 2) % (Math.PI * 2)
+    var angleStartWrapped = (angleStartScreen + Math.PI * 2) % (Math.PI * 2)
+
+    var diff = (angleStartWrapped - angleEndWrapped + Math.PI * 2) % (Math.PI * 2)
+    var diffSun = (awayFromSun - angleEndWrapped + Math.PI * 2) % (Math.PI * 2)
+    var anticlockwise = !(diffSun < diff)
+
+    ctx.beginPath()
+    ctx.moveTo(ellipsePoints[0].x, ellipsePoints[0].y)
+    for (var j = 1; j <= steps; j++) {
+      ctx.lineTo(ellipsePoints[j].x, ellipsePoints[j].y)
+    }
+    ctx.arc(centreX, centreY, globeRadius, angleEndScreen, angleStartScreen, anticlockwise)
+    ctx.closePath()
+    ctx.fillStyle = withAlpha(nightColor, nightOpacity)
+    ctx.fill()
+
+    ctx.beginPath()
+    ctx.moveTo(ellipsePoints[0].x, ellipsePoints[0].y)
+    for (var k = 1; k <= steps; k++) {
+      ctx.lineTo(ellipsePoints[k].x, ellipsePoints[k].y)
+    }
+    ctx.strokeStyle = withAlpha(terminatorColor, terminatorOpacity)
+    ctx.lineWidth = Math.min(2.0, Math.max(1.0, globeRadius / 400))
+    ctx.stroke()
+  }
+
   function paintGlobe(ctx) {
     var centreX = globeCanvas.width / 2
     var centreY = globeCanvas.height / 2
@@ -455,6 +547,7 @@ Item {
     ctx.clip()
     paintGrid(ctx, centreX, centreY, globeRadius)
     paintCountries(ctx, centreX, centreY, globeRadius)
+    if (showTerminator) paintSolarTerminator(ctx, centreX, centreY, globeRadius)
     paintSignals(ctx)
     ctx.restore()
 
@@ -543,6 +636,30 @@ Item {
   onVisibleChanged: {
     if (!visible) stopKineticRotation(true)
   }
+  onSubsolarPointChanged: globeCanvas.requestPaint()
+  onShowTerminatorChanged: {
+    if (showTerminator && visible) refreshSolarPosition()
+    globeCanvas.requestPaint()
+  }
+  onNightColorChanged: globeCanvas.requestPaint()
+  onNightOpacityChanged: globeCanvas.requestPaint()
+  onTerminatorColorChanged: globeCanvas.requestPaint()
+  onTerminatorOpacityChanged: globeCanvas.requestPaint()
+
+  function refreshSolarPosition() {
+    root.subsolarPoint = RadioModel.subsolarPoint(new Date())
+  }
+
+  Timer {
+    id: solarTimer
+    interval: 60000
+    running: root.visible && root.showTerminator
+    repeat: true
+    onRunningChanged: {
+      if (running) root.refreshSolarPosition()
+    }
+    onTriggered: root.refreshSolarPosition()
+  }
 
   Canvas {
     id: globeCanvas

README.md

@@ -12,6 +12,7 @@ usual play, pause, previous, and next controls.
 ## Features
 
 - Kinetic drag rotation that highlights a nearby station when it settles, plus deep wheel zoom on a theme-aware globe
+- Real-time solar day/night terminator with night-side shading across the globe
 - A fast cached world view that progressively adds thousands of stations and keeps the session catalog when closed
 - Country stations stay on the session globe and take priority over background signals
 - Country-level map estimates when a station has no published coordinates

RadioAtlas.qml

@@ -113,6 +113,9 @@ Item {
   property color mapSphere: lightTheme ? "#d2d0ca" : "#11151a"
   property color mapLand: lightTheme ? "#a9aaa6" : "#283039"
   property color mapGrid: lightTheme ? "#3f454a" : "#7d8791"
+  property color mapNight: lightTheme ? "#1b2028" : "#040608"
+  property color mapTerminator: accent
+
 
   property bool windowSetupReady: false
   property bool windowFrameReady: false
@@ -1420,7 +1423,10 @@ Item {
             sphereColor: root.mapSphere
             landColor: root.mapLand
             gridColor: root.mapGrid
+            nightColor: root.mapNight
+            terminatorColor: root.mapTerminator
             outlineColor: root.lightTheme ? "#3c4247" : "#9099a3"
+
             signalColor: root.lightTheme ? "#202428" : "#d9dee3"
             accentColor: root.accent
             textColor: root.foreground

RadioModel.js

@@ -567,3 +567,44 @@ function indexByUuid(stations, uuid) {
   for (var i = 0; i < rows.length; i++) if (rows[i].uuid === uuid) return i
   return -1
 }
+
+function subsolarPoint(date) {
+  var d = date || new Date()
+  var ms = d.getTime()
+  var julianDate = ms / 86400000 + 2440587.5
+  var t = (julianDate - 2451545.0) / 36525.0
+
+  var L0 = (280.46646 + t * (36000.76983 + t * 0.0003032)) % 360
+  if (L0 < 0) L0 += 360
+  var M = (357.52911 + t * (35999.05029 - t * 0.0001537)) % 360
+  if (M < 0) M += 360
+  var e = 0.016708634 - t * (0.000042037 + 0.0000001267 * t)
+
+  var C = Math.sin(M * radians) * (1.914602 - t * (0.004817 + 0.000014 * t))
+        + Math.sin(2 * M * radians) * (0.019993 - 0.000101 * t)
+        + Math.sin(3 * M * radians) * 0.000289
+  var sunTrueLong = L0 + C
+
+  var eps0 = 23.439291 - t * (0.013004167 + t * (0.00000016667 - t * 0.000000502778))
+  var omega = 125.04 - 1934.136 * t
+  var eps = eps0 + 0.00256 * Math.cos(omega * radians)
+  var lambdaApparent = sunTrueLong - 0.00569 - 0.00478 * Math.sin(omega * radians)
+
+  var sinDec = Math.sin(eps * radians) * Math.sin(lambdaApparent * radians)
+  var declination = Math.asin(sinDec) * degrees
+
+  var y = Math.pow(Math.tan((eps / 2) * radians), 2)
+  var eot = 4 * degrees * (
+    y * Math.sin(2 * L0 * radians)
+    - 2 * e * Math.sin(M * radians)
+    + 4 * e * y * Math.sin(M * radians) * Math.cos(2 * L0 * radians)
+    - 0.5 * y * y * Math.sin(4 * L0 * radians)
+    - 1.25 * e * e * Math.sin(2 * M * radians)
+  )
+
+  var utcSeconds = d.getUTCHours() * 3600 + d.getUTCMinutes() * 60 + d.getUTCSeconds() + d.getUTCMilliseconds() / 1000
+  var subsolarLong = wrapLongitude(-((utcSeconds / 3600 - 12) * 15 + eot / 4))
+
+  return { latitude: declination, longitude: subsolarLong }
+}
+

tests/model.test.mjs

@@ -334,4 +334,20 @@ assert.deepEqual(
 )
 assert.deepEqual(Array.from(model.stationWindow(playlistRows, "missing", 5)), [])
 
+// Solar day/night terminator tests
+const summerSolstice = model.subsolarPoint(new Date("2026-06-21T12:00:00Z"))
+assert.ok(summerSolstice.latitude > 23.4 && summerSolstice.latitude < 23.5)
+assert.ok(Math.abs(summerSolstice.longitude) < 2)
+
+const winterSolstice = model.subsolarPoint(new Date("2026-12-21T12:00:00Z"))
+assert.ok(winterSolstice.latitude < -23.4 && winterSolstice.latitude > -23.5)
+assert.ok(Math.abs(winterSolstice.longitude) < 2)
+
+const springEquinox = model.subsolarPoint(new Date("2026-03-20T12:00:00Z"))
+assert.ok(Math.abs(springEquinox.latitude) < 0.5)
+
+const midnightUtc = model.subsolarPoint(new Date("2026-03-20T00:00:00Z"))
+assert.ok(Math.abs(midnightUtc.longitude) > 175)
+
 console.log("RadioModel tests passed")
+