Stretch RGB stars independently before narrowband restoration

Cargo.toml

@@ -48,12 +48,12 @@ regex = "1.12"
 globset = "0.4"
 semver = "1"
 byteorder = "1.5"
-seiza = "0.43.0"
+seiza = "0.44.0"
 seiza-download = "0.9.0"
 seiza-imgproc = { version = "0.3.2", features = ["parallel"] }
 seiza-fits = "=0.6.0"
-seiza-satellites = { version = "0.22.1", features = ["serde"] }
-seiza-stacking = "0.50.0"
+seiza-satellites = { version = "0.22.2", features = ["serde"] }
+seiza-stacking = "0.51.0"
 seiza-stretch = "0.3.2"
 # XISF reading. Already in the tree through seiza-stacking, which decodes both
 # containers into the same `seiza_fits::FitsImage`.

docs/STACKING_PREVIEWS.md

@@ -1707,6 +1707,8 @@ keeps its saved result but does not replace the latest color preview.
 
 ### Automatic narrowband and RGB stars
 
+Use the **✨ Stars** selector beside the palette to choose which stars the preview restores.
+
 Use the regular narrowband card beside RGB and LRGB. Its header has three
 choices: **Palette**, **Stars**, and **Edges**. You do not need to open a
 custom combination to use automatic processing.
@@ -1750,12 +1752,44 @@ by Narrowband Normalization, with no claim of matching the PixInsight script.
 A default Color setup with different per-filter stretches keeps those stretches.
 
 RGB color calibration runs on star-containing linear RGB before star removal.
-The original and starless RGB then receive the same linked display stretch;
-their difference supplies the RGB stars without adding a second nebula. The
-nebula's output stretch stages run after recombination. Foraxx keeps its
+StarXTerminator always separates the RGB stars while the RGB image is linear.
+New automatic recipes then apply **Star Stretch** only to the extracted linear
+stars before screening them over the stretched nebula. Open **Processing stack
+→ Combine and restore stars → RGB star stretch**. Lower **Amount** to make stars
+fainter; 5 is the starting value, and 0 keeps the linear residual without a
+nonlinear lift. The nebula stretch and BXT settings stay independent. **RGB star
+reduction** can further reduce the stretched stars before restoration.
+
+Saved setups keep **Auto MTF (legacy)** until you choose **Star Stretch** and
+apply the processing stack. The legacy mode applies one linked display transfer
+to the original and starless RGB pair before extracting the screen layer.
+Star Stretch uses the tone formula published by [SetiAstro](https://www.setiastro.com/pjsr-scripts);
+it does not reproduce PixInsight's optional saturation or SCNR processes.
+The nebula's output stretch stages run after recombination. Foraxx keeps its
 existing dynamic mapping and disables the new shared H-alpha stretch and
 narrowband balance controls.
 
+![Independent RGB star stretch controls](images/stack-rgb-star-stretch-desktop.png)
+
+### Configure linear star separation
+
+Open **Processing stack → Process linear color**. Each managed narrowband or
+RGB branch has **Star separation** controls for StarXTerminator. **Tile Overlap**
+starts at the installed tool's default and is saved with the processing setup.
+The RGB branch also exposes its Gaia color-calibration choice, before SXT; saved
+setups keep that choice separately from the false-color nebula.
+The Stars selector controls which branches run; use Narrowband to keep native
+stars, or None for a starless result. Star separation always runs on linear data.
+The managed run keeps both the starless and stars images, with Unscreen Stars off.
+
+Completed compositions retain each branch's exact cache ID, tool/model version,
+resolved settings and links to its **Linear … starless FITS** and **Linear … stars
+FITS**. Stretch, palette, green-reduction and star-reduction edits reuse those
+linear outputs when their inputs are unchanged. Broadband structure blend
+amounts also reuse them. Changing one branch's SXT settings reruns that branch;
+new linear inputs, continuum coefficients, calibration or tool/model versions
+invalidate the affected run. Default-valued SXT settings reuse the default run.
+
 ### Sharpen RGB stars with BlurXTerminator
 
 Open the narrowband card's **Processing stack → Process linear color → RGB star processing**. Enable

docs/design/color-channel-processing.md

@@ -289,8 +289,21 @@ neutral pixels are unchanged. This is an aesthetic operation with no SCNR
 parity claim. It runs after mapping, before broadband structure and RGB stars.
 
 An RGB-star branch optionally runs BXT/NXT on linear RGB, then the selected
-Gaia calibration and SXT. The RGB original and starless copy share the same
-color-preserving stretch before screen recombination. Gaia settings, its
+Gaia calibration and SXT, always before a display stretch. With
+`rgb_star_stretch` set, Seiza extracts the linear residual and applies the
+SetiAstro-style rational tone only to those stars. The optional amount is [0,8],
+with 5 seeded into new automatic recipes. A lower amount subdues stars; zero
+keeps the normalized linear residual. One linked source range matches the
+external-tool normalization; the background offset cancels in the residual.
+The stars-only layer is never independently normalized to its own peak.
+
+An absent/null field preserves the legacy common Auto MTF transfer of the RGB
+original/starless pair. The starless RGB still receives that display transfer
+for optional broadband structure. The independent star layer is screened once,
+after optional linked star reduction. Only the final composition identity
+includes the tone amount: linear input, BXT, Gaia and SXT artifacts remain
+reusable. C/Python/CLI surfaces live in Seiza. This implements the published
+tone, without claiming parity with PixInsight ColorSaturation/SCNR. Gaia settings, its
 pixel-solve/catalog basis and RC-Astro/model versions participate in the RGB
 SXT cache identity. Disabling Gaia preserves the RGB processing branch.
 
@@ -449,8 +462,8 @@ changes the final composition identity, with linear inputs, BXT and SXT still
 reusable. It applies only during RGB restoration, after mapping/green reduction
 and broadband-structure blending. Native stars and natural RGB/LRGB are unchanged.
 
-Seiza derives the display screen-star layer from the consistently stretched RGB
-original/starless pair. Its maximum RGB component supplies an intensity plane.
+Seiza uses the independently stretched linear residual when selected; legacy
+mode derives its screen-star layer from the consistently stretched RGB pair. Its maximum RGB component supplies an intensity plane.
 Blend that plane toward a one-pixel cross erosion, then apply the resulting
 common gain to all three star components before screen recombination. This
 preserves layer RGB ratios and cannot brighten stars. Invalid neighbours and
@@ -515,13 +528,61 @@ stored amount. Stored processing fields, algorithms and cache identity are
 unchanged by the layout. The narrowband-only built-in setup is hidden on natural
 RGB/LRGB emission cards; saved setups still use the existing role reconciler.
 
+### Independent star-stretch validation
+
+A fresh RC-Astro 2.6.10 run on SNR G132 compared legacy Auto MTF with Star
+Stretch amounts 5, 4 and 3, plus amount 3 with reduction 0.4. Each result uses
+BXT ML5, solar Gaia calibration and linear SXT ML11. Continuum is off,
+broadband structure is 0, and green reduction is 0.2. Every result shares the
+same 4757 × 3156 grid, linear-input identity and three RC-Astro identities.
+Changes after the first tool run completed in about 16–18 seconds using the
+cached branches. Amounts 3 → 4 → 5 brighten monotonically on every finite pixel;
+the nebula processing is identical.
+
+The native 800 × 800 crops cover (1978,1178)–(2778,1978), without resizing.
+[Validation data](../images/snrg132-star-stretch.json) records settings,
+identities, checksums and timings. The separate local smoke test used registered
+512 × 512 RGB and RC-Astro 2.6.10 BXT ML5 → NXT ML3 → linear SXT ML11 before
+Seiza's tone. SXT's positive residual agreed within 6e-8; negative residuals
+were clipped only in the derived display layer.
+
+![Legacy Auto MTF RGB stars](../images/snrg132-stars-legacy.png)
+
+![Independent Star Stretch amount 5](../images/snrg132-stars-stretch5.png)
+
+![Independent Star Stretch amount 3](../images/snrg132-stars-stretch3.png)
+
+### Cache and configure managed linear SXT
+
+`nebula_star_separation` and `rgb_star_separation` are optional SXT-only
+`RcAstroProcessing` settings on `NarrowbandProcessing`. Each branch resolves its
+own schema-validated parameters and chain identity. Missing/default settings
+retain the original managed identity. Defaults canonicalize before hashing;
+`stars`/`difference` must be true and `unscreen` must be false. Display changes
+never enter these tool settings.
+
+Mapped nebula identities include only the continuum inputs that change linear
+pixels. Broadband structure amount, line display amounts, positive display
+contribution and flux-export calibration no longer invalidate mapped BXT/SXT.
+Input/clipping revisions, subtraction mode, manual coefficients, photometry and
+fit options still do. RGB calibration settings/basis and earlier BXT/NXT identities
+remain part of the RGB separation key. Palette changes reuse only when the same
+physical linear planes and grid are supplied.
+
+`NarrowbandResolution` records typed per-branch linear SXT reports alongside the
+retained chain IDs: cache ID, resolved processing, CLI/model result, starless FITS
+URL and stars FITS URL. They persist in the final composition manifest and latest
+index. Existing cache retention protects those identities; a cache hit reloads
+both linear FITS outputs and refreshes use time. Regression tests count actual
+stand-in invocations across stretch/reduction edits and independent branch retunes,
+round-trip the final manifest, and verify 30-day-old referenced runs survive pruning.
+Missing stars files invalidate the final artifact references; rebuilding repairs only
+the affected branch. The real SNR G132 check reused all three RC-Astro IDs for
+explicit default overlap and broadband blend changes, completing in 10 and 8 seconds.
+[Cache validation](../images/snrg132-sxt-cache.json) records the exact outputs.
+
 ## Follow-up work
 
 - [ ] For automatic RGB-star source selection, prefer the shortest available
   RGB exposure group (for example, 60s rather than 300s) when several exposure
   groups qualify. Preserve explicit source choices in Custom combination.
-- [ ] Match the RGB-star stretch to SetiAstro's Star Stretch script rather than
-  the current general-purpose Auto-MTF/shared display stretch. Research the
-  script's behavior and parity requirements. Add a dedicated operation in
-  Seiza if needed, carry it through the C/Python/CLI surfaces, and expose the
-  matching RGB-star control in PSF Guard.

docs/images/snrg132-star-stretch.json

@@ -0,0 +1,110 @@
+{
+  "dimensions": [
+    4757,
+    3156
+  ],
+  "crop": [
+    1978,
+    1178,
+    2778,
+    1978
+  ],
+  "rc_astro": "2.6.10",
+  "bxt": "ML5, ss default0.5 / halo0",
+  "sxt": "ML11, linear before star stretch",
+  "gaia": "solar",
+  "continuum": "off",
+  "broadband_structure": 0,
+  "green_reduction": 0.2,
+  "maximum_monotonic_error": [
+    0.0,
+    0.0
+  ],
+  "sha256": {
+    "legacy-auto-mtf-crop.png": "9c3192ce5124ccdcbe072ab3ad1365a891f7183655593a694b157e70f82cc80e",
+    "legacy-auto-mtf-full.png": "1fe7cab2f3702f9a37fc86cdee3aac8aa9d7097b3772dfd5153652d29a3002a8",
+    "local-stars-0.png": "f57b41b4e7a5b6b5495556a000c61747368e2b5a857d319ddee0e6d02a40484c",
+    "local-stars-3.png": "5f9025bae9325ca3ef97881bde7455dca2122e14bd139a3559a9d13102681fa7",
+    "local-stars-4.png": "54aded46cec10a5c88cd047674d31b890450b418125c7b1d841f7b4b336b3cae",
+    "local-stars-5.png": "c98e8b34e1e8f6329ede01b5b4379e79d5e201b74bb386e1e1a221ab2d94febf",
+    "stack-rgb-star-stretch-desktop.png": "ef82898bfbbd4042408cb2958f446758da14c96cb11bf3f18ab6aa0c550f3f70",
+    "stack-rgb-star-stretch-phone.png": "ad34d36b08274677ef737aa43e133eaf9d22e34fde6869a37bc8eaadd857db66",
+    "stack-star-policy-desktop.png": "723cfc949b1714a04c3b365f7da2ecd8a4b0503320f5fb9371010086eb785439",
+    "stack-star-policy-phone.png": "c2a8ed2dec0625cb7a580786ffa0b7be3b35f2e17fbe2bc63412c55da127cd6b",
+    "star-stretch-3-crop.png": "ba0075cf8ec245a5d6e7f8baa2ccd077c864300847f8a2572d7947a9c7ab826d",
+    "star-stretch-3-full.png": "a2669b6d17818b42a0d0a93437d8ecfbec7065f2af13c26735ac17e84e4d7250",
+    "star-stretch-3-reduced-crop.png": "c0c71a1ef1e914fabec343e2c2eb6f28f4800b9167a1a341997bd8f260d76406",
+    "star-stretch-3-reduced-full.png": "8c1d1417eab6af3cd72fc06078f60e00ad609be328b490afb752a19a74b0b84d",
+    "star-stretch-4-crop.png": "f95e00d5635615f756d3a37bc94c627df0cbf7f0745427969f69f296c87d9495",
+    "star-stretch-4-full.png": "86868d17e2c716dd5beddb5a9f282c119fb8f4e9211b5f6e4ccd50a1f9bbceba",
+    "star-stretch-5-crop.png": "c05519eaea5050cf676f87a2044bd81d8f8bb6a40c907f5533f1f1887e1c83ae",
+    "star-stretch-5-full.png": "a344e9878f9d823fa9bc75546ae387234765b9ae17c0ba9ddc2d13467f33436c"
+  },
+  "jobs": [
+    {
+      "name": "legacy-auto-mtf",
+      "amount": null,
+      "reduction": 0,
+      "job_id": "59438794e070b178b7daaf8028f8e5a4cb353962dd8cb255a16d0afa96394754",
+      "seconds": 360.96,
+      "rc_astro_ids": [
+        "e35fb9a3ff338a8dd60ea14a45608cc2d257486b55860aa9b592889e8d85c1e1",
+        "7be4806688a3ce2b7e84d67ca965ce6870404e1874f8ae346eeb1504ee5baa1a",
+        "076d26251a8b3596c8d3434d92ba8140d3e1d0c5ba209d34d2101bdf78ada298"
+      ],
+      "linear_input_id": "efc68e0694cda28fd9b5cbf117adb760e2e8ae20cb3e6c3879ffc6b0227561e1"
+    },
+    {
+      "name": "star-stretch-5",
+      "amount": 5,
+      "reduction": 0,
+      "job_id": "90fde6bb4d0b1918cdf300fa579d1e94552a8d3a1ac4e8104ca596877bdb3125",
+      "seconds": 2.2,
+      "rc_astro_ids": [
+        "e35fb9a3ff338a8dd60ea14a45608cc2d257486b55860aa9b592889e8d85c1e1",
+        "7be4806688a3ce2b7e84d67ca965ce6870404e1874f8ae346eeb1504ee5baa1a",
+        "076d26251a8b3596c8d3434d92ba8140d3e1d0c5ba209d34d2101bdf78ada298"
+      ],
+      "linear_input_id": "efc68e0694cda28fd9b5cbf117adb760e2e8ae20cb3e6c3879ffc6b0227561e1"
+    },
+    {
+      "name": "star-stretch-4",
+      "amount": 4,
+      "reduction": 0,
+      "job_id": "dde08ccd393e8b4049d902c250fec930472aff30ea299daf6f27c6500b6f385c",
+      "seconds": 10.18,
+      "rc_astro_ids": [
+        "e35fb9a3ff338a8dd60ea14a45608cc2d257486b55860aa9b592889e8d85c1e1",
+        "7be4806688a3ce2b7e84d67ca965ce6870404e1874f8ae346eeb1504ee5baa1a",
+        "076d26251a8b3596c8d3434d92ba8140d3e1d0c5ba209d34d2101bdf78ada298"
+      ],
+      "linear_input_id": "efc68e0694cda28fd9b5cbf117adb760e2e8ae20cb3e6c3879ffc6b0227561e1"
+    },
+    {
+      "name": "star-stretch-3",
+      "amount": 3,
+      "reduction": 0,
+      "job_id": "3be497e37eb70115d5d7a7dc486831362fd88e369bfc2d72b3613a5d0a8fb6be",
+      "seconds": 16.23,
+      "rc_astro_ids": [
+        "e35fb9a3ff338a8dd60ea14a45608cc2d257486b55860aa9b592889e8d85c1e1",
+        "7be4806688a3ce2b7e84d67ca965ce6870404e1874f8ae346eeb1504ee5baa1a",
+        "076d26251a8b3596c8d3434d92ba8140d3e1d0c5ba209d34d2101bdf78ada298"
+      ],
+      "linear_input_id": "efc68e0694cda28fd9b5cbf117adb760e2e8ae20cb3e6c3879ffc6b0227561e1"
+    },
+    {
+      "name": "star-stretch-3-reduced",
+      "amount": 3,
+      "reduction": 0.4,
+      "job_id": "bf3f819ac1c0c05fcef93949eb046c1c2d1d767b74d3dcfa243b8b1608342392",
+      "seconds": 18.2,
+      "rc_astro_ids": [
+        "e35fb9a3ff338a8dd60ea14a45608cc2d257486b55860aa9b592889e8d85c1e1",
+        "7be4806688a3ce2b7e84d67ca965ce6870404e1874f8ae346eeb1504ee5baa1a",
+        "076d26251a8b3596c8d3434d92ba8140d3e1d0c5ba209d34d2101bdf78ada298"
+      ],
+      "linear_input_id": "efc68e0694cda28fd9b5cbf117adb760e2e8ae20cb3e6c3879ffc6b0227561e1"
+    }
+  ]
+}