KOPR DATA AND FITS QUICK REFERENCE
Baseline: R81 provenance and viewport hotfix — 27 July 2026

SUPPORTED IMAGES
FITS: .fits .fit .fts .fz and .gz/.fz compound variants
RAW:  .cr2 .cr3 .nef .arw .dng

SCIENCE STORAGE
Scientific: BITPIX=-32, KOPRMODE=SCIENTIFIC, STORFMT=FLOAT32, QSTEP=0
Compact: BITPIX=16, KOPRMODE=COMPACT, STORFMT=INT16, BSCALE/BZERO, BLANK=-32768, QSTEP=BSCALE
Compact safety: QSTEP <= 0.25 * sigma_local; unsafe output falls back per file to Scientific.
Policy: REQMODE QPOLICY QMETHOD QFRAC QNOISE QMAX QNSAMP QSAFE QFALLBK

CORE INPUT METADATA
Exposure: EXPTIME, EXPOSURE, XPOSURE, TEL_EXPO, ELAPSED, DURATION
Temperature: CCD-TEMP and common CCD/SET/SENSOR/DET variants
Filter: FILTER, FILTNM, FILTNAM, FILTNAME, OFILTER, FILT
Object: OBJECT, OBJNAME, OBJCTNAM, TARGNAME, TARGET, COMET, COMETNAM
Instrument: INSTRUME, CAMERA, DETECTOR, CCDNAME, SENSOR
Gain: GAIN, EGAIN, CCD-GAIN, CCDGAIN, ISO, ISOSPEED
Offset: OFFSET, CCD-OFFS, CCDOFFST, BLACKLEV, BLACKLVL
Read mode: READMODE, READOUTM, READOUT, AMP-MODE, AMPMODE
Saturation: SATURATE, SATLEVEL, MAXADU, ADC-MAX (DATAMAX and observed maximum are not detector limits)
Detector bits: ADCBITS, ADC-BITS, BITDEPTH, BITDEP, NBITS -> 2**bits - 1

WSTACK STACK COUNTS
NREQUEST = frames requested before relative-WCS QC
WCSREJ   = frames rejected by relative-WCS QC
NCOMBINE = frames actually combined
EXP_NR   = backward-compatible alias of NCOMBINE
NCONTRIB = per-pixel geometric contributions before clipping (extension)
NVALID   = per-pixel accepted contributions after clipping (extension)

STACK EXTENSIONS
NCONTRIB, optional NVALID, optional NSATCON/NSATVAL, PROVENANCE, optional COMETTRK
Automatic WCCD: SATCOMP=COMPLETE + matching NSATVAL is authoritative; aggregate stack peaks are not compared with per-frame ADC limits.
R73 scalar fallback without complete NSATVAL: resolve the established automatic/manual base, then multiply into the current image domain so effective_limit >= finite_image_maximum without copying the observed maximum.
Audited 240P SUM example: base 65535; maximum 1036396.5625; multiplier 16; effective limit 1048560 ADU. SATCOMP=NONE and missing peak provider are diagnostic, not blanket star rejection; flat-top/bleeding morphology remains an independent veto.
Manual WCCD override: editing Saturation level bypasses NSATVAL for that image role, but uses the same shared base-to-effective resolver until its FITS is replaced.
Camera validation: reconstruct native geometry from SRCNAX1/2 (or supported dimensions) × binning; VERIFIED_EXACT and one unique VERIFIED_COMPATIBLE active-area match suppress the selection dialog.
Keep all HDUs intact for WCCD photometry.

MATCHED PAIR
PAIRFILE, PAIRID, PAIRVER, PAIRROLE plus matching object/filter/method/count/time/provenance.

TIME
TIMESYS=UTC
DATE-BEG = first accepted exposure start
DATE-OBS/DATE-MID/DATE-AVG = exposure-weighted midpoint
MJD-OBS/MJD-AVG = same midpoint in MJD UTC
DATE-END = last accepted exposure end
TELAPSE = full elapsed interval including gaps
TIMEALGO=EXP-WMID; TIMECOMP=COMPLETE or PARTIAL

EXPOSURE
TOTEXP=XPOSURE=sum accepted exposures
EXPTIME = numerical exposure represented by stack pixels: total for SUM; one input exposure for MEAN/SIGCLIP
WCCD normalization = 40 - 2.5 log10(net_flux/EXPTIME)
Comet/Stars EXPTIME tolerance = 0.001 s; accepted value freezes at observation preflight
TOTEXP/XPOSURE is reporting metadata only, never the photometric divisor

EXTERNAL FITS
Storage format and origin are separate. External int16 is not a third KOPR mode.
Do not infer missing TOTEXP as EXPTIME*NCOMBINE. Manual WCCD can use ordinary external FITS; automatic hand-off requires the complete native pair/QC/provenance contract.

OBSERVATION SAVE
Append ICQ code writes only the fixed-width ICQ record to <observer-code>.txt
in the current KOPR working directory. CometObs and Af-rho text are displayed,
not appended by that button. Save figure writes a user-selected PNG.

BACK UP
config-files/, custom/local observation data, ST/CO FITS pairs with extensions,
processing_manifest.json, pipeline_state.json and QC reports.

COBS SOURCE CODES (CASE-SENSITIVE)
APASS Sloan g'/r'/i': AG, AR, AI
APASS calculated R/I share AR/AI with direct Sloan-r/i.
Gaia: Bg, Vg, Rg, Ig, gg, rg, ig, zg


R56 ACTIVE SETTINGS
- settings.dat stores/restores active Location, Telescope, Eyepiece and Camera.
- writes use flushed atomic replacement; startup does not force index zero.

R57 WSTACK QSETTINGS
- wstack/comet and wstack/stars are independent namespaces.
- save validated method/sigma only after successful dialog validation.
- comet output mode belongs to wstack/comet.

R58 RESULT COMMENT POLICY
- no automatically generated "Saturation:" sentence in Results, ICQ or COBS comments.
- saturation thresholds, maps and provenance remain internal diagnostic data.


R74 AUTOMATIC DSLR RAW -> TG FITS SESSION CONTRACT
- Physical CR2/CR3/NEF/ARW/DNG files are discovery/materialization sources only.
- Pending/stale extraction candidates start materialization automatically before the current session is replaced; no confirmation or bypass branch is offered.
- Missing rawpy/LibRaw raises DSLR RAW extraction unavailable; existing FITS may still open, but physical RAW is never a fallback input.
- The Raw page and _session_files contain FITS only.
- TG2X2 linear green extraction is materialized beside the source RAW.
- Cooperative progress cancellation occurs between files; completed verified FITS remains and pending work resumes automatically on the next open.
- Conflicting targets are not overwritten; stale targets are atomically replaced only after temporary verification.
- Post-resolution rediscovery selects a created/refreshed TG FITS or the first verified representation; migrate_raw_state_paths_to_fits() then runs before reconcile_session() and preserves historical ON/OFF cascades.


R76 PHYSICAL GEOMETRY
- Camera native identity/geometry and observation binning are separate.
- Shared scale priority: solved WCS/online calibration; manual override; FITS scale metadata; active optics with validated binning.
- Internal DE440s comet positions apply down-leg light-time; external residuals are diagnostic without a universal arcsecond gate.

R77/R78 REFERENCE STAR STATE
- One lossless canonical collection for AutoStars and Manual Stars.
- user_enabled is observer state; pairwise_accepted is derived solver state.
- Extinction-corrected q_i enters the global pairwise solver.
- Every accepted pair must differ by < 0.150 mag; equality fails.
- One accepted-ID set/final solution feeds Reference stars, Process obs. and Af-rho.
- Pairwise audit details are not appended to ICQ comments.


R81 DIRECT RAW REPRESENTATION
- RAWREP=T identifies one direct TG FITS representation of a physical RAW.
- RAWREP=F identifies calibrated/astrometric derivatives with RAW ancestry.
- Final stacks strip direct identity cards: RAWREP, RAWFILE, RAWEXT, RAWMODE, RAWVERS, RAWSIZE, RAWMTIME.
- Multi-frame ancestry remains in HISTORY, REFIMAGE, NCOMBINE and PROVENANCE.
- Derived-product cards/names override historical RAWFILE/RAWEXT claims during discovery; legacy valid _TG.fits without RAWREP remains supported.