Scientific and Compact FITS output

What the modes change

Scientific and Compact are storage representations of the same computed result. Calibration, reprojection, astrometry, stack combination, manual WCCD and automatic helper calculations continue to use floating-point working arrays. The selected mode is applied only when a final product is written to disk.

First start: DE440s ephemeris kernel

The final R27 clean distribution does not bundle the approximately 32.7 MB data/de440s.bsp file. When it is missing, KOPR presents a progress dialog for the verified download.

• Cancel: stop the current attempt and continue with the legacy ephemeris fallback.
• Retry: start a new attempt after a failure or cancellation without restarting KOPR.
• Verified installation: the completed kernel replaces the target atomically only after validation; temporary .part data are cleaned up.
• Command line: run python de440s_fetch.py for a manual attempt.
• Existing kernel: set KOPR_DE440S to a verified file stored elsewhere.

The DE440s delivery mechanism does not change Scientific/Compact FITS encoding or photometric calculations.

Select a mode

Open Settings › Processing › FITS output format and choose:

• Scientific — float32, maximum precision
• Compact — scaled int16, smaller files

The selection affects only products created after the change. Existing FITS files are not converted. A calibration or stacking task reads the setting when that task starts; changing Settings while a batch is running does not change the format within that batch.

Older configuration files without the new value default to Scientific, preserving the historical behaviour.

Scientific format

BITPIX   = -32
KOPRMODE = 'SCIENTIFIC'
STORFMT  = 'FLOAT32'
QSTEP    = 0.0

• four bytes per primary science pixel;
• fractional and negative values are stored directly;
• invalid pixels remain IEEE NaN;
• no value quantization is applied.

Scientific is the default and most conservative output mode.

Compact encoding

Compact maps finite physical values linearly to signed int16 codes:

BITPIX   = 16
KOPRMODE = 'COMPACT'
STORFMT  = 'INT16'
BSCALE   = one quantization step
BZERO    = linear zero point
QSTEP    = BSCALE
BLANK    = -32768

physical_value = stored_integer × BSCALE + BZERO
QSTEP = (DATAMAX - DATAMIN) / 65534

-32768 is reserved for NaN, +inf and -inf. Finite pixels use codes -32767 through 32767, so a valid value cannot collide with BLANK. Astropy normally applies BSCALE, BZERO and BLANK automatically when the file is opened.

Noise-relative safety policy and per-file fallback

KOPR does not force Compact when the necessary step would be too coarse relative to the real image noise. Local pixel noise is estimated robustly from horizontal and vertical neighbour differences using the median and MAD. Compact is accepted only when:

QSTEP ≤ 0.25 × sigma_local

At that limit, quantization adds about 0.52% to pixel-noise variance and about 0.26% to pixel-noise standard deviation.

If the condition fails, KOPR does not clip the image and does not silently use a coarser quantization. That product is written as Scientific float32. The decision is made independently for every output, so a Compact-requested batch may legitimately contain an individual Scientific file.

KOPRMODE, STORFMT, BITPIX and QSTEP always describe the file actually written, not only the user's request.

Products affected by the setting

• new master darks, dark-flats and biases;
• new master flats;
• masters imported and rewritten into the KOPR calibration library;
• calibrated LIGHT frames;
• final Stars stacks;
• final Comet stacks;
• jointly created Stars/Comet pairs.

The mode applies to MEAN, SUM and sigma-clipped mean products. Computation remains floating point; conversion occurs only at the final writer.

WStack FITS structure is unchanged

Compact changes only the primary science HDU. Both modes retain the same auxiliary contract:

• NCONTRIB and, when different, NVALID;
• NSATCON and, when different, NSATVAL;
• PROVENANCE;
• COMETTRK for motion tracking;
• WCS and SIP metadata;
• PAIRID, PAIRROLE and PAIRFILE for matched products.

Auxiliary maps use the smallest lossless integer type and may use lossless RICE_1 compression where appropriate. Compact therefore does not create a reduced or incompatible automatic-photometry contract.

Unified time and exposure contract

Stack timing is derived from the exposures actually accepted into the stack, not copied from the reference frame.

effective_time = sum(EXPTIME_i × midpoint_i) / sum(EXPTIME_i)

Exposure keywords follow the numeric scaling of the primary image:

NCOMBINE is the number of actually combined frames and EXP_NR is its compatibility alias. Mean products require equal positive exposure times; SUM can combine different positive exposure times.

Astrometry preserves the science-pixel representation

Creating an _WCS.fits product copies the complete source FITS, opens the copy without applying scaling to raw pixel storage, and replaces only relevant WCS/SIP/QC header cards. Other extensions are preserved. A Scientific input remains Scientific; a Compact input remains Compact with the same BSCALE, BZERO, BLANK and QSTEP. Astrometry does not perform a second Compact quantization.

WCCD, automatic helpers and external FITS

Supported real-image FITS types are decoded to physical values and copied into a common C-contiguous float32 array before measurement. Manual WCCD can therefore read signed int16, pseudo-unsigned uint16 through FITS scaling, other scaled integers, float32 and float64, with the image in the primary or a supported image extension.

Auxiliary extensions such as coverage, clipping, saturation, PROVENANCE and COMETTRK are skipped when locating the science image.

Native Scientific and Compact Stars/Comet pairs use the same WCCD measurement algorithms and checks. Compact storage alone is never a rejection reason. After decoding, photometry uses m_inst = 40 - 2.5 log10(net_flux / EXPTIME); local sky remains an additive subtraction term. The hand-off still requires the full native WStack pair and QC/provenance contract. Ordinary external FITS can be measured manually, but the shared inspector does not invent missing TOTEXP as EXPTIME × NCOMBINE and does not bypass the native pair-safety contract.

WCCD helpers and Slice

Automatic Comet Finder, its confirmation dialog, Auto Star Measure, Slice Through Comet, Slice Between Points and persistent ACF Review all receive physical floating-point values after FITS scaling. Scientific and Compact therefore use the same numerical helper and display logic.

Available diagnostics can differ when the input lacks native WStack provenance or auxiliary extensions, but storage mode alone must not change the numerical result.

PA-adaptive ACF context

Scientific and Compact files are decoded to the same local read-only float32 ACFMeasurementContext. The PA-adaptive ring algorithm, centroid contract, Review preview and Apply path are therefore identical for both storage modes.

Reviewing or applying ACF parameters never rewrites the source FITS and does not alter the koprfits.py storage contract.

Storage and performance expectations

• Scientific primary science payload: four bytes per pixel.
• Accepted Compact primary science payload: two bytes per pixel.

The complete multi-extension FITS is not necessarily 50% smaller because coverage, clipping, saturation, provenance and tracking data remain. Compact mainly reduces disk space and image I/O. It does not guarantee half the peak RAM, because processing and photometry still use floating-point working arrays.

Validate Scientific and Compact output

The program distribution includes validate_scientific_compact.py.

Synthetic validation

python validate_scientific_compact.py \
  --json validation.json \
  --csv validation.csv \
  --markdown validation.md

Compare two products

python validate_scientific_compact.py \
  --compare scientific.fits compact.fits \
  --json pair-validation.json

Compare with aperture geometry

python validate_scientific_compact.py \
  --compare scientific.fits compact.fits \
  --center 1036.4,1029.8 \
  --aperture-radius 180 \
  --sky-inner 240 \
  --sky-outer 310

Write both modes from one source

python validate_scientific_compact.py \
  --source input.fits \
  --output-dir validation-products \
  --keep-files

The report includes requested and actual mode, fallback reason, QSTEP, local noise, the safety ratio, pixel deviations, optional flux/magnitude/background/centroid differences, file sizes and real-file I/O times. The simple validation aperture checks the storage representation; it does not replace standard WCCD or automatic ACF validation on representative observations.

Download the compact Scientific/Compact reference.

Related chapters

Choose the output mode · Calibration and stacking · FITS keyword reference · CCD photometry · Troubleshooting · Developer algorithm reference · Automatic helpers / Slice