Data

Tools

Indexes

Applications

Experiments

Awesome

An open API service indexing awesome lists of open source software.

https://github.com/jeamy/tile_compile

Toolkit for tile-based quality reconstruction of astronomical image stacks
https://github.com/jeamy/tile_compile

dwarf stacking two-seestar

Last synced: 21 days ago
JSON representation

Toolkit for tile-based quality reconstruction of astronomical image stacks

Awesome Lists containing this project

README 

          
# Tile-Compile



Tile-Compile is a toolkit for **tile-based quality reconstruction** of astronomical image stacks (methodology v3.3).



We present a novel methodology for the reconstruction of high-quality astronomical images from short-exposure deep-sky datasets. Conventional stacking methods often rely on binary frame selection ("lucky imaging"), which discards significant portions of collected frames. Our approach, **Tile-Based Quality Reconstruction (TBQR)**, replaces rigid frame selection with a robust spatio-temporal quality model. By decomposing frames into local tiles and modeling quality along two orthogonal axes—global atmospheric transparency/noise and local structural sharpness—we reconstruct a signal that is physically and statistically optimal at every pixel. We demonstrate that this method preserves the full photometric depth of the dataset while achieving superior resolution improvement compared to traditional reference stacks.



While the methodology was originally conceived to address the specific challenges of short-exposure data from modern smart telescopes (e.g., Dwarf, Seestar), its architectural flexibility makes it equally potent for conventional astronomical setups. The extensive set of tunable parameters—ranging from adaptive tile sizing and cross-correlation thresholds to sophisticated clustering logic—allows the pipeline to be meticulously optimized for a wide array of optical systems and atmospheric conditions.



> **Practical note:** The pipeline is primarily optimized for datasets with many usable frames. With very small frame counts, or with strongly mixed frame quality in one stack, visible tile patterns can occur in difficult cases. This can often be mitigated by testing different configuration settings (especially registration, tile, and reconstruction-related parameters). See the example profiles in `tile_compile_cpp/examples/` and `tile_compile_cpp/examples/README.md`.



> **Note:** This is experimental software primarily developed for processing images from smart telescopes (e.g., DWARF, Seestar, ZWO SeeStar, etc.). While designed for general astronomical image processing, it has been optimized for the specific characteristics and challenges of smart telescope data.



## Documentation (v3.3)



- Normative methodology: [Tile-Based Quality Reconstruction Methodology v3.3.9](doc/v3/tile_basierte_qualitatsrekonstruktion_methodik_v_3.3.9_en.md)

- Methodology paper PDF v3.3.6: [paper-tile_based_quality_reconstruction_methodology_v_3.3.6_en.pdf](doc/v3/paper-tile_based_quality_reconstruction_methodology_v_3.3.6_en.pdf)

- Implementation process flow: [Process flow (English)](doc/v3/process_flow/README_en.md)

- English step-by-step guide: [Step-by-Step Guide](doc/tbqr_step_by_step_en.md)

- GUI2 expert input guide (English): [Expert Input Step-by-Step](doc/gui2/expert_input_step_by_step.md)

- GUI2 guided wizard guide (English): [Guided Wizard Step-by-Step](doc/gui2/guided_wizard_step_by_step.md)

- GUI2 dashboard run guide (English): [Dashboard Run Step-by-Step](doc/gui2/dashboard_run_step_by_step.md)

- German README snapshot: [German README](README_de.md)

- Data flow (user-friendly): [Process Flow – How the System Works](doc/v3/process_flow/data_flow_user_description_en.md)



## Paper Example Data Sources



- M31 lights source for the paper example run (10 GB): [M31 lights](https://wolke.eibrain.org/index.php/s/Z88dmWizEJYjwBe) 

- M31 run source for the paper example run (20 GB): [M31 run](https://wolke.eibrain.org/index.php/s/tfSycSNEzdL7jje)



Given a directory of FITS lights, the pipeline can:



- optionally **calibrate** lights (bias/dark/flat)

- **register** frames using a robust fallback cascade

- compute **global and local (tile) quality metrics**

- reconstruct the image via tile-weighted overlap-add

- optionally cluster frame states and build synthetic frames

- **stack** using sigma-clip or weighted averaging

- **debayer** OSC/CFA data

- run **astrometry** (WCS)

- run optional **background gradient extraction** (BGE, pre-PCC)

- run **photometric color calibration** (PCC)

- write final outputs and detailed diagnostic artifacts



## Active Components



| Component | Directory | Status | Stack |

|-----------|-----------|--------|-------|

| Core pipeline | `tile_compile_cpp/` | Active | C++17 + Eigen + OpenCV + cfitsio + yaml-cpp |

| GUI2 backend | `web_backend_cpp/` | Active | Crow + C++17 |

| GUI2 frontend | `web_frontend/` | Active | HTML + CSS + JavaScript |



## Pipeline Phases



In practical use, the overall workflow is intentionally simple: after you provide the input data and a manageable set of configuration parameters, the pipeline processes the dataset automatically from stacking through astrometry, optional background handling, and PCC to the final result. No complicated manual intermediate steps are required for a normal run. At the same time, the system remains fully configurable in depth, so every stage can still be tuned in fine detail whenever you need tighter control over registration, tiling, reconstruction, stacking, or post-processing behavior.



| ID | Phase | Description |

|----|-------|-------------|

| 0 | SCAN_INPUT | Input discovery, mode detection, linearity check, disk-space precheck |

| 1 | REGISTRATION | Cascaded global registration |

| 2 | PREWARP | Full-frame canvas prewarp (CFA-safe for OSC) |

| 3 | CHANNEL_SPLIT | Metadata phase (channel model) |

| 4 | NORMALIZATION | Linear background-based normalization |

| 5 | GLOBAL_METRICS | Global frame metrics and weights |

| 6 | TILE_GRID | Adaptive tile geometry |

| 7 | COMMON_OVERLAP | Common valid-data overlap (global/tile-local masks) |

| 8 | LOCAL_METRICS | Local tile metrics and local weights |

| 9 | TILE_RECONSTRUCTION | Weighted overlap-add reconstruction |

| 10 | STATE_CLUSTERING | Optional state clustering |

| 11 | SYNTHETIC_FRAMES | Optional synthetic frame generation |

| 12 | STACKING | Final linear stacking |

| 13 | DEBAYER | OSC demosaic to RGB (MONO pass-through) |

| 14 | ASTROMETRY | Plate solving / WCS |

| 15 | BGE | Optional RGB background gradient extraction before PCC |

| 16 | PCC | Photometric color calibration |

| 17 | DONE | Final status (`ok` or `validation_failed`) |



Detailed phase docs: `doc/v3/process_flow/`



## Registration Cascade (Fallback Strategy)



| Stage | Method | Typical use case |

|-------|--------|------------------|

| 1 | Primary engine (`triangle_star_matching`) | Normal star-rich frames |

| 2 | Trail endpoint registration | Star trails / rotation-heavy data |

| 3 | AKAZE feature matching | General feature fallback |

| 4 | Robust phase+ECC | Clouds/nebulosity with larger transforms |

| 5 | Hybrid phase+ECC | Weak star matching cases |

| 6 | Identity fallback | Last resort (CC=0, frame retained) |



## Configuration



- Main config file: `tile_compile.yaml`

- Schemas: `tile_compile.schema.json`, `tile_compile.schema.yaml`

- Reference document: [Configuration Reference](doc/configuration_reference_en.md)

- Practical examples: [Configuration Examples & Best Practices](doc/configuration_examples_practical_en.md)



### Example profiles



Complete standalone example configs are available under `tile_compile_cpp/examples/`.

The filenames no longer use the old `tile_compile.` prefix.



- `full_mode.example.yaml`

- `reduced_mode.example.yaml`

- `emergency_mode.example.yaml`

- `smart_telescope_dwarf_seestar.example.yaml`

- `smart_telescope_very_bright_star.example.yaml`

- `canon_low_n_high_quality.example.yaml`

- `very_bright_star_anti_seam.example.yaml`

- `canon_equatorial_balanced.example.yaml`

- `mono_full_mode.example.yaml`

- `mono_small_n_anti_grid.example.yaml` (recommended for MONO low-frame datasets, e.g. ~10..40, to reduce tile-pattern risk)

- `mono_small_n_ultra_conservative.example.yaml` (recommended for very small MONO datasets, e.g. ~8..25, when seam stability matters more than aggressive enhancement)



See also: [Examples README](tile_compile_cpp/examples/README.md) for the intended use case and tuning focus of each profile.



## Binary Releases (GUI2)



Pre-built GUI2 release bundles are published via [GitHub Releases](https://github.com/jeamy/tile_compile/releases).



Each bundle contains:



- GUI2 frontend (`web_frontend/`)

- Crow backend (`web_backend_cpp/`)

- native C++ tools (`tile_compile_runner`, `tile_compile_cli`, `tile_compile_web_backend`)

- launchers for Linux, macOS, and Windows



At runtime, GUI2 uses the local Crow/C++ backend as the process adapter for the C++ runner/CLI.



## Quickstart



### GUI2 (recommended)



Development start from repository root:



```bash

./start_backend.sh

```



Then open:



```text

http://127.0.0.1:8080/ui/

```



Release bundle start:



- Linux: `start_gui2.sh`

- macOS: `start_gui2.command`

- Windows: `start_gui2.bat`



The launcher copies the bundled payload into a per-user install directory, starts the Crow backend in the foreground, and opens the browser to the local GUI2 URL.



**Installation and update behavior:**



- On first start, the launcher copies all application files to `~/tilecompile/` (Linux/macOS) or `%USERPROFILE%\tilecompile\` (Windows).

- After the first successful start, you can safely delete the downloaded package archive and extracted folder—all data has been copied to your user directory.

- On updates, only the application files (`web_frontend/`, `web_backend_cpp/`, `tile_compile_cpp/`) are replaced. Your user data (configurations, runs, ASTAP catalog, PCC database) remains untouched.



macOS install note:



- On macOS 15.x (including Sequoia 15.1), Gatekeeper may no longer offer the older right-click override path for unknown developers. If `start_gui2.command` or other scripts are blocked, open `System Settings -> Privacy & Security`, scroll to the bottom, and explicitly allow the blocked `start_gui2.command` there before starting it again.



Minimum OS versions for the current GUI2 release bundles:



- Linux: x86_64 Linux with `glibc >= 2.35` (Ubuntu 22.04 or equivalent is the safe baseline for the current CI-built ZIPs)

- macOS: macOS 15

- Windows: Windows 10 x64 or newer



Notes:



- macOS support is currently intended from version 13 upward. It is not restricted to macOS 15+, but macOS 12 and older are not the documented release baseline.

- Linux bundles do not bundle `glibc`, so older distributions than the current build baseline are not guaranteed to work.



### C++ CLI / runner



For a full beginner-friendly walkthrough, see:

[Step-by-Step Guide](doc/tbqr_step_by_step_en.md)



### Build Requirements



- CMake >= 3.21

- C++17 compiler (GCC 11+ or Clang 14+)

- OpenCV >= 4.5

- Eigen3

- cfitsio

- yaml-cpp

- nlohmann-json



#### GPU acceleration requirements



The pipeline supports two GPU backends:



**NVIDIA CUDA (opencv_cuda):**

- Requires OpenCV CUDA modules:

  - `opencv2/core/cuda.hpp`

  - `opencv2/cudawarping.hpp`

  - `opencv2/cudaarithm.hpp`

- At runtime, a CUDA-capable NVIDIA GPU and working CUDA/OpenCV runtime are required.

- `TILE_COMPILE_ENABLE_CUDA` only enables the CUDA hook/build gate.



**AMD/Intel/NVIDIA OpenCL (opencv_opencl):**

- Requires OpenCV OpenCL module:

  - `opencv2/core/ocl.hpp`

- At runtime, an OpenCL-capable GPU (AMD, Intel, NVIDIA) and working OpenCL runtime are required.

- Works with AMD Radeon (Polaris/Vega/RDNA), Intel integrated GPUs, and NVIDIA GPUs.

- Generally easier to set up than CUDA on non-NVIDIA hardware.



**Auto-selection:**

- `acceleration_backend: auto` (default) automatically detects available GPU backends at runtime.

- Priority order: CUDA → OpenCL → CPU

- Falls back gracefully to CPU if no GPU backend is available.



Notes:



- Many default distro/Homebrew/OpenCV packages provide CPU-only builds. GPU acceleration requires OpenCV built with CUDA or OpenCL support.

- For NVIDIA GPUs: CUDA backend typically provides better performance than OpenCL.

- For AMD/Intel GPUs: OpenCL is the only supported GPU backend.

- On macOS: OpenCL support depends on OpenCV build; CUDA is not practical.



#### Package install examples



Linux (Ubuntu/Debian):



```bash

sudo apt-get update

sudo apt-get install -y \

  build-essential cmake pkg-config \

  libeigen3-dev libopencv-dev libcfitsio-dev libyaml-cpp-dev nlohmann-json3-dev libssl-dev \

  libcurl4-openssl-dev

```



Linux (Fedora):



```bash

sudo dnf install -y \

  gcc-c++ cmake pkgconf-pkg-config ninja-build \

  eigen3-devel opencv-devel cfitsio-devel yaml-cpp-devel nlohmann-json-devel openssl-devel \

  libcurl-devel

```



macOS (Homebrew, core libs):



```bash

xcode-select --install

brew install cmake ninja pkg-config eigen cfitsio yaml-cpp nlohmann-json openssl curl

brew install opencv

```



Notes:



- `ninja` is required for the local GUI2 packaging scripts.

- On macOS 12, the default Homebrew `opencv` formula is currently not supported. The Homebrew-based path therefore effectively requires macOS 15 for OpenCV, unless you provide a separate working OpenCV installation yourself.

- The package examples above are sufficient for CPU builds. They do not guarantee GPU acceleration, because the OpenCV package on the host may not include CUDA modules.

- If a downloaded GUI2/release bundle is blocked by Gatekeeper with messages such as “developer cannot be identified” or a bundled `.dylib` cannot be opened, remove the quarantine flag from the extracted release folder with `xattr -dr com.apple.quarantine /path/to/extracted_release` and then start the bundle again.



Windows:



- MinGW/MSYS2: `mingw-w64-x86_64-eigen3`, `mingw-w64-x86_64-opencv`, `mingw-w64-x86_64-cfitsio`, `mingw-w64-x86_64-yaml-cpp`, `mingw-w64-x86_64-nlohmann-json`, `mingw-w64-x86_64-openssl`, `mingw-w64-x86_64-curl`, `mingw-w64-x86_64-pkgconf`

- MSVC/vcpkg: `eigen3`, `opencv`, `cfitsio`, `yaml-cpp`, `nlohmann-json`, `openssl`, `curl`, `pkgconf`



### Build



```bash

cd tile_compile_cpp

mkdir -p build && cd build

cmake .. -DCMAKE_BUILD_TYPE=Release

cmake --build . -j$(nproc)

```



### Release build + packaging



GUI2 release bundles are built by:



- `.github/workflows/release-tile-compile-gui2.yml`



The workflow builds the Qt-free C++ binaries, bundles `web_backend_cpp/` and `web_frontend/`, adds the GUI2 launchers, and creates ZIP artifacts for Linux, Windows, macOS Apple Silicon, and macOS Intel.



Not included by design:



- external Siril catalog data

- external ASTAP binary/data

  

### Docker Build + Run (recommended for isolated environments)



A helper script is available at:

`tile_compile_cpp/scripts/docker_compile_and_run.sh`



What it does:



- `build-image`: builds a Docker image and compiles `tile_compile_cpp` inside the container

- `run-shell`: starts an interactive shell in the compiled container

- `run-app`: runs `tile_compile_runner` directly in the container



Default runs volume mapping:



- Host: `tile_compile_cpp/runs`

- Container: `/workspace/tile_compile_cpp/runs`



Examples:



```bash

# build Docker image and compile inside container

./tile_compile_cpp/scripts/docker_compile_and_run.sh build-image



# open interactive shell inside container

./tile_compile_cpp/scripts/docker_compile_and_run.sh run-shell



# run pipeline in container

./tile_compile_cpp/scripts/docker_compile_and_run.sh run-app -- run \

  --config /mnt/config/tile_compile.yaml \

  --input-dir /mnt/input \

  --runs-dir /workspace/tile_compile_cpp/runs

```



Use `run-shell` if you need additional mounts (e.g., config/input directories) and then start the runner manually.



#### Windows notes (Docker / CLI workflow)



Use a Linux shell (WSL2 Ubuntu) to run the helper script:



```bash

bash scripts/docker_compile_and_run.sh build-image

bash scripts/docker_compile_and_run.sh run-app -- run --config /mnt/config/tile_compile.yaml --input-dir /mnt/input --runs-dir /workspace/tile_compile_cpp/runs

```



### CLI Runner



```bash

./tile_compile_runner \

  run \

  --config ../tile_compile.yaml \

  --input-dir /path/to/lights \

  --runs-dir /path/to/runs

```



Common options:



- `--max-frames ` limit frames (`0` = no limit)

- `--max-tiles ` limit tile count for Phase 5/6 (`0` = no limit)

- `--dry-run` execute validation flow without full processing

- `--run-id ` custom run id for grouping

- `--stdin` with `--config -` to read YAML from stdin



Resume mode:



```bash

./tile_compile_runner resume \

  --run-dir /path/to/runs/ \

  --from-phase BGE

```



Supported resume phases: `ASTROMETRY`, `BGE`, `PCC`.



### CLI Scan



```bash

./tile_compile_cli scan /path/to/lights --frames-min 30

```



### Other CLI Possibilities



```bash

# validate config

./tile_compile_cli validate-config --path ../tile_compile.yaml



# list available runs

./tile_compile_cli list-runs /path/to/runs



# inspect one run

./tile_compile_cli get-run-status /path/to/runs/

./tile_compile_cli get-run-logs /path/to/runs/ --tail 200

./tile_compile_cli list-artifacts /path/to/runs/

```



### GUI2 integration



The recommended UI path is the web-based GUI2:



- backend: `web_backend_cpp/`

- frontend: `web_frontend/`

- orchestration: Crow backend -> `tile_compile_cli` / `tile_compile_runner`



Development start:



```bash

./start_backend.sh

```



Open `http://127.0.0.1:8080/ui/`.



## Outputs



After a successful run (`runs//`):



- `outputs/`

  - `stacked.fits`

  - `reconstructed_L.fit`

  - `stacked_rgb.fits` (OSC)

  - `stacked_rgb_solve.fits` / WCS artifacts

  - `stacked_rgb_bge.fits` (BGE-only snapshot before PCC)

  - `stacked_rgb_pcc.fits`

  - `synthetic_*.fit` (mode-dependent)

- `artifacts/`

  - `normalization.json`

  - `global_metrics.json`

  - `tile_grid.json`

  - `global_registration.json`

  - `local_metrics.json`

  - `tile_reconstruction.json`

  - `state_clustering.json`

  - `synthetic_frames.json`

  - `bge.json`

  - `validation.json`

  - `report.html`, `report.css`, `*.png`

- `logs/run_events.jsonl`

- `config.yaml` (run snapshot)



## External Sources (PCC and Astrometry)



For optional color calibration and astrometric solving, the pipeline can use external data/tools:



- **Siril Gaia DR3 XP sampled catalog** (for PCC)

  - Can be reused if already downloaded by Siril.

  - Typical local path: `~/.local/share/siril/siril_cat1_healpix8_xpsamp/`

  - Upstream source (catalog release): `https://zenodo.org/records/14738271`

- **ASTAP** (for astrometry / WCS plate solving)

  - Requires ASTAP plus a star database (e.g., D50 for deep-sky use).

  - Official site/downloads: `https://www.hnsky.org/astap.htm`



If these resources are not installed, core reconstruction still works, but ASTROMETRY/PCC phases may be skipped or fail depending on configuration.



## Diagnostic Report (`report.html` via C++ backend)



Generate an HTML quality report from a finished run either via GUI2 or directly through the CLI:



```bash

./tile_compile_cli generate-report runs/

```



Output:



- `runs//artifacts/report.html`

- `runs//artifacts/report.css`

- `runs//artifacts/*.png`



The report aggregates data from artifact JSON files, `logs/run_events.jsonl`, and `config.yaml`, including:



- normalization/background trends

- global quality distributions and weights

- registration drift/CC/rotation diagnostics

- tile and reconstruction heatmaps

- clustering/synthetic frame summaries

- BGE diagnostics (grid cells, residuals, channel shifts)

- validation metrics (including tile-pattern indicators)

- pipeline timeline and frame-usage funnel



## Calibration (Bias / Dark / Flat)



- Master frames (`bias_master`, `dark_master`, `flat_master`) can be used directly

- Directory-based masters (`bias_dir`, `darks_dir`, `flats_dir`) can be built automatically

- `dark_auto_select: true` matches darks by exposure time (±5%)



## Project Structure



```text

tile_compile/

├── web_frontend/           # GUI2 HTML/CSS/JS frontend

├── web_backend_cpp/        # GUI2 Crow/C++ backend

├── tile_compile_cpp/

│   ├── apps/                # runner/cli entry points

│   ├── include/tile_compile/

│   ├── src/

│   ├── examples/            # example configs

│   ├── scripts/             # helper scripts

│   ├── tests/

│   ├── tile_compile.yaml

│   ├── tile_compile.schema.json

│   └── tile_compile.schema.yaml

├── packaging/gui2/          # GUI2 release launchers/bundle helpers

├── docker/                  # Docker build/runtime images

├── doc/

│   ├── v3/                  # methodology and process-flow docs

│   └── gui2/                # GUI2 concept/reference docs

├── start_backend.sh         # dev start for Crow backend + GUI2

├── start_gui2_docker.sh     # run GUI2 in Docker

├── README.md

└── README_de.md

```



## Tests



```bash

cd tile_compile_cpp/build

ctest --output-on-failure

```



## Attribution



This project was built with assistance from Windsurf (agentic AI coding assistant), GPT 5.*,Claude 4.* Sonnet. Babysitting by a human in a virtual environment.



## Versions



## v0.1.D (2026-04-04)



- Added `registration.auto_engine` (default: `true`): automatically detects strong field rotation from a small frame probe before registration and overrides the engine to `triangle_star_matching` + `transform_model: affine` when a rotation-blind engine (`robust_phase_ecc`, `hybrid_phase_ecc`) is configured for an Alt/Az dataset. The override threshold is controlled by `auto_engine_rotation_threshold_deg` (default: `0.05°/frame`).



## v0.1.C (2026-04-03)



- Stabilized tile reconstruction after the recent performance optimization rollout, with follow-up fixes and analysis focused on visible tile-seam artifacts in the final reconstruction output.



## v0.1.B (2026-03-31)



- Fixed the late PCC/output path semantics: `stacked_rgb.fits` remains the stacking output, successful `BGE`/`PCC` snapshots stay separated as `stacked_rgb_bge.fits` / `stacked_rgb_pcc.fits`, and `output_stretch` now uses only a pure linear `0..max -> 0..65535` scaling with obsolete nonlinear/quantile stretch code removed.



## v0.1.A (2026-03-29)



- Stabilized the late RGB/PCC output path after the `v3.3.9` rollout: visible RGB stretching now preserves chroma instead of amplifying weak background channel offsets, PCC background neutralization gained the new `always|auto|off` control with a nebulosity-aware auto guard, and the new parameter was propagated through schema, docs, and all example configs.



## v0.1.9 (2026-03-28)



- Promoted the `v3.3.9` methodology into the active reference state across code, frontend, and documentation: the linear reconstruction core, BGE/PCC semantics, Parameter Studio visibility, and process-flow docs now align to the same runtime baseline; backend startup handling was hardened as well.



## v0.1.8 (2026-03-25)



- Improved Linux packaging scripts to bundle all required shared libraries (OpenCV, CFITSIO, yaml-cpp, etc.) for better cross-distribution compatibility and reduced dependency issues.



## v0.1.7 (2026-03-24)



- Fixed Linux AppImage packaging to export `TILE_COMPILE_INPUT_SEARCH_ROOTS` so directory scanning works correctly in packaged releases.

- Enhanced GUI2 file browser to always show parent directory (..) even when not yet granted, triggering permission dialog on click for seamless navigation.



## v0.1.6 (2026-03-24)



- Reworked GUI2 queue/batch handling and run monitoring: batch tabs in Run Monitor, batch-targeted stats/report actions, timestamped queue-root naming with hours/minutes, and updated EN/DE documentation.



## v0.1.5 (2026-03-23)



- Stabilized `PREWARP` for OpenCL and extended GPU acceleration with OpenCL equivalents for the previously CUDA-only `TILE_RECONSTRUCTION` and `STACKING` paths, including sigma-clipping and overlap-add accumulation.



## v0.1.4 (2026-03-22)



- Added a real artifact-based `STACKING` resume path in the C++ runner so `resume --from-phase STACKING` rebuilds from `synthetic_*.fit`/`canvas_mask.fits` instead of replaying the entire pipeline.

- Fixed one synthetic/tile overlap-add weighting failure mode so zero/invalid pixels no longer contribute Hann weights. This removes that specific darkening mechanism, but residual internal line artifacts may still have other causes.



## v0.1.3 (2026-03-21)



- Added per-frame registration provenance and chain-depth tracking in the C++ registration artifacts, including stricter blind-chain anchor rules to limit drift through weak sequential rescue chains.

- Fixed GUI2 resume/run-monitor status updates so the active phase/status becomes visible immediately without requiring a manual page refresh.



## v0.1.2 (2026-03-20)



- Fixed Alt/Az registration validation to score warps on the actual common overlap instead of the cropped full-frame canvas.

- Relaxed over-aggressive CC outlier rejection for long rotating sessions by keeping the CC threshold absolute instead of run-global MAD-relative.

- Fixed field-rotation model extrapolation outside the span of valid registrations so edge/tail frames use bounded bridge prediction instead of unstable local polynomial blow-up.



## v0.1.1 (2026-03-19)



- Improved GUI2 tool persistence and PCC save handling, including temporary-output based saving and cross-platform temp-path behavior.

- Hardened backend memory usage and significantly reduced BGE autotune runtime on the IC434 reference run while preserving the selected solution behavior.



## v0.1.0 (2026-03-18)



- Fixed Astrometry/PCC tool path inputs being overwritten by backend defaults.



## v0.0.F (2026-03-17)



- Promoted the DSO tile-reconstruction methodology to `v3.3.8` in EN/DE and aligned it with the active runtime semantics.

- Corrected the normative method text for runtime-configured mode thresholds, neighborhood-aware local metric normalization, sigma-clipped tile reconstruction, and affine post-OLA photometric restoration.

- Fixed GUI2 run-name reset so changing the input directory clears the shared `run_name` across dashboard, wizard, and input-scan.

- Added a macOS 15 / Sequoia Gatekeeper note for `start_gui2.command` and blocked package approval via `System Settings -> Privacy & Security`.

- Switched ASTAP `d80` catalog downloads to platform-specific upstream packages: Linux `.deb`, macOS `.pkg`, Windows `.exe`.



## v0.0.E (2026-03-15)



- Wired `assumptions.frames_min` into the active runner mode-gate and `assumptions.reduced_mode_cluster_range` into reduced-mode clustering.engine

- Removed stale `assumptions.pipeline_profile`, `assumptions.frames_optimal`, and `assumptions.exposure_time_tolerance_percent` from the active config/schema/frontend/docs/examples surface.

- Regenerated the C++ schema and synchronized Parameter Studio, Assumptions UI, and methodology/reference docs with the active runtime semantics.



## v0.0.D (2026-03-15)



- Expanded `TILE_RECONSTRUCTION` boundary diagnostics to separate raw vs. normalized tile mismatches and exclude masked canvas zones from the metric.

- Added artifact visibility for `tile_norm_bg_*` and `tile_norm_scale` to diagnose whether per-tile normalization itself amplifies visible seams.

- Synchronized GUI2 `run_name` and `runs_dir` across dashboard, wizard, and input-scan, including direct editing on the input-scan page.



## v0.0.C (2026-03-13)



- GUI2 parameter/config handling synchronized with the current C++ config schema, defaults, and reference docs.

- Added boundary diagnostics for visible tile mismatches in `TILE_RECONSTRUCTION` and removed the ineffective dedicated seam-correction config block.

- Expanded run-monitor resume handling, live-log detail visibility, and config revision/template flows.



## v0.0.B (2026-03-12)



- Added server-side persistence for the GUI2 UI draft state via backend API/state storage.

- Migrated UX-relevant frontend parameters away from local browser storage to a central server-backed UI state.

- Synchronized run names, preset selections, config drafts, validation state, and tool inputs/results more consistently across dashboard, parameter studio, wizard, and tools.



## v0.0.A (2026-03-12)



- Bugfixes



## v0.0.9 (2026-03-11)



- Added Linux AppImage generation to the GitHub Actions release workflow.

- Reworked PCC background-noise handling and connected UI/report updates so current PCC diagnostics are exposed more consistently in the GUI.



## v0.0.8 (2026-03-11)



- zero-copy COMMON_OVERLAP

- Scratch reuse in LOCAL_METRICS

- reduced lock contention in tile_weighted-OLA

- faster sigma-clip kernel

- fewer tile copies in tile_weighted path

- parallel BGE autotune candidate evaluation



## v0.0.7 (2026-03-11)



- Supports now:

  - Linux: x86_64 Linux with `glibc >= 2.39` (Ubuntu 24.04 or equivalent is the safe baseline for the current CI-built ZIPs)

  - macOS: macOS 15

  - Windows: Windows 10 x64 or newer



## v0.0.6 (2026-03-11)



- Completed the productive migration to the Crow/C++ backend.

- Integrated C++ report generation.

- Updated launcher scripts, Docker packaging, and GitHub workflows to build and run the C++ backend directly.



## v0.0.5 (2026-03-09)



- Promoted GUI2 as the recommended interface with a web frontend, FastAPI backend, and cross-platform release bundles.

- Expanded DE/EN i18n coverage in the GUI2 frontend and parameter studio, with aligned docs and backend config handling.

- Moved the previous Qt6 GUI path into `legacy/` and clarified the actively maintained GUI2 packaging/start workflow.



## v0.0.4 (2026-03-06)



- Fixed Alt/Az registration for datasets with large field rotation.



## v0.0.3 (2026-03-05)



- Improved BGE/PCC pipeline with clearer phase visibility, stronger guardrails, and a more consistent config surface.

- Expanded parallel execution in compute-heavy stages.

- Multiple phase optimizations for more stable behavior and lower runtime overhead.



## v0.0.2 (2026-02-16)



- First release with pre-built packages for Windows, Linux, and macOS

- Includes GUI, CLI, and runner executables

- Experimental release for testing purposes



## v0.0.1 (2026-02-15)



- First public release



## Changelog



### (2026-04-04)



**Auto-engine for Alt/Az field rotation + registration failure fix (`v0.1.D`):**



- Added `registration.auto_engine` (default: `true`): probes a small set of frames before registration starts and automatically overrides the engine to `triangle_star_matching` + `transform_model: affine` when a rotation-blind engine (`robust_phase_ecc`, `hybrid_phase_ecc`) is configured but strong field rotation is detected. Threshold: `auto_engine_rotation_threshold_deg` (default: `0.05°/frame`, covers Alt/Az at any exposure time while staying well below EQ residual rotation).

- Fixed a complete registration failure mode: `engine: robust_phase_ecc` with `allow_rotation: true` on Alt/Az datasets produced NCC ≈ 0 for all frames, causing 469/470 frames to fall back to identity transform (`model_nearest_copy`) with no actual alignment.

- Updated `tile_compile.yaml` default engine to `triangle_star_matching` and `reject_cc_min_abs` to `0.05`.

- Propagated new config fields to all schemas, example configs, and documentation.



### (2026-04-03)



**Tile-reconstruction stabilization after recent optimization rollout (`v0.1.C`):**



- Stabilized tile reconstruction after the recent performance optimization rollout, with follow-up fixes and analysis focused on visible tile-seam artifacts in the final reconstruction output.



### (2026-03-29)



**RGB/PCC output-path stabilization after the `v3.3.9` rollout (`v0.1.A`):**



- Reworked the visible RGB output stretch so it operates luminance-aware and keeps chroma stable instead of exaggerating small background channel offsets into large blue/gray edge bands.

- Added `pcc.background_neutralization_mode = always|auto|off` with a new auto guard that attenuates or suppresses background neutralization when the measured "background" behaves like diffuse field signal rather than neutral sky.

- Synchronized the new PCC control through schema, defaults, reference docs, and all example configurations so the runtime, documentation, and example surface now expose the same behavior.



### (2026-03-28)



**Implementation and rollout of the `v3.3.9` methodology (`v0.1.9`):**



- Moved the key `v3.3.9` methodology changes into the active runtime path: linear reconstruction core without the old pre-OLA tile normalization, cleaner BGE/PCC semantics, more robust support/seam handling, and updated guards/diagnostics.

- Updated the frontend and configuration surface to the current schema/methodology baseline so new `v3.3.9` parameters are exposed more consistently in Parameter Studio and related documentation.

- Refreshed the process-flow, reference, and comparison documents for `v3.3.9`, and additionally hardened Crow/C++ web-backend startup so failures now report a clear fatal error instead of producing a core dump.



### (2026-03-24)



**AppImage packaging fix + file browser navigation enhancement (`v0.1.7`):**



- Fixed Linux AppImage packaging in `packaging/gui2/start_gui2.sh` to export `TILE_COMPILE_INPUT_SEARCH_ROOTS` environment variable, resolving directory scanning failures in packaged releases where relative paths could not be resolved.

- Enhanced GUI2 file browser (`web_frontend/tooltips.js`) to always display parent directory (..) navigation even when the parent path is not yet granted, showing a lock icon (🔒) for restricted paths and triggering the permission grant dialog on click for seamless upward navigation.

- Updated backend file listing route (`web_backend_cpp/src/routes/system_routes.cpp`) to return `parent_allowed` flag alongside `parent` path, enabling frontend to distinguish between accessible and restricted parent directories.



**GUI2 batch/queue run-monitor refresh + docs update (`v0.1.6`):**



- Reworked the GUI2 Run Monitor for queue/batch runs: queue entries now appear as tabs, redundant duplicate batch/filter rows were removed, and top-level batch/structure summary visibility was corrected again for queued runs.

- Enabled batch-targeted post-run actions in the Run Monitor so `Generate Stats`, stats-folder opening, and report opening can operate on the currently selected finished batch tab instead of only the active root/current run.

- Changed unnamed queue-root naming from date-only to `YYYYMMDD_HHMM`, making batch-root directories less collision-prone and aligning the dashboard/wizard path hints with the actual behavior.

- Expanded the EN/DE step-by-step guides with explicit batch/queue usage notes, including the primary MONO multi-filter use case and Run Monitor tab behavior.



### (2026-03-23)



**OpenCL expansion for `PREWARP`, `TILE_RECONSTRUCTION`, and `STACKING` (`v0.1.5`):**



- Stabilized the OpenCL `PREWARP` path for multi-threaded execution by guarding OpenCV OpenCL/T-API access and forcing explicit host copies where needed.

- Extended `tile_compile_cpp/src/core/acceleration.cpp` with OpenCL equivalents for the previously CUDA-only `TILE_RECONSTRUCTION` and `STACKING` paths, including sigma-clipping and overlap-add accumulation/normalization.



### (2026-03-22)



**Real `STACKING` resume + synthetic OLA seam fix (`v0.1.4`):**



- Implemented a true artifact-based `STACKING` resume path in `tile_compile_cpp/apps/runner_resume.cpp`, so `resume --from-phase STACKING` now rebuilds the stacked outputs directly from existing `synthetic_*.fit` plus `canvas_mask.fits` and continues with later phases instead of triggering an in-place full rerun.

- Fixed one overlap-add accumulation failure mode in `tile_compile_cpp/src/core/acceleration.cpp`: zero/invalid tile pixels no longer add Hann weights to `weight_sum`. This removes that specific darkening path, but residual internal seams/lines may still have other causes.



### (2026-03-21)



**Registration provenance/depth diagnostics + resume status visibility (`v0.1.3`):**



- Extended `tile_compile_cpp/apps/runner_phase_registration.cpp` so each frame now carries explicit registration provenance (`direct_global`, `sequential_rescue`, `temporal_rescue`, modeled variants, etc.) plus `chain_depth`, and writes that information into `global_registration.json`.

- Tightened blind sequential chaining: weak `sequential_rescue` frames no longer act as effectively unlimited anchors; anchor reuse is now capped by chain depth unless correlation is strong enough.

- Added aggregate registration diagnostics such as source counts, maximum observed chain depth, and blocked blind-chain-anchor attempts to the registration artifact metadata.

- Fixed GUI2/backend resume status handling so the monitor subtitle and phase state update immediately after `resume`, including the case where the runner has started but the next `resume_start` event has not yet been written to the run log.



### (2026-03-20)



**Registration/field-rotation stabilization for long Alt/Az sessions (`v0.1.2`):**



- Fixed global registration validation in `tile_compile_cpp/` so NCC comparisons are computed only on the actual valid overlap mask of the warped frame instead of on the cropped full-frame canvas. This prevents correct larger-rotation warps from being rejected just because rotated corners fall outside the fixed proxy image.

- Applied the same overlap-masked NCC validation to temporal rescue chaining, so neighbor-to-reference rescue no longer fails for the same cropped-canvas reason.

- Reworked global registration outlier CC filtering for long rotating runs: the `low_cc` reject gate now uses the configured absolute minimum directly instead of a run-global median/MAD threshold that incorrectly rejected many geometrically plausible edge frames.

- Fixed field-rotation model prediction outside the span of real registrations: tail/head frames no longer use unstable local polynomial extrapolation and instead fall back to bounded bridge-style edge prediction, preventing the severe fan-out / wedge artifacts seen on the M66 Alt/Az regression run.



### (2026-03-19)



**GUI2 tool persistence/PCC UX, backend memory guards, and BGE autotune speed-up:**



- Hardened `web_backend_cpp/` against OOM-prone API/tool paths with capped subprocess/stdout capture, bounded scan/report payload retention, streamed event-file inspection, and retained-job limits plus environment-configurable defaults documented for GUI2.

- Added `packaging/gui2/.env.example` and documented the new backend runtime limit environment variables used by GUI2 launchers.

- Fixed GUI2 frontend/backend asset serving and route behavior so `/ui` and direct asset paths resolve reliably instead of producing 404s.

- Improved Astrometry/PCC tool UX: persistent in-progress download state across page switches, corrected download progress calculation, automatic PCC WCS prefill from matching files, and automatic PCC parameter import from a run `config.yaml` with visible traceability in the UI/log.

- Reworked PCC output handling in GUI2 so `Run PCC` writes to a temporary result, `Save Corrected` uses a styled in-app save dialog, copies the RGB result plus `_R/_G/_B` sidecar files from the temp output, and works consistently across Linux/macOS/Windows temp directories.

- Fixed standalone PCC fallback behavior when `canvas_mask` is missing by using a safe full-image fallback instead of aborting the tool run.

- Added BGE phase timing diagnostics to `bge.json` and optimized the real hotspot in `tile_compile_cpp/`: autotune prep now reuses prepared tile analysis across quantile candidates, reducing measured BGE wall time on the IC434 reference run from about `472s` to about `181s` without adding new full-frame memory pressure.



### (2026-03-18)



- Fixed Astrometry data directory input not being respected when user manually changes the path - now uses `shouldKeepAstapSelection` logic to preserve user input.

- Added server-side persistence for Astrometry and PCC tool parameters via UI state API - settings survive server restarts.

- Improved catalog download intelligence: Astrometry catalogs skip download if already installed, PCC Siril only downloads missing chunks.

- Enhanced archive extraction robustness for macOS `.pkg`, Linux `.deb`, and Windows `.exe` formats with better error messages and validation.

- Fixed macOS release bundle library issues by explicitly bundling GCC runtime libraries (`libgcc_s`, `libgfortran`, `libquadmath`, `libgomp`) and preserving `libstdc++` for Homebrew-compiled dependencies.



### (2026-03-17)



**Methodology `v3.3.8` + GUI2 run-name reset (`v0.0.F`):**



- Added new normative methodology documents `doc/v3/tile_basierte_qualitatsrekonstruktion_methodik_v_3.3.8_en.md` and `doc/v3/tile_basierte_qualitatsrekonstruktion_methodik_v_3.3.8_de.md`.

- Corrected the method specification so it matches the active runtime for operating-mode thresholds, shared-core channel semantics, neighborhood-aware local metric normalization, sigma-clipped tile reconstruction, and affine post-OLA photometric restoration.

- Fixed GUI2 so a changed input directory clears the shared `run_name` across dashboard, wizard, and input-scan.

- Added a short macOS 15 / Sequoia install note for Gatekeeper-blocked `start_gui2.command` launch.

- Changed ASTAP `d80` downloads from the invalid shared ZIP assumption to the real upstream platform packages: Linux `.deb`, macOS `.pkg`, Windows `.exe`.



### (2026-03-15)



**Assumptions runtime/config synchronization (`v0.0.E`):**



- `assumptions.frames_min` is now used by the active C++ runner mode gate instead of the old hardcoded minimum-frame threshold.

- `assumptions.reduced_mode_cluster_range` now affects reduced-mode clustering directly, so the exposed config field is no longer parser-only drift.

- Removed dead assumptions fields from the active config surface: `pipeline_profile`, `frames_optimal`, and `exposure_time_tolerance_percent`.

- Synchronized active C++ config code, generated schemas, example YAMLs, GUI2 Assumptions/Parameter Studio, and DE/EN docs to the remaining runtime-relevant assumptions fields.



### (2026-03-15)



**Boundary diagnostics deepening + GUI2 run-field synchronization:**



- Extended `TILE_RECONSTRUCTION` diagnostics so `tile_reconstruction.json` now exposes raw and normalized tile-boundary metrics separately, plus `tile_norm_bg_r/g/b` and `tile_norm_scale` for direct normalization analysis.

- Corrected tile-boundary analysis to exclude masked `COMMON_OVERLAP` / canvas-invalid zones instead of counting them as valid zero-valued samples.

- Updated the methodology/process/reference/practical docs to reflect the read-only raw/normalized boundary diagnostics and the common-canvas-mask requirement.

- Added `run_name` and `runs_dir` editing to Input&Scan and unified both fields across dashboard, wizard, and input-scan via the shared GUI2 stored state.



### (2026-03-13)



**GUI2 config/studio sync + tile-boundary diagnostics update:**



- Removed the ineffective `stacking.tile_seam_harmonization.*` experiment from the active C++ config surface and replaced it with read-only tile-boundary diagnostics in `TILE_RECONSTRUCTION`.

- Synchronized config code, generated schemas, example configs, and DE/EN reference docs with the active C++ config surface.

- Reworked Parameter Studio so parameter inventory, defaults, ranges, tooltips, and filtering are driven from the current schema/default config instead of stale manual lists.

- Extended GUI2 live-log and run-monitor behavior, including richer phase details, resume config editing/template flows, stored config revisions, and corrected phase status after successful resume.



### (2026-03-12)



**Server-side GUI2 UI-state persistence:**



- Added persistent backend storage plus API access for the GUI2 UI draft state so frontend UX state no longer depends primarily on local browser storage.

- Migrated the major UX-relevant frontend parameters to the shared server-backed UI state, including run naming, preset synchronization, config drafts, validation state, dirty state, queues, and tool path/input settings.

- Restored and synchronized additional tool result state across reloads where useful, while keeping purely ephemeral runtime display state non-persistent.



### (2026-03-11)



**Crow/C++ runtime, release packaging, and PCC update:**



- Finalized the productive GUI2 path around the Crow/C++ backend, including integrated C++ report generation and aligned frontend/backend report handling.

- Updated release packaging, local build/start scripts, and GitHub workflows for Linux, macOS, and Windows, including the documented GUI2 bundle OS baselines.

- Added Linux AppImage creation to the GitHub Actions release workflow so releases now include a portable Linux artifact alongside the ZIP bundle.

- Added date-aware run-directory naming and aligned route/websocket handling plus backend tests for the new naming behavior.

- Reworked PCC background-noise handling and connected UI/report updates so current PCC diagnostics are exposed more consistently in the GUI.



### (2026-03-09)



**GUI2 release + i18n refresh:**



- Promoted the web-based GUI2 stack (`web_frontend/` + `web_backend_cpp/`) to the recommended UI path and updated the top-level docs accordingly.

- Added the dedicated GUI2 release workflow and launcher packaging for Linux, macOS, and Windows under `.github/workflows/release-tile-compile-gui2.yml` and `packaging/gui2/`.

- Expanded frontend localization coverage and parameter-studio translations, with matching backend config contract updates and tests.

- Moved the earlier Qt6 GUI/build-script path into `legacy/` to separate the maintained GUI2 route from the legacy desktop implementation.



### (2026-03-10)



**Python elimination in the productive GUI2 path:**



- Switched GUI2 runtime, packaging, Docker, and CI to the Crow/C++ backend.

- Removed the productive Python dependency for stats/report generation; this now runs via the integrated C++ backend path and CLI support.

- Updated the repository structure and GUI2 documentation to reflect `web_backend_cpp/` as the maintained backend implementation.



### (2026-03-05, later update)



**Strict/Practical runtime unification + verification:**



- Unified the image-processing runtime core path for `assumptions.pipeline_profile: strict|practical`.

- Removed strict-only execution branches in the hot path:

  - no strict-only pre-registration order path,

  - no strict-only reduced/full gate override (`max(200, threshold)`),

  - no strict-only tile re-normalization branch,

  - no strict-only channel re-weighting branch in OSC tile stacking.

- Registration no longer force-overrides `registration.enable_star_pair_fallback=false` in strict mode.

- Updated config reference docs (EN/DE) so profile text matches current runtime behavior.

- Added A/B evidence run pair (`max_frames=80`) confirming same core flow with only minor numeric fit variance.



### (2026-03-05)



**Performance and throughput optimization (large datasets, 1000+ frames):**



- Added adaptive worker selection per phase with I/O-aware caps based on sampled frame size and task count.

- `DiskCacheFrameStore` now uses persistent memory-mapped frame views with rewrite invalidation, reducing repeated open/mmap/unmap overhead for tile access.

- Removed the global PREWARP store mutex so frame-cache writes can proceed concurrently.

- `GLOBAL_METRICS` now runs in a parallel worker pool with thread-safe progress and error aggregation.

- `TILE_RECONSTRUCTION` overlap-add switched from a single global lock to row-stripe locking to reduce contention.

- In OSC tile reconstruction, each valid frame tile is debayered once and cached as R/G/B planes for reuse across channel stacks.

- `LOCAL_METRICS` now skips globally invalid tiles before extraction and limits heavy full-matrix artifact writes for large production runs.



### (2026-03-03)



**Methodology alignment (v3.3.6 strict profile):**



- Added `assumptions.pipeline_profile: practical|strict` to switch between compatibility mode and strict normative behavior.

- In `strict` profile, REGISTRATION/PREWARP is executed before CHANNEL_SPLIT/NORMALIZATION/GLOBAL_METRICS.

- In `strict` profile, reduced/full gating enforces full mode only from `N >= 200`.

- In `strict` profile, phase-7 tile normalization before OLA is always enabled.

- PCC `auto_fwhm` now falls back deterministically to `FWHM=0` when seeing is unavailable.

- Added `registration.enable_star_pair_fallback` (default `true`); strict profile disables it to match the normative cascade order.

- Updated config schema/sample config and v3 reference docs (DE/EN) for these settings.



**BGE/PCC configuration and docs alignment:**



- Restored user-facing BGE fit parameters `bge.fit.robust_loss` and `bge.fit.huber_delta`.

- Added user-facing BGE apply guards `bge.min_valid_sample_fraction_for_apply` and `bge.min_valid_samples_for_apply`.

- Re-enabled parse/serialize/schema support for these keys in the runtime config surface.

- Runner mapping now forwards the configured values (no internal forced override).

- BGE config artifacts in both pipeline and resume paths include `robust_loss` and `huber_delta` again.

- Updated BGE/PCC docs and practical examples (DE/EN) to match current behavior and active parameter set.



### (2026-02-26)



**BGE Phase Visibility / Comparison Outputs:**



- BGE is now emitted as a dedicated pipeline enum phase (`BGE=15`) between `ASTROMETRY` and `PCC`.

- GUI phase progress now shows BGE explicitly, including BGE substep progress updates.

- Added explicit pre-PCC output `outputs/stacked_rgb_bge.fits` for direct BGE-only vs BGE+PCC comparison.

- Configuration docs/examples updated for v3.3.6 option set:

  - `bge.autotune.*` (`enabled`, `strategy`, `max_evals`, `holdout_fraction`, `alpha_flatness`, `beta_roughness`)

  - `pcc.background_model`

  - `pcc.max_condition_number`, `pcc.max_residual_rms`

  - `pcc.radii_mode`

  - `pcc.aperture_fwhm_mult`, `pcc.annulus_inner_fwhm_mult`, `pcc.annulus_outer_fwhm_mult`, `pcc.min_aperture_px`



### (2026-02-25)



**Registration / Canvas / Color-Correctness Fixes:**



- **Bayer parity-safe offsets in registration/prewarp path**: Canvas offsets are now handled consistently to preserve CFA parity across expanded/cropped canvases.

- **Output scaling origin fixes**: Scaling calls now use the correct tile/debayer offsets where required, preventing R/G parity mismatches after crop/canvas transforms.

- **Common-overlap and canvas handling clarified** in process-flow docs and aligned with the current phase model.



**PCC (Photometric Color Calibration) Improvements:**



- **Robust log-chromaticity fit** implemented for PCC matrix estimation (instead of the older proportion-only approach).

- **Guardrails on channel scales** added to avoid extreme global color casts.

- **Aperture annulus contamination filter (IQR gate)** added to reject unstable star measurements in nebulous/gradient-heavy fields.



**Documentation Refresh:**



- `doc/v3/process_flow/*` updated to the current production pipeline state, including `PREWARP`, `COMMON_OVERLAP`, canvas/offset propagation, and current enum phase ordering.



**BGE (Background Gradient Extraction):**



- Added optional pre-PCC BGE stage that directly subtracts modeled background from RGB channels.

- Added foreground-aware BGE fit method `modeled_mask_mesh` for difficult fields with large diffuse objects (e.g. M31/M42) to reduce color-cloud artifacts before PCC.

- Added `artifacts/bge.json` with per-channel diagnostics (tile samples, grid cells, residual statistics).

- Extended report generation to include a dedicated BGE section with summary plots and residual analysis.



### (2026-02-19)



**Calibration Fixes:**



- **GUI dark calibration propagation fixed**: If `use dark` is enabled and either **Darks dir** or **Dark master** is set, these values are now merged into the effective runtime config and applied by the runner. This fixes cases where dark calibration appeared enabled in the GUI but was not present in the run config (`use_dark: false`, empty dark paths).



### (2026-02-17)



**New Registration Features for Alt/Az Mounts Near Pole:**



- **Temporal-Smoothing Registration**: For field rotation, automatically uses neighbor frames (i-1, i+1) for registration when direct registration to reference fails. Chained warps: `i→(i-1)→ref` or `i→(i+1)→ref`. Useful for continuous field rotation (Alt/Az near pole) and clouds/nebula.



- **Adaptive Star Detection**: When too few stars are detected (< topk/2), automatically performs a second pass with lower threshold (2.5σ instead of 3.5σ). This improves star detection in clouds, nebula, or weak frames.



- **New Registration Engine**: `robust_phase_ecc` with LoG gradient preprocessing, optimized for frames with strong nebulae/clouds.



**Field Rotation Support:**



- **Canvas Expansion for Alt/Az Mounts**: Output canvas is now automatically expanded to contain all rotated frames. Previously, stars at the edges were cropped when using Alt/Az mounts near the pole. The bounding box of all warped frames is computed and the canvas is resized accordingly. Log output shows expansion: `"Field rotation detected: expanding canvas from WxH to W'xH'"`.



**Documentation:**



- **New**: [Practical Configuration Examples & Best Practices](doc/configuration_examples_practical_en.md) - Comprehensive guide with use cases for different focal lengths, seeing conditions, mount types, and camera setups (DWARF, Seestar, DSLR, Mono CCD). Includes parameter recommendations based on methodology v3.3.4.