White Balance

Three ways to fix colour: Star-Based uses the detected stellar population to put the scatter on the blackbody locus (physically grounded colour); Manual dials per-channel gains by hand; Auto grey-worlds the whole frame. Mask-aware; the star-based mode also opens a diagnostic before/after plot.

1. Using the tool

Pick a mode from the White Balance Type dropdown; the relevant controls appear below. Then Apply.

Star-Based (default)

Auto σ (waterfall) — on by default. SASpro tries σ = 100, 50, 25, 12, 8, 5, 3 in order and stops at the first value that detects ≥ 1200 stars (§2.3). When this is on the slider becomes a read-out of the resolved σ; uncheck to drive it manually. The choice is remembered.
Detection threshold (σ) — manual threshold in units of background noise. Lower finds more stars but risks nebulosity and noise.
Advanced Color Matrix WB — solve a 3×3 matrix that rotates the stellar colour scatter onto the blackbody locus (§2.5), rather than per-channel gains. Not recommended for narrowband/duoband data — emission lines sit off the locus and the matrix will shift them.
Autostretch overlay preview — stretch the on-screen preview so faint stars are visible; the maths runs on the linear data.
The live preview shows the background-neutralized image with the detected stars circled, and the current star count. Changing settings debounces and re-detects.

Manual

Three gain spinboxes (R / G / B, range 0.5–1.5) scale each channel directly. Useful for fine-tuning after an automatic pass or dialing in a known cast.

Auto

Grey-world: each channel is scaled so its mean matches the overall mean. One button, no settings — fast and simple, but only right when the scene really averages to grey.

Apply, grip & the diagnostic plot

Apply commits a “White Balance” step; Cancel closes. The dialog follows the active image window.
After a Star-Based apply, a separate result window opens with before/after scatter plots in R/B vs G/B space, a best-fit line, the blackbody locus with labeled Kelvin ticks, and the neutral marker — a visual check that the stars now sit along the locus.
Grip (bottom-left) drags to the canvas to mint a shortcut with these settings, or drops on an image to run headlessly. Star-Based presets record the resolved σ so a replay reproduces what the waterfall picked, even on a different field.

RGB only; all three modes blend through any active mask on the destination document (out = src·(1−m) + out·m).

2. Technical details

Auto is one line of maths; Manual is two. Star-Based is the interesting one — it uses the detected stars themselves as a colour reference, aligned to the Planckian locus.

2.1 Auto (grey-world) and Manual

Grey-world scales each channel so its mean matches the overall mean:

k_c=\frac{\bar{I}}{\bar{I}_c}\,,\qquad \mathrm{out}_c=\mathrm{clip}(I_c\,k_c,\,0,\,1)

Manual is the same shape with user-set k_c (0.5–1.5 per channel).

2.2 Star-Based pipeline

The star-based mode runs a five-step pipeline:

Background neutralization on an auto-found 50×50 sky patch (shared with the BN tool) — the stars are then measured against a grey background, so colour balance isn't confounded by a channel pedestal.
SEP star detection on the BN luminance at threshold σ (auto or manual — §2.3), filtered to flux-radius ∈ (0, 10] px, then spatially sampled on a 3×3 grid (max 500 stars per cell) so a dense core doesn't dominate the fit.
Circular-median sampling: each star's colour is the median RGB inside a 3-px-radius aperture at its centroid — robust to a single hot pixel.
Fit the stellar scatter in (R/B, G/B) ratio space and find the slope-correction + neutral-shift gains (§2.4) that align the median star colour to the blackbody locus and put the median at neutral.
Apply the gains with a pivot at the sky background so the correction doesn't push the background off neutral:
\mathrm{out}=(I_{\mathrm{BN}}-p)\cdot g+p

2.3 Auto-σ waterfall

Rather than guessing a detection threshold for each field, the waterfall tries them in order and stops at the first that works:

\sigma \in \{100,\,50,\,25,\,12,\,8,\,5,\,3\}\quad\to\quad \text{stop at first }\sigma\text{ with }N_{\mathrm{stars}}\geq 1200

Only sep.extract is retried per rung — the one-off BN pass and SEP background estimation are computed once — so the extra cost is modest even on large frames. If no rung reaches 1200, the lowest (most sensitive) σ is kept so the pipeline still has something to work with. The resolved σ is reported back and drives the slider.

2.4 Slope correction + neutral shift

In (R/B, G/B) space the stellar scatter lies on a line whose slope depends on colour balance. A linear fit gives the current slope:

g_b = s\,r_b + b\quad(\text{least-squares over stars})

With a target slope s_target = 0.55 matching the blackbody locus, and tilt strength τ = 0.7 (so the full correction isn't forced in one step):

\rho=\frac{s_{\mathrm{target}}}{s_{\mathrm{current}}}\,,\qquad \rho'=1+\tau\,(\rho-1)

Splitting the gain symmetrically between R and G keeps the overall exposure roughly constant:

k_R=\frac{1}{\sqrt{\rho'}}\,,\qquad k_G=\sqrt{\rho'}\,,\qquad k_B=1

The tilt is then applied to the reference star-colour median, and a neutral shift brings that tilted median to grey:

s_c=\frac{\max_j(\mathrm{tilt}_j\cdot \mathrm{ref}_j)}{\mathrm{tilt}_c\cdot \mathrm{ref}_c}\,,\qquad g_c=\mathrm{tilt}_c\cdot s_c

The combined gain g_c is applied at the background pivot (§2.2 step 5), so both the stellar scatter and the sky end up where they should.

2.5 Advanced Color Matrix WB

The matrix mixes channels and can shift narrowband/duoband emission colours off their physically meaningful positions — the amber checkbox label is a reminder. For broadband RGB it produces more accurate star/galaxy colours than per-channel scaling can.

Instead of three scalars, this mode solves a 3×3 matrix that maps measured star colours to targets projected orthogonally onto the blackbody locus. The locus is anchored at the physically correct neutral (R/B = 1, G/B ≈ 0.96) — a truly neutral grey star is slightly green-deficient relative to equal RGB:

g_b = s_{\mathrm{target}}\,r_b + (0.96 - s_{\mathrm{target}})

Each star's current ratio point is projected onto that line and blended toward the target by the tilt strength:

r_b^{\,t}=\frac{r_b+s\,(g_b-c)}{1+s^{2}}\,,\qquad g_b^{\,t}=s\,r_b^{\,t}+c

The matrix is then solved by least-squares (per output channel), weighted so the anchor neutral is reproduced exactly. The result is clamped by a per-pixel negative-fix (shift up by the minimum channel so no pixel goes negative) and a luminance-pivoted ceiling compression — both preserve inter-channel ratios instead of hard-clipping any one channel.

2.6 Diagnostic plot

The result window plots the measured star colours in R/B vs G/B space before and after, over a Planckian locus drawn in the same ratio space (Planck spectrum → approximate CIE 2° XYZ matching functions → linear sRGB → ratios), with Kelvin tick marks at 1500, 2000, 2500, 3000, 4000, 6000 and 10000 K. The blue cross at (1, 1) is the equal-RGB neutral reference. A well-balanced broadband image should land the scatter on the locus and the median near the reference.