PA-adaptive ACF, aperture check and Review dialog

Production ACF principle

The production algorithm is pa-adaptive-upper-v1. The historical symmetric ACF remains an internal rollback path for regression comparison; it is not exposed as a normal user choice.

The image is processed in circular layers. For each ring, KOPR estimates the local brightness trend as a function of position angle inside a fixed 40° window. Only positive outliers above the dynamic robust-noise limit are clipped. The negative side is not clipped.

The ACF is a contamination-control method, not a substitute for inspecting the image and curve of growth. Strong asymmetric comet structures can still influence the result and must be interpreted scientifically.

Relevant settings

The PA window is fixed at 40° and is not a user parameter. The older ACF cut (% above average) item remains only for compatibility and rollback; its percentage is not converted into sigma.

Manual WCCD workflow

After Perform comet measure completes successfully with ACF, Review comet ACF… is available below Reference stars. The frozen context belongs to that successful Comet measurement.

Manual WCCD clicks, automatic candidates and M1 all use the same canonical bounded 2D Gaussian comet centroid. Once accepted, the coordinates are shared by the WCCD marker, Slice, aperture measurement and ACF; Review does not recenter independently.

The measurement also freezes the Comet image's current saturation contract. A complete NSATVAL map is authoritative in automatic policy; an explicitly edited Saturation level instead selects the per-image manual threshold and intentionally bypasses that map.

Review remains available while the Stars image is displayed and after changes to measurement mode, reference stars, filter, magnitude source, catalogue, photometric correction, extinction, displayed aperture value or Stars stack.

Manual aperture adequacy check

The adequacy check is deliberately narrower than automatic coma detection. It asks whether the observer's completed ACF aperture is evidently too small; it does not infer a physical coma radius and it does not require the curve of growth to reach a plateau.

Same-measurement comparison

Trial radii reuse the same Comet image, frozen centroid, exposure time and ACF parameters as the observer's completed measurement. Every trial obtains the canonical WCCD local background for its own radius. A single distant frozen sky value is not reused across the sweep.

Filtered Curve of Growth evidence

The review compares cumulative ACF-filtered flux and the radial trend while retaining evidence about raw versus ACF-used annular flux. A large raw increment that is removed by ACF is contamination evidence, not automatic proof of additional comet flux. Local trend, residual and the extra photometric gain are evaluated together.

Sequential stop and observer-prefix protection

Trial radii are processed in order and stop at the first trustworthy evidence boundary. Before the outward shadow sequence begins, KOPR also inspects the already-measured inner ACF curve from the centre outward; this prevents contamination already inside a large starting aperture from becoming the accepted baseline. Very small starting apertures are allowed to bootstrap enough curve-of-growth points before an insufficient-reference state is treated as a real failure.

Observer action

When a larger radius is supported, the normal dialog shows a compact warning with the recommended radius. Try suggested aperture is preview-only: it changes and draws the selected radius but does not run ACF again or commit a replacement measurement. The observer inspects the geometry and starts Perform comet measure manually if the new radius is acceptable.

If no reliable extrapolation is possible, no false “aperture too small” recommendation is produced. The last trusted radius and contamination/evidence boundary are diagnostic limits, not a claimed coma edge.

Review dialog

The dialog intentionally exposes only four ACF parameters: Starting radius, Radius step, Ignore radius and Upper limit in sigma.

It contains a local image cutout, Min/Max stretch, zoom and pan, a ring map with the active ring highlighted, a selected-ring position-angle graph and a table of sigma/flux diagnostics.

Selected-ring PA graph

• ACF ON: raw, upper-limit and filtered profiles are shown with explicit, distinct styles.
• ACF OFF: clipping/upper-limit curves are not shown, because no ACF clipping is being applied to the ring.

Preview and Apply never write these temporary values back to global Settings.

Apply destination

Apply to measurement always commits to the Comet slot, never to an active Stars slot. It updates the comet measurement and ACF context, writes the concise ACF record to the Comet FITS HISTORY where supported, and refreshes the comet-aperture display.

Actual invalidation events

• opening a new observation;
• resetting the observation, which also closes the foreground Review window;
• loading a different Comet FITS;
• a new successful measurement without ACF;
• replacement by a newer successful ACF measurement;
• a structurally damaged or incompatible frozen context.

ACF provenance

Every PA-adaptive measurement creates a detailed kopr-acf-provenance-v1 record. It includes the algorithm and parameters, fixed 40° PA window, centroid limits and achieved shift, whether Review Apply was used, context/source/run/observation identifiers, normalized float32 type and per-ring diagnostics.

Per-ring evidence includes lower/core/effective sigma, radial slope, positive-clipped sample count and raw/filtered/used flux.

A shortened line is written to the log and compatible FITS HISTORY, for example:

KACF pa-adaptive-upper-v1 s=3 d=2 i=7 u=3 w=40 m=7 l=6 a=1.2 r=0

s = start, d = step, i = ignore, u = upper sigma, w = PA window, m = maximum centroid shift, l = local centroid window, a = achieved shift and r = Review Apply.

The user-facing ICQ/COBS comment remains limited to requested observation metadata and the user's comment. It does not receive an automatically generated Saturation: sentence. Detailed ACF and saturation provenance remain in diagnostics and compatible FITS/log records.

Scientific and Compact compatibility

Scientific and Compact FITS are decoded into the same local read-only float32 ACF context. There is no separate ACF implementation for either storage mode.

Changing ACF parameters does not write to the FITS input and does not modify the koprfits.py storage contract.

Developer API and state contract

context = prepare_acf_context(...)
analysis = analyse_acf_context(context, parameters)
original = reset_acf_analysis(context)
record = acf_measurement_provenance(context, analysis)
line = append_acf_history(header, context, analysis)

ACFMeasurementContext retains only the local patch and masks, not the whole image. Its arrays are read-only. The context is bound to source/run/observation identity. Manual aperture review consumes the frozen original_analysis from the completed measurement rather than rebuilding the starting point from current GUI Settings.

The current aperture-check science owner is src/kopr/core/photometry/comet_aperture_check.py; WCCD orchestration remains in src/kopr/application/wccd_runtime.py and observer-facing presentation in src/kopr/features/wccd/aperture_review_presentation.py. Preview selection and authoritative measurement/commit are separate states.

photom.PhotometryACF() keeps its historical return tuple. The normal selector is photom.ACF_ALGORITHM_ID; the internal rollback is available explicitly through photom.LEGACY_ACF_ALGORITHM_ID.

Release acceptance checklist

• Open and resize the Review dialog in a real Qt environment.
• Verify zoom/pan, ring selection and map redraw.
• Close without Apply and confirm the measurement is unchanged.
• Apply ACF Review while preserving the user-selected fixed aperture radius and then complete the normal save flow.
• With the manual aperture check enabled, verify that a supported larger-radius result produces the compact warning and that Try suggested aperture only previews the new geometry.
• Confirm that preview does not remeasure or commit and that the next authoritative measurement occurs only after a manual Perform comet measure.
• Repeat Perform comet measure on an already active Comet view and confirm zoom/pan are preserved.
• Repeatedly open/close the dialog without unbounded memory growth.
• Confirm concise ACF provenance in the log and FITS HISTORY.

ACF application states

ACF application is controlled by typed status, not by ring-median sign. A valid upper clipping threshold may therefore be applied when the ring median is zero or negative. Raw and filtered annular sums remain signed.

Degenerate sigma and insufficient angular coverage are explicit invalid states. A zero or negative ring median does not by itself disable valid upper-only ACF clipping.

Related chapters

Photometry settings · WCCD workflow · FITS provenance · Scientific / Compact context · · WCCD helper lifecycle