Cosmetic Correction

Detects and repairs hot and cold pixels by comparing each pixel to its neighbours, with a structure guard that keeps star and nebula cores from being clipped. GPU-accelerated (CUDA/MPS) with a transparent CPU fallback; works on single images or in batch.

1. Using the tool

Dial in the detection sigmas while watching the before/after preview, then Apply. The preview shows a tile of the frame, always autostretched, so you can see whether your settings are eating real detail. The two panes are pan/zoom-linked — move one and the other follows.

Detection settings

Control	What it does
Hot pixels σ (0.5–10, default 3)	Threshold for flagging a pixel as too bright vs its neighbours. Lower = more aggressive.
Cold pixels σ (0.5–10, default 3)	Same, for pixels too dark vs their neighbours.
Protect structure σ (2–50, default 5)	The anti-core guard. A region whose local median sits this many σ above the global background is treated as real signal (star / nebula core) and left untouched by the hot pass. Lower = protect more; set very high to disable.
Correct hot / Correct cold	Enable each pass independently.
Bayer pattern	Auto-detect (reads BAYERPAT from the FITS header, only for a raw 2-D mosaic), None (mono / already-debayered), or force RGGB/BGGR/GRBG/GBRG — see §2.3.
Push σ to Stacking Suite	Copies the current Hot/Cold/Protect σ into the Stacking Suite settings, so per-frame cosmetic correction during light calibration uses the same numbers you just tuned.

Previewing

Region (3×3 grid) — choose which part of the frame to preview (corner / edge / centre). A bright centred object can hide hot/cold activity, so shifting to a corner is key for tuning sigmas that don't clip star cores. The choice is remembered.
Refresh preview — recompute the after-pane (it also recomputes automatically when you change a setting).
Pan / zoom — drag to pan, wheel to zoom; both panes stay locked together so before/after line up pixel-for-pixel.
Pixel map → — opens a diagnostic map as a new view: red = hot pixel (pulled down), blue = cold (pushed up), black = untouched, so you can see exactly what gets flagged and how many. The current image isn't modified.

Applying & batch

Apply commits a “Cosmetic Correction” step and reports how many hot / cold pixels were corrected; Cancel closes.
Batch… opens the batch processor: add files or folders (or drag them in), choose output (overwrite in place, add a suffix, or save to a directory), and run the same detection over the whole list on a worker thread with per-file progress.
Grip (bottom-left) drags to the canvas to mint a shortcut with these settings, or drops on an image to apply headlessly. If no image is open, the opener falls back to the batch dialog.

The tool also runs in a Stacking-Suite tuning mode: it previews on a sample light frame (with ◀ / picker / ▶ to step through your lights) and the Apply button becomes “Save σ Settings” — it writes the sigmas back for per-frame calibration without ever modifying the sample.

2. Technical details

A two-pass neighbour-median comparison flags and replaces outliers, gated by a structure test so real detail survives. The detection kernel runs on GPU when available and on CPU otherwise.

2.1 Neighbour-median detection

Each pixel x is compared to the median m of its orthogonal neighbours; if it deviates by more than the chosen number of noise sigmas it is flagged and replaced by that median. The two passes run independently:

\mathrm{hot:}\ \ x-m > \sigma_{\mathrm{hot}}\,\hat{\sigma}\quad\Rightarrow\quad x\to m

\mathrm{cold:}\ \ m-x > \sigma_{\mathrm{cold}}\,\hat{\sigma}\quad\Rightarrow\quad x\to m

Replacing with the neighbour median (rather than the mean) means a corrected pixel takes on a value its surroundings actually support, and a single bad pixel can't drag the estimate. Turning a pass off pushes its threshold out of reach so it contributes nothing:

\sigma \to 10^{9}\quad(\mathrm{pass\ disabled})

2.2 Structure protection (anti-core guard)

The danger with hot-pixel removal is clipping the bright peak of a tight star or nebula core. The guard compares each region's local median to the global background: if it stands too many sigmas above it, the region is real signal and the hot pass skips it.

\mathrm{median}(\mathrm{patch})-\mu_{\mathrm{bg}} > \sigma_{\mathrm{protect}}\,\sigma_{\mathrm{bg}}\ \Rightarrow\ \mathrm{protected}

The key insight: a lone hot pixel can't shift a median, so it is still corrected even inside a bright area — only genuine structure (which does move the local median) is protected. Lower Protect σ shields more; higher corrects more aggressively.

2.3 Bayer-aware neighbours

On a raw, undebayered mosaic the orthogonal neighbours are different colours, so a stride-1 comparison would be meaningless. When a Bayer pattern applies (auto-detected from BAYERPAT only for a 2-D image, or forced), the comparison uses stride-2 same-colour neighbours instead. For mono or already-debayered RGB, standard stride-1 neighbours are used.

2.4 Notes

Runs on float data in [0,1]. With an active mask, the result is blended back against the source over the mask, so only masked pixels change.
Corrected-pixel counts are exact: unchanged pixels come back bit-identical, so the sign of source − corrected cleanly separates hot (>0) from cold (<0) — the same test that drives the pixel map.
The detection kernel (torch_rejection.cosmetic_correction_gpu) picks GPU (CUDA/MPS) or CPU automatically; the batch path preserves each file's bit depth and adds a HISTORY note to FITS headers.