SubframeStudio

2.1 Launching SubframeStudio

SubframeStudio does not operate on a target view, so there is nothing to select first. We just open the cockpit and load frames into it:

1. In Process Explorer or via the PROCESS menu, locate SubframeStudio under the DeepSkyColors category.
2. Double-click it to open the SubframeStudio cockpit.
3. Click Add (or simply double-click the empty preview area) and choose the image files to load. FITS, XISF and TIFF are all accepted.

As soon as the frames are added, SubframeStudio begins loading and measuring them in the background, on several threads at once, so previews appear quickly and the metrics fill in as each frame is measured. Measured frames are cached, so re-loading the same files later is close to instant.

2.2 Licensing

SubframeStudio runs on a trial-then-registered licensing model. During the trial period, the tool is fully functional with no feature restrictions. When the trial expires, SubframeStudio will display a notice at startup and will not open until a valid registration key is entered (see 3.8 Preferences and licensing). No internet connection is needed: keys are validated offline.

3.1 The action toolbar

The toolbar along the top holds the file, grade, reference and session actions, grouped under small labels. Every button carries an icon and a caption.

Files.

• Add: add one or more image files (FITS, XISF or TIFF). Files already loaded are skipped, so we can add to the list at any time.
• Replace: clear the current list and load a fresh selection (asks to confirm first).
• Remove: remove the current frame from the list. This is not a rejection; it just drops the frame, and we can add it back any time.
• Clear: remove all frames and start over (asks to confirm).

Grade.

• Grade: approve or reject the current frame. The button label follows the frame, reading Reject when the frame is approved and Approve when it is rejected. Grading is non-destructive and is a manual override: once we grade a frame by hand, the automatic criteria will not change it back.
• Remove rejected: remove every frame currently graded reject from the list (asks to confirm). This is distinct from the grade itself: it prunes the list rather than just flagging.

Reference.

• Ref: pick the best registration reference frame by a weighted quality score (deep, sharp, round, star-rich). The chosen frame is marked with a REF badge; this is an advisory pick and does not affect grading.

Session.

• Save session: save the loaded frames, their metrics, the thresholds and the grades to a .cull session file. The last file we used is remembered, so a later Save re-targets it.
• Load session: reopen a .cull session file: it re-opens the listed images and restores their metrics, grades and thresholds.
• Export: copy the approved frames to a folder (rejected frames go into a rejected/ subfolder) and write a measurements.csv alongside them. Non-destructive: the originals are untouched.
• Weights: write the approved frames to a folder with the SSWEIGHT FITS keyword set to each frame's weight, ready for weighted stacking in ImageIntegration. For a fully configurable export (custom folder, prefix, postfix, keyword name and error policy) use the Advanced window's Output panel instead (see 4.5 Output).

3.2 Preview and transport

The preview shows the current frame, stretched with a single locked screen stretch that is computed once and held constant across the whole set, so brightness does not jump as we flip through frames and differences read honestly. A small heads-up overlay reports the file name, the frame's FWHM, eccentricity, star count and PSF weight, and the image dimensions.

We zoom with the mouse wheel or the transport zoom buttons, pan by dragging with the left button, and fit the frame to the window with the Fit button. A double-click anywhere in the preview is a shortcut for Add, so an empty cockpit is one double-click away from loading files.

The transport bar under the preview drives navigation and the blink animation:

• First, Previous, Next, Last: jump to the first, previous, next or last frame.
• Play / Pause / Stop: blink through the frames as an animation, so subtle differences in focus, tracking or transparency become obvious as motion.
• Zoom out, Zoom in, Fit: the same zoom controls available from the mouse, plus a one-click fit-to-window.
• Speed: the blink interval, chosen from a list of preset delays in seconds (or Full steam ahead for the fastest the display allows). Choosing Custom... reveals a field for any delay we like.

3.3 Plot, grouping and weighting

The control strip above the plot, framed and titled, selects what the plot shows and how frames are grouped and weighted.

• Plot: the metric drawn in the plot below. The choices are FWHM, Eccentricity, PSF weight, Star count, Noise, Median, Star residual and SNR, plus a special Approval criteria item that plots how many criteria each frame passes instead of a single metric.
• Time axis: spread the plot's X axis by acquisition time (DATE-OBS) instead of by frame index. It falls back to frame index automatically if the set has no readable dates.
• Group: partition the set by Filter or Exposure (or None). With a group active, a second selector picks the group value, and the plot, the status tally and the filmstrip all scope to that group.
• Flagged only: show only the frames that carry an anomaly flag, to review them quickly. This is a view filter; it does not reject anything.
• Weight: the preset that drives each frame's export weight: PSF Signal (the normalized PSF signal weight), FWHM-based, Star count, or Custom blend (a user expression set in the Advanced window). The small readout beside it summarizes the current weighting.
• Advanced...: open the SubframeStudio Advanced window (see 4 The Advanced window).

3.4 The metric plot

The plot draws one dot per frame for the selected metric, in frame order (or by time). Its header names the metric and reminds us which way is worse, since the reject direction is fixed by the metric: FWHM, eccentricity, noise, median and star residual reject above the line (bigger is worse), while PSF weight, star count and SNR reject below it (bigger is better).

When the current metric has a threshold, a horizontal line marks it and the rejected side is shaded. We drag the line to set the threshold live: frames on the reject side flip grade immediately, and the criteria panel, the filmstrip and the status tally all follow. A small grab handle sits in the left margin, clear of the axis numbers, so we can pick the line up without fighting the labels.

Selecting the Approval criteria item in the Plot selector switches the plot to a pass-count view: instead of a single metric it shows how many of the enabled criteria each frame passes, which is a fast way to see how close the borderline frames are to the cut.

3.5 Approval criteria

The Approval criteria panel, in its own titled frame below the plot, is where the automatic grading is defined. A Mode selector chooses which engine decides keep versus reject, and a running keep count shows how many frames survive. Whichever mode is active, a frame we have graded by hand keeps our decision.

• Thresholds: one threshold per metric, each with a checkbox to enable it. The panel shows a cell for FWHM, Eccentricity, Star count and PSF weight, each with its fixed comparator and a value field; the same thresholds can also be dragged directly on the plot. A Keep frames passing selector combines the enabled thresholds with ALL (a frame must pass every one) or ANY (a frame must pass at least one).
• Score / keep best: rank every frame by a single composite quality score and keep the top of the list. A sub-mode chooses how much to keep: the top N percent, the best N frames, or every frame at or above a score value.
• Sigma-clip: reject the statistical outliers of one metric. We pick the metric and a number of sigmas k, and frames on the bad side of the set median by more than k standard deviations are rejected.
• Expression: grade with our own expression over the frame metrics. The panel shows a read-only summary of the active expression and a button that jumps to the Advanced window's Expressions editor, where the expression is written and applied (see 4.3 Expressions).

In the Score and Sigma-clip modes the plot's Approval criteria view shows a draggable cutoff line as well, so the boundary can be nudged by hand and read back as a value.

3.6 The filmstrip navigator

The filmstrip along the bottom is a scrolling strip of thumbnails with a colored grade ribbon beneath them. Each thumbnail shows its frame's FWHM, and the ribbon paints a green bar for an approved frame and a red bar for a rejected one, so the balance of the whole set is visible at a glance even for hundreds of frames. The current frame is boxed, and the frames currently shown in the thumbnail window are bracketed on the ribbon so we always know where we are.

• Click a thumbnail (or a spot on the ribbon) to select that frame.
• Drag on the ribbon to scroll the thumbnail window through a long set without changing the selection.
• Double-click a thumbnail to toggle its grade (approve / reject), the same as the Grade button or the Space key.
• The chevrons at either end page the thumbnail window left and right.

Frames that tripped an anomaly detector carry a small orange flag marker on the strip, and their reason (focus, tracking, cloud or dropped) is summarized in the status line. The flags are advisory: they call our attention to a frame but never reject it on their own. Which detectors are active is set in Preferences (see below).

3.7 Keyboard shortcuts

With the cockpit focused, a few keys speed up the review:

Left	Select the previous frame
Right	Select the next frame
Space	Approve / reject the current frame

The Left and Right keys stop the blink animation if it is running, so we can pause on a frame and step through by hand.

3.8 Preferences and licensing

The Preferences button (the wrench icon on the process interface bar) opens the SubframeStudio preferences dialog.

Anomaly flags. A group of checkboxes turns each advisory detector on or off: Focus (frames whose FWHM is well above the set), Tracking (an eccentricity spike), Cloud (high background or a low star count), and Dropped ((near-)empty frames). The flags are statistical and relative to the loaded set, so if a detector is firing on frames that look fine to us, we can simply turn it off here.

Metrics cache. A Clear cache button deletes the stored per-frame measurements (the source images are untouched; frames are simply re-measured the next time they are loaded).

LocalNormalization data. An optional fallback folder (with Browse...) for the .xnml files that PSFScale and PSFScaleSNR read (see 4.3 Expressions). Leave it blank to look only next to each subframe, which covers the common case.

License information. A License information... button opens the license dialog, which reports the current state:

• Licensed: shows the email the module is licensed to.
• Trial: shows the number of trial days remaining.
• Expired: prompts us to register to keep using the tool.

When the module is not yet licensed, the dialog offers a link to register. Clicking it opens the registration dialog, where we enter our email and license key; the fields are validated as we type, and the Register button enables only once a valid email and key pair is present. After a successful registration the info dialog refreshes in place to the licensed state, with no need to reopen it.

4.1 Measurements table

The measurements table lists every loaded frame, one row per frame, with all of its metrics side by side. The columns are: a frame number, an App column (a green check for approved, a red cross for rejected), a Man column (a padlock when a manual grade is locking the frame), the File name, the export Weight, and then the metric columns: FWHM, FWHMs (the frame's FWHM in standard deviations from the set), Ecc, SNR, Median, Noise, Stars, Resid (the PSF goodness-of-fit residual) and PSFwt (the PSF signal weight). Cells fill in live as the background loader measures each frame.

A toolbar above the table controls sorting and per-row actions:

• Sort column and Asc / Desc: order the rows by any column, ascending or descending. Sorting is numeric where the column is numeric.
• Save CSV: write every column of the current table (including the sigma column) to a comma-separated file.
• Toggle approve: flip the grade of the selected frame (a manual override).
• Toggle lock: lock the selected frame at its current grade (or unlock it), so the automatic criteria will not change it.

Clicking a row selects that frame in the cockpit; double-clicking a row toggles its grade.

4.2 Distribution

The distribution panel is a histogram of one metric over the measured frames, with its own metric selector that is independent of the cockpit plot. Each bar is split into a green (kept) and a red (rejected) portion, and a thin curve traces the cumulative distribution, so we can see both the shape of the metric across the set and where the current cut falls. When the chosen metric has a threshold, a vertical line marks it and the rejected side is shaded; dragging the line moves the very same threshold the cockpit plot and criteria panel use.

4.3 Expressions

The Expressions tab holds two independent editors, side by side, for driving the grade and the weight with our own formulas. The expressions are written in JavaScript and are 100% compatible with SubframeSelector: an approval or weighting expression written for SubframeSelector runs here unchanged, with the same variable names and the same syntax.

• Approval expression: a boolean (or numeric) JavaScript expression over the frame's measurements. A frame is approved when the result is non-zero. For example: FWHM < 3.5 && Eccentricity < 0.55.
• Weighting expression: a numeric JavaScript expression giving each frame's weight, used when the weighting preset is Custom blend; negative results clamp to zero. For example: PSFSignalWeight * SNRWeight.

Each editor shows a live validity indicator as we type (a syntax error or an unknown variable is reported), but typing never changes anything on its own: a change is applied only when we press that editor's Apply button, which sets the cockpit's approval mode to Expression (or its weighting preset to Custom). A variable inserter below the editors composes a variable and drops it at the cursor of whichever editor we last clicked in: pick a property from the Variable list, pick value, Min, Max, Median or Sigma from the Statistic list, then press Insert.

For the full set, the Variable Finder... button opens a separate, non-modal window with every variable organized into a searchable, grouped tree (star shape, signal and noise, flux, position, and so on). Type in its filter box to narrow the list, then double-click a name to insert it, again into whichever editor last had focus. The Variable Finder can stay open alongside the Advanced window while we build an expression.

Available variables. Every measurement is exposed as a per-frame value plus four set-wide statistics, named <Property>Min, <Property>Max, <Property>Median and <Property>Sigma (the last is the frame's deviation from the set median, in mean-deviation units). So FWHM, FWHMMin, FWHMMax, FWHMMedian and FWHMSigma are all available, which lets us write set-relative rules such as FWHM < FWHMMedian or FWHMSigma < 2. The measurement properties are:

Stars, FWHM, Eccentricity	star count, median FWHM, median eccentricity
FWHMMeanDev, EccentricityMeanDev, StarResidualMeanDev	the dispersion of those values across the frame's stars
StarResidual	PSF goodness-of-fit residual
PSFSignalWeight (alias PSFSignal), PSFSNR	PSF signal weight and PSF signal-to-noise ratio
SNRWeight (alias SNR)	noise-scaling signal-to-noise weight
PSFFlux, PSFFluxPower, PSFTotalMeanFlux, PSFTotalMeanPowerFlux, PSFCount	PSF flux estimates and the count of PSF-fitted stars
Median, MedianMeanDev	image median and its mean deviation
MStar, NStar, Noise	robust background and noise estimates
Altitude, Azimuth	read from the OBJCTALT / OBJCTAZ keywords when present
Weight	the frame's current export weight
Index	the frame index (this one has no statistics)

FWHM units. Exactly like SubframeSelector, FWHM (and its statistics) is reported in the unit chosen in the Star detection tab: pixels, or arcseconds when an image scale is set. Storage and grading are unaffected; only the value the expression sees follows the unit.

PSFScale and PSFScaleSNR. These read the relative scale factor from a LocalNormalization .xnml file, exactly as SubframeSelector does: SubframeStudio does not compute local normalization itself, it only reads an existing .xnml. For each subframe it looks for <subframe-basename>.xnml next to the subframe file (LocalNormalization's own default output location), and, if not found there, in an optional fallback folder set in Preferences (see 3.8 Preferences and licensing). A subframe with no matching .xnml found leaves both at zero, the same as any other measurement with nothing to measure.

Not available. NoiseRatio evaluates to zero in this version: an expression that references it still runs, it just always sees zero.

4.4 Star detection

The Star detection tab exposes the detector and PSF-fit settings that drive every measurement. The defaults reproduce a robust general-purpose configuration, but undersampled, noisy or wide-field data can measure better with a tuned detector. The controls are:

• Structure layers: the wavelet scale of detected structures; larger values detect larger stars.
• Noise layers: small-scale wavelet layers removed before detection, to keep noise from being detected as stars. Raise it for very noisy subframes.
• Hot pixel radius: a median prefilter that removes hot pixels before detection (0 disables it).
• Noise reduction radius: a Gaussian prefilter applied before detection (0 disables it).
• Min structure size: the smallest star area, in pixels, that will be measured (0 selects it automatically).
• Sensitivity: detection sensitivity; higher values detect fainter stars (and more noise).
• Peak response: lower values accept flatter, less peaked stars, such as slightly saturated ones.
• Max distortion: the maximum star distortion allowed; lower values reject elongated or trailed detections.
• Upper limit: stars with peaks above this normalized level are rejected as saturated (1.0 keeps everything).
• Max stars: a cap on the number of stars measured per frame; the brightest stars dominate the statistics, so a cap keeps rich fields fast.
• PSF fit function: the analytic profile fitted to each star to derive FWHM and eccentricity (Gaussian, several Moffat betas, or Lorentzian).

Edits here are staged: nothing is recomputed until we press a button, so several knobs can be dialed at once. Apply & re-measure commits the settings and re-measures the whole set (frames already measured under identical settings re-use the cache, so it is instant when nothing changed). Preview on current frame commits the settings without a full re-measure and opens the current frame in a new image window with the detected stars marked, for quick visual tuning. Reset defaults restores the default settings and re-measures.

A final row controls how FWHM is reported: Report FWHM in Pixels or Arcseconds, with an Image scale field in arcseconds per pixel. This is a display choice only, applied live: switching to arcseconds shows FWHM as pixels times the image scale everywhere it appears (the table, the plots, the readouts and the FWHM threshold), while the values stored internally, and therefore the grading, stay in pixels.

4.5 Output

The Output tab is the fully configurable version of the toolbar's Weights export. It writes a copy of every approved frame with each frame's weight embedded in a FITS keyword, using options we set here:

• Output directory (with Browse...): the folder to write the copies into; leave it blank to write each copy next to its own source file.
• Prefix and Postfix: text added to the start and end of each output file name (the postfix defaults to _a).
• Weight keyword: the FITS keyword the per-frame weight is written to (SSWEIGHT by default); leave it blank to write the image without a weight keyword.
• Never overwrite existing files: when on, an output file that already exists is skipped and logged rather than overwritten.
• On error: what to do if a frame fails to write: Ask, Continue (log and carry on) or Stop (abort the export).

Two action buttons finish the panel: Output approved runs the export with the options above, and Star-detection preview re-runs the detector on the current frame and opens a new image window with the detected stars marked (the same preview available from the Star detection tab).