Data formats and FITS metadata

Supported image inputs

WStack calculations use a two-dimensional floating-point representation. New products can be written as Scientific float32 or safely scaled Compact int16; see the next section.

DSLR RAW materialization contract

R74 automatically materializes each pending or stale DSLR source into a linear TG FITS beside the RAW file. The pixel model remains the existing TG2X2 extraction: the two green photosites in each native Bayer 2×2 cell are combined after per-channel black subtraction, without demosaicing, white balance, gamma or highlight recovery.

After the batch, discovery runs again. KOPR selects the first created/refreshed TG FITS, or the first verified green representation when all products were already current. Missing rawpy/LibRaw produces a critical extraction-unavailable message; existing FITS may still open, but physical RAW is never used as a fallback.

R81 direct/derived provenance: a direct TG FITS created from one physical RAW carries RAWREP=T. Calibrated and astrometric descendants carry RAWREP=F. Final stacks remove RAWREP, RAWFILE, RAWEXT, RAWMODE, RAWVERS, RAWSIZE and RAWMTIME, because these cards identify one direct materialized source rather than a multi-frame result. Stack ancestry remains in HISTORY, REFIMAGE, NCOMBINE and PROVENANCE.

Discovery remains backward compatible: legacy valid _TG.fits without RAWREP is accepted, while cards such as CALSTAT, ASTROMET, STACKTYP, STACKMTH, NCOMBINE, PROVEXT, TRACKEXT or REFIMAGE identify derived products whose historical RAWFILE/RAWEXT claims must not create a direct-representation conflict.

After materialization, pipeline_state.json migrates a historical physical RAW path to the verified TG FITS path. When both representations have separate records, the historical RAW record is authoritative for stage ON/OFF switches and their downstream disable cascade.

Scientific and Compact primary science storage

Compact uses physical_value = stored_integer × BSCALE + BZERO and, for a non-constant image, QSTEP = (DATAMAX - DATAMIN) / 65534.

A noise-relative policy accepts Compact only when QSTEP ≤ 0.25 × sigma_local. Policy keywords include REQMODE, QPOLICY=NOISESIG, QMETHOD=DIFFMAD, QFRAC, QNOISE, QMAX, QNSAMP, QSAFE and QFALLBK. If unsafe, the individual product is stored as Scientific without clipping.

The setting applies to created/imported masters, calibrated LIGHT frames and final star/comet stacks. Auxiliary extensions remain lossless and unchanged. Full details: Scientific and Compact FITS output.

Input metadata contract

KOPR accepts several common aliases. The first usable value is normalized internally. Missing metadata are not silently treated as confirmed compatibility: processing may warn, request a manual value or reject an ambiguous group.

Frame type is normally read from IMAGETYP or equivalent descriptive metadata on the FITS representation. Physical RAW files are not selected directly by master, calibration, astrometry or stacking actions.

R76 camera identity and authoritative binning

Camera identity and native geometry are stored separately from observation binning. The image/workflow binning is validated for the loaded observation and combines with native pixel pitch and focal length only when the shared physical-scale resolver reaches the active-optics fallback.

Time and exposure semantics

Stack metadata are computed from the frames actually accepted into the stack. Old inherited time/exposure cards from the reference FITS are removed before the result contract is written.

MEAN and sigma-clipped mean require equal positive input exposure times. SUM can combine different positive input exposures.

Comet ephemeris timing: when the DE440s path is available, the internal comet position uses down-leg light-time rather than treating the observation timestamp as the uncorrected target epoch. External Guide/Tycho/Horizons residuals are recorded diagnostically for the tested object and epoch; no universal arcsecond acceptance threshold is defined.

WCS and astrometric metadata

A photometric image needs a valid celestial WCS: axis types, reference coordinates and pixels, and a valid linear transformation using CD, PC/CDELT or an equivalent standard representation. SIP distortion cards may be present when the CTYPE values consistently declare SIP.

After a local Astrometry.net solution, KOPR writes:

The solved file is written as <source stem>_WCS.fits; the calibrated input is retained. The primary WCS is replaced cleanly rather than mixed with an older solution.

Astrometric _WCS.fits output preserves the source science-pixel representation. WCS/SIP/QC metadata are updated without decoding and requantizing Compact pixels, and all other extensions are copied.

Shared physical-scale priority: solved WCS or trusted online calibration; explicit manual override; credible FITS scale metadata; active camera/telescope geometry with validated observation binning.

Calibration products

Master dark, dark-flat and bias

Names are deterministic and encode calibration type, exposure, temperature, dimensions, binning, instrument, gain, offset, read mode, number of used frames and combination method. Prefixes are DA, DF and BI.

Master flat

Every accepted input filename is also recorded in FITS HISTORY.

All calibration calculations remain floating point. The selected Scientific/Compact mode is applied only when each final master is written, and an unsafe Compact request can fall back independently for that file.

Calibrated and solved LIGHT frames

A calibrated output is named from the source stem with a calibration suffix such as _CA_DA_FL.fits. The source image is not overwritten.

The calibration directory also receives processing_manifest.json, linking raw, calibrated and solved paths, selected masters, QC inclusion, enabled state and quality information. The observation-session root stores pipeline_state.json, which is the current per-directory workflow state used by the GUI.

Calibrated LIGHT files may be Scientific or Compact. A later astrometry pass preserves that storage mode instead of rewriting the science array.

WStack output names and primary header

Science stack names follow:

ST_<object>_<filter>_<effective exposure>s_N<frames>.fits
CO_<object>_<filter>_<effective exposure>s_N<frames>.fits

ST is aligned on stars; CO is aligned on the comet. For SUM, the filename exposure is the total; for mean methods it represents one input exposure. Unsafe filename characters are normalized and decimal points in tokens become p.

Sigma-clipped products additionally carry SIGCLIP, SIGMA, SIGITER, SIGMINN, SIGMAXR, CLIPREJ, CLIPPIX, CLIPEXCS and CLIPFRAC.

Primary headers also record the actual storage through KOPRMODE, STORFMT, BITPIX and QSTEP. When Compact was requested, the Q* policy cards record acceptance or Scientific fallback.

Stack FITS extensions

A WStack science product is a multi-extension FITS file. Do not discard the non-primary HDUs before WCCD photometry.

The primary header points to these extensions using VALEXT, COVEXT, PROVEXT, optional SATCEXT/SATEXT and optional TRACKEXT. SATCOMP=COMPLETE means saturation provenance is reliable for every combined source exposure. In automatic WCCD policy, this complete map replaces the invalid comparison of an aggregate MEAN/SUM stack value with a per-source-frame ADC limit. SATCOMP=NONE remains diagnostic but is not by itself a measurement failure: the shared scalar resolver can still produce an effective image-domain limit. An explicit per-image manual base is GUI/observation state and intentionally bypasses the map for that role.

Matched star/comet pairs

Products created in one paired run contain reciprocal metadata:

WStack/WCCD also checks object, filter, method, frame count, total exposure, timing/provenance and the COMETTRK row count. Renaming a product without updating PAIRFILE can break strict pair validation.

External FITS inspection and use

Storage format and file origin are separate properties. An external BITPIX=16 file is an external FITS with integer, Compact-compatible storage; it is not a third KOPR mode.

The shared inspector can identify the science HDU and dimensions, BITPIX/BSCALE/BZERO/BLANK/QSTEP, object, filter, method, time/exposure data, NCOMBINE, WCS, pair metadata and the availability of coverage, clipping, saturation, provenance and COMETTRK information without unnecessarily loading all science pixels.

Ordinary external FITS can be used in manual WCCD when their image and basic metadata are usable. Current automatic hand-off still requires the complete native WStack pair plus QC/provenance contract. The inspector can diagnose missing object, filter, effective time, exposure, total exposure, count, method, WCS and Comet/Stars role for a future import workflow, but does not bypass that safety rule.

ICQ, CometObs and Afρ outputs

ICQ record

Visual and CCD result dialogs generate the fixed-width ICQ observation line plus a human-readable CometObs representation. The ICQ record contains designation, fractional UTC date, method and flags, magnitude and source, optical/aperture data, coma/tail information, observer code and—where applicable—CCD camera/chip/scale metadata.

Append ICQ code appends only the ICQ record to <observer code>.txt in KOPR's current working directory. Closing the dialog without appending does not save the observation. The button is disabled after one append to prevent a duplicate from the same dialog.

CometObs and CARA Afρ

The CometObs representation is displayed for review/copying. CCD results can additionally display CARA-style Afρ rows with object, Julian date, heliocentric/geocentric distance, phase angle, band, aperture radius, Afρ and error. These text blocks are not appended by the ICQ button.

Save figure opens a file chooser and writes a PNG of the result plot to the selected path.

COBS magnitude-source identifiers are case-sensitive. R47 writes direct APASS Sloan g′/r′/i′ as AG/AR/AI; calculated APASS R/I share AR/AI with their direct Sloan-r/i counterparts, and Gaia codes retain their defined mixed case.

R58 removes automatically generated saturation wording from Results, ICQ and COBS comments. The comment contains the requested observation metadata and any user-entered text, but no automatic Saturation: sentence. Role-specific saturation policy, threshold source, provenance status and WStack map use remain available to internal validation and diagnostics. For floating FITS without explicit detector metadata, the automatic threshold is 1.0 only for normalized 0–1 data; otherwise the field receives an editable, non-authoritative 65535 fallback.

R78 uses the one canonical reference-star solution for Process obs. and Af-rho. The ICQ comment does not receive the internal pairwise audit trail or a second post-success scatter decision.

ACF measurement provenance

PA-adaptive comet measurements create a detailed kopr-acf-provenance-v1 diagnostic record. It identifies pa-adaptive-upper-v1, ACF start/step/ignore/upper-sigma values, the fixed 40° PA window, centroid limits and achieved shift, Review Apply state, normalized float32 context and source/context/run/observation identifiers.

Each ring can retain lower/core/effective sigma, radial slope, positive-clipped sample count and raw/filtered/used flux.

Compatible output headers and logs contain a shortened HISTORY line such as:

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

The ICQ free-text comment format is unchanged. Detailed ACF evidence belongs in diagnostics rather than being expanded into the observation comment.

A Review Apply commits to the Comet slot and appends the concise KACF line to the Comet FITS HISTORY where the current file/format supports that update. Slice and unconfirmed helper candidates do not alter FITS science data or photometric output.

Working and configuration files

Download the compact data/FITS reference.

Minimal header examples

Useful LIGHT input

IMAGETYP= 'LIGHT'
OBJECT  = 'C/2023 R1'
DATE-OBS= '2026-07-23T00:15:00'
EXPTIME = 60.0
FILTER  = 'R'
XBINNING= 2
YBINNING= 2
INSTRUME= 'QHY G1600'
SATURATE= 60000

A valid celestial WCS must be present before stacking or WCCD measurement. The exact linear-WCS card set can be CD-matrix or standards-compliant PC/CDELT form.

Ambiguous input

DATE-OBS= '2026-07-23T00:15:00'
EXPTIME = 60.0

This image may load, but missing frame type, object, filter, binning, instrument and saturation information prevent several compatibility and provenance checks. Add genuine metadata at acquisition/processing time rather than inventing values after the observation.

Backup and portability

• Back up the entire config-files/ directory before replacing or migrating KOPR.
• Keep ST/CO FITS pairs and every extension intact; simple image-only export loses validity, saturation and provenance data.
• Keep processing_manifest.json, pipeline_state.json and QC reports with the associated observation when reproducibility matters.
• Absolute paths in JSON state/manifest files may need regeneration after moving a session to another computer.
• Do not manually change scientific header values solely to bypass a compatibility check. Correct the acquisition metadata or document a deliberate override.

Related chapters

Calibration and stacking workflow · CCD photometry and observation output · Visual ICQ output · Local observations and MagParams.dat · Troubleshooting · Algorithm reference · Scientific / Compact output