getframes 2.0.0__tar.gz

getframes-2.0.0/.gitignore

@@ -0,0 +1,224 @@
+# Byte-compiled / optimized / DLL files
+__pycache__/
+*.py[codz]
+*$py.class
+
+# C extensions
+*.so
+
+# Distribution / packaging
+.Python
+build/
+develop-eggs/
+dist/
+downloads/
+eggs/
+.eggs/
+lib/
+lib64/
+parts/
+sdist/
+var/
+wheels/
+share/python-wheels/
+*.egg-info/
+.installed.cfg
+*.egg
+MANIFEST
+
+# PyInstaller
+#   Usually these files are written by a python script from a template
+#   before PyInstaller builds the exe, so as to inject date/other infos into it.
+*.manifest
+*.spec
+
+# Installer logs
+pip-log.txt
+pip-delete-this-directory.txt
+
+# Unit test / coverage reports
+htmlcov/
+.tox/
+.nox/
+.coverage
+.coverage.*
+.cache
+nosetests.xml
+coverage.xml
+*.cover
+*.py.cover
+.hypothesis/
+.pytest_cache/
+cover/
+
+# Translations
+*.mo
+*.pot
+
+# Django stuff:
+*.log
+local_settings.py
+db.sqlite3
+db.sqlite3-journal
+
+# Flask stuff:
+instance/
+.webassets-cache
+
+# Scrapy stuff:
+.scrapy
+
+# Sphinx documentation
+docs/_build/
+
+# PyBuilder
+.pybuilder/
+target/
+
+# Jupyter Notebook
+.ipynb_checkpoints
+
+# IPython
+profile_default/
+ipython_config.py
+
+# pyenv
+#   For a library or package, you might want to ignore these files since the code is
+#   intended to run in multiple environments; otherwise, check them in:
+# .python-version
+
+# pipenv
+#   According to pypa/pipenv#598, it is recommended to include Pipfile.lock in version control.
+#   However, in case of collaboration, if having platform-specific dependencies or dependencies
+#   having no cross-platform support, pipenv may install dependencies that don't work, or not
+#   install all needed dependencies.
+# Pipfile.lock
+
+# UV
+#   Similar to Pipfile.lock, it is generally recommended to include uv.lock in version control.
+#   This is especially recommended for binary packages to ensure reproducibility, and is more
+#   commonly ignored for libraries.
+# uv.lock
+
+# poetry
+#   Similar to Pipfile.lock, it is generally recommended to include poetry.lock in version control.
+#   This is especially recommended for binary packages to ensure reproducibility, and is more
+#   commonly ignored for libraries.
+#   https://python-poetry.org/docs/basic-usage/#commit-your-poetrylock-file-to-version-control
+# poetry.lock
+# poetry.toml
+
+# pdm
+#   Similar to Pipfile.lock, it is generally recommended to include pdm.lock in version control.
+#   pdm recommends including project-wide configuration in pdm.toml, but excluding .pdm-python.
+#   https://pdm-project.org/en/latest/usage/project/#working-with-version-control
+# pdm.lock
+# pdm.toml
+.pdm-python
+.pdm-build/
+
+# pixi
+#   Similar to Pipfile.lock, it is generally recommended to include pixi.lock in version control.
+# pixi.lock
+#   Pixi creates a virtual environment in the .pixi directory, just like venv module creates one
+#   in the .venv directory. It is recommended not to include this directory in version control.
+.pixi
+
+# PEP 582; used by e.g. github.com/David-OConnor/pyflow and github.com/pdm-project/pdm
+__pypackages__/
+
+# Celery stuff
+celerybeat-schedule
+celerybeat.pid
+
+# Redis
+*.rdb
+*.aof
+*.pid
+
+# RabbitMQ
+mnesia/
+rabbitmq/
+rabbitmq-data/
+
+# ActiveMQ
+activemq-data/
+
+# SageMath parsed files
+*.sage.py
+
+# Environments
+.env
+.envrc
+.venv
+env/
+venv/
+ENV/
+env.bak/
+venv.bak/
+
+# Spyder project settings
+.spyderproject
+.spyproject
+
+# Rope project settings
+.ropeproject
+
+# mkdocs documentation
+/site
+
+# mypy
+.mypy_cache/
+.dmypy.json
+dmypy.json
+
+# Pyre type checker
+.pyre/
+
+# pytype static type analyzer
+.pytype/
+
+# Cython debug symbols
+cython_debug/
+
+# PyCharm
+#   JetBrains specific template is maintained in a separate JetBrains.gitignore that can
+#   be found at https://github.com/github/gitignore/blob/main/Global/JetBrains.gitignore
+#   and can be added to the global gitignore or merged into this file.  For a more nuclear
+#   option (not recommended) you can uncomment the following to ignore the entire idea folder.
+# .idea/
+
+# Abstra
+#   Abstra is an AI-powered process automation framework.
+#   Ignore directories containing user credentials, local state, and settings.
+#   Learn more at https://abstra.io/docs
+.abstra/
+
+# Visual Studio Code
+#   Visual Studio Code specific template is maintained in a separate VisualStudioCode.gitignore 
+#   that can be found at https://github.com/github/gitignore/blob/main/Global/VisualStudioCode.gitignore
+#   and can be added to the global gitignore or merged into this file. However, if you prefer, 
+#   you could uncomment the following to ignore the entire vscode folder
+# .vscode/
+# Temporary file for partial code execution
+tempCodeRunnerFile.py
+
+# Ruff stuff:
+.ruff_cache/
+
+# macOS
+.DS_Store
+
+# Generated frames
+*.fits
+
+# PyPI configuration file
+.pypirc
+
+# Marimo
+marimo/_static/
+marimo/_lsp/
+__marimo__/
+
+# Streamlit
+.streamlit/secrets.toml

getframes-2.0.0/CHANGELOG.md

@@ -0,0 +1,253 @@
+# Changelog
+
+All notable changes to this project are documented here. The format is based on
+[Keep a Changelog](https://keepachangelog.com/en/1.1.0/), and this project adheres
+to [Semantic Versioning](https://semver.org/spec/v2.0.0.html).
+
+## [Unreleased]
+
+## [2.0.0] - 2026-06-29
+
+The 2.0 cut promotes the full surface grown across 1.1–1.6 to **stable** and lands
+the one planned dependency change. There are **no breaking API removals**: code
+written against 1.x continues to work.
+
+### Changed
+
+- **`astropy` is now a core dependency** (roadmap decision #2). It powers FITS I/O,
+  WCS pixel↔world projection, and catalogs; it is still imported lazily inside the
+  functions that use it so `import getframes` stays fast. `matplotlib` remains the
+  only `examples` extra.
+- **API stability**: the detector, scene, calibration, observation, radiometry, and
+  dataset APIs are now frozen under SemVer for the 2.x series (see
+  `docs/stability.md`).
+
+### Added
+
+- A **validation suite** (`tests/test_validation.py`) and a
+  [validation guide](docs/guides/validation.md) asserting the physics against
+  analytic / 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.
+- Three worked **examples** for the newer features: `11_radiometry_and_ir.py`,
+  `12_ml_dataset.py`, and `13_crowded_field.py`.
+
+### Added (1.x features, first released in 2.0)
+
+- **Scale & datasets** (roadmap phase 1.6): generate large detectors and bulk
+  raw+truth training data, all additive.
+  - **float32 fast path**: `Camera(..., precision="float32")` runs the whole signal
+    chain (and each frame's ground truth) in single precision, halving the per-pixel
+    memory for large detectors and bulk generation. The digitised ADU stay integer;
+    `noise.simulate_frame` and `Scene.photon_rate_map` gain a `float_dtype`/`dtype`
+    argument (`float64` exact default).
+  - **Vectorised multi-source rendering**: `GaussianPSF.add_sources` deposits a whole
+    catalog in one batched, memory-chunked NumPy expression (exact match to the
+    per-source path), so a 10⁵-star `Catalog` no longer loops in Python. The base
+    `PSF.add_sources` falls back to a loop for other PSFs.
+  - **Dataset generator** (`getframes.dataset`): `pairs(camera=, scenes=, exposure=)`
+    streams `{"raw": ADU, "truth": e-}` pairs reproducibly to disk via
+    `PairDataset.to_npz` (or `to_arrays`), and `random_star_fields(n, shape, ...)` is
+    a re-iterable source of random star-field scenes to feed it.
+  - **`getframes` CLI**: a console entry point with `presets`, `generate config.toml
+    -o frame.fits`, and `dataset config.toml -o train/` subcommands, so an experiment
+    is a shareable TOML file (`getframes.cli`).
+  - **Benchmarks**: `benchmarks/run.py`, a dependency-light throughput harness for the
+    signal chain, catalog rendering, and dataset generation (not part of the gate).
+- **Radiometry & the infrared** (roadmap phase 1.5): quantitative photometry and
+  honest IR backgrounds, all additive.
+  - **AB system**: `Bandpass.ab(band)` alongside the Vega-system `Bandpass.johnson`,
+    with the zero point computed from the band's transmission shape (3631 Jy
+    reference). Ships **SDSS ugriz**, **Gaia** (`gaia_g`/`gaia_bp`/`gaia_rp`), and
+    **2MASS** (`J`/`H`/`Ks`) bands as tophat responses.
+  - **Real transmission products**: `SpectralBandpass.from_file` /
+    `Spectrum.from_file` / `QE.from_file` load measured curves; `product(...)` and
+    `SpectralBandpass.from_product(...)` fold filter x QE x atmosphere into one
+    response.
+  - **Extinction**: `Extinction(a_v, r_v)` applies a Cardelli–Clayton–Mathis (1989)
+    interstellar extinction curve — `transmission`, `redden(sed)`,
+    `band_attenuation_mag(band)`.
+  - **Spectral flux integration**: `SED.from_flux_density(...)` builds an *absolute*
+    SED (photons/s/m²/nm). Sources gain a `flux_sed` brightness option (alongside
+    `magnitude`/`photon_rate`) whose integral over the band sets the rate, via
+    `Telescope.photon_rate_from_sed` / `Bandpass.photon_flux_from_sed`.
+  - **Thermal background & glow**: `Thermal(temperature_k, emissivity)` is a graybody
+    background (the IR analogue of `Sky`) attached to a `Scene`;
+    `CameraConfig.detector_glow_e_per_s` adds exposure-scaled, dark-removable
+    detector self-emission.
+  - **astropy.units interop**: the spectral constructors accept `astropy.units`
+    quantities for wavelength/flux (optional; plain arrays assumed to be nm).
+- **Detector depth** (roadmap phase 1.4): the artifacts a real calibration
+  pipeline must survive, all off by default and additive on `CameraConfig`.
+  - **CTI**: `cti` smears charge by a CCD's charge-transfer inefficiency, deferring
+    a `cti * n_transfers` fraction into a trailing tail away from the readout
+    register (`noise.apply_cti`).
+  - **Blooming**: `blooming=True` bleeds charge above `full_well_e` symmetrically
+    along the column, charge-conserving (`noise.apply_blooming`).
+  - **IPC**: `ipc_coupling` applies a charge-conserving 3x3 inter-pixel-capacitance
+    kernel (`noise.apply_ipc`).
+  - **kTC/reset noise**: `reset_noise_e` adds a per-pixel, per-frame Gaussian charge
+    uncertainty alongside read noise.
+  - **Multi-amplifier readout**: `amplifier_layout=(n_rows, n_cols)` tiles the
+    sensor into amplifier blocks, each with its own fixed gain
+    (`amp_gain_nonuniformity`) and offset (`amp_offset_spread_adu`) error —
+    producing quadrant seams.
+  - **Cosmic-ray tracks**: `cosmic_ray_track_length_px` upgrades cosmic rays from
+    single pixels to extended tracks (exponential length, random direction).
+  - **Defects & structured bias**: `bad_column_fraction` / `dead_pixel_fraction`
+    impose a fixed map of dead columns/pixels that collect no charge;
+    `bias_structure_amplitude_adu` adds a fixed gradient-plus-column bias pattern on
+    top of the flat pedestal.
+  - **Polynomial nonlinearity**: `nonlinearity_coeffs=(c1, c2, ...)` generalises the
+    single-parameter `nonlinearity` to an arbitrary measured response curve.
+- **Richer scenes** (roadmap phase 1.3): build crowded, structured fields beyond
+  point sources on a flat sky.
+  - `ExtendedSource` for resolved sources: `ExtendedSource.sersic(...)` (a Sersic
+    surface-brightness profile, optionally elliptical with a position angle) and
+    `ExtendedSource.from_array(image, ...)` (an arbitrary normalised cutout).
+  - `UniformIllumination`: a spatially flat, PSF-free illumination — a clean flat
+    field for photon-transfer-curve work.
+  - `Catalog.from_table(table, ...)` places many sources at once from any
+    column-indexable table (astropy `Table`, pandas, or a dict). Entries may be
+    given by pixel `(x, y)` or sky `(ra, dec)`; with a scene `WCSInfo`, RA/Dec is
+    projected to pixels (the WCS now *does* something, not just tags).
+  - New PSFs: `AiryPSF` (diffraction-limited, with optional central obstruction),
+    `ArrayPSF` (a user kernel, e.g. from an AO simulation, with sub-pixel shifting),
+    and `EllipticalGaussianPSF` (independent major/minor widths and a position
+    angle).
+  - `Telescope` gains optional `vignetting` (`Vignetting` illumination falloff) and
+    `distortion` (`RadialDistortion` barrel/pincushion) models.
+  - `Scene.add(*sources)` appends sources; `Scene.sources` now accepts any
+    `Source` (point, extended, catalog, or uniform).
+- **Time as a first-class dimension** (roadmap phase 1.2): observe a scene over
+  time and validate the result against a ground-truth light curve.
+  - `getframes.Observation` (and `ObservationTruth`): the iterable stack returned
+    by `Camera.observe_series`, carrying the frames, per-frame timestamps, realised
+    pointing offsets, and the per-source truth `light_curve`.
+  - `LightCurve` (owned by the source): `PointSource` gains optional `brightness`
+    (a `LightCurve`) and `name` fields. `LightCurve.box` / `sinusoidal` /
+    `constant` / `from_function` make a source vary in time; `observe_series`
+    samples it at each frame's timestamp.
+  - `Pointing`: per-frame field offsets from jitter (Gaussian, also models
+    atmospheric tip-tilt / image motion), slow linear drift, and a programmed
+    dither pattern. `Camera.observe_series(..., jitter_arcsec=...)` is a shortcut.
+  - **Persistence / latent images** (the deferred 1.0 item): new
+    `CameraConfig.persistence_fraction` and `persistence_decay` carry trapped
+    charge across the frames of an `Observation` (IR arrays). `Camera.expose` and
+    `noise.simulate_frame` gain an `extra_electrons` argument that injects this
+    latent charge before shot noise.
+  - `Scene.photon_rate_map` / `photoelectron_rate_map` gain optional `time_s` and
+    `offset_xy` arguments (backwards-compatible no-ops by default).
+- **Calibration loop** (`getframes.calibrate` module, roadmap phase 1.1): combine
+  frames into masters and reduce raw frames against them.
+  - `combine(frames, method=...)` stacks frames into a master (`"mean"`,
+    `"median"`, or `"sigma_clip"`), reducing random noise by ~`sqrt(n)`.
+  - `calibrate(raw, *, bias, dark, flat, dark_scale)` performs standard
+    exposure-matched reduction `(raw - dark) / normalised(flat)`, so a reduced
+    frame can be compared directly against `Frame.truth`.
+  - `Camera.master_bias`, `Camera.master_dark`, and `Camera.master_flat`
+    (with optional `bias=` subtraction) build calibration masters from a series.
+- **Series symmetry**: `Camera.expose_series` and `Camera.observe_series` mirror
+  `dark_series` (independent-but-reproducible derived seeds; per-frame metadata).
+- `CameraConfig.fixed_pattern_seed`: seeds the sensor's fixed-pattern noise.
+
+### Changed
+
+- `Camera.observe_series` now returns an `Observation` rather than a lazy
+  iterator. The `Observation` is iterable and indexable over its frames, so
+  `for frame in cam.observe_series(...)` and `list(cam.observe_series(...))` keep
+  working; the new `cadence`, `pointing`, and `jitter_arcsec` keyword arguments
+  are additive.
+- **Fixed-pattern noise is now genuinely fixed.** PRNU, DSNU, and the hot-pixel
+  map are drawn from a deterministic per-sensor stream (keyed on
+  `CameraConfig.fixed_pattern_seed`) instead of the per-frame RNG, so the pattern
+  repeats across every frame a camera produces — which is what lets a master flat
+  or dark actually remove it. This changes the exact per-pixel output (for a given
+  `seed`) of any config with `prnu`, `dark_current_nonuniformity`, or hot pixels;
+  statistical behaviour is unchanged. `noise.dark_signal_map` and
+  `noise.photo_signal_map` no longer take an `rng` argument.
+
+## [1.0.0] - 2026-06-28
+
+First stable release. The public API is now frozen under
+[Semantic Versioning](https://semver.org/spec/v2.0.0.html): the names exported
+from `import getframes` (and `getframes.analysis`) will not change incompatibly
+without a major-version bump. See [API stability](docs/stability.md).
+
+This release consolidates the work from the 0.2–0.6 development series — the
+photon/signal path, the unified gain stage, the scene/optics layer, analysis
+helpers, detector-realism effects, and opt-in spectral mode — into a supported,
+documented surface. Everything below was developed across those phases and ships
+together in 1.0.
+
+### Added
+
+- **Spectral mode** (opt-in, additive): a new `getframes.spectral` module with
+  `Spectrum`, `SED` (flat/blackbody/power-law shapes), `QE` (wavelength-resolved
+  quantum efficiency), and `SpectralBandpass` (tophat / Johnson responses).
+  `Bandpass.johnson` now ships a spectral `response` by default and gains
+  `Bandpass.effective_qe`. Setting `CameraConfig.qe_curve` makes `Camera.observe`
+  switch to a colour-dependent **effective QE**, folding each source's SED with the
+  band response and the detector QE curve; the magnitude-to-photon-rate conversion
+  is unchanged (the SED shape only affects the photon-to-electron step). Presets
+  may carry a `[qe_curve]` table (added to `leonardo_saphira`).
+- **WCS tagging** via `WCSInfo` (TAN projection): emits FITS WCS header cards with
+  no third-party dependency (written into the observed `Frame` metadata and FITS
+  output) and offers astropy-backed `pixel_to_world` / `world_to_pixel`. A `Scene`
+  may carry an optional `wcs`.
+- `PointSource.sed` and `Sky.sed` optional spectral energy distributions; an
+  optional `quantum_efficiency` override on `Camera.expose` / `noise.simulate_frame`.
+- **Detector-realism effects**, all off by default: nonlinearity (`nonlinearity`),
+  cosmic rays (`cosmic_ray_rate_per_cm2_s`), and per-pixel sCMOS read noise
+  (`read_noise_nonuniformity`). New `SensorType.SCMOS` and presets
+  `hamamatsu_orca_fusion` and `generic_scmos`.
+- **Analysis helpers** (`getframes.analysis`): `aperture_sum`, `centroid`, and a
+  `photon_transfer_curve` that fits gain and read noise. Pure NumPy; used by the
+  examples and handy for quick checks.
+- **Scene/optics layer** (`getframes.scene`) and `Camera.observe(scene, ...)`:
+  render astronomical sources through a PSF and telescope into an incident
+  photon-rate map, then expose it. New public types: `Scene`, `Telescope`,
+  `Bandpass` (Johnson UBVRI zero points), `PointSource`, `Sky`, and the PSFs
+  `GaussianPSF` (exact, flux-conserving) and `MoffatPSF`.
+- **Unified stochastic gain stage** (`noise.apply_gain_stage`): one model for both
+  EMCCD electron multiplication and eAPD avalanche gain, parameterised by mean gain
+  and excess noise factor `F` via a Gamma model (`alpha = 1/(F^2-1)`). Reproduces
+  the requested `F` exactly; recovers the previous EMCCD model at `F = sqrt(2)`.
+- `SensorType.EAPD` and `CameraConfig.excess_noise_factor` /
+  `gain_excess_noise_factor` / `has_gain_stage`.
+- eAPD presets: `leonardo_saphira` (SAPHIRA IR array) and `generic_eapd`.
+- **Photon/signal path** (`Camera.expose`): generate frames from an incident
+  photon rate (scalar or per-pixel map), with quantum-efficiency conversion,
+  photo-response non-uniformity (PRNU), shot noise, dark current, optional EM
+  gain, read noise, and digitisation.
+- `Camera.flat_frame` and `Camera.bias_frame` convenience wrappers.
+- `FrameTruth`: noise-free ground truth (mean electron maps) attached to frames
+  for pipeline validation; available on `Frame.truth`.
+- `noise.simulate_frame` / `noise.photo_signal_map` / `noise.frame_electrons`
+  building blocks. `noise.generate_dark_frame` is now the `photon_rate = 0` case.
+- `CameraConfig.prnu` field.
+
+### Changed
+
+- `scipy` is now a core dependency (groundwork for the scene/optics layer).
+
+## [0.1.0] - 2026-06-27
+
+### Added
+
+- Initial release.
+- `Camera`, `CameraConfig`, `Frame`, and `SensorType` public API.
+- Dark-frame generation for CCD, CMOS, and EMCCD sensors with read noise, dark
+  current (temperature-scaled), shot noise, fixed-pattern non-uniformity (DSNU),
+  hot pixels, EM gain, and clock-induced charge.
+- `Camera.dark_series` for generating reproducible frame stacks.
+- Preset library with `load_preset`, `available_presets`, and `preset_info`,
+  including Andor iKon-M 934, Andor iXon Ultra 888, ZWO ASI2600MM, and generic
+  CCD/CMOS/EMCCD references.
+- Optional FITS export via `Frame.to_fits`.
+- Documentation, runnable examples, and CI (lint, type-check, test matrix, PyPI
+  release via Trusted Publishing).
+
+[Unreleased]: https://github.com/jacotay7/getframes/compare/v1.0.0...HEAD
+[1.0.0]: https://github.com/jacotay7/getframes/compare/v0.1.0...v1.0.0
+[0.1.0]: https://github.com/jacotay7/getframes/releases/tag/v0.1.0

getframes-2.0.0/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Jacob Taylor
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.