Hot Pixels & Saturation¶
Two unrelated artifacts pollute star measurements: single bright hot pixels that masquerade as tiny stars, and saturated (clipped) cores that flatten the bright peak of an otherwise good star. Hocus Focus handles them up front in the detection pipeline. Hot pixels are cleaned out of the source image before star structures are found, and saturated pixels are masked out of the PSF fit so they do not bias the fitted profile.
Hotpixel Threshold and Saturation Threshold control hot-pixel rejection and the saturation cutoff.
These options live in the Advanced star-detection settings. In Simple mode only Hotpixel Filtering follows a preset: it switches on unless Noise Level is set to None. Hotpixel Threshold is held at its 0.1% default, and the other three keep their stored values.
Settings at a glance¶
| Setting | Default | Range | Effect |
|---|---|---|---|
| Hotpixel Filtering | On | On / Off | Apply a 3×3 median filter to remove hot pixels before detection |
| Use Hotpixel Thresholding | On | On / Off | Replace only pixels that differ sharply from the median, instead of blurring everything |
| Hotpixel Threshold | 0.1% (0.001) | (0, 100%] | How far a pixel must sit from its 3×3 median (as a fraction of full well) to count as a hot pixel |
| Saturation Threshold | 99% (0.99) | (0, 100%] | Pixels at or above this fraction of full well are treated as saturated and masked during PSF fitting |
| Exclude Saturated Stars From HFR | On | On / Off | Leave partially-saturated stars out of the per-frame HFR average; they stay detected and counted |
Hotpixel Filtering¶
What it does: runs a 3×3 box-median convolution over the source image to suppress isolated hot pixels before star structures are detected.
Uses a 3x3 box median convolution to filter out hotpixels. This should be on, unless you're working with a calibrated image with hotpixels removed
- Default: On
- Range: On / Off
A hot pixel is a single sensor cell that reads anomalously high regardless of incoming light. Left in the image it forms a tiny, sharp, one-pixel "star" that survives structure detection and contaminates HFR and star-count statistics. A 3×3 median replaces each pixel with the median of its neighborhood, which removes a lone outlier while leaving genuine multi-pixel stars intact. The median filter radius is fixed at 1 (a 3×3 window); only that size is supported.
When noise reduction is in play, hot-pixel filtering also runs first so the hot pixels are not smeared into their neighbors by the noise-reduction blur.
A single hot pixel (left) reads far above its neighbors; the 3×3 median (right) replaces it with the local median while leaving the real star untouched.
When this helps
Leave this on for raw or uncalibrated frames. Almost every sensor has some hot pixels, and any that survive read as spurious one-pixel "stars." Turn it off only when you are feeding already-calibrated images whose hot pixels have been removed (e.g., by dark subtraction or a defect map), so you avoid a redundant filtering pass.
Use Hotpixel Thresholding¶
What it does: restricts the median replacement to pixels that differ sharply from their local median, instead of replacing every pixel and blurring the whole image.
A more sophisticated version of hotpixel filtering that limits pixel replacement to those where the median is far off of the pixel value. This prevents the whole image from being blurred, which can have a negative effect on HFR and PSF measurement accuracy
- Default: On
- Range: On / Off
A plain 3×3 median replaces every pixel with its neighborhood median. That is effectively a light blur across the entire frame, which softens real stars and biases HFR and PSF measurements. Thresholded filtering compares each pixel against its 3×3 median and only swaps it when the difference exceeds Hotpixel Threshold. Pixels that match their surroundings are left exactly as-is, so only true outliers are touched and the rest of the image keeps its native sharpness. It is somewhat more compute-intensive than the unconditional median, but preserves measurement accuracy.
When this helps
Leave this on in almost all cases. It removes hot pixels without softening real stars, which protects HFR and PSF fit quality. Turning it off reverts to an unconditional median that blurs everything; Simple mode compensates for that blur by widening the noise-reduction radius, but in Advanced mode you would be giving up sharpness for no benefit.
Note
When thresholding is on, the filter only replaces outlier pixels and does not blur, so Simple mode adds 1 to the noise-reduction radius (whenever hot-pixel filtering is on with thresholding enabled, the default) to compensate; with thresholding off, the plain median already blurs, so no extra radius is added.
Hotpixel Threshold¶
What it does: sets how far a pixel must sit from its 3×3 median (as a fraction of full well) before it is replaced as a hot pixel.
A percentage representing the cutoff threshold for detecting a hotpixel. It's the percentage of full well difference between the 3x3 median blurred value and the pixel value
- Default: 0.1% (0.001)
- Range: greater than 0% up to and including 100% (the editor accepts 0–100%; values must be within \((0, 1]\) as a fraction)
This setting only takes effect when Use Hotpixel Thresholding is on. A pixel is replaced when
so at the 0.1% default a pixel must exceed its local median by one part in a thousand of the full ADU range to be treated as a defect. Lower values are more aggressive (more pixels replaced, risking real star cores); higher values are more permissive (only the most extreme outliers are touched).
When this helps
Leave the default unless you have a specific reason. Lower the threshold if obvious hot pixels are surviving and being detected as stars; raise it if the filter is clipping the bright cores of real, well-sampled stars. Because the threshold is a fixed fraction of full well rather than a multiple of the frame's noise, the same value sits many times the noise at low gain and below the noise at high gain, so re-check it if you change gain or exposure substantially.
Warning
The threshold is a fraction of full well, not an absolute ADU count. Setting it too low on a high-bit-depth sensor can replace the peak pixels of sharp, in-focus stars and bias HFR low.
Saturation Threshold¶
What it does: marks pixels at or above this fraction of full well as saturated; star candidates containing them are still measured, but the saturated pixels are masked out of the PSF fit.
A percentage representing the cutoff threshold for detecting a saturated pixel. Star candidates containing saturated pixels are processed with those pixels masked during PSF fitting
- Default: 99% (0.99)
- Range: greater than 0% up to and including 100% (the editor accepts 0–100%; values must be within \((0, 1]\) as a fraction)
When a star's core clips at the sensor's full-well limit, its peak flattens into a plateau, and the true profile is lost in those pixels. Fitting a Gaussian or Moffat through a flat top would distort the amplitude, width, and therefore the reported FWHM and eccentricity. Hocus Focus does not reject a partially-saturated star outright; instead, during PSF fitting it discards every pixel whose raw value is at or above the saturation threshold and fits the model to the remaining, unclipped pixels. (A fit is only attempted if at least 10 unsaturated pixels survive the mask; otherwise the star gets no PSF model.) The bright but unclipped wings still carry enough shape information to recover a clean profile. The count of saturated pixels and saturated stars is tracked in the detection metrics.
The saturated core (left) reads a flat plateau; its horizontal cut (right) clips at the threshold. Those plateau pixels are excluded from the PSF fit, which is anchored on the unclipped wings.
When this helps
Leave the default (99%) for most setups. Lower it if your sensor or processing introduces non-linearity or blooming just below the full-well point, so those tainted near-saturation pixels are also excluded from fits. Raise it toward 100% only if you are confident your sensor stays linear right up to the clip point and want to keep as many pixels as possible in the fit. Setting it too low needlessly throws away good pixels and can leave too few for a reliable fit.
Exclude Saturated Stars From HFR¶
What it does: keeps partially-saturated stars out of the per-frame HFR average, while still detecting and counting them.
When enabled (default), partially-saturated stars (those whose peak reaches the Saturation Threshold) are left out of the per-frame HFR average — their flat, saturated cores bias HFR high and can pull the focus curve. The stars are still detected and counted; only the HFR average excludes them, and only while enough unsaturated stars remain. Disable to include every star's HFR as before.
- Default: On
- Range: On / Off
A saturated core clips flat at the full-well limit, so the half-flux radius measured from it reads larger than the star's true size. That inflated HFR drags the frame's aggregate HFR upward and can distort the focus curve the optimizer fits to find best focus. This setting drops such stars from the per-frame HFR average (and its standard deviation), so the curve point reflects the well-behaved stars instead.
It does not reject the star. A partially-saturated star is still a real detection with a valid position and structure, so it stays in the accepted set: the total star count, the star centers, and each star's own measured HFR are unchanged. Only the per-frame average leaves it out. Rejecting it outright would discard a genuine star, and on a frame with few stars that loss matters most. For that reason the exclusion applies only while at least three unsaturated stars remain on the frame; below that floor every star is kept, so a bright, saturation-heavy frame still produces an HFR. A star counts as saturated by the same test the rest of the pipeline uses: its background plus peak brightness reaches the Saturation Threshold above. With nothing saturated, or with this option off, the HFR average is exactly what it was before.
When this helps
Leave it on. It matters most on frames that hold a bright, clipped star next to fainter ones, where that single star would otherwise pull the HFR curve. Turn it off only to restore the legacy behavior, where every accepted star contributes to the HFR average regardless of saturation.