localization

src/sun_times.h

@@ -1,24 +1,24 @@
 #pragma once
 #include <Arduino.h>
 
-// Berechnet Sonnenauf-/untergang (lokale Zeit) fuer einen gegebenen Ort und
-// Tag - Grundlage fuer die standortbasierte Nachtdimmung (siehe main.cpp::
-// isNightDimHours()), die das vorherige feste 22:00-06:00-Fenster ersetzt.
+// Calculates sunrise/sunset (local time) for a given location and
+// day - basis for the location-based night dimming (see main.cpp::
+// isNightDimHours()), which replaces the previous fixed 22:00-06:00 window.
 namespace SunTimes {
 
     struct Result {
-        bool valid = false;       // false = Standort noch unbekannt (lat/lon == 0,0)
-        bool alwaysDay = false;   // Polartag: Sonne geht heute an diesem Ort nicht unter
-        bool alwaysNight = false; // Polarnacht: Sonne geht heute an diesem Ort nicht auf
-        float sunriseHour = 0;    // Lokale Dezimalstunde (0-24), nur gueltig wenn weder
-        float sunsetHour = 0;     // alwaysDay noch alwaysNight gesetzt ist.
+bool valid = false;       // false = location still unknown (lat/lon == 0,0)
+        bool alwaysDay = false;   // polar day: sun does not set today at this location
+        bool alwaysNight = false; // polar night: sun does not rise today at this location
+        float sunriseHour = 0;    // local decimal hour (0-24), only valid if neither
+        float sunsetHour = 0;     // alwaysDay nor alwaysNight is set.
     };
 
-    // year/month/day sind lokale Kalenderdatumswerte (z.B. aus localtime_r()),
-    // utcOffsetSeconds die bekannte Zeitzonenverschiebung (siehe
-    // LocationManager::utcOffsetSeconds()). Nutzt den klassischen "Almanac"-
-    // Sonnenauf-/untergangsalgorithmus (Sonnenzenit 90.833 Grad, beruecksichtigt
-    // atmosphaerische Refraktion) - Genauigkeit liegt typischerweise im Bereich
-    // weniger Minuten, fuer eine sanfte Backlight-Dimmung mehr als ausreichend.
+// year/month/day are local calendar date values (e.g. from localtime_r()),
+    // utcOffsetSeconds is the known timezone offset (see
+    // LocationManager::utcOffsetSeconds()). Uses the classic "Almanac"
+    // sunrise/sunset algorithm (solar zenith 90.833 degrees, accounting for
+    // atmospheric refraction) - accuracy is typically within a few minutes,
+    // more than sufficient for smooth backlight dimming.
     Result compute(double lat, double lon, int year, int month, int day, int32_t utcOffsetSeconds);
 }