ASTRO-ZENTRIERER
================
Version 1.0.1

Zentriert einen hellen, rundlichen Himmelskoerper (Sonne, Mond, Planet --
auch als Sichel, z.B. waehrend einer Finsternis) automatisch in einer
Serie von Fotos, damit daraus eine ruhige Zeitraffer-Sequenz ohne
Springen/Wackeln wird.


INSTALLATION
------------
Keine. Einfach AstroZentrierer.exe an einen beliebigen Ort kopieren (z.B.
Desktop oder in den Bilderordner) und doppelklicken. Kein Python, keine
weitere Software noetig.


WARNUNG BEIM ERSTEN START
--------------------------
Windows zeigt beim ersten Start moeglicherweise die Meldung
"Windows hat den Start dieser App verhindert" (SmartScreen), weil das
Programm nicht mit einem kostenpflichtigen Zertifikat signiert ist.
Das ist normal fuer kleine, frei weitergegebene Programme.

  -> Auf "Weitere Informationen" klicken
  -> Dann auf "Trotzdem ausfuehren"

Falls stattdessen der Virenschutz die Datei blockiert oder loescht: das
ist eine bekannte Fehlmeldung ("false positive"), die bei mit PyInstaller
gepackten Programmen haeufiger vorkommt, weil sich viele solcher Programme
aehnlich verhalten wie manche Schadsoftware (sie entpacken sich selbst beim
Start). Datei ggf. aus der Quarantaene wiederherstellen bzw. eine Ausnahme
dafuer eintragen. Das Programm greift auf nichts ausserhalb der von dir
gewaehlten Ordner zu und braucht keine Internetverbindung.


BENUTZUNG
---------
1. AstroZentrierer.exe starten.
2. Bei "Bilder-Ordner" ueber "Durchsuchen..." den Ordner mit deinen Fotos
   waehlen.
3. Der "Ausgabe-Ordner" wird automatisch als Unterordner "centered"
   vorgeschlagen, kann aber geaendert werden.
4. Optionen nach Bedarf anpassen (siehe unten) oder einfach bei den
   Standardeinstellungen belassen.
5. "Start" druecken. Fortschritt und Meldungen erscheinen im Protokoll-
   fenster. Am Ende zeigt eine Zusammenfassung, wie viele Bilder erfolgreich
   verarbeitet wurden.

Tipp: Mit dem Knopf "Vorschau..." (neben "Start") laesst sich VOR einem
grossen Lauf pruefen, ob die Erkennung fuer die eigene Bilderserie
funktioniert -- ein Fenster zeigt das gewaehlte Bild mit eingezeichnetem
erkanntem Rand (gruener Kreis) und Mittelpunkt (rotes Kreuz), dazu die
genauen Zahlenwerte. Mit "Vorheriges"/"Naechstes" durch die ganze Serie
blaettern, um mehrere Bilder stichprobenartig zu pruefen, oder mit "Bild
waehlen..." gezielt ein einzelnes (auch ausserhalb des Bilder-Ordners)
anschauen. Passt der erkannte Kreis nicht zum sichtbaren Rand, hilft das
direkt beim Einschaetzen, welche der erweiterten Optionen anzupassen sind
(siehe unten).

Sobald ein Bilder-Ordner gewaehlt ist, zeigt die Spalte "Alle Bilder"
sofort die komplette, sortierte Liste aller gefundenen Dateinamen -- auch
VOR einem Lauf schon nutzbar. Ein einfacher Klick auf eine Zeile zeigt
sofort rechts im Feld "Live-Erkennung" das gewaehlte Bild mit
eingezeichnetem erkanntem Rand (gruener Kreis) und Mittelpunkt (rotes
Kreuz) -- so laesst sich jedes Bild der Serie einzeln durchklicken und
pruefen, ohne extra ein neues Fenster zu oeffnen. Ein Doppelklick oeffnet
zusaetzlich das groessere Vorschau-Fenster mit Vor/Zurueck-Navigation
durch die ganze Serie.

Das Feld "Live-Erkennung" nimmt die gesamte Fensterhoehe auf der rechten
Seite ein und zeigt dabei nicht das ganze Originalfoto (das Objekt waere
darin oft nur ein kleiner Punkt), sondern einen Ausschnitt, der auf den
erkannten Rand zugeschnitten und zentriert ist -- der gruene Kreis fuellt
so einen Grossteil des Vorschaubilds und laesst sich viel leichter
beurteilen, gerade bei einer duennen Sichel. Das gilt auch fuer das
Vorschau-Fenster (Doppelklick bzw. Knopf "Vorschau...").

WAEHREND eines Laufs aktualisiert sich das Live-Erkennung-Feld automatisch
mit dem jeweils zuletzt verarbeiteten Bild (per Haekchen "Live-Vorschau
waehrend der Verarbeitung anzeigen" abschaltbar, falls das bei sehr
grossen Serien etwas Zeit kostet) -- die passende Zeile in "Alle Bilder"
wird automatisch mitmarkiert/mitgescrollt. Sobald Schritt 1 (Erkennung)
fertig ist -- also noch waehrend Schritt 2 laeuft -- werden die Zeilen der
Bilder mit unplausibler Erkennung rot (komplett ausgelassen) bzw. orange
(interpoliert) eingefaerbt. (Ob ein Bild unplausibel ist, steht technisch
erst nach der Erkennung ALLER Bilder fest, weil dabei der Gesamtverlauf
verglichen wird -- eine Faerbung schon waehrend Schritt 1 ist deshalb
nicht moeglich, die Liste selbst ist aber von Anfang an vollstaendig
sichtbar und anklickbar.)


WICHTIGSTE OPTIONEN
--------------------
- Fortlaufend nummerieren: benennt die Ausgabedateien 001_..., 002_..., usw.,
  damit sie garantiert in der richtigen Reihenfolge fuer eine Zeitraffer-
  Software einsortiert werden.
- nur Nummer als Dateiname: wie oben, aber ohne den Originalnamen
  (001.jpg statt 001_original.jpg).
- Groesse ueberall angleichen: skaliert die Bilder zusaetzlich so, dass
  das Objekt ueberall gleich gross erscheint. Bei Aufnahmen nahe am
  Horizont (Auf-/Untergang) besser ausgeschaltet lassen, da die scheinbare
  Groesse dort real kleiner wird.
- Ziel-Position: "Bildmitte" zentriert auf die Bildmitte (Standard),
  "Median aller Bilder" zentriert stattdessen auf die durchschnittliche
  erkannte Position (kann bei sehr ungleichmaessig gerahmten Serien
  weniger Bildrand verschenken).
- Glaettung (Frames): standardmaessig 0 (aus) -- das ist fast immer die
  bessere Wahl, da die Einzelbild-Erkennung meist praeziser ist als ein
  ueber Nachbarbilder gemittelter Wert. Nur bei sehr duenner Sichel (kurzer
  sichtbarer Rand-Bogen) probehalber auf z.B. 2.5 stellen, falls dort noch
  Zittern auffaellt.


WENN DIE ZENTRIERUNG NICHT SAUBER AUSSIEHT
--------------------------------------------
Im Ausgabeordner liegt neben den Bildern eine Datei "alignment_log.csv".
Darin steht fuer jedes Bild, ob die Erkennung als plausibel akzeptiert
wurde (Spalte "accepted"). Steht dort bei einem Bild "False", wurde es
verworfen und stattdessen zu seinen Nachbarn interpoliert -- das ist bei
einzelnen, verstreuten Bildern normal und gewollt (schuetzt genau vor dem
Springen) und kein Problem fuer sich. Auffaellig wird es erst, wenn sehr
viele Bilder AM STUECK "False" sind (lange zusammenhaengende Bloecke) --
dann konnte sich die Erkennung fuer diesen Abschnitt nicht mehr sauber
einpendeln, meist am Ende einer Serie bei tiefstehendem/verdecktem Objekt.

Am schwierigsten ist grundsaetzlich die Phase der staerksten Verfinsterung
bzw. duennsten Sichel: dort ist nur noch ein kurzer Bogen des Rands
sichtbar, wodurch die Kreiserkennung weniger gut bestimmt ist als bei
voller/halber Scheibe. Einzelne staerkere Ausreisser genau in dieser Phase
sind daher am ehesten zu erwarten.

Falls trotzdem noch zu viele Bilder verworfen werden oder die Zentrierung
nicht ueberzeugt, unter "Erweiterte Optionen anzeigen" versuchen:

- "Erkennungs-Aufloesung (1/N)" steht standardmaessig schon auf 1 (volle
  Aufloesung, am genauesten). Nur bei sehr grossen Fotos und wenn
  Geschwindigkeit wichtiger als Praezision ist, auf 2 oder 4 stellen.
- "Radius-Toleranz (%)" erhoehen, wenn sich die scheinbare Groesse in der
  Serie tatsaechlich stark aendert (z.B. nahe am Horizont).
- "Sprung-Toleranz (Faktor)" nur erhoehen, wenn sich das Objekt zwischen
  zwei Bildern nachweislich stark bewegt (z.B. sehr grosse Zeitabstaende
  zwischen Aufnahmen) -- ein zu hoher Wert laesst wieder mehr
  Fehlerkennungen durch.

AUSLASSEN STATT RATEN: WARUM MANCHMAL WENIGER BILDER HERAUSKOMMEN
--------------------------------------------------------------------
Manchmal zeigt ein einzelnes Foto das Objekt wirklich an einer anderen
Stelle als seine Nachbarn -- z.B. durch eine kurze Kamera-Erschuetterung
(Windstoss), eine Wolke oder ein Objekt im Vordergrund, das kurz die
Erkennung gestoert hat. Das ist kein Fehler im Programm: es wertet nur
aus, was im Foto zu sehen ist, und kann eine so entstandene, aber echte
Verschiebung nicht von einer "richtigen" Position unterscheiden.

Frueher hat das Programm solche Bilder zu ihren Nachbarn interpoliert
(eine Position geraten). Das hat sich in der Praxis als schlechter
erwiesen, als das betroffene Bild einfach auszulassen: eine geratene
Position kann selbst wie ein kleiner Sprung wirken. Deshalb werden
Bilder mit unplausibler Erkennung jetzt standardmaessig komplett
ausgelassen -- die Ausgabe wird danach luecken los neu durchnummeriert,
sodass daraus trotzdem eine zusammenhaengende Zeitraffer-Sequenz entsteht
(nur eben mit etwas weniger Bildern als Quellfotos vorhanden waren; bei
mehreren hundert Fotos faellt eine Handvoll fehlender Bilder in der
fertigen Sequenz praktisch nicht auf).

Ueber "Erweiterte Optionen" -> "Sprung-Toleranz" laesst sich diese
Schwelle anpassen; per Kommandozeile steuert "--skip-run-threshold" direkt,
ab welcher Lauflaenge verworfener Bilder ausgelassen statt interpoliert
wird (Default 1 = jedes verworfene Bild einzeln). Wer stattdessen lieber
alle Bilder behalten und geratene Positionen fuer einzelne Ausreisser in
Kauf nehmen moechte, kann diesen Wert per Kommandozeile auf 0 setzen.

Die Datei "alignment_log.csv" zeigt genau, welche Bilder ausgelassen
wurden (Spalte "skipped" = True) bzw. nur interpoliert (Spalte "accepted"
= False, "skipped" = False).

Voraussetzung fuer eine gute Erkennung ist immer: das Objekt ist der
deutlich hellste, weitgehend freistehende Bereich im Bild vor einem
dunklen Hintergrund (typisch fuer Sonnenaufnahmen mit Sonnenfilter oder
Mond-/Planetenaufnahmen am dunklen Nachthimmel). Ist das Objekt stark
durch Gebaeude, Baeume o.ae. verdeckt, kann die automatische Erkennung
unzuverlaessig werden. Bei einem verfinsterten ("roten") Vollmond waehrend
der Totalitaet kann der Kontrast zum Himmel stark absinken -- am besten
mit ein paar echten Bildern aus dieser Phase ueber "Vorschau..." pruefen,
ob die Erkennung dort noch sauber sitzt. Bei Planeten mit sichtbaren
Ringen (z.B. Saturn) wird der Ring aktuell mit in die Kreis-Anpassung
einbezogen, was den erkannten Mittelpunkt/Radius verfaelschen kann.
