Public Release of getframes

getframes 2.0.0

getframes is a Python library for generating physically realistic synthetic
camera frames — dark, bias, flat, and rendered star fields — from CCD, CMOS,
EMCCD, eAPD, and sCMOS detectors. It models the complete
photon → electron → ADU signal path with auditable noise physics, so you can
build and test image-processing pipelines against known ground truth.

This is the first PyPI release. The full public API is frozen under Semantic
Versioning for the 2.x series.

Install

pip install getframes

Quick start

import getframes as gf

# Dark frame from a built-in preset
cam = gf.Camera.from_preset("andor_ikon_m934")
frame = cam.dark_frame(exposure=60.0, temperature=-60.0, seed=0)
frame.data       # 2-D NumPy array of ADU
frame.truth      # noise-free ground truth

# Render a star field
scene = gf.Scene(
    shape=(512, 512),
    optics=gf.Telescope(
        aperture_diameter_m=2.5,
        throughput=0.3,
        plate_scale_arcsec_per_pixel=0.4,
        band=gf.Bandpass.johnson("V"),
    ),
    psf=gf.MoffatPSF(fwhm_arcsec=1.1, beta=3.0),
    sources=[gf.PointSource(x=256, y=256, magnitude=18.0)],
    sky=gf.Sky(surface_brightness_mag_arcsec2=21.5),
)
frame = cam.with_config(resolution=(512, 512)).observe(scene, exposure=300.0, seed=1)

What's included

Detector physics

The full noise chain for five sensor types: read noise, dark current
(temperature-scaled with a doubling-temperature model), PRNU/DSNU fixed-pattern
noise, shot noise, a unified stochastic EM/avalanche gain stage (EMCCD and eAPD),
clock-induced charge, digitization, bias, and saturation.

Optional realism effects — all off by default — add CTI trailing, charge blooming,
inter-pixel capacitance, kTC/reset noise, multi-amplifier readout offsets,
cosmic-ray tracks, defect maps, and polynomial nonlinearity.

Scene rendering

Render astronomical sources through a PSF and telescope onto a detector with
Camera.observe. Sources include point sources, extended sources (Sérsic profiles
or array cutouts), spatially uniform illumination, and large catalogs. PSF models
cover Gaussian, Moffat, Airy (with central obstruction), elliptical Gaussian, and
user-supplied arrays. The scene layer supports vignetting, radial distortion, and
WCS sky-coordinate projection.

Calibration

combine stacks frames into masters (mean, median, or sigma-clip). calibrate
performs the standard bias/dark/flat reduction so a reduced frame can be compared
directly against Frame.truth — the noise-free ground truth attached to every
frame.

Time series and observations

Camera.observe_series returns an Observation — a structured sequence of frames
with per-frame timestamps, pointing offsets, and per-source truth light curves.
Sources can carry LightCurve brightness variations (box transit, sinusoidal, or
arbitrary function). Pointing models jitter, linear drift, and programmed dither.

Quantitative radiometry

AB-system and Vega-system photometry via Bandpass.ab (SDSS ugriz, Gaia, 2MASS)
and Bandpass.johnson (Johnson UBVRI). Spectral energy distributions with
SED.from_flux_density, real measured transmission curves via
SpectralBandpass.from_file, interstellar extinction (Cardelli–Clayton–Mathis
1989), and thermal background graybody emission for IR scenes. astropy.units
quantities are accepted wherever wavelength or flux density is expected.

Dataset generation and CLI

getframes.dataset.pairs() streams {"raw": ADU array, "truth": electrons array}
pairs reproducibly to disk for training ML pipelines. The getframes CLI
(presets / generate config.toml / dataset config.toml) turns a shareable
TOML file into frames or a dataset without writing Python.

Preset library

Ten built-in camera presets covering the full sensor-type range:

Preset	Type	Notes
andor_ikon_m934	CCD	Deep-cooled back-illuminated scientific CCD
andor_ixon_ultra_888	EMCCD	Single-photon-sensitive
leonardo_saphira	eAPD	HgCdTe IR avalanche array
zwo_asi2600mm	CMOS	Sony IMX571 cooled CMOS
hamamatsu_orca_fusion	sCMOS	Back-thinned, per-pixel read noise
generic_ccd / generic_cmos / generic_emccd / generic_eapd / generic_scmos	—	Idealised references for testing

Validation

tests/test_validation.py asserts the physics against analytic and published
references: AB/Vega zero points, the gain-stage excess noise factor,
CTI/IPC/blooming charge conservation, PSF flux conservation, PTC parameter
recovery, and reduced-frame truth recovery.

Requirements

Python 3.10–3.13. Core dependencies: numpy, scipy, astropy. matplotlib
is available as pip install getframes[examples] for the runnable examples.