getframes 2.1.1__tar.gz → 2.2.0__tar.gz

{getframes-2.1.1 → getframes-2.2.0}/.gitignore

@@ -223,4 +223,6 @@ __marimo__/
 # Streamlit
 .streamlit/secrets.toml
 keck_ttf
-*.png
+*.png
+.vscode
+*.npz

{getframes-2.1.1 → getframes-2.2.0}/CHANGELOG.md

@@ -6,6 +6,218 @@ to [Semantic Versioning](https://semver.org/spec/v2.0.0.html).
 
 ## [Unreleased]
 
+## [2.2.0] - 2026-08-24
+
+### Added
+
+- **`CameraConfig.read_noise_correlated_fraction`.** The part of read noise that
+  is common to every read of a nondestructive ramp, and so cancels when two
+  reads are differenced. Without it every read was an independent draw and
+  correlated double sampling could only ever cost a factor of `sqrt(2)` — but a
+  real CDS frame is often *quieter* than a single read, because reference-level
+  drift, bias settling, and 1/f noise persist between the two reads and
+  differencing removes them. Defaults to `0`, which is the previous behaviour.
+  Only a differenced measurement can constrain it; single-read data cannot.
+
+- **Vega-system J, H, and Ks bands.** `Bandpass.johnson` previously stopped at
+  I, so any near-infrared work had to leave the Vega system for AB — a
+  different magnitude for the same star, by +0.89 (J), +1.37 (H), and +1.84
+  (Ks). The zero points are derived from the 2MASS absolute calibration (Cohen,
+  Wheaton & Megeath 2003) through the same integral the AB path uses, so the
+  two systems now differ only in the reference spectrum and not in the
+  convention. `SpectralBandpass.johnson` gained the matching tophats, which are
+  the same shapes the AB survey table already used: a filter's shape is a
+  property of the filter, not of the magnitude system.
+- **Correlated double sampling as a first-class readout mode.**
+  `Camera.correlated_double_sample` resets, reads the pedestal, integrates, reads
+  again, and returns the signed `int32` ADU difference — the frame a camera in
+  CDS mode actually delivers. It shares one reset-correlated readout core with
+  `nondestructive_series`, so kTC noise and fixed bias structure cancel, read
+  noise grows by `sqrt(2)`, common mode is partly removed through its AR(1)
+  correlation, and reset settling leaves its pedestal-to-signal residual. The
+  interval-proportional bias rate survives differencing by construction and is
+  documented as a dark-subtractable pedestal. `pedestal_interval_s` models a
+  finite reset-to-read delay. `correlated_double_sample_spectral` is the
+  wavelength-resolved twin, standing to it as `expose_spectral` does to
+  `expose`; both spectral entry points now share one QE-folding step, so a cube
+  cannot have QE applied twice or applied differently per readout mode.
+- **Global-reset nondestructive read series for eAPD arrays.**
+  `Camera.nondestructive_series` and `dark_nondestructive_series` accumulate
+  Poisson charge between resets, preserve a ramp's kTC realization, redraw read
+  noise on every sample, and expose ramp/read timing in frame metadata.
+- **A measured C-RED One preset and hybrid-array readout structure.** The new
+  `first_light_imaging_cred_one` preset separates the complete camera from the
+  bare `leonardo_saphira` detector and models its 32 interleaved output channels,
+  edge-dependent pedestal/noise, stable per-channel offsets and noise scales, and
+  correlated frame-wide readout pedestal. Its spatial and temporal dark-frame
+  parameters are constrained by the July 2026 CRED1 dark stack.
+- **Reset-aware stack characterization.** `nondestructive_stack_statistics`
+  measures strong-reset cadence, ramp slopes, common mode, CDS/pixel noise,
+  interleaved channels, and edge structure without treating correlated reads as
+  independent exposures. `ramp_photon_transfer` fits conversion gain and
+  split-ramp response nonuniformity from repeated NDR ramps.
+- **`examples/16_detector_showcase.py`** renders an animated WebP that exposes one
+  incident photon field on a CCD, EMCCD, sCMOS, and eAPD side by side, each panel
+  overlaid with the frame rate that camera sustained on the running machine. The
+  clip is the README header image.
+
+### Changed
+
+- **Refined the measured C-RED One response across gain and read rate.** Fixed
+  avalanche-gain nonuniformity, sublinear gain noise, NDR read-interval scaling,
+  observed 42/3/5-read electronic cadences, reset settling, and separate broad
+  side/narrow row-edge pedestal terms now reproduce the local operating-point
+  stacks. The C-RED One and SAPHIRA QE curves were corrected to the manufacturer
+  plot: 60% through 950 nm, linear to 80% at 1450 nm, then 80% to 2500 nm.
+
+- **The README follows the documentation-first structure** used across the sibling
+  projects: docs link, showcase clip, install, quickstart, benchmarks, then the
+  feature list. The preset table and the dark-frame model walkthrough now live
+  only in the presets and noise-model guides, which they already duplicated.
+- **Refreshed `benchmarks/device-results.{json,md}`** on the RTX 5090 / Ryzen 9
+  9950X3D reference machine against getframes 2.1.1, NumPy 2.2.6, and CuPy 14.1.1.
+
+### Fixed
+
+- **Benchmark provenance now records the CuPy version** when CuPy is installed
+  under a CUDA-specific wheel name (`cupy-cuda12x`/`cupy-cuda11x`). The metadata
+  block previously reported `cupy: null` on exactly the machines that had
+  produced the GPU column.
+
+- **Persistent cameras now cache the dark-signal expectation.** Repeated exposures
+  at the same exposure time, temperature, precision, and detector configuration
+  reuse the full-detector DSNU/hot-pixel/glow map; changing either physical key
+  rebuilds it. Seeded stochastic frames and detector truth remain unchanged.
+
+- **sCMOS per-pixel read noise is now a fixed property of the sensor.** The
+  per-pixel read-noise RMS map implied by `read_noise_nonuniformity` was drawn from
+  the *per-frame* generator, so it was re-randomised in every frame. Single-frame
+  spatial statistics were unaffected, but every pixel ended up with the same
+  expected noise *through time*, which is not how an sCMOS behaves: each pixel has
+  its own source-follower and column ADC. The map is now built once from
+  `fixed_pattern_seed` and cached in `FixedPatternMaps`, alongside PRNU and DSNU.
+  Verified against dark stacks from three real back-illuminated sCMOS cameras
+  (KURO 1200B, Prime 95B, Marana 4.2B-11): splitting a stack in half and
+  correlating the two per-pixel temporal-variance maps gives r = 0.89–0.94 on the
+  real detectors and r = 0.004 with the old model, now r ≈ 0.96.
+  **This changes generated pixel values** for any configuration with
+  `read_noise_nonuniformity > 0`; `read_noise_e` and the spatial statistics of a
+  single frame are unchanged.
+
+### Added
+
+- `DetectorWorkspace` plus optional `workspace=` / caller-owned `out=` execution
+  on scalar and spectral camera exposures. Full-detector ROI inputs, private
+  photo/total scratch, and digitised destinations can now be reused without
+  allowing returned truth or default frames to alias mutable scratch. The
+  workspace is device/shape/precision-bound and rejects concurrent use.
+- `CameraConfig.charge_diffusion_fwhm_px`, `charge_diffusion_kernel()`, and
+  `apply_charge_diffusion()` make lateral detector charge spreading available to
+  focal-plane simulators at their own oversampling. The OCAM2K preset declares
+  its measured 0.37-pixel FWHM; under-resolved kernels fail explicitly, while
+  native-resolution camera frames state in metadata that diffusion was not
+  applied rather than silently becoming a numerical no-op.
+- Full-detector region-of-interest simulation through
+  `CameraConfig.roi=(left, top, width, height)`. Cameras accept and return
+  ROI-shaped arrays while evaluating detector physics and fixed patterns on the
+  native sensor before cropping. `Camera.sensor_resolution`,
+  `CameraConfig.output_resolution`, and active amplifier-boundary properties make
+  the full-versus-ROI geometry explicit. Exact full-detector split pixels remain
+  available when an ROI is active.
+- **`getframes.analysis.characterize`: detector characterisation from frame
+  stacks.** Where `photon_transfer_curve` drives a *simulated* camera, this works
+  on stacks that already exist -- raw data off a real detector, or simulated
+  frames. `stack_statistics` reduces any iterable of frames (arrays, `Frame`s, a
+  `dark_series` generator, your own file reader) to per-pixel temporal mean and
+  variance in one streaming pass, so stacks larger than memory are fine.
+  `characterize_dark` then measures conversion gain, read noise (with its
+  per-pixel map, log-normal width and RTS tail), dark current, bias and DSNU from
+  darks alone -- no flat field needed, because dark charge is Poisson and so
+  serves as the PTC charge source. `characterize_flat` adds full well, PRNU and
+  linearity. `DarkCharacterization.to_config()` returns a `CameraConfig`, closing
+  the loop: measure a real camera, then simulate it. `StackStats.split=True`
+  additionally gives `temporal_repeatability`, the split-half test that separates
+  genuine per-pixel noise structure from chi-squared sampling scatter.
+  New guide (`docs/guides/characterization.md`) and example
+  (`examples/15_detector_characterization.py`).
+- `read_noise_rts_fraction` / `read_noise_rts_factor`: an optional second,
+  noisier read-noise population modelling the random-telegraph-signal (RTS) pixels
+  of a real sCMOS array. Measured on three real sensors, ~0.5% of pixels sit above
+  3x the median read noise where a single log-normal predicts ~0.01%; these are the
+  pixels that limit faint-source detection. Defaults to off.
+- `detector_glow_edge_scale_px`: makes `detector_glow_e_per_s` edge-concentrated
+  with an exponential falloff, instead of uniform, modelling amplifier glow emitted
+  at the array periphery. Renormalised so the array mean is unchanged; still fixed
+  and exposure-scaling, so an exposure-matched master dark removes it. Defaults to
+  `0` (uniform, the previous behaviour).
+
+### Changed
+
+- Float32 cameras now cache amplifier gain/offset and structured-bias maps in
+  float32 instead of retaining detector-sized float64 coefficients. The float64
+  reference path is unchanged. A matched 2048x2048 structured-digitization
+  benchmark improved by 1.328x on the local CPU and 1.382x on a Quadro P620 while
+  persistent coefficient storage fell from 96 MiB to 48 MiB.
+
+- The `princeton_instruments_kuro_1200b`, `photometrics_prime_95b`, and
+  `andor_marana_4_2b_11` presets now carry **measured** conversion gain, read noise,
+  dark current, bias offset, and non-uniformity terms, fitted from a per-pixel dark
+  photon-transfer analysis of real frames rather than taken from datasheets. The
+  largest corrections: conversion gain (1.25-1.3 -> 0.77-0.87 e-/ADU, the low-signal
+  leg of these dual-gain modes) and `dark_current_nonuniformity` (0.03 -> 0.11-0.33,
+  which had been roughly an order of magnitude too low). Each preset documents the
+  operating mode and temperature the values apply to.
+- `dark_current_nonuniformity` raised to `0.23` on the remaining sCMOS presets
+  (`generic_scmos`, `hamamatsu_orca_fusion`, `hamamatsu_orca_quest_2`,
+  `tucsen_aries_6504_pro`, `andor_cb1_0_5mp`), which previously carried 0.02-0.03 or
+  omitted the field entirely. `0.23` is the median of the three cameras measured
+  against real dark stacks (0.11, 0.23, 0.33); each preset documents that it is a
+  realistic default carried over from characterised hardware rather than a figure
+  from that camera's datasheet. The same four conventional sCMOS presets also gain
+  the measured RTS population (`read_noise_rts_fraction = 0.016`, factor 2.65), and
+  `andor_cb1_0_5mp` / `hamamatsu_orca_quest_2` gain a `read_noise_nonuniformity` of
+  0.2 where they previously had none at all. `hamamatsu_orca_quest_2` deliberately
+  keeps no RTS population --- photon-number resolution depends on a tightly screened
+  read-noise distribution, and importing a tail measured on conventional 11 um sCMOS
+  would misrepresent it.
+- `andor_marana_4_2b_11` gains its measured hot-pixel population
+  (`hot_pixel_fraction = 1e-4` above 10x the median dark rate).
+- `docs/guides/validation.md` documents how to validate a preset against a real dark
+  stack: measuring conversion gain from darks alone (no flats needed), and the
+  split-half test for repeatable per-pixel read noise.
+- **`examples/16_detector_showcase.py` now shows each detector in the regime it is
+  built for** rather than putting all four on one shared V-band field at a shared
+  200 ms exposure. The old framing was a tidy controlled comparison but an unfair
+  showcase: once `leonardo_saphira` carried a realistic near-infrared
+  dark-plus-background ceiling, its panel was dark-noise dominated in a visible
+  200 ms exposure (star/noise 0.93 against 7.4-22.6 for the other three), and no
+  exposure time fixes that, because amplified dark noise grows as `sqrt(t)` while
+  the star signal grows as `t`. The panels are now a 5 s deep-sky CCD field, a
+  500 Hz EMCCD wavefront sensor, 100 ms wide-field sCMOS, and the C-RED One eAPD
+  doing H-band AO in correlated double sampling at its 1750 Hz maximum frame
+  rate — which the clip measures at ~1,789 frames/s on an RTX 5090. The clip is
+  the README header image and exercises this release's CDS path, C-RED One preset,
+  and Vega H band.
+
+### Fixed
+
+- **The detector showcase no longer scales a panel to its own hot pixels.** The
+  clip took its per-panel display maximum at a hardcoded 99.95th percentile, which
+  is exactly the `hot_pixel_fraction` that `leonardo_saphira` declares, so the
+  display range was pinned to a defect population sitting near 20,000 ADU behind
+  the avalanche gain stage and every physical feature crushed to black. The
+  percentile is now taken from below the preset's declared defect fraction.
+- **The detector showcase subtracts a measured dark pedestal rather than the bias
+  offset alone.** Bias is not the zero point once a detector carries real dark
+  current through a gain stage — 80 e-/s at 50x avalanche gain is ~400 ADU per
+  200 ms frame — and a CDS frame sits on its own exposure-dependent bias-rate
+  pedestal rather than on the bias offset at all.
+- Declared the license as a PEP 639 SPDX expression (`license = "MIT"` plus
+  `license-files`) instead of the deprecated `license = { text = "MIT" }` table,
+  and dropped the now-redundant `License ::` classifier. The built distribution
+  carries `License-Expression: MIT` and `License-File: LICENSE`. No change to the
+  license itself.
+
 ## [2.1.1] - 2026-07-26
 
 ### Added
@@ -346,7 +558,8 @@ together in 1.0.
 - Documentation, runnable examples, and CI (lint, type-check, test matrix, PyPI
   release via Trusted Publishing).
 
-[Unreleased]: https://github.com/jacotay7/getframes/compare/2.1.1...HEAD
+[Unreleased]: https://github.com/jacotay7/getframes/compare/2.2.0...HEAD
+[2.2.0]: https://github.com/jacotay7/getframes/compare/2.1.1...2.2.0
 [2.1.1]: https://github.com/jacotay7/getframes/compare/2.1.0...2.1.1
 [2.1.0]: https://github.com/jacotay7/getframes/compare/2.0.0...2.1.0
 [2.0.0]: https://github.com/jacotay7/getframes/compare/1.0.0...2.0.0

getframes-2.2.0/PKG-INFO

@@ -0,0 +1,215 @@
+Metadata-Version: 2.5
+Name: getframes
+Version: 2.2.0
+Summary: Generate physically realistic synthetic camera frames (CCD/CMOS/EMCCD/eAPD/sCMOS) — dark, bias, flat, and rendered star fields — with auditable noise physics for scientific imaging pipelines.
+Project-URL: Homepage, https://github.com/jacotay7/getframes
+Project-URL: Documentation, https://jacotay7.github.io/getframes/
+Project-URL: Repository, https://github.com/jacotay7/getframes
+Project-URL: Issues, https://github.com/jacotay7/getframes/issues
+Project-URL: Changelog, https://github.com/jacotay7/getframes/blob/main/CHANGELOG.md
+Author-email: Jacob Taylor <jacobataylor7@gmail.com>
+License-Expression: MIT
+License-File: LICENSE
+Keywords: astronomy,camera,ccd,cmos,detector,emccd,imaging,noise,simulation
+Classifier: Development Status :: 5 - Production/Stable
+Classifier: Intended Audience :: Science/Research
+Classifier: Operating System :: OS Independent
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3.10
+Classifier: Programming Language :: Python :: 3.11
+Classifier: Programming Language :: Python :: 3.12
+Classifier: Programming Language :: Python :: 3.13
+Classifier: Topic :: Scientific/Engineering :: Astronomy
+Classifier: Topic :: Scientific/Engineering :: Image Processing
+Classifier: Typing :: Typed
+Requires-Python: >=3.10
+Requires-Dist: astropy>=5.0
+Requires-Dist: numpy>=1.23
+Requires-Dist: scipy>=1.10
+Requires-Dist: tomli>=2.0; python_version < '3.11'
+Provides-Extra: dev
+Requires-Dist: build>=1.0; extra == 'dev'
+Requires-Dist: mypy>=1.8; extra == 'dev'
+Requires-Dist: pytest-cov>=4.0; extra == 'dev'
+Requires-Dist: pytest>=7.0; extra == 'dev'
+Requires-Dist: ruff>=0.6; extra == 'dev'
+Provides-Extra: docs
+Requires-Dist: mkdocs-material>=9.5; extra == 'docs'
+Requires-Dist: mkdocs>=1.5; extra == 'docs'
+Requires-Dist: mkdocstrings[python]>=0.24; extra == 'docs'
+Provides-Extra: examples
+Requires-Dist: matplotlib>=3.7; extra == 'examples'
+Provides-Extra: gpu
+Requires-Dist: cupy-cuda12x>=13.0; extra == 'gpu'
+Description-Content-Type: text/markdown
+
+# getframes
+
+[![CI](https://github.com/jacotay7/getframes/actions/workflows/ci.yml/badge.svg)](https://github.com/jacotay7/getframes/actions/workflows/ci.yml)
+[![PyPI](https://img.shields.io/pypi/v/getframes.svg)](https://pypi.org/project/getframes/)
+[![Python](https://img.shields.io/pypi/pyversions/getframes.svg)](https://pypi.org/project/getframes/)
+[![Docs](https://img.shields.io/badge/docs-jacotay7.github.io%2Fgetframes-teal.svg)](https://jacotay7.github.io/getframes/)
+[![License: MIT](https://img.shields.io/badge/License-MIT-blue.svg)](LICENSE)
+
+**Documentation: [jacotay7.github.io/getframes](https://jacotay7.github.io/getframes/)**
+
+**Realistic synthetic camera frames for scientific imaging pipelines.**
+
+<p align="center">
+  <img src="examples/detector_showcase.webp" width="503" alt="Animated detector showcase: a CCD, EMCCD, sCMOS and C-RED One eAPD each simulated in the regime it is built for — deep-sky, AO wavefront sensing, wide-field, and near-infrared CDS — with live throughput.">
+</p>
+
+`getframes` generates the frames a real detector would have produced: the full
+**photon → electron → ADU** signal path for **CCD**, **CMOS**, **EMCCD**,
+**eAPD** and **sCMOS** sensors, with auditable noise physics (read noise, dark
+current, shot noise, fixed-pattern non-uniformity, a unified stochastic gain
+stage, clock-induced charge, nonlinearity, cosmic rays). It produces **dark**,
+**bias** and **flat** frames, and renders **star fields** through a PSF and
+telescope into a realistic science frame — so you can build and validate
+image-processing pipelines against ground truth. It runs on NumPy by default and
+switches to CUDA (via CuPy) with a single argument.
+
+## Install
+
+```bash
+pip install getframes            # CPU (NumPy + SciPy + astropy)
+pip install 'getframes[gpu]'     # + CuPy for CUDA 12.x
+pip install -e '.[dev]'          # from a clone, for development
+```
+
+## Quickstart
+
+```python
+import getframes as gf
+
+cam = gf.Camera.from_preset("andor_ikon_m934")  # 21 presets, or your own CameraConfig
+frame = cam.dark_frame(exposure=60.0, temperature=-60.0, seed=0)
+
+frame.data  # (1024, 1024) array of ADU
+frame.stats()  # {'mean': ..., 'median': ..., 'std': ..., 'min': ..., 'max': ...}
+frame.metadata  # camera/exposure/temperature provenance
+
+scene = gf.Scene(  # render a sky, then expose it
+    shape=(256, 256),
+    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=128, y=128, magnitude=20.0)],
+    sky=gf.Sky(surface_brightness_mag_arcsec2=21.0),
+)
+frame = cam.with_config(resolution=(256, 256)).observe(scene, exposure=300.0, seed=0)
+
+import cupy as cp  # and the same path on a GPU
+
+cam = gf.Camera.from_preset("andor_ocam2k", device="gpu", precision="float32")
+rate = cp.full(cam.resolution, 2.0e6, dtype=cp.float32)  # photons/s/pixel
+frame = cam.expose(rate, exposure=1.0e-3, seed=0)  # CuPy ADU, no host copy
+```
+
+See **[Getting started](https://jacotay7.github.io/getframes/guides/getting-started/)**
+for the full walkthrough,
+**[Observing scenes](https://jacotay7.github.io/getframes/guides/scenes/)** for
+sources, PSFs and telescopes,
+**[Camera presets](https://jacotay7.github.io/getframes/guides/presets/)** for the
+preset library, and
+**[The noise model](https://jacotay7.github.io/getframes/guides/noise-model/)** for
+the physics behind every stage.
+
+## Benchmarks
+
+Warm bulk-frame throughput on an AMD Ryzen 9 9950X3D and an NVIDIA RTX 5090
+(`float32`, truth enabled, persistent camera, device-resident input/output, no
+host transfers). The raw artifact and its invocation are
+[versioned with the benchmarks](benchmarks/device-results.json):
+
+| Workflow | Native shape | CPU (frames/s) | GPU (frames/s) | Speedup |
+| --- | ---: | ---: | ---: | ---: |
+| Pyramid WFS CMOS | 80×80 | 5,240 | 11,514 | 2.20× |
+| Shack-Hartmann WFS CMOS | 160×160 | 1,386 | 11,471 | 8.27× |
+| OCAM2K EMCCD | 240×240 | 357 | 8,045 | 22.53× |
+| SAPHIRA eAPD | 256×320 | 280 | 7,497 | 26.74× |
+| Large science CMOS | 1024×1024 | 31 | 1,453 | 47.21× |
+
+Higher is better; CUDA was synchronized around every timed region and
+construction was excluded. Even the smallest case reaches about 2×, while larger
+arrays and gain-stage detectors expose much more parallel work. Reproduce the
+table with
+
+```bash
+python benchmarks/bench_devices.py --seconds 2 --warmup 10 --device both
+python benchmarks/run.py                    # the CPU hot-path sweep
+```
+
+See the [full snapshot](benchmarks/device-results.md) and the
+**[GPU guide](https://jacotay7.github.io/getframes/guides/gpu/#reference-throughput)**
+for the methodology.
+
+## Features
+
+- **Five detector families** — CCD, CMOS, EMCCD, eAPD and sCMOS, from a library
+  of sourced **[presets](https://jacotay7.github.io/getframes/guides/presets/)**
+  (`andor_ikon_m934`, `andor_ocam2k`, `leonardo_saphira`,
+  `first_light_imaging_cred_one`,
+  `andor_marana_4_2b_11`, `zwo_asi2600mm`, …) or any `CameraConfig` you define.
+- **Auditable noise physics** — dark current vs. temperature, shot noise, a
+  unified stochastic gain stage (EM and avalanche) with realistic excess noise,
+  clock-induced charge, per-pixel sCMOS read noise, polynomial nonlinearity,
+  saturation and quantisation, each a small documented pure function in
+  **[the noise model](https://jacotay7.github.io/getframes/guides/noise-model/)**.
+- **Detector realism** — CTI, blooming, IPC, kTC/reset noise, multi-amplifier
+  readout, cosmic-ray tracks, defect and structured-bias maps, vignetting and
+  radial distortion.
+- **Fixed patterns that behave like silicon** — PRNU, DSNU, hot pixels, defects
+  and amplifier structure are keyed on `fixed_pattern_seed`, so they repeat in
+  every frame and are genuinely removable by a master frame.
+- **Scenes** — point, extended and catalog sources, Gaussian/Moffat/Airy/array
+  PSFs, a `Telescope` with Vega (Johnson) and AB (ugriz, Gaia, 2MASS) bandpasses,
+  extinction, graybody thermal background, WCS pixel↔world, and light curves.
+- **Calibration & ground truth** — master bias/dark/flat builders and a
+  `calibrate` reduction that closes the
+  **[raw → reduced → truth loop](https://jacotay7.github.io/getframes/guides/calibration/)**.
+- **Observations** — `Observation` drives time series with jitter, drift, dither
+  and persistence, carrying per-frame
+  **[truth](https://jacotay7.github.io/getframes/guides/time-series/)**.
+- **Spectral mode** (opt-in) — QE curves, relative or absolute SEDs, transmission
+  products and wavelength-resolved exposure; see
+  **[Spectral mode](https://jacotay7.github.io/getframes/guides/spectral/)** and
+  **[Radiometry & the infrared](https://jacotay7.github.io/getframes/guides/radiometry/)**.
+- **Analysis on real data too** — aperture sums, centroids, photon-transfer
+  curves, independent-stack characterization, and reset-aware nondestructive-ramp
+  analysis run on measured detector frames as readily as on simulated ones.
+- **Scale & datasets** — a float32 fast path, vectorised multi-source rendering,
+  a streaming raw+truth `dataset` generator and a `getframes` CLI; see
+  **[Scale & datasets](https://jacotay7.github.io/getframes/guides/datasets/)**.
+- **GPU-optional** — every camera takes `device="gpu"` (CuPy) and keeps the
+  detector path and truth arrays device-resident. CPU and GPU have independent
+  RNG streams, so a `seed` repeats exactly on a fixed backend while parity across
+  backends means matching statistics, not identical pixels.
+- **Reproducible and typed** — all randomness flows through a camera-owned seeded
+  generator, never global state; `mypy --strict` passes; every public name is
+  frozen under [SemVer](https://jacotay7.github.io/getframes/stability/) as of 2.0.
+- **Validated** — noise models are checked against published forms in CI; see
+  **[Validation](https://jacotay7.github.io/getframes/guides/validation/)**.
+
+See the **[API reference](https://jacotay7.github.io/getframes/reference/)** for
+every public function and class, the
+**[runnable examples](examples/)** for PTC, exposure planning, AO limiting
+magnitude, transit photometry and detector realism, and the
+**[roadmap](https://jacotay7.github.io/getframes/roadmap/)** for what is next.
+
+## Contributing
+
+Contributions — especially new camera presets — are welcome. See
+[CONTRIBUTING.md](CONTRIBUTING.md). Run the checks locally with:
+
+```bash
+ruff check . && ruff format --check . && mypy && pytest
+```
+
+## License
+
+MIT — see [LICENSE](LICENSE).

getframes-2.2.0/README.md

@@ -0,0 +1,170 @@
+# getframes
+
+[![CI](https://github.com/jacotay7/getframes/actions/workflows/ci.yml/badge.svg)](https://github.com/jacotay7/getframes/actions/workflows/ci.yml)
+[![PyPI](https://img.shields.io/pypi/v/getframes.svg)](https://pypi.org/project/getframes/)
+[![Python](https://img.shields.io/pypi/pyversions/getframes.svg)](https://pypi.org/project/getframes/)
+[![Docs](https://img.shields.io/badge/docs-jacotay7.github.io%2Fgetframes-teal.svg)](https://jacotay7.github.io/getframes/)
+[![License: MIT](https://img.shields.io/badge/License-MIT-blue.svg)](LICENSE)
+
+**Documentation: [jacotay7.github.io/getframes](https://jacotay7.github.io/getframes/)**
+
+**Realistic synthetic camera frames for scientific imaging pipelines.**
+
+<p align="center">
+  <img src="examples/detector_showcase.webp" width="503" alt="Animated detector showcase: a CCD, EMCCD, sCMOS and C-RED One eAPD each simulated in the regime it is built for — deep-sky, AO wavefront sensing, wide-field, and near-infrared CDS — with live throughput.">
+</p>
+
+`getframes` generates the frames a real detector would have produced: the full
+**photon → electron → ADU** signal path for **CCD**, **CMOS**, **EMCCD**,
+**eAPD** and **sCMOS** sensors, with auditable noise physics (read noise, dark
+current, shot noise, fixed-pattern non-uniformity, a unified stochastic gain
+stage, clock-induced charge, nonlinearity, cosmic rays). It produces **dark**,
+**bias** and **flat** frames, and renders **star fields** through a PSF and
+telescope into a realistic science frame — so you can build and validate
+image-processing pipelines against ground truth. It runs on NumPy by default and
+switches to CUDA (via CuPy) with a single argument.
+
+## Install
+
+```bash
+pip install getframes            # CPU (NumPy + SciPy + astropy)
+pip install 'getframes[gpu]'     # + CuPy for CUDA 12.x
+pip install -e '.[dev]'          # from a clone, for development
+```
+
+## Quickstart
+
+```python
+import getframes as gf
+
+cam = gf.Camera.from_preset("andor_ikon_m934")  # 21 presets, or your own CameraConfig
+frame = cam.dark_frame(exposure=60.0, temperature=-60.0, seed=0)
+
+frame.data  # (1024, 1024) array of ADU
+frame.stats()  # {'mean': ..., 'median': ..., 'std': ..., 'min': ..., 'max': ...}
+frame.metadata  # camera/exposure/temperature provenance
+
+scene = gf.Scene(  # render a sky, then expose it
+    shape=(256, 256),
+    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=128, y=128, magnitude=20.0)],
+    sky=gf.Sky(surface_brightness_mag_arcsec2=21.0),
+)
+frame = cam.with_config(resolution=(256, 256)).observe(scene, exposure=300.0, seed=0)
+
+import cupy as cp  # and the same path on a GPU
+
+cam = gf.Camera.from_preset("andor_ocam2k", device="gpu", precision="float32")
+rate = cp.full(cam.resolution, 2.0e6, dtype=cp.float32)  # photons/s/pixel
+frame = cam.expose(rate, exposure=1.0e-3, seed=0)  # CuPy ADU, no host copy
+```
+
+See **[Getting started](https://jacotay7.github.io/getframes/guides/getting-started/)**
+for the full walkthrough,
+**[Observing scenes](https://jacotay7.github.io/getframes/guides/scenes/)** for
+sources, PSFs and telescopes,
+**[Camera presets](https://jacotay7.github.io/getframes/guides/presets/)** for the
+preset library, and
+**[The noise model](https://jacotay7.github.io/getframes/guides/noise-model/)** for
+the physics behind every stage.
+
+## Benchmarks
+
+Warm bulk-frame throughput on an AMD Ryzen 9 9950X3D and an NVIDIA RTX 5090
+(`float32`, truth enabled, persistent camera, device-resident input/output, no
+host transfers). The raw artifact and its invocation are
+[versioned with the benchmarks](benchmarks/device-results.json):
+
+| Workflow | Native shape | CPU (frames/s) | GPU (frames/s) | Speedup |
+| --- | ---: | ---: | ---: | ---: |
+| Pyramid WFS CMOS | 80×80 | 5,240 | 11,514 | 2.20× |
+| Shack-Hartmann WFS CMOS | 160×160 | 1,386 | 11,471 | 8.27× |
+| OCAM2K EMCCD | 240×240 | 357 | 8,045 | 22.53× |
+| SAPHIRA eAPD | 256×320 | 280 | 7,497 | 26.74× |
+| Large science CMOS | 1024×1024 | 31 | 1,453 | 47.21× |
+
+Higher is better; CUDA was synchronized around every timed region and
+construction was excluded. Even the smallest case reaches about 2×, while larger
+arrays and gain-stage detectors expose much more parallel work. Reproduce the
+table with
+
+```bash
+python benchmarks/bench_devices.py --seconds 2 --warmup 10 --device both
+python benchmarks/run.py                    # the CPU hot-path sweep
+```
+
+See the [full snapshot](benchmarks/device-results.md) and the
+**[GPU guide](https://jacotay7.github.io/getframes/guides/gpu/#reference-throughput)**
+for the methodology.
+
+## Features
+
+- **Five detector families** — CCD, CMOS, EMCCD, eAPD and sCMOS, from a library
+  of sourced **[presets](https://jacotay7.github.io/getframes/guides/presets/)**
+  (`andor_ikon_m934`, `andor_ocam2k`, `leonardo_saphira`,
+  `first_light_imaging_cred_one`,
+  `andor_marana_4_2b_11`, `zwo_asi2600mm`, …) or any `CameraConfig` you define.
+- **Auditable noise physics** — dark current vs. temperature, shot noise, a
+  unified stochastic gain stage (EM and avalanche) with realistic excess noise,
+  clock-induced charge, per-pixel sCMOS read noise, polynomial nonlinearity,
+  saturation and quantisation, each a small documented pure function in
+  **[the noise model](https://jacotay7.github.io/getframes/guides/noise-model/)**.
+- **Detector realism** — CTI, blooming, IPC, kTC/reset noise, multi-amplifier
+  readout, cosmic-ray tracks, defect and structured-bias maps, vignetting and
+  radial distortion.
+- **Fixed patterns that behave like silicon** — PRNU, DSNU, hot pixels, defects
+  and amplifier structure are keyed on `fixed_pattern_seed`, so they repeat in
+  every frame and are genuinely removable by a master frame.
+- **Scenes** — point, extended and catalog sources, Gaussian/Moffat/Airy/array
+  PSFs, a `Telescope` with Vega (Johnson) and AB (ugriz, Gaia, 2MASS) bandpasses,
+  extinction, graybody thermal background, WCS pixel↔world, and light curves.
+- **Calibration & ground truth** — master bias/dark/flat builders and a
+  `calibrate` reduction that closes the
+  **[raw → reduced → truth loop](https://jacotay7.github.io/getframes/guides/calibration/)**.
+- **Observations** — `Observation` drives time series with jitter, drift, dither
+  and persistence, carrying per-frame
+  **[truth](https://jacotay7.github.io/getframes/guides/time-series/)**.
+- **Spectral mode** (opt-in) — QE curves, relative or absolute SEDs, transmission
+  products and wavelength-resolved exposure; see
+  **[Spectral mode](https://jacotay7.github.io/getframes/guides/spectral/)** and
+  **[Radiometry & the infrared](https://jacotay7.github.io/getframes/guides/radiometry/)**.
+- **Analysis on real data too** — aperture sums, centroids, photon-transfer
+  curves, independent-stack characterization, and reset-aware nondestructive-ramp
+  analysis run on measured detector frames as readily as on simulated ones.
+- **Scale & datasets** — a float32 fast path, vectorised multi-source rendering,
+  a streaming raw+truth `dataset` generator and a `getframes` CLI; see
+  **[Scale & datasets](https://jacotay7.github.io/getframes/guides/datasets/)**.
+- **GPU-optional** — every camera takes `device="gpu"` (CuPy) and keeps the
+  detector path and truth arrays device-resident. CPU and GPU have independent
+  RNG streams, so a `seed` repeats exactly on a fixed backend while parity across
+  backends means matching statistics, not identical pixels.
+- **Reproducible and typed** — all randomness flows through a camera-owned seeded
+  generator, never global state; `mypy --strict` passes; every public name is
+  frozen under [SemVer](https://jacotay7.github.io/getframes/stability/) as of 2.0.
+- **Validated** — noise models are checked against published forms in CI; see
+  **[Validation](https://jacotay7.github.io/getframes/guides/validation/)**.
+
+See the **[API reference](https://jacotay7.github.io/getframes/reference/)** for
+every public function and class, the
+**[runnable examples](examples/)** for PTC, exposure planning, AO limiting
+magnitude, transit photometry and detector realism, and the
+**[roadmap](https://jacotay7.github.io/getframes/roadmap/)** for what is next.
+
+## Contributing
+
+Contributions — especially new camera presets — are welcome. See
+[CONTRIBUTING.md](CONTRIBUTING.md). Run the checks locally with:
+
+```bash
+ruff check . && ruff format --check . && mypy && pytest
+```
+
+## License
+
+MIT — see [LICENSE](LICENSE).