PA-adaptive ACF, centroid 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.

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_id, context_id, run_id and observation_id.

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 in manual WCCD while preserving the fixed user-selected radius.
• Complete the normal save flow after Apply.
• Repeatedly open/close the dialog without unbounded memory growth.
• Confirm concise ACF provenance in the log and FITS HISTORY.

Related chapters

Photometry settings · WCCD workflow · FITS provenance · Scientific / Compact context · Developer algorithms · Release tests · WCCD helper lifecycle