WCCD Automatic Helpers and Slice profiles

Automatic helpers in New CCD/DSLR observation

The dialog order is Comet stack, Stars stack (optional), then Comet designation. The designation may be normalized from FITS OBJECT until the user edits it manually.

• Automatic comet finder, Auto star measure and dependent JPL Horizons are persistent dialog defaults.
• Cancel does not overwrite the saved defaults.
• Observation state, queue and run identity remain one-observation data.
• The new observation is committed only after Accepted and successful preflight.

If Stars is empty or identical to Comet, WCCD exposes the Comet FITS as a full logical Stars role using comet_fallback. The source is read once; mutable annotations and measurement/view state remain independent.

Automatic Comet Finder

The finder starts only after the new observation has committed successfully. Numerical work runs outside the GUI thread. R93 sends progress, completion, errors and cleanup to QObject-bound pyqtSlot receivers; the progress window is hidden before the confirmation window is constructed in the main Qt thread.

It is a candidate-only helper: it proposes or accepts a centre but does not perform comet photometry.

Expected position and search radius

The expected sky position comes from JPL Horizons when explicitly requested and successful; otherwise it comes from the internal KOPR application ephemeris. R92 automatically requests DE440s N-body when the runtime is available. The confirmation summary identifies the actual engine, while terminal provenance records requested, used, cache action and any fallback reason. WCS converts the selected RA/Dec to the expected image position.

R59 uses a 120-arcsec candidate-search radius for the interactive WCCD review. The wider neighbourhood is safe because every result requires visual confirmation. The unattended complete automatic-photometry path retains its stricter 30-arcsec gate. Primary/Extended candidate classification is preserved.

Comet + Stars mode

With both images available, the finder uses the shared paired-image candidate model: ephemeris distance, local significance, centroid stability, FWHM, elongation, stellar-PSF ratio, wing excess, stellar-trail detection/projection and diagnostic ranking.

Comet-only mode

With comet_fallback, the finder receives a valid Stars logical role backed by the same immutable FITS data. It does not gain an independently star-aligned PSF surface, so visual confirmation remains important, but the helper contract no longer receives null Stars image/header values.

One comet-centroid model

R60 uses one canonical bounded 2D Gaussian comet-centroid model for manual WCCD selection, automatic finder candidates and visual M1 placement. The user click or candidate supplies the starting position; the same bounded model determines the centre offered for confirmation.

Confirmation dialog and image selection

• Displayed automatic candidates are renumbered consecutively C1 through Cn after filtering, sorting and deduplication.
• Select a candidate by clicking its table row or by left-clicking near its circle in the image.
• Left-clicking another visible object creates a user-selected M1 starting position and applies the canonical bounded comet centroid.
• The resulting manual candidate appears as a selectable row and highlighted circle.
• Pan and zoom toolbar modes suppress image-selection clicks.

A valid WCS/ephemeris cutout is opened even when no numerical candidate survives. In that case, click the visible comet to create M1 and then confirm the resulting centre.

Rejecting or closing the candidate dialog leaves the comet centre, aperture, reference stars and observation intact. Manual work can continue.

High-precision position — JPL Horizons

The optional online service provides only J2000 right ascension and declination for locating the expected pixel position. It uses the topocentric location of the active KOPR observatory and selects the nearest matching apparition when a periodic-comet designation is ambiguous.

JPL does not replace the observation ephemeris for heliocentric distance, geocentric distance, altitude, magnitude, Afρ, ICQ output or other photometric values.

Auto Star Measure

When enabled for the committed observation, Auto Star Measure starts on the first entry into Measure Stars. It runs once per observation rather than on every mode switch.

• With a Stars stack, measurement occurs on the Stars image.
• Without one, measurement occurs on the Comet image and masks/excludes the comet region when a centre or expected position is available.

R55 keeps one Automatic Star Measure pipeline for ordinary and crowded fields; there is no separate crowded-field mode. Catalogue routing, colour conditions, basic WCS matching, saturation provenance, coma masks, the S/N sequence, iterative individual-zero-point clipping and the R50 final warning/failure limits remain unchanged. R55 improves how projected sources, masked centroid regions, stellar profiles, the global PSF scale, blends and partially masked backgrounds are handled.

Stellar shape policy

Common-aperture calibration sorts standard-shape stars first. Moderately elongated stars are used only when they are needed to reach the available calibrator set. This policy is separate from, and does not relax, basic WCS catalogue-to-image alignment.

Projection and mask-aware centroid

Before centroiding, KOPR checks that the catalogue projection is finite and inside the image, that its central science pixel is valid and that a minimum configurable centroid region with enough valid pixels can be formed. This lightweight precheck does not require the entire later search box to be valid.

The centroid calculation uses only finite science-valid pixels. NaN values are not replaced by zero and never enter the weight normalization. The algorithm separately checks valid coverage of the search region, near-complete validity of the central core, sufficient local-background samples, finite moments and validity of every iterated position.

Stellar profile and robust FWHM

The centroid search radius is used only to locate the star. FWHM and elongation are then remeasured in a smaller adaptive profile around the result, so a distant neighbour in the search box does not automatically broaden the target. The preferred profile is a local two-dimensional Gaussian fit to the compact positive component; masked compact second moments are the fallback.

The global stellar FWHM is derived from quality, unsaturated, significant, shape-accepted and catalogue-isolated sources. A compact isolated distribution uses its robust median. If the distribution has a strong high-FWHM tail, or too few isolated stars are available, the lower 30% of acceptable profile widths provides the guarded fallback. The final report shows both the raw median and robust FWHM, its method and source count, plus the 25/50/75% profile-width percentiles.

Common stellar aperture and final blend check

The robust median curve-of-growth plateau remains preferred. A plateau must be supported by the requested following stable increments; the terminal sample alone cannot prove stability. Growth-curve radii, calibrator isolation and the fallback are all tied to the robust stellar FWHM rather than a raw median contaminated by blends.

If no valid plateau exists, Auto Star Measure continues with a fallback radius of 3.5 × robust FWHM, clipped to the supported aperture-factor interval and never exceeding 4.0 × robust FWHM. The fallback is a warning, not a bypass: image coverage, saturation, masks, background, positive flux, S/N, zero point and final scatter are still checked normally.

After the actual aperture is known, every candidate is checked again for catalogue neighbours. The final blend gate is at least aperture radius + 0.75 × robust FWHM and never smaller than the original blend radius. The report records the gate, neighbours inside the aperture and post-aperture blend rejections.

Strict aperture validity and background

Any non-finite or masked pixel with a non-zero fractional aperture weight above the numerical tolerance causes invalid_aperture. Missing stellar flux is never replaced, interpolated or treated as zero.

The square background annulus excludes NaN and masked pixels statistically while retaining absolute usable-pixel, usable-fraction, quadrant-coverage, asymmetry, sector-consistency, radial-gradient and coma-contamination checks. A mildly cropped annulus can pass only with stricter usable coverage and at least three representative quadrants. If the square annulus fails only because of geometry or spatial coverage, KOPR tries the balanced_boxes fallback with its own sector-consistency and gradient checks.

Zero point and result policy

• Fewer than 3 stars after clipping: FAILED.
• 3–7 stars: valid solution with a prominent WARNING.
• 8 or more stars: normal continuation.
• Rejecting more than 40% of candidates during unchanged iterative median/MAD clipping records a warning and diagnostics, but is not a failure by itself.
• Final robust scatter ≤ 0.08 mag: normal.
• Scatter > 0.08 and ≤ 0.15 mag: retained with warning.
• Scatter > 0.15 mag: hard failure. The computed zero point and scatter remain visible in diagnostics.

Saturation checks

Auto Star Measure uses the shared saturation resolver for the image role being measured. A complete, shape-compatible WStack NSATVAL map is authoritative. Without a complete map, the established automatic base is converted by an integer multiplier into an effective image-domain threshold that is never below the finite image maximum; the observed maximum itself is never adopted as the threshold.

If the user explicitly edits Saturation level, that role switches to a manual base and intentionally bypasses the source-frame map. The same resolver converts the manual base into the effective image-domain threshold, so an identical automatic or manual base yields an identical result. Comet and Stars state remains independent and is reset only when the corresponding FITS is replaced.

Final diagnostic dialog

The selectable, read-only result remains open until the user closes it. Its summary follows the processing order: projected catalogue candidates; detected/centroided objects; WCS/shape acceptance; raw and robust FWHM with method, source count and percentiles; common aperture and its plateau/fallback source; final blend gate and post-aperture rejections; successfully measured stars; S/N acceptance; zero-point outliers; final-star count; final zero point; final scatter; background method; and OK, WARNING or FAILED. Warnings follow the summary, then rejection counts by precise centroid/background reason.

Atomic transfer to WCCD

Only a result that passes all hard gates is committed. Accepted stars, catalogue magnitudes, fluxes, local backgrounds, actual apertures, quality flags and display diagnostics are transferred together. The user can then remove, add or inspect stars with the normal WCCD controls.

Coordination of finder and star measurement

Auto Star Measure cannot commit while Automatic Comet Finder is active or its confirmation window is open. Requests are queued and released only after finder confirmation, rejection or definitive failure.

• Numerical workers never create Qt/Matplotlib review windows directly.
• QObject-bound GUI slots own progress updates, completion, failure, cleanup and final dialog creation.
• The finder progress dialog is hidden synchronously before review preparation.
• Reset or a new observation invalidates workers, clears queues and closes foreground helper windows.
• Observation ID, source identity, run token, process state and target slot are checked before any commit.

Therefore a stale result cannot commit or open a dialog after the observation changes, and reaching 100% is followed by safe GUI-thread review preparation rather than the former freeze.

Named measurement modes

The measurement selector contains stable named modes:

• Measure Comet
• Measure Tail
• Measure Stars
• Slice Through Comet
• Slice Between Points
• Fix Astrometry

The GUI stores stable identifiers in Qt itemData. Application logic does not depend on the visual order or numeric combobox index.

Slice Through Comet

1. Establish a comet centre with the finder or manual measurement.
2. Select Slice Through Comet.
3. Right-click a point that defines direction and half-length.
4. KOPR joins the point to the comet centre and extends the same distance on the opposite side.
5. If the line would leave the image, both sides are shortened symmetrically so the comet remains at the profile centre.

Without a known comet centre, KOPR displays a warning and creates no slice.

Slice Between Points

1. The first right-click sets the start point.
2. The second right-click sets the end point and creates the profile.
3. A third right-click starts a new selection.

This mode does not require a comet centre. If the known centre lies on the selected line, its profile position is marked.

Slice mathematics and output

KOPR uses an integer Bresenham line. Every profile sample is one actually visited image pixel. There is no bilinear interpolation, multi-pixel width, perpendicular-strip mean or median.

The profile opens in an independent non-modal window, so the main WCCD image remains interactive while the profile is visible. The Slice window remains available until the user closes it or the observation is reset/replaced; reset also clears the obsolete Slice selection and closes its foreground window safely.

Slice performs no background subtraction, magnitude conversion, angular conversion, calibration or interpretation. NaN remains NaN. It can support visual inspection of coma asymmetry, structures, fragments, condensations or possible disruption signatures, but does not identify any physical process automatically.

Slice needs no aperture and changes neither comet measurement, ACF, reference stars, final magnitude nor ICQ output.

Persistent Review comet ACF lifecycle

Review belongs to the last successful ACF comet measurement, not to the current GUI view. It remains available while the Stars image is shown and after changes to measurement mode, reference stars, filter, magnitude source, catalogue, photometric correction, extinction, displayed aperture value or Stars stack.

Apply always writes to the Comet slot, updates its ACF context and measurement, appends the Comet FITS HISTORY record and refreshes the comet aperture display.

• A cancelled or failed new measurement preserves the previous valid Review context.
• A new successful ACF measurement replaces it.
• A new successful non-ACF measurement disables Review.
• New observation, observation reset, a different Comet FITS or a structurally incompatible context invalidates it.

See the detailed ACF and Review lifecycle guide.

Scientific and Compact compatibility

Automatic Comet Finder, candidate confirmation, Auto Star Measure, Slice and Review use physical float32 image values after FITS scaling. Scientific and Compact storage therefore share the same numerical GUI workflows. The amount of available diagnostic metadata may depend on the input provenance contract, but the selected storage mode does not create a different algorithm.

Fallback and error scenarios

When the observation is otherwise valid, every helper failure leaves a manual route available.

Related chapters

Process CCD Obs. · ACF Review lifecycle · Scientific/Compact FITS · Troubleshooting · Developer architecture