PSF Viewer

Statistical PSF analysis — HFR / FWHM / flux histograms, per-metric stats, and a two-mode median star profile widget that lets you flip between the smoothed analytic shape and the actual pixel-level data.

1. Overview

PSF Viewer opens on the active image and runs star detection, then reports population statistics across every detection that passed the quality filter. The window has three main regions:

• Top-left: histogram — distribution of HFR (default) or flux, with linear/log x-axis toggle and a zoom slider for close inspection of any part of the range.
• Top-right: median star profile widget — a synthetic rendering of the median star with FWHM and HFR ellipses, major/minor axis lines, cyan crosshair, and a legend. Click the widget to toggle to the real-pixel view, which shows a median-stacked actual-pixel stamp with the same overlays drawn at native pixel resolution.
• Middle: stats table — median, min, max, and standard deviation for HFR, FWHM, eccentricity, a, b, θ, and flux across the full detected population.

Below those sits the detection threshold panel, a status line that reports what the detector did (e.g. "Auto — 1024 stars at σ=12, kept 1024/17800 at that threshold"), and the Close button.

2. Workflow

Open the viewer on your image and the detector runs automatically. Watch the status line for the "kept X/Y" summary — it tells you both how many stars contribute to the statistics (X) and how many detections SEP found before quality filtering (Y). On a well-populated frame X ≈ 1000 by default. On a sparse frame all detections survive, and X ≈ Y.

3. The two-mode star widget

The widget starts in smooth mode: an analytic Gaussian with semi-major axis a and semi-minor axis b (both medians across the detected population), rotated by the median orientation θ. Overlaid on top:

• Green FWHM ellipse — drawn at diameters (FWHM_a, FWHM_b) scaled to match the blob rendering. This is where the fitted Gaussian falls to half its peak.
• Orange HFR ellipse — drawn at diameters (HFR_a, HFR_b). This is the half-flux-radius proxy (2·a) commonly used in astro imaging.
• Red line (PSF X) — the major axis direction, length 2.4·a.
• Blue line (PSF Y) — the minor axis direction, length 2.4·b, perpendicular to red.
• Cyan crosshair — image-aligned reference axes.
• Legend at top left, eccentricity readout at bottom left, mode hint at bottom right.

Click the widget to switch to pixel mode:

• The display switches to a median-stacked real-pixel stamp — up to 500 small cutouts of actual stars from the image, each background-subtracted from its 1-pixel edge median, peak-normalized, then median-combined pixel-by-pixel. The stamp half-size is 2.5·FWHM, clamped to the range 5-25 pixels.
• Each image pixel is rendered as a crisp integer-sized screen square with nearest-neighbor scaling. A faint grid is drawn between pixels so you can count them.
• The same FWHM and HFR ellipses are drawn against the real pixel grid at the same image-coordinate scale, so you can directly measure the FWHM claim against the data.
• The header shows the stamp size in pixels and the pixel-to-screen scale factor, e.g. "True Pixels 21×21 px · 1 px → 14 px".

4. Detection modes

The detection panel at the bottom has a σ slider and an Auto checkbox.

Auto (default) runs the shared waterfall detector: SEP's background estimator runs once, then sep.extract re-runs at progressively lower sigma thresholds — 100 → 50 → 25 → 12 → 6 → 3 — stopping as soon as ~1000 quality-filtered stars are detected. On a rich field this takes 2-3 extractions; on a sparse one it descends to the bottom and keeps whatever it got.

Manual (uncheck Auto) uses the σ slider value as the one and only extraction threshold. The slider ranges 1-50; the current value is shown next to it. The debounce timer waits 500 ms after the last slider change before re-running the extraction, so you can scrub smoothly without triggering a burst of worker threads.

Either way, a quality filter is applied before statistics are computed:

• SEP's blend/truncation/saturation flag must be zero
• Detection pixel count must be at least 5 (rejects hot pixels and cosmic rays)
• Shape ellipse must be well-formed: a > 0, b > 0, b ≤ a

The status line reports how many detections survived the filter, so you can see whether your extraction is noise-dominated (large Y, small X ratio) or clean (X ≈ Y).

5. The stats table

Seven columns, each with four rows (median, min, max, std):

Median is the single most useful number — it's robust to outliers and is what the star-shape widget is drawn at. Min and max tell you the extremes present in the frame. StdDev tells you how homogeneous the population is: a tight StdDev on FWHM means your frame has consistent focus across the field; a wide StdDev means some corners are soft or guiding wandered during the sub.

6. Technical details

The math behind every number the tool reports.

6.1 SEP second-moment star measurement

SEP (Source Extractor in Python) measures each detected source's shape via the second central moments of its pixel distribution. For a detection with centroid (x̄, ȳ) and pixel values I_i:

in the principal axes frame (after rotation to diagonalize the moment matrix). The orientation that performs this diagonalization is:

SEP returns a, b, and θ directly as per-detection attributes. The semi-major axis a is interpreted as the equivalent Gaussian σ along the long direction of the star; b is the equivalent σ along the short direction.

6.2 FWHM from a

For a 2D Gaussian with σ along the measured direction, the Full-Width-at-Half-Maximum is:

evaluated in pixel units since SEP reports a in pixels. This is the proper statistical FWHM of the Gaussian model fit through the second-moment measurement; it is not the direct peak-to-half-peak distance that you would get by profile-fitting to the pixel data, but for well-sampled Gaussian-like stars the two agree to within a few percent.

6.3 HFR convention

The tool reports:

This is a common astro-imaging convention for "Half-Flux Radius" that is not the mathematical half-light radius. The true half-light radius for a 2D Gaussian is:

which is smaller than 2σ by a factor of about 1.7. The HFR = 2·a convention is what guiding software (PHD2, SharpCap) and focus tools (SGP, N.I.N.A.) typically report, so following it keeps numbers from this tool directly comparable to those from your capture pipeline. If you need the proper mathematical half-light radius, divide the reported HFR by about 1.7.

6.4 Eccentricity

This is the standard eccentricity of the ellipse that passes through the a and b points. It ranges from 0 (circular star, b = a) to approaching 1 (highly elongated).

For reference, the alternative convention used by Image Peeker's Focal Plane Analysis is:

which ranges from 0 (round) to approaching 1 (elongated) but has different numerical scaling. For a star with b/a = 0.8: this tool reports e = 0.6, Image Peeker reports ε = 0.2. Both are correct for their respective conventions.

6.5 Waterfall star detection

The shared detect_stars_waterfall function runs SEP's background estimator once (the expensive fixed cost) and then re-extracts at progressively lower sigma thresholds:

σ-ladder: 100 → 50 → 25 → 12 → 6 → 3

At each level, the raw detections are quality-filtered:

where the flag check rejects saturation, blends, and truncations; the pixel-count check rejects single-pixel spikes and cosmic rays; and the shape check rejects malformed ellipses. If the surviving count reaches the target (1000 by default) the ladder stops; otherwise it descends further.

Rationale: on a rich field, SEP at σ=3 can produce 50000+ detections (Frank's example: 53105 sources at σ=15 on one image). Fitting shape moments to that many detections wastes seconds on sources that will fail the quality filter anyway. Starting at σ=100 and only descending until a stable statistic is in hand gives the same median numbers in a fraction of the time. On sparse fields where σ=3 is needed to find anything, the ladder reaches the bottom naturally and the tool uses what it got.

6.6 Median star stamp assembly

When the widget is in pixel mode, the displayed stamp is a median stack of up to 500 real-image cutouts around detected stars. The process:

1. Choose stamp size. The half-width is set from the median FWHM:
   L_{\mathrm{stamp}} = 2 \lceil 2.5 \cdot \mathrm{FWHM} \rceil + 1
   clamped to the range 5-25 pixels so very small or very large FWHM don't produce an unusable display.
2. Cut around each star. Extract an (L × L) window centered on the integer-rounded centroid position (xᵢ, yᵢ). Stars whose window would overrun the image edge are skipped.
3. Background-subtract per stamp. The 1-pixel edge of each stamp (top row + bottom row + two side columns) is the local sky estimate:
   s_i' = s_i - \mathrm{median}(s_i^{\mathrm{edge}})
   This handles local sky-gradient variation across the frame without needing a global background model.
4. Peak-normalize. Divide by the stamp's peak value so bright stars don't dominate the median:
   s_i'' = \frac{s_i'}{\max(s_i')}
5. Median-combine. Stack all normalized stamps and take the per-pixel median:
   \mathrm{PSF}_{\mathrm{stamp}} = \mathrm{median}\{s_i''\}_{i=1}^{N}
   This produces a robust representative shape that rejects individual star defects (overlapping neighbours, diffraction spikes from oversaturated stars, cosmic-ray residuals).

Cap at 500 stars because 500 median-stacked cutouts already give pixel-level stability well below the noise in any individual cutout; more would just cost memory and time with no visible benefit.

6.7 Smooth-view Gaussian rendering

The smooth mode renders:

on a 300×300 grid with the median a, b, and θ. The rotated coordinates are:

The in-frame scaling is set so that the Gaussian occupies a comfortable fraction of the widget regardless of the star's absolute size; the ellipse overlays are scaled by the same factor so FWHM, HFR, and the axis lines match the rendered blob's extent. This is a cached QPixmap; resizing the widget just scales the pixmap, so there's no per-pixel work at resize time.

6.8 Threaded extraction

Star detection runs in a background QThread (_PSFWorker). The GUI thread shows a semi-transparent "Processing… extracting stars / PSFs" overlay on top of the histogram while the worker runs, and the status line updates when results arrive. A 500 ms debounce timer on the σ slider ensures that scrubbing the slider doesn't fire off a worker on every pixel of motion; the extraction only starts once the slider has been idle for half a second. The worker is cleanly stopped and replaced if a second extraction request comes in before the first completed.