Pixel Math

An expression language for combining images arithmetically. Write an expression using img (the active view), the identifiers for any other open views, and the built-in function library; the expression is evaluated per-pixel and the result replaces the active image or opens as a new document. Think of it as a scratchpad where every pixel in your image is a variable, and every open view is in scope.

PixelMath is the most flexible tool in SASpro by a wide margin, which is also what makes it the hardest to approach cold. This document lays it all out: the two modes, the variables, the operators and broadcasting rules, every function in the library, the common recipes, and the mechanics of the dialog itself.

1. The two modes

At the top of the editor column, two radio buttons pick the mode:

• Single Expression (default) — one expression produces the whole result. If the expression returns a 2-D array (or a scalar), the result is mono; if it returns a 3-D array shaped (H, W, 3), the result is RGB. SASpro infers mono vs RGB automatically. Most work happens here.
• Separate (R / G / B) — three editor tabs, one expression per output channel. Each expression must return a 2-D plane (or an RGB array, from which the matching channel is auto-selected). The three planes stack into the final RGB result.

2. The dialog at a glance

Left column (controls, scrollable):

• Variables list — one row per open view. The row shows the window title and the sanitised identifier that references it in your expression. Double-click a row to insert its identifier into the current editor at the cursor.
• Output — Overwrite active (replace the current document's image on Apply) or Create new view (open the result as a new document).
• Mode — Single Expression / Separate (R / G / B).
• Expression editor — multi-line text editor for the current mode. Supports Ctrl + wheel for standard text scrolling.
• Glossary… button opens a searchable function reference (§ 9).
• Examples dropdown inserts a ready-made recipe (§ 11).
• Favorites dropdown + Save as Favorite / Delete Favorite buttons persist your own expressions across sessions.
• OK / Cancel / Help at the bottom.
• Draggable splitter between the two columns.

Right column (preview):

• Preview button runs the current expression and shows the result without committing.
• Auto-stretch button is a toggle with a dropdown menu for the preview's display stretch (§ 6). Non-destructive — affects only what you see.
• Zoom In / Zoom Out / 1:1 / Fit buttons; the preview also supports left-drag pan and Ctrl + wheel cursor-anchored zoom.
• Preview area itself is a QGraphicsView showing the computed result.

3. Variables

Every open view is in scope. The dialog auto-generates a Python-safe identifier for each one from its window title:

• img — always refers to the active view, regardless of its title.
• Every other open view gets an identifier derived from its title (non-alphanumeric characters become underscores, leading digits get a leading underscore). If two titles would collide, the second gets a numeric suffix (andromeda, andromeda_2).
• You can also write the raw title directly in your expression — PixelMath rewrites it to the identifier before evaluation. So andromeda.png works even though the sanitised name is andromeda_png.

Three other sets of names are always available:

• Dimensions — H, W, C, and shape (a tuple).
• Coordinate grids — X and Y, both (H, W) arrays ramping linearly from 0 to 1 across the frame. Use these for position-dependent effects (gradients, radial masks, horizontal fades).
• Constants — pi, e, EPS (= 10⁻⁸).

4. Operators

Mono-friendly indexing. On a mono image, any channel index returns the mono plane itself. So L[2] on a mono L is just L. This means LRGB recipes work regardless of whether L is a mono or RGB document — you can write img * (L[0] / (luma(img) + EPS)) and it does the right thing in both cases.

Caret note. In standard Python, ^ is XOR. PixelMath rebinds it to power for astro-user convenience, so img ^ 0.5 is the square root. Mixing ^ with Python code expectations trips people up; stick with ** if that bothers you.

5. Broadcasting rules

Mono and RGB values mix freely. The usual case:

• A mono value (H, W) and an RGB value (H, W, 3) combine with the mono broadcast to all three channels. So rgb * mono_mask dims every channel of rgb by the same per-pixel factor.
• A scalar combines with anything, applied uniformly.
• Two RGB values combine channel-wise.

Reducer functions (med, mean, min, max, std, mad) return per-channel scalars for RGB input, shaped (1, 1, C). These broadcast transparently so img − med(img) subtracts each channel's own median from itself.

PixelMath auto-crops to the common size if two images are mismatched by ≤ 4 px in height or width (common after warps or reprojections that round pixel dimensions differently). Larger mismatches raise a shape error.

6. Preview and auto-stretch

The Preview button runs the current expression and shows the result in the right-hand panel without committing. Everything you see is exactly what Apply will produce.

The Auto-stretch button beside Preview toggles a non-destructive display stretch on the preview panel — it's only for making the preview readable, especially for linear data. It never changes what Apply writes. The dropdown menu offers:

• Enable Auto-stretch — same as clicking the button itself. Mirrors state.
• Target median — 0.18 (soft), 0.25 (default), or 0.35 (brighter). Controls how aggressive the stretch is; low values show your data closer to its linear state.
• Black-point sigma — σ=2.5, 3 (default), or 4. Controls how deeply the black point is pulled below the MAD-based noise floor; higher sigma leaves more foot room for faint signal.
• Linked channels — when on, uses image luminance to derive one stretch applied to all three channels (colour-preserving). When off, each channel stretches independently (equivalent to a white-balance step but may change colour cast).
• Use 16-bit stats — computes the stretch histogram at 16-bit precision rather than the default. Slower but better for very high dynamic range data.

All these preferences persist across sessions via QSettings. If a preview is on screen and you change any auto-stretch setting, the preview is re-rendered automatically.

7. Output routing

The Output group picks what happens when you click OK:

• Overwrite active (default) — the result replaces the active document's image as an undoable edit named “Pixel Math”.
• Create new view — the result opens as a new document titled “<source> — Pixel Math”, with the source document's metadata carried over. Useful when you want to keep the original around while comparing with the derived image.

8. Mask integration

If the active document carries a mask, the result of your expression is automatically blended with the untouched source through that mask on Apply — the pixels outside the mask stay untouched, the pixels inside receive the computed result, and feathered mask regions get a proportional blend.

You can also control masking explicitly with the mask() and apply_mask(base, out, m) helpers:

This computes a sharpened version, builds a smoothstep weight based on luminance (sharpen only midtones), and blends via apply_mask — which is just base · (1−m) + out · m. This computed-in-expression mask composes with the document's own mask if one exists.

9. The Glossary dialog

The Glossary… button opens a searchable list of every available function with its signature and a one-line description. Type in the search box to filter; double-click an entry to insert its signature at the cursor in whichever editor is active. Covers the entire function library in § 10.

10. Function reference

10.1 Element-wise math

10.2 Logs and hyperbolics

10.3 Reducers (per-channel on RGB)

10.4 Element-wise min / max

10.5 Smooth curves

10.6 Statistics / normalisation

10.7 Channels and colour

10.8 Masks

10.9 Filters

10.10 Astro-specific

10.11 Conditional

11. Example recipes

The Examples dropdown in the dialog has these pre-filled recipes ready to insert. Here they are with brief explanations — a mental model of what each one does helps when you want to adapt them.

11.1 Basic combinations

• Average two views — (img + other) / 2. The naive stack of two aligned frames.
• Difference (A − B) — img - other. Useful for frame-to-frame comparison, dark-frame subtraction, spotting what changed.
• Invert active — ~img (equivalent to 1 - img).
• Subtract median (bias remove) — img - med(img). Zero-centres the median; useful before operations that assume zero-mean data.
• Zero-centre by mean — img - mean(img). Same idea with mean instead of median; less robust to outliers but preserves additive constants.
• Min + Max combine — min(img) + max(img). Simple statistical constant image, used mostly for diagnostics.

11.2 Transforms

• Log transform — log(img + 1e-6). Compresses dynamic range; classical for displaying linear data.
• Midtones transform m=0.25 — mtf(img, 0.25). Shift midtones down (brighten); the lower m, the more aggressive the midpoint shift.
• Gamma 0.6 — gamma(img, 0.6). Brightens midtones with a power curve.
• Sigmoid contrast — sigmoid(img, k=12, mid=0.4). Add contrast around the midpoint 0.4 with slope 12. Steeper k gives sharper transition.
• Normalize to 0–1 — normalize01(img). Each channel's min becomes 0, max becomes 1. Can clip faint signal if your image has hot pixels — use the percentile variant instead.

11.3 Thresholding and masks

• Binarise at median — iff(img < med(img), 0, 1). Simple threshold mask.
• Horizontal gradient blend — lerp(img, other, X). The frame transitions from img on the left to other on the right because X ramps 0 to 1 across the width.
• Apply active mask to blend A → B — apply_mask(img, other, mask()). The document's active mask drives the blend.
• Masked unsharp (luma-based) — multiline:
  base = img sh = unsharp(img, sigma=1.2, amount=0.8) m = smoothstep(0.10, 0.60, luma(img)) apply_mask(base, sh, m)
  Compute a sharpened version, build a smoothstep mask that activates only on midtones, blend. The last line is what gets returned.

11.4 Multi-view calibration

• Match medians of A to B — img * (med(other) / med(img)). Multiplicative rescale so img's median equals other's.
• Safe divide — img / maximum(other, 1e-6). Avoids division by zero in the denominator view.
• Percentile stretch 0.5–99.5% — multiline:
  lo = percentile(img, 0.5) hi = percentile(img, 99.5) clamp((img - lo) / (hi - lo), 0, 1)
  Robust alternative to normalize01 that ignores extreme-tail pixels.

11.5 Per-channel operations

(Single Expression mode — channel indexing with [i].)

• Luma to all channels (desaturate to greyscale) — compose(luma(img), luma(img), luma(img)) or in Separate mode luma(img) in each tab.
• Swap R↔B — Separate mode: img[2] / img[1] / img[0].
• Build RGB from three sources — Separate mode: a[0] / b[1] / c[2]. Takes the red channel from one view, green from another, blue from a third.

11.6 Small filters

• Gaussian blur σ=2 — gauss(img, sigma=2.0).
• Median filter k=3 — median(img, k=3).

11.7 LRGB recombination

The classical LRGB workflow: pair a stretched luminance (shot through a clear or L filter) with a stretched colour image (RGB) by using the L for structure and the RGB for hue. The lumarecom helper does exactly this:

which rescales each channel of rgb_view so the result's Rec. 709 luminance equals L_view, preserving the R/G and B/G hue ratios. See § 14.4 for the math.

12. Favorites

The Save as Favorite button saves whatever is in the current editor to the Favorites dropdown. Favorites persist across sessions (stored in QSettings), so recipes you use often don't need to be rebuilt or remembered. In Separate mode the three channel expressions are stored together with [R], [G], [B] tags; selecting a saved Separate recipe repopulates all three tabs. Right-click any favorite to delete it (also available via the Delete Favorite button).

13. Multiline expressions

Both Single and Separate modes let you write multi-line expressions with intermediate variables:

Every line except the last is executed for its side effects (variable assignment). The last line is the returned result and must be an expression, not an assignment. Writing C = B * 2.0 as the last line returns nothing — the error message is a cue that you need to drop the C = part. (Or add a bare C as the final line.)

The namespace used inside multi-line expressions is a safe subset — no file I/O, no imports, no builtins. Only the functions in § 10 and the variables in § 3 are available.

14. Technical details

All processing on float32 in [0, 1]. The expression is parsed and evaluated by Python's exec / eval in a sandboxed namespace with no built-ins. Operator overloading happens through a lightweight PixelImage wrapper that routes arithmetic to NumPy with the broadcasting / coercion rules described in § 5.

14.1 The PixelImage wrapper

Every image variable is wrapped in a PixelImage object that:

• Overrides __add__, __sub__, __mul__, __truediv__, __pow__ to coerce shapes before the NumPy operation (so mono + RGB works without surprise).
• Overrides __invert__ to compute 1 − x instead of bitwise NOT.
• Overrides __xor__ to delegate to __pow__ so ^ means power. (NumPy bitwise XOR is still available through np.bitwise_xor.)
• Supports __getitem__ for the channel-indexing syntax with the mono-friendly fallback (§ 4).
• Sets __array_priority__ = 10 000 so NumPy defers to the wrapper's dunder methods when the two interoperate.

14.2 Midtones Transfer Function

The classical PixInsight MTF, usable both as a tonal transform and as the engine behind Levels and Curves' midtones:

with m = 0.5 giving the identity, lower values brightening midtones (shifting the mid-level up), higher values darkening them. Fixed points: mtf(0, m) = 0 and mtf(1, m) = 1.

14.3 Sigmoid, smoothstep, lerp

Standard tone-shaping primitives:

Sigmoid is the logistic function: smooth S-curve with centre m and slope k at the centre. Smoothstep is a cubic ramp with zero derivatives at both endpoints — the standard no-visible-transition weight function. Lerp is just the linear blend.

14.4 Rec. 709 LRGB recombination

Classical LRGB combines a sharp mono L with a soft RGB C so the result has L's luminance and C's chroma. The implementation computes Rec. 709 luma of the current RGB:

then rescales every channel uniformly by the ratio of target to source luminance:

which preserves the R:G:B ratios of each pixel (so hue and saturation are unchanged) and only shifts overall brightness. The ε floor avoids division by zero on pure-black pixels. The result is optionally clipped to [0, 1] (parameter clip=True by default); turn clipping off if you want to preserve above-unity excess for further processing. Alpha channels pass through untouched.

14.5 Reducer broadcast shapes

Reducers return the smallest broadcastable representation of their result:

which still broadcasts identically to the full-size tiled output you would get from np.full_like(x, med(x)), but a 4000×6000 RGB median drops from ~288 MB of memory to 12 bytes. For mono input, the result is a plain Python float.

14.6 Unsharp mask

Classical form: subtract the Gaussian-blurred image from itself to isolate detail above spatial scale σ, add it back scaled by a. The result is clipped to [0, 1].

14.7 Normalisation primitives

Both operate per-channel on RGB inputs (minc, μc, etc. means per-channel). Not clipped by default — zscore in particular will produce values outside [0, 1] and typically needs sigmoid or clamp downstream.

14.8 Rescale

Linear re-mapping. Extrapolates outside [a, b]; wrap in clamp for hard bounds. Useful for display calibration (rescale(x, 0.1, 0.9, 0, 1) stretches the 0.1–0.9 range of the input to full dynamic range).

14.9 Expression safety

User expressions run in a namespace with __builtins__ explicitly set to None, so open, __import__, exec, and the rest of the standard library are not reachable. Only the functions in § 10, the variables in § 3, and the mapped view identifiers are available. This is a soft sandbox — sufficient to prevent accidental damage, not a hard security boundary — so don't paste arbitrary expressions from untrusted sources.

14.10 Mono vs RGB result handling

In Single mode on a mono source, if your expression returns an RGB array whose three channels are identical (to float32 tolerance), the result is collapsed back to mono. If the three channels differ (you explicitly built an RGB from a mono source), the mono source gets promoted to RGB and the output is RGB — so compose(L, L, L) + small_perturbation on a mono L correctly produces an RGB output.

In Separate mode on any source, each per-channel expression must produce a 2-D plane. If an expression returns an RGB array, the matching channel is auto-selected (the R tab takes [0], G takes [1], B takes [2]).