Tools: Continuum Subtract Utility - setiastro/setiastrosuitepro GitHub Wiki

Continuum Subtract

A production tab/tool that subtracts broadband “continuum” signal from narrowband (NB) data (Hα, S II, O III), with optional star-based white balance, background neutralization, and paired starless processing. Designed for OSC+NB or pure NB workflows. Runs heavy math in a worker thread, shows live diagnostics, and can push results to new documents.

What it does

  • Continuum subtraction: For each NB filter, removes scaled broadband (R for Hα/S II, G for O III; or OSC R/G channels) to isolate line emission.
  • Star-based WB (starlight present path): Detects stars, balances colors from stellar samples, and reuses the learned WB for the starless pass.
  • Background neutralization: Finds darkest patches and computes per-channel pedestals to stabilize backgrounds.
  • Red↔Green normalization: Affine normalization of R to G to improve linear fit stability.
  • Linear or non-linear output: Either return linear result, or apply stretch+curves for preview-ready imagery.
  • Paired starless: If starless NB/continuum are provided, applies the exact recipe learned from the starry pass to the starless set.

Inputs & channels

  • Narrowband (NB): Ha, SII, OIII (starry and/or starless).
  • Continuum: Red, Green, or OSC (R/G extracted from OSC for Hα/S II and O III respectively; both starry and/or starless).
  • Each slot can be loaded From View (open ImageDocument) or From File (via legacy loader).

UI overview

  • Narrowband Filters group: Load Ha/SII/OIII (+ optional starless).

  • Continuum Sources group: Load Red/Green/OSC (+ optional starless).

  • Star-Based WB panel (scrolling): Shows per-filter diagnostics (star count, star-color overlay thumbnail, optional scatter).

  • Advanced (collapsible):

    • WB star detect threshold (σ).
    • Continuum Q factor (scale of broadband subtraction).

  • Output Linear Image Only checkbox.

  • Execute button + spinner + status line.

  • Clear Loaded Images resets all slots.

Parameters

  • WB threshold (σ): Sensitivity for star detection (default 5.0; range ~0.5–50).
  • Q factor: Continuum scale in linear subtraction (default 0.80; typical 0.6–1.0).
  • Summary gamma: Brightens the star overlay in diagnostics (default 0.6).
  • Linear output only: If on, skip non-linear finishing.

Processing flow (per NB filter)

  1. Assemble RGB pair: R = NB, G = Continuum, B = G (float32 in [0,1]).

  2. Background neutralization:

    • Tile sampling + downhill walk to find dark patches.
    • Compute per-channel pedestal from reference patch vs global medians.
    • Apply pedestal to stabilize channel floors.

  3. R→G normalization: Affine transform on R to match G’s robust stats (gain+offset).

  4. Star-based white balance (starry pass only):

    • Detect stars (σ threshold), compute WB per channel.
    • Fit per-channel affine maps a*c + b to reproduce WB later.
    • Produce diagnostics: star count, color overlay (gamma brightened), and raw/after star color arrays.

  5. Continuum subtraction (linear):

    • Let g_med = median(G_after_WB).
    • Compute line = R_after_WB - Q * (G_after_WB - g_med), clipped to [0,1].

  6. Finalize:

    • If linear output: emit linear line.
    • Else non-linear: percentile stretch to target median (~0.25), subtract small pedestal, apply a curves adjustment (Numba-accelerated), emit final image.

  7. Starless paired pass (if provided):

    • Re-apply the learned recipe from the starry run: pedestal, R→G normalization, per-channel WB affine, same Q, same g_med.
    • Emit linear/non-linear as chosen, using reused diagnostics from starry pass.

Starless-only mode: If only starless inputs exist, runs BN → R→G norm → linear subtraction with default Q≈0.9 (no star detection/WB).

Diagnostics & previews

  • Overlay thumbnail: Per-filter star overlay (gamma-adjusted) with star count.

  • Scatter (optional): If OpenCV present and enough points: plot NB vs BB with best-fit line.

  • Clicking overlays/scatters opens a Detail View:

    • Zoom controls, one-click autostretch, and Push to New Document.

Threading & responsiveness

  • Each filter pair is processed in its own QThread (ContinuumProcessingThread).
  • Status messages are emitted during each stage.
  • Results (images + diagnostics) are gathered; when all expected tasks finish, the tool pushes new documents (one per result) via DocManager.

Outputs

  • For each processed channel (e.g., Ha (starry), Ha (starless)), creates a new ImageDocument named {Filter}_ContSub, float32 [0,1], preserving original_header when available.
  • Metadata includes display_name, bit_depth, is_mono, and provenance tags.

Implementation highlights

  • Curves finishing is accelerated via legacy.numba_utils.apply_curves_numba.
  • Stretch helpers: stretch_mono_image, stretch_color_image.
  • WB step: apply_star_based_white_balance (optionally reuses cached sources).
  • Robust fits: Least-squares for per-channel WB affine and for scatter trend line.
  • Optional deps: OpenCV (scatter rendering), PyWavelets (placeholder import; not required).

Usage tips

  • Load matching continuum for each NB band (R for Hα/S II, G for O III). If using OSC, you can skip separate R/G loads—the tool extracts them.
  • Start with Q ~ 0.8–1.0. If residual stars remain (under-subtraction), increase Q slightly; if halos invert (over-subtraction), decrease Q.
  • Use Linear output for integration into a linear pipeline; use non-linear for quick-look or presentation.
  • The Advanced WB threshold mainly affects star counts and the WB robustness; raise in crowded/noisy fields.

Error handling

  • Graceful status messages on failures; per-thread exceptions are caught and surfaced via status_update.
  • Guarded array conversions and label updates prevent UI crashes on missing/invalid inputs.

Minimal example

tab = ContinuumSubtractTab(doc_manager=my_doc_manager, parent=main_window)
# Load images via UI buttons, then:
tab.execute_button.click()
# Results appear as new ImageDocuments titled “Ha_ContSub”, “OIII_ContSub”, etc.

Dependencies

  • Required: NumPy, PyQt6, project’s DocManager, imageops helpers.
  • Optional: OpenCV (scatter), PyWavelets (not essential here), Numba backend via apply_curves_numba.

This module provides a robust, reproducible NB–continuum workflow with strong diagnostics and convenient multi-document output, suitable for both OSC+NB and classic tri-band NB projects.