{"id":44828547,"url":"https://github.com/jeamy/tile_compile","last_synced_at":"2026-06-11T23:00:39.193Z","repository":{"id":338668998,"uuid":"1126429589","full_name":"jeamy/tile_compile","owner":"jeamy","description":"Toolkit for tile-based quality reconstruction of astronomical image stacks","archived":false,"fork":false,"pushed_at":"2026-06-07T20:58:01.000Z","size":56834,"stargazers_count":0,"open_issues_count":0,"forks_count":0,"subscribers_count":0,"default_branch":"master","last_synced_at":"2026-06-07T22:26:03.176Z","etag":null,"topics":["dwarf","stacking","two-seestar"],"latest_commit_sha":null,"homepage":"","language":"C++","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"gpl-3.0","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/jeamy.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":null,"funding":null,"license":"LICENSE","code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null,"zenodo":null,"notice":null,"maintainers":null,"copyright":null,"agents":null,"dco":null,"cla":null}},"created_at":"2026-01-01T22:31:08.000Z","updated_at":"2026-06-05T22:13:15.000Z","dependencies_parsed_at":null,"dependency_job_id":null,"html_url":"https://github.com/jeamy/tile_compile","commit_stats":null,"previous_names":["jeamy/tile_compile"],"tags_count":41,"template":false,"template_full_name":null,"purl":"pkg:github/jeamy/tile_compile","repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/jeamy%2Ftile_compile","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/jeamy%2Ftile_compile/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/jeamy%2Ftile_compile/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/jeamy%2Ftile_compile/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/jeamy","download_url":"https://codeload.github.com/jeamy/tile_compile/tar.gz/refs/heads/master","sbom_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/jeamy%2Ftile_compile/sbom","scorecard":null,"host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":286080680,"owners_count":34221150,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2026-05-26T15:22:16.424Z","status":"online","status_checked_at":"2026-06-11T02:00:06.485Z","response_time":57,"last_error":null,"robots_txt_status":"success","robots_txt_updated_at":"2025-07-24T06:49:26.215Z","robots_txt_url":"https://github.com/robots.txt","online":true,"can_crawl_api":true,"host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":["dwarf","stacking","two-seestar"],"created_at":"2026-02-16T23:26:05.480Z","updated_at":"2026-06-11T23:00:39.181Z","avatar_url":"https://github.com/jeamy.png","language":"C++","funding_links":[],"categories":[],"sub_categories":[],"readme":"# Tile-Compile\n\nTile-Compile is a toolkit for high-quality astronomical image reconstruction from short-exposure deep-sky datasets. The default reconstruction method is **AQMH (Adaptive Quality Map Harvesting)** — a per-pixel, quality-map-driven approach that replaces tile-based overlap-add stacking with a physically optimal pixel-wise weighted average.\n\n\u003e **Classic Tile-Compile (TBQR):** The original tile-based quality reconstruction methodology is still available and fully supported. See [Classic Tile-Compile README (EN)](README_classic_tile_compile_en.md) and the [Classic Tile-Compile README (DE)](README_classic_tile_compile_de.md). Set `aqmh.enabled: false` to revert to classic TILE_RECONSTRUCTION.\n\n\u003e **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.\n\n## AQMH — Adaptive Quality Map Harvesting (Default)\n\nAQMH is the default reconstruction path as of v0.3.0. For each input frame a **dense quality map** `Q_map_{f,c}(x,y)` is computed using a **4-scale Laplacian pyramid**, combining sharpness and SNR metrics into a per-pixel quality value. The final image is reconstructed as a **per-pixel weighted mean** — effective weight `W = G_{f,c} * Q_map_{f,c}(x,y)`, where `G_{f,c}` is the global frame weight from shared preprocessing. No tile grid, no OLA seams.\n\n\u003e **Normative specification:** [AQMH Methodology v0.1.0](docs/AQMH/aqmh_methodik_en.md)\n\n### How it works\n\n```\nFor each frame f, channel c:\n  For each pyramid scale s (D_s = 4^s, window R_s = 4 px in downscaled pixels):\n    1. Downsample I_{f,c} by D_s (mask-aware area average)\n    2. Compute per-window:\n         Phi_sharp = local variance of masked Laplacian (sharpness)\n         Phi_snr   = local SNR = mu / max(1.4826*MAD, eps)\n         Phi_artifact = 1 - clip(outlier_frac / frac_artifact_max, 0, 1)\n    3. Psi_s = sigmoid(w_sharp*z(Phi_sharp) + w_snr*z(Phi_snr)) * Phi_artifact\n       (z = robust z-score; artifact gate is multiplicative — one bad scale vetos pixel)\n    4. Upsample Psi_s to canvas resolution (mask-aware bilinear)\n  Q_map_{f,c} = geometric_mean over scales(Psi_s)  # all scales must agree\n  Store Q_map to disk cache (default: 1/4-area float32)\n\nReconstruction (per canvas-valid pixel p):\n  W_{f,c}(p) = G_{f,c} * Q_map_{f,c}(p)\n  R_c(p) = sum_f( W_{f,c}(p) * I_{f,c}(p) ) / sum_f( W_{f,c}(p) )\n```\n\n### Key parameters (`aqmh.*`)\n\n| Parameter | Default | Description |\n|-----------|---------|-------------|\n| `aqmh.enabled` | `true` | Enable AQMH (false = use classic TILE_RECONSTRUCTION) |\n| `aqmh.pyramid.scales` | `4` | Pyramid levels for multi-scale analysis |\n| `aqmh.pyramid.base_window_px` | `4` | Window size at lowest pyramid level |\n| `aqmh.pyramid.w_sharp` | `0.6` | Sharpness weight in quality index |\n| `aqmh.pyramid.w_snr` | `0.4` | SNR weight in quality index |\n| `aqmh.pyramid.k_artifact` | `3.0` | MAD multiplier for artifact detection (higher = more tolerant) |\n| `aqmh.pyramid.frac_artifact_max` | `0.25` | Max artifact fraction per window before discard |\n| `aqmh.storage.resolution_divisor` | `2` | Quality map cache resolution (1/2/4) |\n| `aqmh.storage.dtype` | `float32` | Cache data type (`float32` or `uint8`) |\n| `aqmh.storage.max_resident_maps` | `2` | Max quality maps in RAM simultaneously |\n| `aqmh.cherry_pick.enabled` | `false` | Stack only top-quality frames |\n| `aqmh.cherry_pick.k_frac` | `0.30` | Fraction of best frames to use (0.30 = best 30%) |\n| `aqmh.cherry_pick.k_min` | `3` | Minimum frames always included |\n| `aqmh.diagnostics.tau_artifact` | `0.20` | Artifact threshold for `artifacts/aqmh.json` |\n| `aqmh.diagnostics.q_region` | `0.75` | Quantile for regional quality statistics |\n| `aqmh.diagnostics.r_morph_canvas_px` | `6` | Morphological radius for diagnostic quality map |\n\nFull parameter documentation: [Configuration Reference — §12b AQMH](docs/configuration_reference_en.md)  \nPractical examples: [Configuration Examples — AQMH section](docs/configuration_examples_practical_en.md)  \nNormative specification: [AQMH Methodology v0.1.0](docs/AQMH/aqmh_methodik_en.md)\n\n### When to use AQMH vs. Classic\n\n| Situation | Recommendation |\n|-----------|----------------|\n| Default / most sessions | **AQMH** (enabled by default) |\n| Tile seams or OLA artifacts visible | **AQMH** eliminates seams entirely |\n| Strongly varying frame quality (seeing, clouds) | **AQMH** with `cherry_pick.enabled: true` |\n| Very large sessions, RAM-limited | **AQMH** with `storage.resolution_divisor: 4`, `dtype: uint8` |\n| Sessions with satellite trails / cosmetic issues | **AQMH** with `k_artifact: 5.0`, `frac_artifact_max: 0.35` |\n| Research requiring TBQR tile-weighted OLA | Classic (`aqmh.enabled: false`) |\n\n### Minimal AQMH config\n\n```yaml\naqmh:\n  enabled: true          # default — can be omitted\n  pyramid:\n    k_artifact: 3.0      # default\n    frac_artifact_max: 0.25  # default\n```\n\n### Disable AQMH (revert to classic)\n\n```yaml\naqmh:\n  enabled: false\n```\n\n## Documentation\n\n- **AQMH methodology (normative):** [AQMH Methodology v0.1.0](docs/AQMH/aqmh_methodik_en.md)\n- **AQMH parameter reference:** [Configuration Reference — §12b AQMH](docs/configuration_reference_en.md)\n- **AQMH practical examples:** [Configuration Examples \u0026 Best Practices](docs/configuration_examples_practical_en.md)\n- Configuration reference (full): [Configuration Reference (EN)](docs/configuration_reference_en.md)\n- German README: [README_de.md](README_de.md)\n- GUI2 packaging and launch notes: [GUI2 README](packaging/gui2/README.md)\n- Data flow (user-friendly): [Process Flow - How the System Works](docs/process_flow/data_flow_user_description_en.md)\n- Full documentation site: [https://jeamy.github.io/tile_compile/](https://jeamy.github.io/tile_compile/)\n- Raw Stack GUI guide (English): [docs/raw_stack_gui_en.md](docs/raw_stack_gui_en.md)\n- Step-by-step guide: [Step-by-Step Guide](docs/tbqr_step_by_step_en.md)\n\n### Classic Tile-Compile (TBQR) documentation\n\n- Classic README (EN): [README_classic_tile_compile_en.md](README_classic_tile_compile_en.md)\n- Classic README (DE): [README_classic_tile_compile_de.md](README_classic_tile_compile_de.md)\n- Normative TBQR methodology: [Tile-Based Quality Reconstruction Methodology v3.3.9](docs/v3/tile_basierte_qualitatsrekonstruktion_methodik_v_3.3.9_en.md)\n- Methodology paper PDF v3.3.6: [paper-tile_based_quality_reconstruction_methodology_v_3.3.6_en.pdf](docs/v3/paper-tile_based_quality_reconstruction_methodology_v_3.3.6_en.pdf)\n- Implementation process flow: [Process flow (English)](docs/process_flow/README_en.md)\n\n## Paper Example Data Sources\n\n- M31 lights source for the paper example run (10 GB): [M31 lights](https://wolke.eibrain.org/index.php/s/Z88dmWizEJYjwBe) \n- M31 run source for the paper example run (20 GB): [M31 run](https://wolke.eibrain.org/index.php/s/tfSycSNEzdL7jje)\n\nGiven a directory of FITS lights, the pipeline can:\n\n- optionally **calibrate** lights (bias/dark/flat)\n- **register** frames using a robust 6-stage fallback cascade\n- compute **global quality metrics** (transparency, SNR, weights)\n- compute **per-frame AQMH quality maps** (sharpness + SNR, Laplacian pyramid)\n- **reconstruct** the image via per-pixel AQMH weighted average (default) or tile-weighted OLA (classic)\n- optionally **cherry-pick** only the best frames for AQMH reconstruction\n- optionally cluster frame states and build synthetic frames\n- **stack** using sigma-clip or weighted averaging\n- **debayer** OSC/CFA data\n- run **astrometry** (WCS)\n- run optional **background gradient extraction** (BGE, pre-PCC)\n- run **photometric color calibration** (PCC)\n- write final outputs and detailed diagnostic artifacts (including `artifacts/aqmh.json`)\n\n## Active Components\n\n| Component | Directory | Status | Stack |\n|-----------|-----------|--------|-------|\n| Core pipeline | `tile_compile_cpp/` | Active | C++17 + Eigen + OpenCV + cfitsio + yaml-cpp |\n| GUI2 backend | `web_backend_cpp/` | Active | Crow + C++17 |\n| GUI2 frontend | `web_frontend/` | Active | HTML + CSS + JavaScript |\n\n## Pipeline Phases\n\nIn practical use, the overall workflow is intentionally simple: provide the input data and a manageable set of configuration parameters; the pipeline processes the dataset automatically from AQMH reconstruction through astrometry, optional background handling, and PCC to the final result.\n\n| ID | Phase | Description |\n|----|-------|-------------|\n| 0 | SCAN_INPUT | Input discovery, mode detection, linearity check, disk-space precheck |\n| 1 | REGISTRATION | Cascaded global registration |\n| 2 | PREWARP | Full-frame canvas prewarp (CFA-safe for OSC) |\n| 3 | CHANNEL_SPLIT | Metadata phase (channel model) |\n| 4 | NORMALIZATION | Linear background-based normalization |\n| 5 | GLOBAL_METRICS | Global frame metrics and weights |\n| 6 | TILE_GRID | Adaptive tile geometry (used by classic TILE_RECONSTRUCTION) |\n| 7 | COMMON_OVERLAP | Common valid-data overlap (global/tile-local masks) |\n| 8 | LOCAL_METRICS | Local tile metrics + **AQMH quality map computation** |\n| 9 | TILE_RECONSTRUCTION | **AQMH per-pixel weighted reconstruction** (default) or tile-weighted OLA (classic) |\n| 10 | STATE_CLUSTERING | Optional state clustering |\n| 11 | SYNTHETIC_FRAMES | Optional synthetic frame generation |\n| 12 | STACKING | Final linear stacking |\n| 13 | DEBAYER | OSC demosaic to RGB (MONO pass-through) |\n| 14 | ASTROMETRY | Plate solving / WCS |\n| 15 | BGE | Optional RGB background gradient extraction before PCC |\n| 16 | PCC | Photometric color calibration |\n| 17 | HYPERMETRIC_STRETCH | Optional VeraLux HyperMetric Stretch after PCC |\n| 18 | DONE | Final status (`ok` or `validation_failed`) |\n\nDetailed phase docs: `docs/process_flow/`\n\n## Registration Cascade (Fallback Strategy)\n\n| Stage | Method | Typical use case |\n|-------|--------|------------------|\n| 1 | Primary engine (`triangle_star_matching`) | Normal star-rich frames |\n| 2 | Trail endpoint registration | Star trails / rotation-heavy data |\n| 3 | AKAZE feature matching | General feature fallback |\n| 4 | Robust phase+ECC | Clouds/nebulosity with larger transforms |\n| 5 | Hybrid phase+ECC | Weak star matching cases |\n| 6 | Identity fallback | Last resort (CC=0, frame retained) |\n\n## Configuration\n\n- Main config file: `tile_compile.yaml`\n- Schemas: `tile_compile.schema.json`, `tile_compile.schema.yaml`\n- Reference document: [Configuration Reference](docs/configuration_reference_en.md)\n- Practical examples: [Configuration Examples \u0026 Best Practices](docs/configuration_examples_practical_en.md)\n\n### Example profiles\n\nComplete standalone example configs are available under `tile_compile_cpp/examples/`.\nThe filenames no longer use the old `tile_compile.` prefix.\n\n- `full_mode.example.yaml`\n- `reduced_mode.example.yaml`\n- `emergency_mode.example.yaml`\n- `smart_telescope_dwarf_seestar.example.yaml`\n- `smart_telescope_very_bright_star.example.yaml`\n- `canon_low_n_high_quality.example.yaml`\n- `very_bright_star_anti_seam.example.yaml`\n- `canon_equatorial_balanced.example.yaml`\n- `mono_full_mode.example.yaml`\n- `mono_small_n_anti_grid.example.yaml` (recommended for MONO low-frame datasets, e.g. ~10..40, to reduce tile-pattern risk)\n- `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)\n\nSee also: [Examples README](tile_compile_cpp/examples/README.md) for the intended use case and tuning focus of each profile.\n\n## Binary Releases (GUI2)\n\nPre-built GUI2 release bundles are published via [GitHub Releases](https://github.com/jeamy/tile_compile/releases).\n\nEach bundle contains:\n\n- GUI2 frontend (`web_frontend/`)\n- Crow backend (`web_backend_cpp/`)\n- native C++ tools (`tile_compile_runner`, `tile_compile_cli`, `tile_compile_web_backend`)\n- launchers for Linux, macOS, and Windows\n\nAt runtime, GUI2 uses the local Crow/C++ backend as the process adapter for the C++ runner/CLI.\n\n## Quickstart\n\n### GUI2 (recommended)\n\nDevelopment start from repository root:\n\n```bash\n./start_backend.sh\n```\n\nThen open:\n\n```text\nhttp://127.0.0.1:8080/ui/\n```\n\nRelease bundle start:\n\n- Linux: `start_gui2.sh`\n- macOS: `start_gui2.command`\n- Windows: `start_gui2.bat`\n\nThe 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.\n\n**Installation and update behavior:**\n\n- On first start, the launcher copies all application files to `~/tilecompile/` (Linux/macOS) or `%USERPROFILE%\\tilecompile\\` (Windows).\n- 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.\n- 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.\n\nmacOS install note:\n\n- 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 -\u003e Privacy \u0026 Security`, scroll to the bottom, and explicitly allow the blocked `start_gui2.command` there before starting it again.\n\nMinimum OS versions for the current GUI2 release bundles:\n\n- Linux: x86_64 Linux with `glibc \u003e= 2.35` (Ubuntu 22.04 or equivalent is the safe baseline for the current CI-built ZIPs)\n- macOS: macOS 15\n- Windows: Windows 10 x64 or newer\n\nNotes:\n\n- 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.\n- Linux bundles do not bundle `glibc`, so older distributions than the current build baseline are not guaranteed to work.\n\n### C++ CLI / runner\n\nFor a full beginner-friendly walkthrough, see:\n[Step-by-Step Guide](docs/tbqr_step_by_step_en.md)\n\n### Build Requirements\n\n- CMake \u003e= 3.21\n- C++17 compiler (GCC 11+ or Clang 14+)\n- OpenCV \u003e= 4.5\n- Eigen3\n- cfitsio\n- yaml-cpp\n- nlohmann-json\n\n#### GPU acceleration requirements\n\nThe pipeline supports two GPU backends:\n\n**NVIDIA CUDA (opencv_cuda):**\n- Requires OpenCV CUDA modules:\n  - `opencv2/core/cuda.hpp`\n  - `opencv2/cudawarping.hpp`\n  - `opencv2/cudaarithm.hpp`\n- At runtime, a CUDA-capable NVIDIA GPU and working CUDA/OpenCV runtime are required.\n- `TILE_COMPILE_ENABLE_CUDA` only enables the CUDA hook/build gate.\n\n**AMD/Intel/NVIDIA OpenCL (opencv_opencl):**\n- Requires OpenCV OpenCL module:\n  - `opencv2/core/ocl.hpp`\n- At runtime, an OpenCL-capable GPU (AMD, Intel, NVIDIA) and working OpenCL runtime are required.\n- Works with AMD Radeon (Polaris/Vega/RDNA), Intel integrated GPUs, and NVIDIA GPUs.\n- Generally easier to set up than CUDA on non-NVIDIA hardware.\n\n**Auto-selection:**\n- `acceleration_backend: auto` (default) automatically detects available GPU backends at runtime.\n- Priority order: CUDA → OpenCL → CPU\n- Falls back gracefully to CPU if no GPU backend is available.\n\nNotes:\n\n- Many default distro/Homebrew/OpenCV packages provide CPU-only builds. GPU acceleration requires OpenCV built with CUDA or OpenCL support.\n- For NVIDIA GPUs: CUDA backend typically provides better performance than OpenCL.\n- For AMD/Intel GPUs: OpenCL is the only supported GPU backend.\n- On macOS: OpenCL support depends on OpenCV build; CUDA is not practical.\n\n#### Package install examples\n\nLinux (Ubuntu/Debian):\n\n```bash\nsudo apt-get update\nsudo apt-get install -y \\\n  build-essential cmake pkg-config \\\n  libeigen3-dev libopencv-dev libcfitsio-dev libyaml-cpp-dev nlohmann-json3-dev libssl-dev \\\n  libcurl4-openssl-dev\n```\n\nLinux (Fedora):\n\n```bash\nsudo dnf install -y \\\n  gcc-c++ cmake pkgconf-pkg-config ninja-build \\\n  eigen3-devel opencv-devel cfitsio-devel yaml-cpp-devel nlohmann-json-devel openssl-devel \\\n  libcurl-devel\n```\n\nmacOS (Homebrew, core libs):\n\n```bash\nxcode-select --install\nbrew install cmake ninja pkg-config eigen cfitsio yaml-cpp nlohmann-json openssl curl\nbrew install opencv\n```\n\nNotes:\n\n- `ninja` is required for the local GUI2 packaging scripts.\n- 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.\n- 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.\n- 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.\n\nWindows:\n\n- 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`\n- MSVC/vcpkg: `eigen3`, `opencv`, `cfitsio`, `yaml-cpp`, `nlohmann-json`, `openssl`, `curl`, `pkgconf`\n\n### Build\n\n```bash\ncd tile_compile_cpp\nmkdir -p build \u0026\u0026 cd build\ncmake .. -DCMAKE_BUILD_TYPE=Release\ncmake --build . -j$(nproc)\n```\n\n### Release build + packaging\n\nGUI2 release bundles are built by:\n\n- `.github/workflows/release-tile-compile-gui2.yml`\n\nThe 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.\n\nNot included by design:\n\n- external Siril catalog data\n- external ASTAP binary/data\n  \n### Docker Build + Run (recommended for isolated environments)\n\nA helper script is available at:\n`tile_compile_cpp/scripts/docker_compile_and_run.sh`\n\nWhat it does:\n\n- `build-image`: builds a Docker image and compiles `tile_compile_cpp` inside the container\n- `run-shell`: starts an interactive shell in the compiled container\n- `run-app`: runs `tile_compile_runner` directly in the container\n\nDefault runs volume mapping:\n\n- Host: `tile_compile_cpp/runs`\n- Container: `/workspace/tile_compile_cpp/runs`\n\nExamples:\n\n```bash\n# build Docker image and compile inside container\n./tile_compile_cpp/scripts/docker_compile_and_run.sh build-image\n\n# open interactive shell inside container\n./tile_compile_cpp/scripts/docker_compile_and_run.sh run-shell\n\n# run pipeline in container\n./tile_compile_cpp/scripts/docker_compile_and_run.sh run-app -- run \\\n  --config /mnt/config/tile_compile.yaml \\\n  --input-dir /mnt/input \\\n  --runs-dir /workspace/tile_compile_cpp/runs\n```\n\nUse `run-shell` if you need additional mounts (e.g., config/input directories) and then start the runner manually.\n\n#### Windows notes (Docker / CLI workflow)\n\nUse a Linux shell (WSL2 Ubuntu) to run the helper script:\n\n```bash\nbash scripts/docker_compile_and_run.sh build-image\nbash 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\n```\n\n### CLI Runner\n\n```bash\n./tile_compile_runner \\\n  run \\\n  --config ../tile_compile.yaml \\\n  --input-dir /path/to/lights \\\n  --runs-dir /path/to/runs\n```\n\nCommon options:\n\n- `--max-frames \u003cn\u003e` limit frames (`0` = no limit)\n- `--max-tiles \u003cn\u003e` limit tile count for Phase 5/6 (`0` = no limit)\n- `--dry-run` execute validation flow without full processing\n- `--run-id \u003cid\u003e` custom run id for grouping\n- `--stdin` with `--config -` to read YAML from stdin\n\nResume mode:\n\n```bash\n./tile_compile_runner resume \\\n  --run-dir /path/to/runs/\u003crun_id\u003e \\\n  --from-phase BGE\n```\n\nSupported resume phases (any phase from 0..17):\n- Early: `SCAN_INPUT`, `CHANNEL_SPLIT`, `NORMALIZATION`, `GLOBAL_METRICS`, `TILE_GRID`\n- Mid: `REGISTRATION`, `PREWARP`, `COMMON_OVERLAP`, `LOCAL_METRICS`, `TILE_RECONSTRUCTION`\n- Late: `STATE_CLUSTERING`, `SYNTHETIC_FRAMES`, `STACKING`, `DEBAYER`, `ASTROMETRY`, `BGE`, `PCC`, `HYPERMETRIC_STRETCH`\n\nCommon resume points: `ASTROMETRY` (re-solve), `BGE` (re-extract background), `PCC` (re-calibrate color), `HYPERMETRIC_STRETCH` (rerun final VeraLux stretch), `STACKING` (re-stack from synthetic frames).\n\n### CLI Scan\n\n```bash\n./tile_compile_cli scan /path/to/lights --frames-min 30\n```\n\n### Other CLI Possibilities\n\n```bash\n# Config handling\n./tile_compile_cli get-schema                              # Print JSON schema\n./tile_compile_cli dump-default-config                     # Print default config as JSON\n./tile_compile_cli load-config \u003cpath\u003e                    # Load and display config YAML\n./tile_compile_cli save-config \u003cpath\u003e [--stdin]            # Save config YAML\n./tile_compile_cli validate-config (--path P | --yaml Y | --stdin)\n\n# Run inspection\n./tile_compile_cli list-runs /path/to/runs\n./tile_compile_cli get-run-status /path/to/runs/\u003crun_id\u003e\n./tile_compile_cli get-run-logs /path/to/runs/\u003crun_id\u003e [--tail N]\n./tile_compile_cli list-artifacts /path/to/runs/\u003crun_id\u003e\n\n# Input scanning\n./tile_compile_cli scan /path/to/lights [--frames-min N]\n\n# FITS analysis\n./tile_compile_cli fits-stats /path/to/image.fits\n\n# Photometric color calibration (PCC)\n./tile_compile_cli pcc-run \u003cin.fits\u003e \u003cout.fits\u003e --wcs \u003cwcs.fits\u003e [--source vizier|siril]\n./tile_compile_cli pcc-apply \u003cin.fits\u003e \u003cout.fits\u003e [--r X] [--g Y] [--b Z]\n\n# GUI state (for external tool integration)\n./tile_compile_cli load-gui-state [--path \u003cfile\u003e]\n./tile_compile_cli save-gui-state [--path \u003cfile\u003e] [--stdin | \u003cJSON\u003e]\n```\n\n### GUI2 integration\n\nThe recommended UI path is the web-based GUI2:\n\n- backend: `web_backend_cpp/`\n- frontend: `web_frontend/`\n- orchestration: Crow backend -\u003e `tile_compile_cli` / `tile_compile_runner`\n\nDevelopment start:\n\n```bash\n./start_backend.sh\n```\n\nOpen `http://127.0.0.1:8080/ui/`.\n\n## Outputs\n\nAfter a successful run (`runs/\u003crun_id\u003e/`):\n\n- `outputs/`\n  - `stacked.fits`\n  - `reconstructed_L.fit`\n  - `stacked_rgb.fits` (OSC)\n  - `stacked_rgb_solve.fits` / WCS artifacts\n  - `stacked_rgb_bge.fits` (BGE-only snapshot before PCC)\n  - `stacked_rgb_pcc.fits`\n  - `stacked_rgb_hms.fits` (optional VeraLux HyperMetric Stretch output)\n  - `synthetic_*.fit` (mode-dependent)\n- `artifacts/`\n  - `normalization.json`\n  - `global_metrics.json`\n  - `tile_grid.json`\n  - `global_registration.json`\n  - `local_metrics.json`\n  - `tile_reconstruction.json`\n  - `aqmh.json` (AQMH quality diagnostics — artifact fractions, regional quality stats)\n  - `state_clustering.json`\n  - `synthetic_frames.json`\n  - `bge.json`\n  - `validation.json`\n  - `report.html`, `report.css`, `*.png`\n- `logs/run_events.jsonl`\n- `config.yaml` (run snapshot)\n\n## External Sources (PCC and Astrometry)\n\nFor optional color calibration and astrometric solving, the pipeline can use external data/tools:\n\n- **Siril Gaia DR3 XP sampled catalog** (for PCC)\n  - Can be reused if already downloaded by Siril.\n  - Typical local path: `~/.local/share/siril/siril_cat1_healpix8_xpsamp/`\n  - Upstream source (catalog release): `https://zenodo.org/records/14738271`\n- **ASTAP** (for astrometry / WCS plate solving)\n  - Requires ASTAP plus a star database (e.g., D50 for deep-sky use).\n  - Official site/downloads: `https://www.hnsky.org/astap.htm`\n\nIf these resources are not installed, core reconstruction still works, but ASTROMETRY/PCC phases may be skipped or fail depending on configuration.\n\n## Diagnostic Report (`report.html` via C++ backend)\n\nGenerate an HTML quality report from a finished run either via GUI2 or directly through the CLI:\n\n```bash\n./tile_compile_cli generate-report runs/\u003crun_id\u003e\n```\n\nOutput:\n\n- `runs/\u003crun_id\u003e/artifacts/report.html`\n- `runs/\u003crun_id\u003e/artifacts/report.css`\n- `runs/\u003crun_id\u003e/artifacts/*.png`\n\nThe report aggregates data from artifact JSON files, `logs/run_events.jsonl`, and `config.yaml`, including:\n\n- normalization/background trends\n- global quality distributions and weights\n- registration drift/CC/rotation diagnostics\n- tile and reconstruction heatmaps\n- clustering/synthetic frame summaries\n- BGE diagnostics (grid cells, residuals, channel shifts)\n- validation metrics (including tile-pattern indicators)\n- pipeline timeline and frame-usage funnel\n\n## Calibration (Bias / Dark / Flat)\n\n- Master frames (`bias_master`, `dark_master`, `flat_master`) can be used directly\n- Directory-based masters (`bias_dir`, `darks_dir`, `flats_dir`) can be built automatically\n- When `use_bias: true` and `use_dark: true`, raw darks are bias-corrected internally unless `dark_already_bias_corrected: true` is set\n- `dark_auto_select: true` matches darks by exposure time (±5%)\n\n## Project Structure\n\n```text\ntile_compile/\n├── web_frontend/           # GUI2 HTML/CSS/JS frontend\n├── web_backend_cpp/        # GUI2 Crow/C++ backend\n├── tile_compile_cpp/\n│   ├── apps/                # runner/cli entry points\n│   ├── include/tile_compile/\n│   ├── src/\n│   ├── examples/            # example configs\n│   ├── scripts/             # helper scripts\n│   ├── tests/\n│   ├── tile_compile.yaml\n│   ├── tile_compile.schema.json\n│   └── tile_compile.schema.yaml\n├── packaging/gui2/          # GUI2 release launchers/bundle helpers\n├── docker/                  # Docker build/runtime images\n├── docs/\n│   ├── v3/                  # methodology docs\n│   └── process_flow/        # implementation process-flow docs\n├── start_backend.sh         # dev start for Crow backend + GUI2\n├── start_gui2_docker.sh     # run GUI2 in Docker\n├── README.md\n└── README_de.md\n```\n\n## Tests\n\n```bash\ncd tile_compile_cpp/build\nctest --output-on-failure\n```\n\n## Attribution\n\nThis project was built with assistance from Windsurf, Kiro, Antigravity, GPT 5.*,Claude 4.* Sonnet, Codex, ***. Babysitting by a human in a virtual environment.\n\nThe HyperMetric Stretch (HMS) phase is derived from the VeraLux HyperMetric Stretch Siril script:\n\n- (c) 2025 Riccardo Paterniti\n- VeraLux - HyperMetric Stretch\n- SPDX-License-Identifier: GPL-3.0-or-later\n- Version 1.5.2\n- Inspired by the \"True Color\" methodology of Dr. Roger N. Clark\n- Math basis: Inverse Hyperbolic Stretch (IHS) and Vector Color Preservation\n- Sensor science: hardware-specific Quantum Efficiency weighting\n\n\n## Versions\n\n## v0.3.0 (2026-06-09)\n\n**AQMH as default reconstruction method:**\n- AQMH (Adaptive Quality Map Harvesting) is now the default reconstruction path (`aqmh.enabled: true`).\n- Classic TILE_RECONSTRUCTION is still available via `aqmh.enabled: false`.\n- All example profiles updated with `aqmh:` block.\n- Full AQMH parameter documentation added to configuration reference and practical examples.\n- `k_artifact` default changed to `3.0`, `frac_artifact_max` default changed to `0.25`.\n\n## v0.2.A (2026-05-26)\n- Calibration Bug fixes\n\n## v0.2.9 (2026-05-25)\n\n**Raw Stack preprocessing pipeline:**\n- New standalone Raw Stack UI: preprocessing from FITS light frames to final stacked image, separate from the Tile-Compile run studio.\n- Pipeline covers: Calibration, CFA/Mono Prep, Registration, Quality Filtering, Stacking, Astrometry, BGE, PCC, HyperMetric Stretch.\n- All parameters (sigma-clip, rejection, weighting, BGE, PCC, Astrometry, HMS) are taken from the Parameter Studio config — nothing is hardcoded.\n- See [docs/raw_stack_gui_en.md](docs/raw_stack_gui_en.md) for GUI documentation.\n\n## v0.2.8 (2026-05-23)\n\n-- HMS Bug fixes\n\n## v0.2.7 (2026-05-22)\n\n**implementationHMS:**\n- Added VeraLux HyperMetric Stretch (HMS) as a post-PCC pipeline phase.\n\n## v0.2.6 (2026-05-20)\n\n**Build hardening \u0026 Frontend cleanup:**\n- Hardened web_backend_cpp build with CUDA 13 + OpenCV 4.11 CUDA 13 configuration\n- Frontend refactoring: centralized utilities in `src/utils.js` (escapeHtml, getMessage, getStorageJson, humanizeControlId, etc.)\n- Migrated shell.js, parameter-studio-page.js, and tooltips.js to ES6 modules with shared utils.js imports\n- Removed dead code\n\n## v0.2.5 (2026-04-26)\n\n- v0.2.5 combines the documentation-system refresh with a BGE robustness update for difficult chromatic gradients such as IC434. BGE sample-estimator selection is now exposed in YAML, schema validation, and Parameter Studio, while autotune can compare robust estimators and reject degenerate flat background models when significant background or chroma spread remains.\n- Professional documentation system with MkDocs Material + Doxygen\n- Installation instructions for pre-built binaries (Ubuntu, Fedora, Arch)\n- Configurable BGE sample estimators: `quantile`, `sigma_clipped_median`, `sextractor_mode`, and `biweight`\n- BGE autotune now sweeps sample estimators and applies chroma/background-spread guards for flat or imbalanced correction surfaces\n- Reconstruction fallback path hardened: safer shape/weight validation, corrected OLA memory budgeting, tile-local temporary buffers, and removal of ineffective scheduler/config dead code\n\n## v0.2.4 (2026-04-25)\n\n- Registration performance: anchor-promotion rounds now reuse the parallel worker pool and only retry unresolved frames whose nearest anchor changed after promotion, instead of running repeated full-frame single-threaded passes. Added `reg_promotion_retry_frames` diagnostics.\n\n## v0.2.3 (2026-04-24)\n\n- More robust registration: deep-chain outlier rejection (reject long chains with low CC), doubled anchor density for large-N sessions, \"hopping\" sequential rescue that searches past weak neighbors for better anchors, and ASTAP plate-solving as fallback even for model-interpolated frames.\n\n## v0.2.2 (2026-04-24)\n\n- **Hot/dead-pixel correction fixed** (`cosmetic_correction_cfa`): defective pixels inside star regions were not corrected because `neighbor_threshold` was set too low — star-halo pixels were incorrectly counted as \"hot neighbours\" and suppressed the correction. The threshold is now aligned with the full global hot-pixel threshold. Additionally: pixels exceeding 5× the local floor are now replaced unconditionally (`extreme_outlier` bypass). Dead/cold-pixel detection added. Works without dark frames.\n\n## v0.2.1 (2026-04-23)\n\n- Registration phase: NCC computation made more robust against background subtraction and hot pixels (clamp + Gaussian blur before NCC); the near-identity bypass condition strengthened with an `ncc_identity \u003e 0.7` guard to prevent false acceptance for frames far from the reference.\n\n## v0.2.0 (2026-04-14)\n\n- Registration for long Alt/Az sessions was expanded substantially: N-scaled multi-anchor reference selection, N-scaled anchor promotion, astrometric registration/rescue for weak or unresolved frames, plus new practical example configs and refreshed process documentation for difficult rotation/seeing cases.\n\n## v0.1.F (2026-04-07)\n\n- TILE_RECONSTRUCTION performance: replaced the memory-driven worker reduction (3 workers instead of 8) with frame sub-batching. Workers now always run at the configured `parallel_workers` count; the memory budget controls how many frames are processed per batch instead of how many threads are active. Expected speedup: ~2.7× for OSC runs with 600+ frames on a 2 GB memory budget.\n\n## v0.1.E (2026-04-06)\n\n- Calibration/UI follow-up: dark+bias calibration now handles raw darks without double bias subtraction, `dark_already_bias_corrected` was propagated through backend, schema, example YAMLs, and Parameter Studio, and the Parameter Studio now shows one consolidated section per selected category instead of a split double view.\n\n## v0.1.D (2026-04-04)\n\n- 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`).\n\n## v0.1.C (2026-04-03)\n\n- 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.\n\n## v0.1.B (2026-03-31)\n\n- 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 -\u003e 0..65535` scaling with obsolete nonlinear/quantile stretch code removed.\n\n## v0.1.A (2026-03-29)\n\n- 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.\n\n## v0.1.9 (2026-03-28)\n\n- 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.\n\n## v0.1.8 (2026-03-25)\n\n- Improved Linux packaging scripts to bundle all required shared libraries (OpenCV, CFITSIO, yaml-cpp, etc.) for better cross-distribution compatibility and reduced dependency issues.\n\n## v0.1.7 (2026-03-24)\n\n- Fixed Linux AppImage packaging to export `TILE_COMPILE_INPUT_SEARCH_ROOTS` so directory scanning works correctly in packaged releases.\n- Enhanced GUI2 file browser to always show parent directory (..) even when not yet granted, triggering permission dialog on click for seamless navigation.\n\n## v0.1.6 (2026-03-24)\n\n- 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.\n\n## v0.1.5 (2026-03-23)\n\n- 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.\n\n## v0.1.4 (2026-03-22)\n\n- 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.\n- 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.\n\n## v0.1.3 (2026-03-21)\n\n- 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.\n- Fixed GUI2 resume/run-monitor status updates so the active phase/status becomes visible immediately without requiring a manual page refresh.\n\n## v0.1.2 (2026-03-20)\n\n- Fixed Alt/Az registration validation to score warps on the actual common overlap instead of the cropped full-frame canvas.\n- Relaxed over-aggressive CC outlier rejection for long rotating sessions by keeping the CC threshold absolute instead of run-global MAD-relative.\n- 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.\n\n## v0.1.1 (2026-03-19)\n\n- Improved GUI2 tool persistence and PCC save handling, including temporary-output based saving and cross-platform temp-path behavior.\n- Hardened backend memory usage and significantly reduced BGE autotune runtime on the IC434 reference run while preserving the selected solution behavior.\n\n## v0.1.0 (2026-03-18)\n\n- Fixed Astrometry/PCC tool path inputs being overwritten by backend defaults.\n\n## v0.0.F (2026-03-17)\n\n- Promoted the DSO tile-reconstruction methodology to `v3.3.8` in EN/DE and aligned it with the active runtime semantics.\n- 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.\n- Fixed GUI2 run-name reset so changing the input directory clears the shared `run_name` across dashboard, wizard, and input-scan.\n- Added a macOS 15 / Sequoia Gatekeeper note for `start_gui2.command` and blocked package approval via `System Settings -\u003e Privacy \u0026 Security`.\n- Switched ASTAP `d80` catalog downloads to platform-specific upstream packages: Linux `.deb`, macOS `.pkg`, Windows `.exe`.\n\n## v0.0.E (2026-03-15)\n\n- Wired `assumptions.frames_min` into the active runner mode-gate and `assumptions.reduced_mode_cluster_range` into reduced-mode clustering.engine\n- Removed stale `assumptions.pipeline_profile`, `assumptions.frames_optimal`, and `assumptions.exposure_time_tolerance_percent` from the active config/schema/frontend/docs/examples surface.\n- Regenerated the C++ schema and synchronized Parameter Studio, Assumptions UI, and methodology/reference docs with the active runtime semantics.\n\n## v0.0.D (2026-03-15)\n\n- Expanded `TILE_RECONSTRUCTION` boundary diagnostics to separate raw vs. normalized tile mismatches and exclude masked canvas zones from the metric.\n- Added artifact visibility for `tile_norm_bg_*` and `tile_norm_scale` to diagnose whether per-tile normalization itself amplifies visible seams.\n- Synchronized GUI2 `run_name` and `runs_dir` across dashboard, wizard, and input-scan, including direct editing on the input-scan page.\n\n## v0.0.C (2026-03-13)\n\n- GUI2 parameter/config handling synchronized with the current C++ config schema, defaults, and reference docs.\n- Added boundary diagnostics for visible tile mismatches in `TILE_RECONSTRUCTION` and removed the ineffective dedicated seam-correction config block.\n- Expanded run-monitor resume handling, live-log detail visibility, and config revision/template flows.\n\n## v0.0.B (2026-03-12)\n\n- Added server-side persistence for the GUI2 UI draft state via backend API/state storage.\n- Migrated UX-relevant frontend parameters away from local browser storage to a central server-backed UI state.\n- Synchronized run names, preset selections, config drafts, validation state, and tool inputs/results more consistently across dashboard, parameter studio, wizard, and tools.\n\n## v0.0.A (2026-03-12)\n\n- Bugfixes\n\n## v0.0.9 (2026-03-11)\n\n- Added Linux AppImage generation to the GitHub Actions release workflow.\n- Reworked PCC background-noise handling and connected UI/report updates so current PCC diagnostics are exposed more consistently in the GUI.\n\n## v0.0.8 (2026-03-11)\n\n- zero-copy COMMON_OVERLAP\n- Scratch reuse in LOCAL_METRICS\n- reduced lock contention in tile_weighted-OLA\n- faster sigma-clip kernel\n- fewer tile copies in tile_weighted path\n- parallel BGE autotune candidate evaluation\n\n## v0.0.7 (2026-03-11)\n\n- Supports now:\n  - Linux: x86_64 Linux with `glibc \u003e= 2.39` (Ubuntu 24.04 or equivalent is the safe baseline for the current CI-built ZIPs)\n  - macOS: macOS 15\n  - Windows: Windows 10 x64 or newer\n\n## v0.0.6 (2026-03-11)\n\n- Completed the productive migration to the Crow/C++ backend.\n- Integrated C++ report generation.\n- Updated launcher scripts, Docker packaging, and GitHub workflows to build and run the C++ backend directly.\n\n## v0.0.5 (2026-03-09)\n\n- Promoted GUI2 as the recommended interface with a web frontend, FastAPI backend, and cross-platform release bundles.\n- Expanded DE/EN i18n coverage in the GUI2 frontend and parameter studio, with aligned docs and backend config handling.\n- Moved the previous Qt6 GUI path into `legacy/` and clarified the actively maintained GUI2 packaging/start workflow.\n\n## v0.0.4 (2026-03-06)\n\n- Fixed Alt/Az registration for datasets with large field rotation.\n\n## v0.0.3 (2026-03-05)\n\n- Improved BGE/PCC pipeline with clearer phase visibility, stronger guardrails, and a more consistent config surface.\n- Expanded parallel execution in compute-heavy stages.\n- Multiple phase optimizations for more stable behavior and lower runtime overhead.\n\n## v0.0.2 (2026-02-16)\n\n- First release with pre-built packages for Windows, Linux, and macOS\n- Includes GUI, CLI, and runner executables\n- Experimental release for testing purposes\n\n## v0.0.1 (2026-02-15)\n\n- First public release\n\n## Changelog\n\n### (2026-06-09)\n\n**Switch to AQMH as default reconstruction method:**\n- AQMH (Adaptive Quality Map Harvesting) is now the default reconstruction path. Set `aqmh.enabled: false` to revert to classic TILE_RECONSTRUCTION.\n- Normative specification: [AQMH Methodology v0.1.0](docs/AQMH/aqmh_methodik_en.md)\n- All example YAML profiles updated with `aqmh:` configuration block.\n- Full AQMH parameter documentation added to configuration reference and practical examples.\n- `k_artifact` implementation default changed to `3.0`, `frac_artifact_max` to `0.25`.\n- Main READMEs restructured; classic TBQR documentation preserved in `README_classic_tile_compile_en.md` / `README_classic_tile_compile_de.md`.\n\n### (2026-05-25)\n\n**Raw Stack preprocessing pipeline (`v0.2.8`):**\n\n- Added a new standalone Raw Stack page in GUI2 for end-to-end preprocessing of FITS light frames through to a stacked and post-processed image, running fully separately from the normal Tile-Compile run studio.\n- The pipeline covers all phases: Calibration (Bias/Dark/Flat), CFA/Mono Prep, Registration, Quality Analysis, Frame Filtering, Stacking (Sigma/Median/Winsor), Astrometry (ASTAP), Background Gradient Extraction (BGE), Photometric Color Calibration (PCC), and HyperMetric Stretch.\n- All configurable parameters (sigma-clip, rejection method, stacking weighting, BGE, PCC, Astrometry, and HyperMetric Stretch) are taken directly from the Parameter Studio configuration — no hardcoded values.\n- Output scaling correctly restores background and scale after stacking to produce accurate pixel values.\n- Raw Stack UI cleanup: removed Run Monitor button, added full i18n coverage for all labels and buttons.\n- See [docs/raw_stack_gui_en.md](docs/raw_stack_gui_en.md) for the full GUI reference.\n\n### (2026-05-22) \n\n**implementationHMS:**\n- Added VeraLux HyperMetric Stretch (HMS) as a post-PCC pipeline phase.\n- HMS now defaults to enabled in the C++ config defaults, `tile_compile.yaml`, and all example YAML profiles.\n- The default mode is `ready_to_use`, using adaptive anchor, Auto LogD, target background `0.2`, and output `outputs/stacked_rgb_hms.fits`.\n- `mode: scientific` is implemented for controlled stretch output without ready-to-use final scaling/soft clip and with optional `linear_expansion`.\n- Resume supports rerunning HMS directly via `--from-phase HYPERMETRIC_STRETCH` for historical runs with existing PCC artifacts.\n\n### (2026-05-20) \n\n**Build hardening \u0026 Frontend cleanup:**\n- Fixed RunnerFrameCache build errors: implemented missing `try_load_normalized` and `store_normalized` methods\n- Migrated both C++ projects to C++20 (GCC 13+, Clang 16+)\n- Hardened web_backend_cpp build with CUDA 13 + OpenCV 4.11 CUDA 13 configuration\n- Backend route_utils: fixed incomplete AppState type errors, hardened path validation\n- Frontend refactoring: centralized utilities in `src/utils.js` (escapeHtml, getMessage, getStorageJson, humanizeControlId, etc.)\n- Migrated shell.js, parameter-studio-page.js, and tooltips.js to ES6 modules with shared utils.js imports\n- Eliminated duplicate I18N functions across frontend scripts (message(), textFor(), activeLocale(), getLocale())\n- Removed dead code: `param_editor_index.json` (36KB unused duplicate)\n- Updated documentation: unified C++20 requirements, release URLs updated to v0.2.5\n\n### (2026-04-26)\n\n**Documentation system and BGE robustness (`v0.2.5`, 2026-04-26):**\n\n- Added professional documentation system using MkDocs Material with Doxygen integration for C++ API reference\n- Updated all GitHub Releases documentation with correct binary filenames (tile_compile_gui2-linux-v0.2.4.zip, etc.)\n- Added comprehensive installation instructions for pre-built binaries on Ubuntu/Debian, Fedora/RHEL, and Arch/Manjaro\n- Restructured navigation with separate User Guide, Configuration, Methodology, and API Reference sections\n- Added configurable `bge.sample_estimator` support in YAML configs, schema files, and Parameter Studio (`quantile`, `sigma_clipped_median`, `sextractor_mode`, `biweight`)\n- Extended BGE autotune so it can compare sample estimators and penalize or reject flat models when background/chroma spread indicates a real gradient\n- Extended RGB chroma guards across BGE methods, including conservative fallbacks for imbalanced per-channel correction surfaces\n- Updated `ic434_background_gradient.example.yaml` with robust RBF/`sextractor_mode` settings for IC434-like red/green background gradients\n- Added `docs/reconstruction_audit_2026-04-26.md` with the reconstruction audit checklist and implementation notes\n- Hardened reconstruction fallback helpers against mismatched frame/tile shapes and missing or invalid tile weights\n- Reworked `reconstruct_tiles_parallel()` to use tile-sized temporary OLA buffers instead of full-frame scratch matrices per tile/sub-batch\n- Updated reconstruction memory budgeting so it accounts for global overlap-add accumulators plus per-worker tile scratch\n- Removed ineffective reconstruction scheduler/config dead code, including the unused GPU batch field, unused `make_hann_1d()` API, and non-functional underutilization detector\n\n### (2026-04-25)\n\n**Registration performance: parallel anchor-promotion retries (`v0.2.4`):**\n\n- Fixed the direct-registration anchor-promotion loop so promoted-anchor retry passes use the configured parallel registration worker pool instead of falling back to a single-threaded `reg_worker()` call.\n- Promotion rounds now build a targeted retry list and only revisit unresolved frames whose nearest active anchor is one of the newly promoted anchors, avoiding repeated full 325-frame passes when the anchor set changes.\n- Registration progress now reports the actual job count and worker count for each pass, and `global_registration.json` diagnostics include `reg_promotion_retry_frames` for future runtime analysis.\n\n### (2026-04-24)\n\n**Registration robustness: deep-chain rejection + adaptive anchors + hopping rescue + astrometric fallback (`v0.2.3`):**\n\n- Reject chain-validated frames with `chain_depth \u003e max_blind_chain_depth` and `cc \u003c reject_cc_min_abs` as `deep_chain_low_cc` outliers instead of accepting them; this prevents drift from long sequential chains through cloudy blocks.\n- Increased adaptive active-anchor target from `min(21, max(3, (N+59)/60))` to `min(32, max(4, (N+29)/30))`, doubling anchor density for large-N sessions (e.g., 325 frames now use ~12 anchors instead of ~6).\n- \"Hopping\" sequential rescue: when the direct neighbor has low CC or cannot anchor a blind chain, search up to 5 frames (for refine) or 8 frames (for rescue) in each direction for a better anchor with CC \u003e 0.3–0.4, dramatically reducing chain depth in scattered-cloud conditions.\n- Astrometric rescue moved to run *after* model-based warp prediction (Section 4b), so ASTAP can now also rescue frames that only have interpolated `model_*` provenances; added `weak_model` condition to `should_try_astrometry` so low-CC model frames are eligible for plate-solving.\n\n### (2026-04-24)\n\n**Hot/dead-pixel correction fix + registration code quality (`v0.2.2`):**\n\n- Fixed `cosmetic_correction_cfa` silently skipping defective pixels inside star regions: `neighbor_threshold` was set to `0.5 × global_threshold`, so star-halo pixels (which sit well above that low bar) were counted as \"hot neighbours\" and blocked correction of genuine hot pixels nearby. The threshold is now raised to the full global hot-pixel threshold, so only pixels that are themselves hot-pixel candidates count as hot neighbours.\n- Added `extreme_outlier` bypass: pixels exceeding `local_median + 5 × local_floor` are replaced unconditionally regardless of neighbourhood support. No real star-PSF pixel reaches that level relative to its same-colour neighbours.\n- Added dead/cold-pixel correction: `global_candidate_cold` (`\u003c median − σ_threshold × σ`) and `cold_outlier` (`\u003c local_median − local_floor`) are now also replaced with the local same-colour median.\n- All three fixes operate on the raw CFA mosaic before warping and require no dark frames.\n- Diagnostic keys in `global_reg_extra` moved into a `diag` sub-object (4.2); downstream-facing keys remain at top level.\n- Section headers added to `run_phase_registration_prewarp` to mark the seven major processing phases (4.1).\n\n### (2026-04-23)\n\n**Registration NCC robustness + near-identity guard (`v0.2.1`):**\n\n- NCC computation in `try_method` now clamps negative values and applies a Gaussian blur (σ=1.5) before computing `ncc_identity_overlap` and `ncc_warped`. Raw normalized proxy images carry negative background values and hot pixels that caused NCC to collapse from ~0.88 to ~0.05 for sub-pixel shifts, triggering false near-identity rejections.\n- Near-identity bypass condition strengthened with an `ncc_identity \u003e 0.7` guard: a near-zero warp is only accepted as a valid near-identity result when the frame is already close to the reference, preventing false bypasses for frames that simply failed to find a shift.\n\n### (2026-04-14)\n\n**Registration v0.2.0: multi-anchor scaling + astrometric registration/rescue:**\n\n- Global registration no longer relies on rigid `1/3/5` reference buckets. It now uses an N-scaled anchor selection with roughly one requested anchor per 80 frames, forced to odd anchor counts and currently capped at 15.\n- Anchor promotion after strong direct matches now scales with `N` as well: the active-anchor target is roughly one anchor per 60 frames, while per-round promotions and the number of extra direct passes grow in a controlled way for long sessions.\n- This reduces the classic late-reference failure mode on long Alt/Az datasets, because early and late parts of the sequence can attach directly to nearer temporal anchors instead of being forced through one distant master frame.\n- Astrometric registration/rescue in the runner was upgraded in practice: ASTAP-based solves are no longer limited to `cc \u003c= 0`, but can also replace weak or deeply chained results, using the nearest active anchor as the astrometric reference basis.\n- New registration telemetry was added to `global_registration.json`, including `requested_ref_frames`, `active_ref_frames`, `reg_target_active_anchor_count`, `reg_promote_limit_per_round`, `reg_max_direct_anchor_rounds`, `reg_direct_anchor_rounds`, and `reg_source_counts`.\n- Added the new example profile [tile_compile_cpp/examples/m104.example.yaml](tile_compile_cpp/examples/m104.example.yaml) for the concrete problem class \"Alt/Az, somewhat stronger rotation, poor seeing, weight better frames more strongly\"; the DE/EN practical examples and [docs/process_flow/phase_1_registration.md](docs/process_flow/phase_1_registration.md) were updated to match the current registration flow.\n\n### (2026-04-07)\n\n**TILE_RECONSTRUCTION performance: sub-batch stacking replaces worker reduction (`v0.1.F`):**\n\n- Replaced the memory-budget-driven worker reduction in TILE_RECONSTRUCTION with frame sub-batching. Previously, a 2 GB memory budget capped OSC runs at 3 parallel workers (instead of the configured 8) because the peak RAM estimate assumed all frames loaded simultaneously per worker. Workers now always run at the configured `parallel_workers` count; the budget controls the sub-batch size (frames per batch) instead. For the reference run (610 frames, 475 tiles, 8 workers, 2 GB budget) this yields ~3 batches of ~205 frames each — same quality, ~2.7× faster TILE_RECONSTRUCTION.\n- `tile_boundary_diagnostics_enabled` added to `runtime_limits` (default: `false`). Boundary diagnostics are now opt-in; the previous default of always running them added ~5–10 % overhead per production run.\n- `tile_grid.json` now includes `estimated_reconstruction_time_s` (calibrated estimate based on tile count, frame count, and worker count) and `coverage_filtered_tiles`.\n- `runtime_limits.json` now includes `tile_analysis_to_stack_ratio`; a warning is logged when the ratio exceeds 10.\n- `phase_end` event for TILE_RECONSTRUCTION now includes `duration_s`.\n- web_backend_cpp code-quality fixes: consolidated three duplicate `utc_now_iso()` implementations into a shared header, fixed SIGKILL being sent on every polling cycle after SIGTERM (now waits ~3 s), fixed FD leak on `fork()` failure, fixed sequential stdout/stderr read deadlock in `run_subprocess()`, and reduced `prune_locked()` call frequency from every mutation to terminal-state transitions only.\n\n### (2026-04-06)\n\n**Calibration fix + Parameter Studio reorganization (`v0.1.E`):**\n\n- Fixed the bias/dark calibration path: when bias and dark are both enabled, a raw dark is now bias-corrected internally before being applied to lights, preventing double subtraction of the bias pedestal.\n- Added the new config field `calibration.dark_already_bias_corrected` across runner, schema, docs, defaults, example configs, and GUI2 so pre-bias-corrected master darks can be marked explicitly.\n- Reorganized Parameter Studio: selecting a category such as `registration` or `calibration` now shows exactly one consolidated section; missing schema parameters are injected into that same block instead of being rendered in a separate section editor above it.\n\n### (2026-04-05)\n\n**Calibration guardrails and backend persistence for calibration paths:**\n\n- Updated GUI2 calibration-path handling so disabling a calibration stage removes its paths from the active config immediately and re-enabling restores the previously used paths from backend UI state, without using browser storage.\n- Added extra calibration guardrails, including warnings for obvious gain mismatches between light frames and calibration files.\n\n### (2026-04-04)\n\n**Auto-engine for Alt/Az field rotation + registration failure fix (`v0.1.D`):**\n\n- 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).\n- 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.\n- Updated `tile_compile.yaml` default engine to `triangle_star_matching` and `reject_cc_min_abs` to `0.05`.\n- Propagated new config fields to all schemas, example configs, and documentation.\n\n### (2026-04-03)\n\n**Tile-reconstruction stabilization after recent optimization rollout (`v0.1.C`):**\n\n- 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.\n\n### (2026-03-29)\n\n**RGB/PCC output-path stabilization after the `v3.3.9` rollout (`v0.1.A`):**\n\n- 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.\n- 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.\n- 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.\n\n### (2026-03-28)\n\n**Implementation and rollout of the `v3.3.9` methodology (`v0.1.9`):**\n\n- 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.\n- 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.\n- 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.\n\n### (2026-03-24)\n\n**AppImage packaging fix + file browser navigation enhancement (`v0.1.7`):**\n\n- 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.\n- 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.\n- 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.\n\n**GUI2 batch/queue run-monitor refresh + docs update (`v0.1.6`):**\n\n- 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.\n- 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.\n- 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.\n- 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.\n\n### (2026-03-23)\n\n**OpenCL expansion for `PREWARP`, `TILE_RECONSTRUCTION`, and `STACKING` (`v0.1.5`):**\n\n- Stabilized the OpenCL `PREWARP` path for multi-threaded execution by guarding OpenCV OpenCL/T-API access and forcing explicit host copies where needed.\n- 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.\n\n### (2026-03-22)\n\n**Real `STACKING` resume + synthetic OLA seam fix (`v0.1.4`):**\n\n- 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.\n- 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.\n\n### (2026-03-21)\n\n**Registration provenance/depth diagnostics + resume status visibility (`v0.1.3`):**\n\n- 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`.\n- 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.\n- Added aggregate registration diagnostics such as source counts, maximum observed chain depth, and blocked blind-chain-anchor attempts to the registration artifact metadata.\n- 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.\n\n### (2026-03-20)\n\n**Registration/field-rotation stabilization for long Alt/Az sessions (`v0.1.2`):**\n\n- 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.\n- 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.\n- 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.\n- 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.\n\n### (2026-03-19)\n\n**GUI2 tool persistence/PCC UX, backend memory guards, and BGE autotune speed-up:**\n\n- 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.\n- Added `packaging/gui2/.env.example` and documented the new backend runtime limit environment variables used by GUI2 launchers.\n- Fixed GUI2 frontend/backend asset serving and route behavior so `/ui` and direct asset paths resolve reliably instead of producing 404s.\n- 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.\n- 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.\n- Fixed standalone PCC fallback behavior when `canvas_mask` is missing by using a safe full-image fallback instead of aborting the tool run.\n- 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.\n\n### (2026-03-18)\n\n- Fixed Astrometry data directory input not being respected when user manually changes the path - now uses `shouldKeepAstapSelection` logic to preserve user input.\n- Added server-side persistence for Astrometry and PCC tool parameters via UI state API - settings survive server restarts.\n- Improved catalog download intelligence: Astrometry catalogs skip download if already installed, PCC Siril only downloads missing chunks.\n- Enhanced archive extraction robustness for macOS `.pkg`, Linux `.deb`, and Windows `.exe` formats with better error messages and validation.\n- Fixed macOS release bundle library issues by explicitly bundling GCC runtime libraries (`libgcc_s`, `libgfortran`, `libquadmath`, `libgomp`) and preserving `libstdc++` for Homebrew-compiled dependencies.\n\n### (2026-03-17)\n\n**Methodology `v3.3.8` + GUI2 run-name reset (`v0.0.F`):**\n\n- Added new normative methodology documents `docs/v3/tile_basierte_qualitatsrekonstruktion_methodik_v_3.3.8_en.md` and `docs/v3/tile_basierte_qualitatsrekonstruktion_methodik_v_3.3.8_de.md`.\n- 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.\n- Fixed GUI2 so a changed input directory clears the shared `run_name` across dashboard, wizard, and input-scan.\n- Added a short macOS 15 / Sequoia install note for Gatekeeper-blocked `start_gui2.command` launch.\n- Changed ASTAP `d80` downloads from the invalid shared ZIP assumption to the real upstream platform packages: Linux `.deb`, macOS `.pkg`, Windows `.exe`.\n\n### (2026-03-15)\n\n**Assumptions runtime/config synchronization (`v0.0.E`):**\n\n- `assumptions.frames_min` is now used by the active C++ runner mode gate instead of the old hardcoded minimum-frame threshold.\n- `assumptions.reduced_mode_cluster_range` now affects reduced-mode clustering directly, so the exposed config field is no longer parser-only drift.\n- Removed dead assumptions fields from the active config surface: `pipeline_profile`, `frames_optimal`, and `exposure_time_tolerance_percent`.\n- Synchronized active C++ config code, generated schemas, example YAMLs, GUI2 Assumptions/Parameter Studio, and DE/EN docs to the remaining runtime-relevant assumptions fields.\n\n### (2026-03-15)\n\n**Boundary diagnostics deepening + GUI2 run-field synchronization:**\n\n- 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.\n- Corrected tile-boundary analysis to exclude masked `COMMON_OVERLAP` / canvas-invalid zones instead of counting them as valid zero-valued samples.\n- Updated the methodology/process/reference/practical docs to reflect the read-only raw/normalized boundary diagnostics and the common-canvas-mask requirement.\n- Added `run_name` and `runs_dir` editing to Input\u0026Scan and unified both fields across dashboard, wizard, and input-scan via the shared GUI2 stored state.\n\n### (2026-03-13)\n\n**GUI2 config/studio sync + tile-boundary diagnostics update:**\n\n- 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`.\n- Synchronized config code, generated schemas, example configs, and DE/EN reference docs with the active C++ config surface.\n- Reworked Parameter Studio so parameter inventory, defaults, ranges, tooltips, and filtering are driven from the current schema/default config instead of stale manual lists.\n- 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.\n\n### (2026-03-12)\n\n**Server-side GUI2 UI-state persistence:**\n\n- 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.\n- 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.\n- Restored and synchronized additional tool result state across reloads where useful, while keeping purely ephemeral runtime display state non-persistent.\n\n### (2026-03-11)\n\n**Crow/C++ runtime, release packaging, and PCC update:**\n\n- Finalized the productive GUI2 path around the Crow/C++ backend, including integrated C++ report generation and aligned frontend/backend report handling.\n- Updated release packaging, local build/start scripts, and GitHub workflows for Linux, macOS, and Windows, including the documented GUI2 bundle OS baselines.\n- Added Linux AppImage creation to the GitHub Actions release workflow so releases now include a portable Linux artifact alongside the ZIP bundle.\n- Added date-aware run-directory naming and aligned route/websocket handling plus backend tests for the new naming behavior.\n- Reworked PCC background-noise handling and connected UI/report updates so current PCC diagnostics are exposed more consistently in the GUI.\n\n### (2026-03-09)\n\n**GUI2 release + i18n refresh:**\n\n- Promoted the web-based GUI2 stack (`web_frontend/` + `web_backend_cpp/`) to the recommended UI path and updated the top-level docs accordingly.\n- 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/`.\n- Expanded frontend localization coverage and parameter-studio translations, with matching backend config contract updates and tests.\n- Moved the earlier Qt6 GUI/build-script path into `legacy/` to separate the maintained GUI2 route from the legacy desktop implementation.\n\n### (2026-03-10)\n\n**Python elimination in the productive GUI2 path:**\n\n- Switched GUI2 runtime, packaging, Docker, and CI to the Crow/C++ backend.\n- Removed the productive Python dependency for stats/report generation; this now runs via the integrated C++ backend path and CLI support.\n- Updated the repository structure and GUI2 documentation to reflect `web_backend_cpp/` as the maintained backend implementation.\n\n### (2026-03-05, later update)\n\n**Strict/Practical runtime unification + verification:**\n\n- Unified the image-processing runtime core path for `assumptions.pipeline_profile: strict|practical`.\n- Removed strict-only execution branches in the hot path:\n  - no strict-only pre-registration order path,\n  - no strict-only reduced/full gate override (`max(200, threshold)`),\n  - no strict-only tile re-normalization branch,\n  - no strict-only channel re-weighting branch in OSC tile stacking.\n- Registration no longer force-overrides `registration.enable_star_pair_fallback=false` in strict mode.\n- Updated config reference docs (EN/DE) so profile text matches current runtime behavior.\n- Added A/B evidence run pair (`max_frames=80`) confirming same core flow with only minor numeric fit variance.\n\n### (2026-03-05)\n\n**Performance and throughput optimization (large datasets, 1000+ frames):**\n\n- Added adaptive worker selection per phase with I/O-aware caps based on sampled frame size and task count.\n- `DiskCacheFrameStore` now uses persistent memory-mapped frame views with rewrite invalidation, reducing repeated open/mmap/unmap overhead for tile access.\n- Removed the global PREWARP store mutex so frame-cache writes can proceed concurrently.\n- `GLOBAL_METRICS` now runs in a parallel worker pool with thread-safe progress and error aggregation.\n- `TILE_RECONSTRUCTION` overlap-add switched from a single global lock to row-stripe locking to reduce contention.\n- In OSC tile reconstruction, each valid frame tile is debayered once and cached as R/G/B planes for reuse across channel stacks.\n- `LOCAL_METRICS` now skips globally invalid tiles before extraction and limits heavy full-matrix artifact writes for large production runs.\n\n### (2026-03-03)\n\n**Methodology alignment (v3.3.6 strict profile):**\n\n- Added `assumptions.pipeline_profile: practical|strict` to switch between compatibility mode and strict normative behavior.\n- In `strict` profile, REGISTRATION/PREWARP is executed before CHANNEL_SPLIT/NORMALIZATION/GLOBAL_METRICS.\n- In `strict` profile, reduced/full gating enforces full mode only from `N \u003e= 200`.\n- In `strict` profile, phase-7 tile normalization before OLA is always enabled.\n- PCC `auto_fwhm` now falls back deterministically to `FWHM=0` when seeing is unavailable.\n- Added `registration.enable_star_pair_fallback` (default `true`); strict profile disables it to match the normative cascade order.\n- Updated config schema/sample config and v3 reference docs (DE/EN) for these settings.\n\n**BGE/PCC configuration and docs alignment:**\n\n- Restored user-facing BGE fit parameters `bge.fit.robust_loss` and `bge.fit.huber_delta`.\n- Added user-facing BGE apply guards `bge.min_valid_sample_fraction_for_apply` and `bge.min_valid_samples_for_apply`.\n- Re-enabled parse/serialize/schema support for these keys in the runtime config surface.\n- Runner mapping now forwards the configured values (no internal forced override).\n- BGE config artifacts in both pipeline and resume paths include `robust_loss` and `huber_delta` again.\n- Updated BGE/PCC docs and practical examples (DE/EN) to match current behavior and active parameter set.\n\n### (2026-02-26)\n\n**BGE Phase Visibility / Comparison Outputs:**\n\n- BGE is now emitted as a dedicated pipeline enum phase (`BGE=15`) between `ASTROMETRY` and `PCC`.\n- GUI phase progress now shows BGE explicitly, including BGE substep progress updates.\n- Added explicit pre-PCC output `outputs/stacked_rgb_bge.fits` for direct BGE-only vs BGE+PCC comparison.\n- Configuration docs/examples updated for v3.3.6 option set:\n  - `bge.autotune.*` (`enabled`, `strategy`, `max_evals`, `holdout_fraction`, `alpha_flatness`, `beta_roughness`)\n  - `pcc.background_model`\n  - `pcc.max_condition_number`, `pcc.max_residual_rms`\n  - `pcc.radii_mode`\n  - `pcc.aperture_fwhm_mult`, `pcc.annulus_inner_fwhm_mult`, `pcc.annulus_outer_fwhm_mult`, `pcc.min_aperture_px`\n\n### (2026-02-25)\n\n**Registration / Canvas / Color-Correctness Fixes:**\n\n- **Bayer parity-safe offsets in registration/prewarp path**: Canvas offsets are now handled consistently to preserve CFA parity across expanded/cropped canvases.\n- **Output scaling origin fixes**: Scaling calls now use the correct tile/debayer offsets where required, preventing R/G parity mismatches after crop/canvas transforms.\n- **Common-overlap and canvas handling clarified** in process-flow docs and aligned with the current phase model.\n\n**PCC (Photometric Color Calibration) Improvements:**\n\n- **Robust log-chromaticity fit** implemented for PCC matrix estimation (instead of the older proportion-only approach).\n- **Guardrails on channel scales** added to avoid extreme global color casts.\n- **Aperture annulus contamination filter (IQR gate)** added to reject unstable star measurements in nebulous/gradient-heavy fields.\n\n**Documentation Refresh:**\n\n- `docs/process_flow/*` updated to the current production pipeline state, including `PREWARP`, `COMMON_OVERLAP`, canvas/offset propagation, and current enum phase ordering.\n\n**BGE (Background Gradient Extraction):**\n\n- Added optional pre-PCC BGE stage that directly subtracts modeled background from RGB channels.\n- 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.\n- Added `artifacts/bge.json` with per-channel diagnostics (tile samples, grid cells, residual statistics).\n- Extended report generation to include a dedicated BGE section with summary plots and residual analysis.\n\n### (2026-02-19)\n\n**Calibration Fixes:**\n\n- **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).\n\n### (2026-02-17)\n\n**New Registration Features for Alt/Az Mounts Near Pole:**\n\n- **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.\n\n- **Adaptive Star Detection**: When too few stars are detected (\u003c 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.\n\n- **New Registration Engine**: `robust_phase_ecc` with LoG gradient preprocessing, optimized for frames with strong nebulae/clouds.\n\n**Field Rotation Support:**\n\n- **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'\"`.\n\n**Documentation:**\n\n- **New**: [Practical Configuration Examples \u0026 Best Practices](docs/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.\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fjeamy%2Ftile_compile","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fjeamy%2Ftile_compile","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fjeamy%2Ftile_compile/lists"}