v1.3.0 — Lunar eclipses, total solar eclipses, and a visual crop frame

The headline: Eclipse Cleaner now handles lunar eclipses, total solar eclipses and planetary footage — every new capability in this release was driven by user reports and shared footage. Thank you all.

Eclipse types

• Presets sun / moon / planetary / custom — the type of eclipse is detected automatically when a video is analyzed (and always overridable, from the page or with --preset). A preset picks the measurement strategies, not just thresholds: lit-region detection, radius estimation by vote-peak scan, and the Hough-vote regime.
• Lunar eclipses — calibrated on real Seestar lunar timelapses kindly shared by users: a video that used to crash the tool with "Aucune mesure valide" now tracks 100 % of its frames. See the new before/after comparison in the README.
• Total solar eclipses — totality (dark disc ringed by the corona) used to defeat the tracker entirely. A dark-disc vote regime now locks the lunar silhouette, one radius is measured per regime (in a total eclipse the Moon's apparent disc is larger than the Sun's), and regime switching uses hysteresis so nothing flickers at the contacts.
• The custom preset reproduces the previous behavior exactly (verified bit-identical on the reference sequence). Existing analyses are re-run once on first open — cache format v8 — and your manual review decisions survive.

Viewer

• Crop frame — the crop window is drawn right on the current frame (its crosshair marks the tracked disc center) and can be resized with the mouse to trade field of view against stabilization margin; ↺ returns to the recommended size, the choice is remembered per video, and the render uses it. Visual design follows @mireianievas' ROI prototype (#1).
• Raw-video player — a collapsible player with play/pause/stop/timeline to watch the source itself, plus a clear loading state while a newly picked video is probed.
• One work folder per video — the analysis cache, review decisions, thumbnails, render and PNG export now live in <video>-eclipse/ next to the source. Files left loose by earlier versions are migrated automatically (and announced) the first time the viewer opens that video.
• No more crash when no frame yields a usable position: the page explains what to try instead.

macOS

• The Browse… dialog is properly fixed: it now opens through osascript (native NSOpenPanel), off the Cocoa main-thread trap — diagnosis and route by @mireianievas (#1), hardened and integrated with co-author credit. The v1.2.2 stopgap remains only where osascript is unavailable.

Documentation

• README (EN/FR): eclipse types and presets, a preset × parameter table, documented bounds for custom analyses, the crop frame, and a lunar before/after comparison.
• Honest known limitations: brightness normalization can blow out the corona during totality, and the planetary preset has not yet been calibrated on real footage — sample videos are very welcome.

As always: Windows SmartScreen will warn on first launch (unsigned program) — More info, then Run anyway; details in the beginners guide.

---

La nouveauté : Eclipse Cleaner traite désormais les éclipses lunaires, les éclipses solaires totales et les vidéos planétaires — chaque capacité de cette version vient des retours et des vidéos partagées par les utilisateurs, merci à tous. Le type d'éclipse est détecté automatiquement (et toujours modifiable) via des presets sun / moon / planetary / custom qui choisissent les stratégies de mesure ; une vidéo lunaire qui faisait planter l'outil est maintenant suivie à 100 % (comparaison avant/après dans le README), et la totalité solaire reste verrouillée sur la silhouette lunaire, couronne stable. Le viewer gagne un cadre de recadrage redimensionnable à la souris directement sur les frames (design du prototype de @mireianievas, #1), un lecteur de la vidéo brute, et un dossier de travail unique par vidéo (<video>-eclipse/, migration automatique annoncée des anciens fichiers). Sous macOS, le bouton Parcourir… est réparé pour de bon (route osascript, diagnostic et prototype de @mireianievas). Le preset custom reproduit exactement le comportement précédent ; les analyses existantes sont refaites une fois à la première ouverture (cache v8), vos décisions de tri sont conservées. SmartScreen avertira au premier lancement : Informations complémentaires puis Exécuter quand même — détails dans le guide débutants.

v1.2.2 — no more crash when clicking Browse… on macOS

Fixed

• On macOS, clicking Browse… killed Python (#4) — the system file dialog was opened from a background thread, which macOS forbids to the point of terminating the process. The viewer no longer attempts it: the page stays up and tells you to pass the video path on the command line instead, in your interface language:

  python -m eclipse viewer /path/to/your/video.mp4
  

  Everything else (thumbnails, analysis, review, render) works normally in the browser. A real native macOS file dialog is planned (#1).

Documentation

• The macOS limitation is now listed under Known limitations in both READMEs.

To update:

python -m pip install --force-reinstall https://github.com/bebkill/Eclipse-Cleaner/archive/refs/heads/main.zip

Windows executable

Unchanged — this release only affects macOS behavior. Download the executable from v1.2.0.

v1.2.1 — pip installs get their data files back

Fixed

• pip installs of the viewer were broken since v1.0.0 — the wheel was missing viewer.html and the interface language files, so the very first request answered nothing and the browser showed ERR_EMPTY_RESPONSE on 127.0.0.1. The data files are now declared in the packaging metadata, and a new CI test builds the wheel and checks they are inside, so this cannot silently come back. (Reported by a user of the beginner guide — thank you!)

If you installed with pip (git, zip, or clone — anything but pip install -e), update with:

python -m pip install --force-reinstall https://github.com/bebkill/Eclipse-Cleaner/archive/refs/heads/main.zip

Windows executable

Unchanged — it was never affected (it bundles its data files separately). Download it from v1.2.0.

v1.2.0 — Standalone Windows executable

The headline: a standalone Windows executable — no Python, no pip, no terminal. Requested by @LuckyHead11 in #3.

Windows executable

• Each release now ships eclipse-cleaner-vX.Y.Z-windows-x64.exe (below, under Assets): download it, double-click it, and the review viewer opens in your browser. Python is no longer needed.
• Double-click = viewer. Without arguments the executable launches the viewer; with arguments it behaves exactly like python -m eclipse — every subcommand (analyze, render, run, viewer) is available.
• Windows SmartScreen will warn on first launch — the program is not signed with a paid publisher certificate. Click More info, then Run anyway. It only asks once; details in the beginners guide.
• The executable is built and verified by CI at every tag: the frozen program must pass a smoke test — a parallel render of a synthetic video through the bundled ffmpeg, and the viewer served over HTTP from its embedded resources — before it is attached here.

Documentation

• The beginners guide now opens with the shortcut (download the exe, nothing else to install), in both languages; both READMEs point to it at the top of Installation.
• A bilingual roadmap lists what is under consideration next (SER input, raw Bayer AVI, choice of output container…), fed by user feedback.

---

La nouveauté : un exécutable Windows autonome — sans Python, sans pip, sans terminal (demandé par @LuckyHead11 dans #3). Chaque release fournit désormais eclipse-cleaner-vX.Y.Z-windows-x64.exe (ci-dessous, sous Assets) : téléchargez, double-cliquez, le viewer s'ouvre dans le navigateur ; avec des arguments, l'exécutable se comporte exactement comme python -m eclipse. Windows SmartScreen avertira au premier lancement (programme non signé) : Informations complémentaires puis Exécuter quand même — détails dans le guide débutants, qui s'ouvre désormais sur ce raccourci. L'exécutable est construit et vérifié par la CI à chaque tag. S'ajoute une feuille de route bilingue, nourrie des retours utilisateurs.

v1.1.2 — Color-stabilization controls polish

Polish of the color-stabilization controls introduced in v1.1.0, based on first-use feedback.

Viewer

• The collapsible section is now titled “parameters” — “stabilization settings” read as if it configured image stabilization (the reframing), which has no settings on the page.
• The two parameter fields align in a column instead of each following its label's length.
• Tooltips now state the typical value and the actual bounds of each parameter.
• The window field is capped at the number of frames of the loaded sequence: beyond it, the tint reference saturates and a larger window changes nothing. This is a UI cap — a value recorded above it (e.g. from the CLI) still works, it simply saturates.

Documentation

• The viewer guide in both READMEs now covers the stabilize color checkbox and its parameters (typical values, window cap and saturation, and the “to redo” staleness marker a change triggers).

---

Polissage des contrôles de stabilisation de couleur de la v1.1.0 : la section s'intitule « paramètres » (l'ancien titre se lisait comme la stabilisation d'image), les champs s'alignent en colonne, les info-bulles portent valeur typique et bornes réelles, et le champ fenêtre est plafonné au nombre d'images de la séquence (au-delà, la référence sature). Les README documentent désormais ces contrôles.

v1.1.1 — Beginner install guides

Documentation release — no code changes.

Step-by-step guides for absolute beginners

Following feedback from a Windows 11 user lost in the README, this release adds BEGINNERS.md and BEGINNERS.fr.md: installing Python from the Microsoft Store, using a terminal for the first time, pasting commands, troubleshooting — linked from a 🔰 box at the top of both READMEs.

Also fixed along the way: pip install git+… requires git, which Windows does not ship. The zip form is now documented everywhere as the alternative:

python -m pip install https://github.com/bebkill/Eclipse-Cleaner/archive/refs/heads/main.zip

---

Version documentaire, sans changement de code : guides d'installation pas à pas pour vrais débutants (BEGINNERS.md / BEGINNERS.fr.md, liés en tête des README), et la forme d'installation zip documentée partout — pip install git+… exige git, absent de Windows par défaut.

v1.1.0 — Exposure & white-balance stabilization

This release addresses the flicker reported on the published timelapse: “the light and white balance keeps changing.”

Brightness — auto-exposure flicker is now actually removed

Exposure was already normalized, but the per-frame gain was computed against a smoothed brightness curve: the frame-to-frame jumps of a phone's auto-exposure lived exactly in the band the smoothing preserved, and passed through untouched. The gain is now inverted on the raw measured level (a median over thousands of lit pixels — its measurement noise is negligible), so real exposure steps are cancelled instead of kept.

White balance — stabilized toward its own trajectory, never toward neutral

Auto white balance oscillates from frame to frame; the sequence's real tint should not. Each channel is now corrected toward a step-preserving reference of the sequence's own chroma trajectory (3-tap binomial + rolling median over 31 frames, capped at ±25 % per channel, luminance-neutral per frame). In practice:

• the oscillation of the phone's auto white balance disappears;
• a red solar filter stays red, a sunset stays warm — this is not a neutralization;
• removing the filter mid-sequence remains a clean, immediate change;
• frames without a usable measurement are left untouched.

Enabled by default. --sans-couleur disables it (brightness stays normalized); --couleur-fenetre and --couleur-amplitude tune it.

Viewer

The render step gains a “stabilize color” checkbox, with a collapsible fine-tuning section (reference window, maximum correction) shown only while the feature is enabled. Settings changed from the page enter the render descriptor, so the pipeline banner correctly reports an existing render as “to redo” after a change — including renders made with v1.0.0, which predate these settings.

---

Cette version corrige le scintillement rapporté sur le timelapse publié (luminosité et balance des blancs). La luminance est désormais corrigée image par image sur le niveau mesuré brut (les sauts d'auto-exposition étaient auparavant préservés par le lissage), et la balance des blancs est stabilisée vers sa propre trajectoire — jamais vers le neutre : un filtre solaire rouge reste rouge, et son retrait en cours de séquence reste un vrai changement. Actif par défaut (--sans-couleur pour désactiver) ; le viewer gagne une case « stabiliser la couleur » avec une section de réglages dépliable.