Beobachtungsvorschläge rein

docs/BEOBACHTUNGSVORSCHLAEGE_FILTER.md

@@ -0,0 +1,77 @@
+# Berechnung und Filter für Beobachtungsvorschläge
+
+Stand: 15. September 2026. Die GUI ist mit einer eigenständigen Berechnung verbunden. Grundlage sind die Projektstruktur und lesende Abfragen der konfigurierten Datenbank.
+
+## Aufbau
+
+- `public/beobachtungsvorschlaege.php`: Formular, Standardstandort und Sitzungstoken.
+- `public/js/observation_suggestions.js`: Anfrage und Ergebnisliste mit 50 Zielen pro Seite.
+- `public/ajax/observation_suggestions.php`: POST-Endpunkt mit Anmeldung, derselben Seitenberechtigung wie die GUI, CSRF-Prüfung und erneuter serverseitiger Abfrage des Standardstandorts.
+- `public/observation_suggestions_helpers.php`: Katalogauswahl und Python-Prozess mit temporärer JSON-Datei, Shell-freiem Aufruf und 90-Sekunden-Zeitlimit.
+- `public/py/observation_suggestions_api.py`: eigenständige Berechnung mit der lokalen Astronomy-Engine-Bibliothek und dem vorhandenen Kometen-Bahnhelfer `comets.py`. Kein Import und kein Aufruf von `api.py`.
+
+Der Browser darf Filter senden, aber weder fremde Standorte noch Katalogdaten vorgeben. Die Berechnung schreibt keine Daten in die Datenbank. Der Python-Prozess benötigt Python 3.10+ und eine verfügbare Zeitzonendatenbank (`zoneinfo`, auf Windows gegebenenfalls das Paket `tzdata`).
+
+## Zuordnung der Checkboxen
+
+| GUI-Wert | Quelle / Auswahl |
+| --- | --- |
+| `open_clusters` | `dso_objects.object_type_abrev = 'OCl'` |
+| `globular_clusters` | `GCl` |
+| `galaxies` | `G`, `GPair`, `GTrpl`, `GGroup` |
+| `nebulae` | `Neb`, `EmN`, `HII`, `RfN`, `SNR`, `Cl+N` |
+| `planetary_nebulae` | `PN` |
+| `double_stars` | Zunächst `dso_objects` mit `**`; kein vollständiger Doppelsternkatalog |
+| `variable_stars` | Kandidaten aus `star_hipparcos` mit nicht leerem `var`; Periodizität und Ereignisvorhersagen benötigen zusätzliche geprüfte Daten |
+| `comets` | Bahnelemente aus `comets_mpc`; Position und scheinbare Helligkeit zeitabhängig berechnen |
+| `moon`, `planets` | Bestehende astronomische Berechnungen |
+
+`Cl+N` wird eindeutig der Nebel-Auswahl zugeordnet. Mehrere ausgewählte Typen werden vereinigt; ein Objekt soll nur einmal erscheinen.
+
+Nur explizit zugeordnete DSO-Typen berücksichtigen. Insbesondere `Dup` (Dubletten), `NonEx` (nicht existente Objekte), `Other`, einfache Sterne (`*`) und Novae (`Nova`) nicht automatisch übernehmen. Sternassoziationen (`*Ass`) sind vorerst keiner Checkbox zugeordnet.
+
+## Größe und Helligkeit
+
+- Der Größenfilter gilt ausschließlich für die fünf Deep-Sky-Gruppen in der Tabelle, niemals für Einzelsterne, Doppelsterne, Veränderliche, Planeten, Mond oder Kometen.
+- Vorgabe für die maximale Deep-Sky-Größe: 500 Bogensekunden; im Formular änderbar oder durch Leeren aufhebbar.
+- Als Größenmaß dient die große Achse `major_axis`: Bogenminuten × 60 = Bogensekunden. Der Import übernimmt diesen Wert unverändert; die Einheit ist in der [OpenNGC-Katalogbeschreibung](https://github.com/mattiaverga/OpenNGC/blob/master/NGC_guide.txt) dokumentiert. Fehlende oder nicht positive Größen werden bei aktiver Größengrenze ausgelassen.
+- Für Deep Sky die visuelle Helligkeit `v_mag` verwenden. Andere Filterbänder nicht stillschweigend als V-Helligkeit einsetzen. `cstar_v_mag` ist die Helligkeit des Zentralsterns, nicht des gesamten Nebels.
+- Vorgabe: 12 mag oder heller, also numerisch `v_mag <= 12`.
+- Bei aktiver Helligkeitsgrenze Objekte ohne Helligkeitsangabe standardmäßig auslassen. Die neue, zunächst nicht ausgewählte Checkbox `include_unknown_magnitude` erlaubt ihre gesonderte Aufnahme als „Helligkeit unbekannt“. Alle anderen anwendbaren Filter gelten weiterhin.
+- Ohne Helligkeitsgrenze schränkt ein fehlender Helligkeitswert die Auswahl nicht ein.
+- Bei Sternen und Kometen die jeweils passende scheinbare Helligkeit verwenden; die absolute Kometenhelligkeit ist kein direkter Ersatz.
+
+## Beobachtungsnacht
+
+- Standardstandort des Benutzers aus dem gemeinsamen Header verwenden.
+- Datum bezeichnet den Abend bis zum folgenden Morgen; Vorgabe ist heute in der Standortzeitzone.
+- Sonnenhöhe höchstens −12° als Vorgabe. Erste und zweite Hälfte des passenden nächtlichen Zeitfensters sind separat auswählbar, zunächst beide.
+- Höhe, Azimut, Sonnenhöhe und optionalen Mondabstand für den jeweiligen Zeitpunkt berechnen. Die Auswahl der Nachtabschnitte und die Bedingungen müssen gleichzeitig erfüllt sein.
+
+## Verfahren und Genauigkeit
+
+1. Suche zwischen 12 Uhr am gewählten Datum und 12 Uhr am Folgetag in Standortzeit nach Unterschreitungen der Sonnenhöhen-Grenze. Sonnenhöhe: topozentrischer Sonnenmittelpunkt, ohne atmosphärische Refraktion. Übergänge werden im Fünf-Minuten-Raster gesucht und per Intervallhalbierung auf etwa eine Sekunde eingegrenzt.
+2. Teile jeden gefundenen Dunkelabschnitt in zwei gleich lange Hälften. Zeitrechnung erfolgt intern in UTC; dadurch werden Sommerzeitwechsel berücksichtigt. Bei durchgängiger Dunkelheit wird die Begrenzung auf 12 Uhr bis 12 Uhr ausdrücklich angezeigt; bei fehlender Dunkelphase gibt es eine entsprechende Meldung.
+3. Prüfe die ausgewählten Abschnitte alle fünf Minuten einschließlich der Randpunkte. DSO- und Sternkoordinaten werden vom J2000-System in das horizontale System des Beobachters gedreht, einschließlich Präzession/Nutation. Sterneigenbewegung und jährliche Aberration der Katalogsterne sind in dieser Planungsversion nicht enthalten. Höhen sind geometrisch, ohne Refraktion; Azimut zählt von Nord über Ost.
+4. Für Mond und Planeten liefert Astronomy Engine topozentrische Positionen mit Lichtlaufzeit und Aberration sowie modellierte Helligkeiten. Kometen verwenden den vorhandenen Zweikörper-Bahnhelfer, mit iterierter Lichtlaufzeit und Beobachterparallaxe; Bahnstörungen sind nicht enthalten. Bahnepoche und Modellcharakter werden angezeigt.
+5. Prüfe alle Filter gemeinsam an jedem Zeitpunkt. Der Mondabstand greift nur bei Mond über dem geometrischen Horizont und niemals für den Mond selbst. Zusammenhängende passende Messpunkte bilden ungefähre Zeitfenster. Sehr kurze Fenster oder kurze Unterbrechungen zwischen Messpunkten können unentdeckt bleiben.
+6. Die Spalte „Zeit der größten Höhe (ca.)“ zeigt den passenden Messpunkt mit der größten Höhe innerhalb der ausgewählten Filter und Nachtabschnitte. Das muss nicht die Kulmination der gesamten Nacht sein. Höhe, Azimut und Helligkeit der Ergebniszeile beziehen sich auf diesen Zeitpunkt.
+7. Die GUI sortiert zunächst nach Höhe absteigend. Alle acht Spalten sind per Überschrift auf- und absteigend sortierbar, jeweils über die komplette Ergebnisliste vor der Paginierung. Höhe und Azimut sind getrennte Spalten. Zeiten werden nach ihrem tatsächlichen Zeitpunkt, Zahlen numerisch und Objektnamen mit natürlicher Zahlensortierung verglichen. Zeitfenster werden nach ihrem ersten Beginn sortiert. Fehlende Werte der gewählten Sortierspalte bleiben in beiden Richtungen am Ende. Ein Sortierwechsel springt zur ersten Seite; eine neue Berechnung behält die Sortierauswahl bei.
+
+Sichtbarkeit bedeutet hier Erfüllung der gewählten geometrischen und Helligkeitsfilter, keine Garantie für visuelle Erkennbarkeit. Wetter, Seeing, lokale Horizonthindernisse, Teleskopöffnung und Flächenhelligkeit gehen noch nicht in eine Bewertung ein. Veränderliche werden anhand der Kataloghelligkeit gefiltert; aktuelle Helligkeiten und Extremzeiten werden nicht behauptet.
+
+## Prüfung
+
+Ergebnisbegrenzung: Das Feld „Maximal pro Objektgruppe“ ist mit 30 vorbelegt. Der Button „Hellste je Gruppe anzeigen“ wählt aus sämtlichen berechneten Treffern je Checkbox-Gruppe maximal X Objekte nach aufsteigender mag-Helligkeit aus. Bei gleicher Helligkeit entscheidet die größere Höhe, danach Name und Kennung. Unbekannte Helligkeiten werden in dieser Auswahl ausgelassen. Anschließend greifen die gewählten Sortierkriterien und die Paginierung. Die Begrenzung bleibt bei erneuter Berechnung aktiv; „Alle Treffer anzeigen“ hebt sie ohne Neuberechnung auf. Beim ersten Laden ist die Begrenzung noch nicht angewendet.
+
+Mehrfachsortierung in der GUI: Ein normaler Überschriftenklick ersetzt die Sortierkriterien. Umschalt + Klick oder der aktivierte Modus „Weitere Sortierkriterien hinzufügen“ ergänzt ein Kriterium bzw. kehrt die Richtung eines vorhandenen Kriteriums um. Nummerierte Pfeile und ein lesbarer Statustext zeigen die Priorität. Folge-Kriterien entscheiden bei gleichen Werten der vorherigen Kriterien; fehlende Werte folgen innerhalb der jeweiligen Gruppe am Ende. Die Kriterien bleiben bei einer neuen Berechnung erhalten.
+
+`python -m unittest discover -s public/py -p test_observation_suggestions_api.py`
+
+Die Tests prüfen unter anderem Azimut über Norden, Größenausnahmen, Helligkeitsrichtung, Mondabstand, Nachthälften, Sommerzeitwechsel, Polartag/-nacht und die Koordinatentransformation gegen den separaten Horizont-Aufruf der Bibliothek. Zusätzlich wurde ein vollständiger Browserdurchlauf mit echten Katalogdaten, Paginierung und schmalem Bildschirm geprüft; API-Prüfungen deckten fehlende Anmeldung, ungültigen CSRF-Token und unzulässige Filterwerte ab.
+
+## Datenlücken
+
+Bei der Prüfung hatten nur 1.379 von 10.489 einzelnen Galaxien und 9 von 245 DSO-Doppelsternen eine V-Helligkeit. Daher die Option für unbekannte Helligkeiten.
+
+In `star_hipparcos` waren 5.990 Sterne mit nicht leerem `var` vorhanden. Das allein belegt weder eine stabile Periode noch ein bevorstehendes Minimum oder Maximum. Dazu siehe [Datenquellen für veränderliche Sterne](DATENQUELLEN_VERAENDERLICHE_STERNE.md).

docs/DATENQUELLEN_VERAENDERLICHE_STERNE.md

@@ -0,0 +1,98 @@
+# Datenquellen für Minima und Maxima veränderlicher Sterne
+
+Recherchestand: 15. September 2026. Überlegungen für die Seite „Beobachtungsvorschläge“; noch keine Implementierung oder Datenübernahme.
+
+## Empfehlung
+
+Für einen ersten, überschaubaren Sternbestand würde ich **BAV-Vorhersagen als Ausgangspunkt**, **AAVSO VSX für Stammdaten und Referenzen** und **VarAstro beziehungsweise AAVSO-Beobachtungen zur Überprüfung** verwenden. Eine einzige Quelle sollte nicht ungeprüft alle Sterntypen abdecken.
+
+Dabei drei unterschiedliche Datenarten getrennt behandeln:
+
+- **Vorhersagen:** bereits berechnete zukünftige Minima oder Maxima.
+- **Ephemeridenelemente:** Referenzzeitpunkt und Periode, aus denen wir Ereignisse berechnen können.
+- **Beobachtungen:** tatsächlich gemessene Helligkeiten oder Extremzeiten; damit lassen sich Vorhersagen prüfen und aktualisieren.
+
+## 1. BAV – fertige Jahresvorhersagen
+
+Die Bundesdeutsche Arbeitsgemeinschaft für Veränderliche Sterne veröffentlicht das BAV Circular. Heft 1 beschreibt Programme und Anwendung; Heft 2 enthält Ephemeriden unter anderem für Bedeckungsveränderliche, kurzperiodische Pulsatoren und Mirasterne. Auf der Übersichtsseite ist die Ausgabe 2026 verlinkt.
+
+Links:
+
+- [BAV Circular mit Jahresausgaben](https://www.bav-astro.de/index.php/veroeffentlichungen/bav-circular)
+- [BAV: Vorhersagen](https://www.bav-astro.eu/index.php/materialien-beobachter/134-vorhersagen)
+- [BAV Circular 2026, Heft 1: Erläuterungen (PDF)](https://www.bav-astro.eu/images/BAV-Veroeffentlichungen/BAV%20Circular/BAVC_2026_Heft_1.pdf)
+
+**Einschätzung:** Besonders geeignet für den fachlichen Einstieg und als Vergleich für eigene Berechnungen. Die konkrete Abdeckung von Algol und Mira muss im jeweiligen Heft geprüft werden; nicht für jeden Katalogstern gibt es eine Vorhersage.
+
+**Zu beachten:** Laut Heft 1 sind die Vorhersagen in Heft 2 in **MEZ** angegeben, auch während der Sommerzeit. Zur Anzeige als MESZ muss dann eine Stunde hinzukommen. Die Übersicht nennt auch eine Korrektur zu einer früheren Ausgabe: immer Jahr und Berichtigungen beachten. PDF-Zugriff ist belegt; eine dokumentierte maschinenlesbare Schnittstelle wurde hier nicht verifiziert.
+
+## 2. AAVSO VSX – Sternkatalog und Ephemeridenelemente
+
+Der International Variable Star Index liefert unter anderem Veränderlichentyp, Helligkeitsbereich und Periode sowie Literaturhinweise. Bei geeigneten Einträgen steht eine Epoche als Referenz für die Phase zur Verfügung.
+
+Links:
+
+- [VSX-Suche](https://vsx.aavso.org/index.php?ql=1&view=search.top)
+- [VSX-Handbuch (PDF)](https://vsx.aavso.org/_images/Manual.pdf)
+- [VSX: Fragen und Erläuterungen](https://vsx.aavso.org/index.php?view=about.faq)
+
+**Einschätzung:** Geeignet als Grundlage einer kleinen lokalen Sternliste. Suchnamen wären beispielsweise `bet Per` / Algol und `omi Cet` / Mira; Identität und Komponenten müssen am Eintrag geprüft werden.
+
+**Zu beachten:** Die Bedeutung der Epoche hängt vom Sterntyp ab: bei Bedeckungsveränderlichen ein Minimum, bei den meisten Pulsatoren ein Maximum; es gibt Ausnahmen. Die Spalten für maximale und minimale **Helligkeit** sind keine Ereignistermine. Das Handbuch verwendet heliocentrische julianische Tage (HJD) und Perioden in Tagen. Aktualität und Herkunft der Elemente pro Stern prüfen. Eine aktuelle API mit garantierten Feldern und Abrufgrenzen wurde nicht verifiziert.
+
+## 3. VarAstro / tschechische Fachsektion – Bedeckungsminima
+
+VarAstro wird von der Sektion für veränderliche Sterne und Exoplaneten der Tschechischen Astronomischen Gesellschaft betrieben. Das Portal führt die früheren Angebote unter var.astro.cz / var2.astro.cz und das O–C-Gateway fort. Die Fachsektion verweist für Bedeckungsveränderliche ausdrücklich auf Minima-Vorhersagen im Portal.
+
+Links:
+
+- [VarAstro, englischer Einstieg](https://var3.astro.cz/en)
+- [VarAstro, Hauptportal](https://var.astro.cz/cs/Home/)
+- [Fachsektion: Beobachtungsprogramme und Minima-Vorhersagen](https://sphe.astro.cz/en/observation-programs/)
+
+**Einschätzung:** Gute ergänzende Quelle für Algol-artige Sterne: Vorhersagen und gemessene Minima ermöglichen einen Vergleich. Ein O–C-Diagramm zeigt die Differenz zwischen beobachtetem und berechnetem Ereigniszeitpunkt und kann veraltete Elemente sichtbar machen.
+
+**Zu beachten:** Laut Portal stehen die meisten Funktionen erst nach Anmeldung zur Verfügung. Sternabdeckung, Export und automatisierter Abruf wurden nicht geprüft. Alte BRNO-Links sollten nicht ungeprüft als zukünftige Schnittstelle eingeplant werden.
+
+## 4. AAVSO-Beobachtungen – besonders für Mira-Sterne
+
+Die AAVSO International Database enthält Helligkeitsmessungen, die sich über die Datensuche herunterladen lassen. Das ist eine Grundlage, um den aktuellen Verlauf einer Lichtkurve zu beurteilen; sie liefert nicht automatisch fertige Zukunftstermine.
+
+Links:
+
+- [AAVSO: Daten suchen und herunterladen, mit Nutzungshinweisen](https://aavso.org/search-and-download-data/)
+- [AAVSO: Sammlung zu gemessenen LPV-Maxima und -Minima](https://www.aavso.org/index.php/category/tags/maxmin)
+- [Fachartikel: Maxima und O–C-Diagramme für 489 Mirasterne (2013, PDF)](https://www.aavso.org/sites/default/files/jaavso/v41n2/348.pdf)
+
+**Einschätzung:** Für Mira-Vorhersagen sind jüngere Beobachtungen ein wertvoller Abgleich. Historische Extremzeiten helfen, Schwankungen zwischen den Zyklen einzuschätzen.
+
+**Zu beachten:** Bei der Maxima-/Minima-Sammlung unterscheidet AAVSO veröffentlichte Daten bis 2008 und vorläufige spätere Daten. Die tatsächliche zeitliche Abdeckung ist je Stern zu prüfen. Einen laufenden **LPV-Vorhersagedienst für 2026** konnte diese Recherche nicht bestätigen. Der ältere [AAVSO-Bulletin-Link](https://www.aavso.org/aavso-bulletin) ließ sich beim Abruf nicht verifizieren; deshalb vorerst keine zentrale Abhängigkeit darauf aufbauen.
+
+## Wie daraus später Beobachtungsvorschläge werden könnten
+
+Die folgenden Punkte sind ein eigener Umsetzungsvorschlag, keine bereits vorhandene Funktion.
+
+### Algol und andere Bedeckungsveränderliche
+
+Mit einem passenden Referenzminimum `T0` und einer Periode `P` ergibt ein lineares Modell die folgenden gleichartigen Minima als `T(E) = T0 + E × P`, wobei `E` eine ganze Zykluszahl ist. Das reicht nur, solange die Elemente im betrachteten Zeitraum brauchbar sind; jüngere Minima und O–C-Verläufe dienen als Kontrolle. Fachlicher Hintergrund: [SPHE-Beobachtungsprogramme](https://sphe.astro.cz/en/observation-programs/).
+
+Haupt- und Nebenminimum getrennt führen. Andere Extremphasen nicht pauschal durch eine halbe Periode ergänzen: Dafür muss die Lichtkurve beziehungsweise das Modell des Sterns bekannt sein. Für den Einstieg würde ich bei Algol zunächst nur geprüfte Hauptminima vorschlagen.
+
+### Mira und andere langperiodische Pulsatoren
+
+Das VSX-Handbuch weist ausdrücklich auf Zyklusschwankungen bei Miras hin. Eine mittlere Periode ist daher keine Garantie für ein exakt eintretendes Maximum. Quelle: [VSX-Handbuch](https://vsx.aavso.org/_images/Manual.pdf).
+
+Ich würde ein **ungefähres Zeitfenster** um ein erwartetes Maximum ausgeben, möglichst anhand jüngerer Beobachtungen aktualisiert. Breite und Qualität des Fensters müssen aus den konkreten Daten folgen; keine allgemeine Genauigkeit behaupten. Ein Minimum sollte nur erscheinen, wenn dafür eigene belastbare Angaben vorliegen.
+
+### Gemeinsame Anforderungen
+
+- Pro Stern: eindeutige Kennung, Koordinaten, Typ, Helligkeitsbereich mit Filterband und Quellenlink.
+- Pro Ephemeride: Referenzzeit, Periode, Ereignistyp, Zeitstandard, Veröffentlichungs-/Aktualisierungsstand und gegebenenfalls Unsicherheit.
+- Pro Ereignis: „beobachtet“ oder „vorhergesagt“, Herkunft und Genauigkeit kenntlich machen.
+- HJD/BJD und die zugehörige Zeitskala nicht ungeprüft als UTC interpretieren; die Zeitumrechnung vor einer minutengenauen Anzeige fachlich festlegen.
+- Anschließend für den Benutzerstandort prüfen: Stern über dem Horizont, ausreichende Höhe und dunkler Himmel. Ein Ereignistermin allein bedeutet noch keine Beobachtbarkeit.
+- Vor einer Datenanbindung die tatsächlichen Exportmöglichkeiten, Nutzungsbedingungen und Aktualisierungsintervalle der ausgewählten Quellen prüfen.
+
+## Sinnvoller nächster Schritt
+
+Zunächst exemplarisch **Algol und Mira** anhand der aktuellen Einträge und Jahresvorhersagen prüfen: Welche Ereignisse sind vorhanden, wie frisch sind die Grundlagen und stimmen unabhängige Quellen überein? Erst danach eine kleine Auswahl weiterer Sterne aufnehmen und das Importformat entscheiden. Damit bleibt die spätere Umsetzung fachlich prüfbar und überschaubar.