Docs · FITS headers

FITS headers Photon Ledger reads

Photon Ledger is header-only: it parses the FITS primary HDU header of each sub-frame and never touches the pixel data array. This page is a reference of the specific keywords it reads from each frame, grouped by purpose, and how each one feeds into integration-time tracking, rig detection, and dashboard analytics.

Core capture fields

These are the primary keywords PL relies on to classify a frame and bucket its exposure time.

Header	What PL does with it
`OBJECT`	Canonical target name. Used to group light frames into target totals.
`FILTER`	Filter wheel position (e.g. `Ha`, `L`, `R`, `OIII`). Drives per-filter integration breakdowns.
`EXPTIME` / `EXPOSURE`	Exposure in seconds. Summed across frames to produce total integration. `EXPTIME` is preferred; `EXPOSURE` is used as a fallback.
`DATE-OBS`	UTC capture timestamp. Used to assign a frame to a session/night and to sort timelines.
`IMAGETYP`	Frame type — `LIGHT`, `FLAT`, `DARK`, `BIAS`. Only light frames contribute to target integration.
`INSTRUME`	Camera name. Used to identify rig and to detect rig changes across sessions.
`TELESCOP`	Telescope name. Combined with `INSTRUME` to fingerprint a rig.

Mount / pointing fields

Pointing data is read defensively — it's used to validate, not to classify.

Header	What PL does with it
`OBJCTRA`, `OBJCTDEC`	Target right ascension and declination as commanded by the sequencer.
`RA`, `DEC`	Mount-reported coordinates. Cross-checked against `OBJECT` to flag mis-labelled frames.
`OBJCTAZ`, `OBJCTALT`	Azimuth and altitude. Reserved for future analytics (e.g. low-altitude frame quality).
`AIRMASS`	Reserved for future analytics — sky condition and altitude correlation.

Sensor parameters

Sensor metadata is used to detect rig configuration changes between sessions and to track sensor health over time.

Header	What PL does with it
`XBINNING`, `YBINNING`	Binning factor. Frames at different binnings are tracked as distinct configurations.
`XPIXSZ`, `YPIXSZ`	Pixel size in microns. Used (with `FOCALLEN`) to derive image scale, and to detect rig changes.
`GAIN`	Camera gain setting. Tracked per-rig for sensor-health trending.
`OFFSET`	Camera offset (bias level). Tracked alongside gain.
`CCD-TEMP`, `SET-TEMP`	Sensor temperature actual and setpoint. Charted over time to spot cooler drift.
`READOUTM`, `READMODE`	Readout mode (e.g. high-gain, low-noise). Captured as part of the rig fingerprint.

Optics / setup

Optical parameters describe the imaging train and let PL derive image scale.

Header	What PL does with it
`FOCALLEN`	Focal length in mm. Combined with pixel size to derive `XPIXSZ_arcsec` (image scale in arcsec/pixel).
`APTDIA`	Aperture diameter in mm. Part of the rig fingerprint.
`FOCRATIO`	Focal ratio (f-number). Cross-checked against `FOCALLEN` / `APTDIA`.

When both XPIXSZ and FOCALLEN are present, PL derives the image scale as XPIXSZ * 206.265 / FOCALLEN arcsec/pixel. If either is missing the scale is left undefined rather than guessed.

Bayer / colour metadata

For one-shot-colour (OSC) cameras, PL records the Bayer matrix metadata so analytics can distinguish OSC from mono workflows. It does not demosaic — this is header-only.

Header	What PL does with it
`BAYERPAT`	Bayer pattern (e.g. `RGGB`, `GRBG`). Recorded with the frame.
`XBAYROFF`, `YBAYROFF`	Bayer matrix origin offsets. Recorded for completeness.
`COLORTYP`	Colour type indicator. Used to tag the rig as OSC vs mono.

Software / sequencer hints

These keywords identify the capture software that wrote the frame. PL uses them to attribute behaviour by sequencer (relevant for an upcoming blog post on per-sequencer header quirks).

Header	What PL does with it
`SWCREATE`, `CREATOR`	Capture software name and version. Used to detect NINA vs SGP vs APT vs other sequencers.
`SEQGUID`, `RUNGUID`	Sequence and run identifiers (when present). Used to group frames captured in the same run.

Headers PL does NOT read (intentionally)

To keep the privacy story honest, PL deliberately skips pixel-data-related keywords and anything that would require reading the data array:

BSCALE, BZERO — pixel scaling parameters; only meaningful when applied to data.
The DATA array itself — never read, never copied, never opened beyond the header bytes.
HISTORY records that contain processed-image traces (calibration, stacking, integration logs).

The scanner stops at the end of the primary HDU header. Pixel data stays on your disk and never enters Photon Ledger's memory.

What to do if a header is missing or wrong

PL is built for the reality that headers vary between sequencers and observers. When a key field is missing or contradicts the file's location, PL falls back to folder-structure heuristics (see folder schemas) and surfaces affected frames in "unknown" buckets in the Dashboard so you can spot mis-labelled frames at a glance. You can then re-tag affected frames in bulk after the fact — the underlying FITS files are never modified, only PL's internal classification.