Path analysis: own ground height ASL and highest point of the remote locator square (#133)

* Path analysis: own ground height ASL and highest point of the remote square

Two new settings in the path-analysis section of the Station tab:

- Own ground height ASL (stn_pathAnalysisOwnHeightAslMeters). Empty keeps
  the elevation model value at the own locator centre; a value from -500 to
  9000 m replaces the elevation of the first profile sample. The antenna
  height AGL is still added on top. The field commits on Enter or focus
  loss into the settings draft and reports a refused entry; it keeps the
  operator's spelling while that names the drafted number, because the
  draft is Compose state and would otherwise swap "25" for "25.0" under
  the cursor right after Enter.
- Target station on the highest point of its locator square
  (stn_pathAnalysisDxHighestPointInSquare, on by default). The remote square
  is sampled on a 5 x 5 grid of cell centres in one batched request against
  the Open-Meteo provider, the highest sample becomes the path end with its
  position and elevation. LocatorHighestPointResolver caches the result per
  locator for the session and backs off five minutes after a failure
  (failure list pruned and bounded); the analysis then falls back to the
  square centre and that result is not kept.

Both settings are drafted like the other path-analysis settings and take
effect with Apply/Close or Save; the reachability service reads the stored
values only.

The lookup runs on the reachability thread only. Building a request peeks
the resolver cache without blocking, so a cached square moves the endpoint
right away. The calculation key now includes the own height and the remote
ground elevation at full precision, and the switch, so changing either
recalculates.

Also assign the result of sanitizeEffectiveEarthRadiusFactor in the
PathAnalysisRequest constructor; it was called and dropped. No behaviour
change: the sanitizer is the identity for valid factors, and the analysis
service sanitizes again.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>

* Document own ground height and highest-point setting of the path analysis

Changelog v1.50 (New), configuration and features pages in English and
German, and the terrain section of PROJECT_CONTEXT.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>

---------

Co-authored-by: Claude Opus 5.5 <noreply@anthropic.com>

github_docs/de-Changelog.md

@@ -28,6 +28,8 @@ Mehrere Operateure an einem Rechner können jetzt eigene Rufzeichen, Locators un
 
 - **Windows-Installer:** Neben dem portablen ZIP-Paket gibt es für Windows bei Stable-Releases jetzt einen MSI-Installer (`KST4Contest-v<Version>-windows-x64.msi`). Er installiert KST4Contest ohne Administratorrechte für das aktuelle Benutzerkonto, legt einen Startmenü-Eintrag und eine Desktop-Verknüpfung an und ersetzt bei einem Update die vorhandene Installation. Einstellungen und Datenbank bleiben unter `%USERPROFILE%\.praktiKST` und werden mit einer portablen Kopie geteilt. Damit ist die erste Stufe von [Issue #61](https://github.com/praktimarc/kst4contest/issues/61) umgesetzt.
 
+- **Eigene Standorthöhe und höchster Punkt des Gegenstationsfelds in der Streckenanalyse:** Der Reiter **Station** hat im Abschnitt der Streckenanalyse zwei neue Einstellungen. **Eigene Standorthöhe über NN, Meter** ersetzt den Wert des Höhenmodells am eigenen Locatormittelpunkt durch die Höhe des tatsächlichen Standorts; bleibt das Feld leer, entscheidet wie bisher das Höhenmodell. **Gegenstation auf dem höchsten Punkt ihres Locatorfelds**, standardmäßig eingeschaltet, lässt die Strecke am höchsten von 25 abgetasteten Punkten des Locatorfelds der Gegenstation enden statt in dessen Mitte, weil Conteststationen meist vom höchsten Punkt ihres Feldes aus arbeiten. Die Suche kostet pro Gegenstationsfeld und Sitzung eine zusätzliche Anfrage an den Höhendienst; schlägt sie fehl, rechnet die Analyse wie bisher mit der Feldmitte.
+
 ### Geändert
 
 - **Zwischenspeicher der Geländeprofile getrennt:** Berechnete Geländeprofile liegen jetzt in der eigenen, gemeinsam genutzten Datei `terrainprofilecache.db` und werden nach Besitzer getrennt gespeichert. Bisher wurde der gesamte Zwischenspeicher gelöscht, sobald sich Rufzeichen oder Locator änderten; bei einem Profilwechsel wäre damit jedes berechnete Profil verloren gegangen.

github_docs/de-Funktionen.md

@@ -965,6 +965,8 @@ Aus den Höhenpunkten berechnet KST4Contest unter anderem:
 
 Die eingestellte eigene Antennenhöhe wird zur lokalen Geländehöhe addiert. Für die Gegenstation wird derzeit eine feste angenommene Antennenhöhe von 10 Metern über Grund verwendet.
 
+Standardmäßig endet die Strecke am höchsten Punkt des Locatorfelds der Gegenstation, nicht in dessen Mitte; die lokale Geländehöhe lässt sich durch die tatsächliche Höhe des eigenen Standorts ersetzen. Beide Einstellungen sind unter [Streckenanalyse und Link-Budget](de-Konfiguration#streckenanalyse-und-link-budget) beschrieben.
+
 Bewegst du die Maus über das Profil, wird der dazugehörige Abfragepunkt zusätzlich auf der Karte markiert. Dadurch lässt sich ein auffälliger Berg oder Geländeeinschnitt leichter einer geografischen Position zuordnen.
 
 ### Welche Frequenz wird für die Berechnung verwendet?

github_docs/de-Konfiguration.md

@@ -72,13 +72,21 @@ Die Stationskarte verwendet mehrere Werte aus dem Reiter **Station**, um das Gel
 | Einstellung | Verwendung |
 |---|---|
 | **Own antenna height AGL** | Höhe der eigenen Antenne über dem lokalen Gelände in Metern |
+| **Eigene Standorthöhe über NN, Meter** | Optional: Geländehöhe des eigenen Standorts über dem Meeresspiegel. Leer lassen, um das Höhenmodell zu verwenden |
 | **Own TX power W** | Eigene Sendeleistung in Watt |
 | **Own ant. gain dBi** | Gewinn der eigenen Antenne in dBi |
 | **DX OM TX power W** | Angenommene Sendeleistung der Gegenstation in Watt |
 | **DX OM ant. gain dBi** | Angenommener Antennengewinn der Gegenstation in dBi |
+| **Gegenstation auf dem höchsten Punkt ihres Locatorfelds** | Lässt die Strecke am höchsten Punkt des Locatorfelds der Gegenstation enden statt in dessen Mitte (standardmäßig eingeschaltet) |
 
 **AGL** bedeutet *Above Ground Level*. Trage hier nicht die Höhe über dem Meeresspiegel ein. Die Geländehöhe am eigenen Standort stammt bereits aus dem Höhenprofil; KST4Contest addiert die konfigurierte Antennenhöhe zu diesem Wert.
 
+Dieses Feld nimmt nur die Antennenhöhe über Grund auf; für die Höhe des Standorts über dem Meeresspiegel gibt es ein eigenes Feld, das im nächsten Absatz beschrieben ist.
+
+Das Höhenprofil nimmt die Geländehöhe am Mittelpunkt des eigenen Locatorfelds. Liegt der tatsächliche Standort deutlich höher oder tiefer, etwa auf einem Hügel am Rand des Feldes, trägst du seine Geländehöhe unter **Eigene Standorthöhe über NN, Meter** ein. KST4Contest verwendet dann diesen Wert statt des Höhenmodells und addiert die Antennenhöhe weiterhin darauf. Zulässig sind Werte von -500 bis 9000 Metern. Ein leeres Feld stellt das Höhenmodell wieder her. Die eigene Position auf der Karte und im Profil bleibt der Locatormittelpunkt.
+
+Ein Locator sagt nur, in welchem Feld eine Gegenstation steht, nicht wo darin. Conteststationen arbeiten meist vom höchsten Punkt ihres Feldes aus. Ist **Gegenstation auf dem höchsten Punkt ihres Locatorfelds** eingeschaltet, tastet KST4Contest das Feld der Gegenstation mit einem Raster von 5 x 5 Punkten ab, nimmt den höchsten davon und lässt die Strecke dort enden, mit Position und Höhe dieses Punktes. Die Suche braucht je Locatorfeld der Gegenstation eine Anfrage an den Online-Höhendienst; das Ergebnis bleibt bis zum Beenden von KST4Contest erhalten. Schlägt die Suche fehl, rechnet die Analyse wie bisher mit der Feldmitte und versucht es einige Minuten später erneut.
+
 Für die Gegenstation verwendet KST4Contest derzeit eine feste Antennenhöhe von 10 Metern über dem lokalen Gelände. Sendeleistung und Antennengewinn der Gegenstation stammen aus den beiden **DX OM**-Feldern. Diese Werte sind bewusst nur Annahmen: Der ON4KST-Chat überträgt weder die tatsächliche Antennenhöhe noch die vollständigen Stationsdaten der Gegenstation.
 
 Antennengewinne müssen in `dBi` eingetragen werden. Liegt ein Wert in `dBd` vor, muss vor der Eingabe `2.15 dB` addiert werden:

github_docs/en-Changelog.md

@@ -28,6 +28,8 @@ Several operators sharing one computer can now use their own callsigns, locators
 
 - **Windows installer:** next to the portable ZIP package, stable releases now also ship an MSI installer for Windows (`KST4Contest-v<version>-windows-x64.msi`). It installs KST4Contest for the current user account without administrator rights, adds a Start menu entry and a desktop shortcut, and replaces the existing installation on an update. Settings and database stay under `%USERPROFILE%\.praktiKST` and are shared with a portable copy. This implements the first stage of [Issue #61](https://github.com/praktimarc/kst4contest/issues/61).
 
+- **Own site height and highest point of the remote square in the path analysis:** the **Station** tab has two new settings in its path-analysis section. **Own ground height ASL, metres** replaces the elevation-model value at the own locator centre by the height of the actual site; left empty, the elevation model decides as before. **Target station on the highest point of its locator square**, on by default, ends the path at the highest of 25 sampled points of the remote locator square instead of at its centre, because contest stations usually operate from the high ground of their square. The lookup costs one additional request to the elevation service per remote square and session; if it fails, the analysis uses the square centre as before.
+
 ### Changed
 
 - **The terrain profile cache is separate:** computed terrain profiles now live in their own shared file `terrainprofilecache.db` and are stored per owner. Previously the whole cache was dropped whenever the callsign or locator changed, which would have discarded every computed profile on each profile switch.

github_docs/en-Configuration.md

@@ -68,13 +68,21 @@ The station map uses several values from the **Station** tab to calculate the te
 | Setting | Use |
 |---|---|
 | **Own antenna height AGL** | Height of the local antenna above the surrounding terrain in metres |
+| **Own ground height ASL, metres** | Optional: ground elevation of the own site above sea level. Leave empty to use the elevation model |
 | **Own TX power W** | Local transmit power in watts |
 | **Own ant. gain dBi** | Gain of the local antenna in dBi |
 | **DX OM TX power W** | Assumed transmit power of the remote station in watts |
 | **DX OM ant. gain dBi** | Assumed antenna gain of the remote station in dBi |
+| **Target station on the highest point of its locator square** | Ends the path at the highest point of the remote locator square instead of at its centre (on by default) |
 
 **AGL** means *Above Ground Level*. Do not enter the height above sea level. The terrain elevation at the local station already comes from the elevation profile; KST4Contest adds the configured antenna height to this value.
 
+This field is for the antenna height above ground only; the height of the site above sea level, if you want to set it, has its own field, described next.
+
+The elevation profile takes the local terrain elevation at the centre of the own locator square. If the actual site lies noticeably higher or lower, for example on a hill at the edge of the square, enter its ground elevation in **Own ground height ASL, metres** (**ASL**: *Above Sea Level*). KST4Contest then uses this value instead of the elevation model and still adds the antenna height on top. Values from -500 to 9000 metres are accepted. An empty field restores the elevation model. The own position on the map and in the profile remains the locator centre.
+
+A locator only tells which square a remote station is in, not where in it. Contest stations usually operate from the high ground of their square, so with **Target station on the highest point of its locator square** switched on, KST4Contest samples the remote square on a grid of 5 x 5 points, takes the highest of them and ends the path there, at that point's position and elevation. The lookup needs one request to the online elevation service per remote locator square; the result is kept until KST4Contest is closed. If the lookup fails, the analysis uses the centre of the square as before and tries again a few minutes later.
+
 For the remote station, KST4Contest currently uses a fixed antenna height of 10 metres above the local terrain. Its transmit power and antenna gain come from the two **DX OM** fields. These values are deliberately assumptions: ON4KST provides neither the actual antenna height nor the complete station data of the remote operator.
 
 Antenna gains must be entered in `dBi`. Add `2.15 dB` before entering a value specified in `dBd`:

github_docs/en-Features.md

@@ -949,6 +949,8 @@ The profile combines:
 
 The configured **Own antenna height AGL** is added to the terrain elevation at the local station. For the remote station, KST4Contest currently assumes an antenna height of 10 metres above the local terrain.
 
+By default the path ends at the highest point of the remote station's locator square, not at its centre; the local terrain elevation can be replaced by the actual height of the own site. Both settings are described under [Path Analysis and Link Budget](en-Configuration#path-analysis-and-link-budget).
+
 Moving the mouse over the path profile marks the corresponding position on the map. This makes it easier to identify which hill or terrain section causes a reported obstruction.
 
 ### Frequency selection