getframes 2.0.0__py3-none-any.whl

getframes/observation.py

@@ -0,0 +1,162 @@
+# SPDX-License-Identifier: MIT
+"""Time as a first-class dimension: pointing models and the :class:`Observation`.
+
+A single :class:`~getframes.frame.Frame` is a snapshot. An :class:`Observation` is
+a *sequence* of frames of one scene over time, produced by
+:meth:`getframes.Camera.observe_series`. It bundles:
+
+* the realised :class:`~getframes.frame.Frame` stack,
+* the per-frame timestamps,
+* the realised per-frame pointing offsets (from a :class:`Pointing` model), and
+* an :class:`ObservationTruth` light curve --- the injected, noise-free signal of
+  each named source at each frame, for validating photometry against ground truth.
+
+Time variability itself lives on the sources (a
+:class:`~getframes.scene.sources.LightCurve` on a
+:class:`~getframes.scene.sources.PointSource`); the observation only samples them.
+"""
+
+from __future__ import annotations
+
+from collections.abc import Iterator, Sequence
+from dataclasses import dataclass, field
+from typing import TYPE_CHECKING
+
+import numpy as np
+
+if TYPE_CHECKING:
+    from numpy.typing import NDArray
+
+    from .frame import Frame
+
+
+@dataclass(frozen=True)
+class Pointing:
+    """A per-frame pointing model: jitter, slow drift, and a programmed dither.
+
+    The three components combine additively into a whole-field offset applied to
+    every source in the scene at each frame. Offsets are specified in arcseconds
+    (converted to pixels with the scene's plate scale) so the model is independent
+    of the detector sampling.
+
+    Parameters
+    ----------
+    jitter_arcsec:
+        RMS of a per-frame Gaussian offset drawn independently for each axis and
+        each frame. Models random tracking jitter and atmospheric tip-tilt / image
+        motion (e.g. for AO sub-apertures). ``0`` disables it.
+    drift_arcsec_per_s:
+        A constant ``(vx, vy)`` velocity giving a slow linear drift; the offset at
+        time ``t`` is ``(vx * t, vy * t)``. Models tracking error / field rotation
+        creep.
+    dither_arcsec:
+        An optional sequence of programmed ``(dx, dy)`` offsets, cycled by frame
+        index (frame ``i`` uses entry ``i % len``). Models a deliberate dither
+        pattern. ``None`` for no dither.
+    """
+
+    jitter_arcsec: float = 0.0
+    drift_arcsec_per_s: tuple[float, float] = (0.0, 0.0)
+    dither_arcsec: Sequence[tuple[float, float]] | None = None
+
+    def __post_init__(self) -> None:
+        if self.jitter_arcsec < 0:
+            raise ValueError("jitter_arcsec must be non-negative.")
+
+    @property
+    def is_static(self) -> bool:
+        """Whether this model never moves the field (a no-op pointing)."""
+        return (
+            self.jitter_arcsec == 0.0
+            and self.drift_arcsec_per_s == (0.0, 0.0)
+            and not self.dither_arcsec
+        )
+
+    def offset_pixels(
+        self,
+        frame_index: int,
+        time_s: float,
+        plate_scale_arcsec_per_pixel: float,
+        rng: np.random.Generator,
+    ) -> tuple[float, float]:
+        """The realised ``(dx, dy)`` offset in pixels for one frame.
+
+        Combines drift (deterministic in ``time_s``), the cycled dither entry, and a
+        fresh Gaussian jitter draw, then converts arcseconds to pixels.
+        """
+        dx_as = self.drift_arcsec_per_s[0] * time_s
+        dy_as = self.drift_arcsec_per_s[1] * time_s
+        if self.dither_arcsec:
+            ddx, ddy = self.dither_arcsec[frame_index % len(self.dither_arcsec)]
+            dx_as += ddx
+            dy_as += ddy
+        if self.jitter_arcsec > 0:
+            dx_as += float(rng.normal(0.0, self.jitter_arcsec))
+            dy_as += float(rng.normal(0.0, self.jitter_arcsec))
+        return dx_as / plate_scale_arcsec_per_pixel, dy_as / plate_scale_arcsec_per_pixel
+
+
+@dataclass(frozen=True)
+class ObservationTruth:
+    """The noise-free ground truth of an :class:`Observation`.
+
+    Attributes
+    ----------
+    times_s:
+        The frame timestamps, in seconds from the start of the observation,
+        shape ``(n_frames,)``.
+    light_curve:
+        Per-source injected signal: a mapping from source name to an array of the
+        noise-free incident photons collected from that source in each frame
+        (photon rate x exposure, post-optics, pre-quantum-efficiency), shape
+        ``(n_frames,)``. This is the true light curve to validate measured
+        photometry against. Unnamed sources are keyed ``"source_{index}"``.
+    """
+
+    times_s: NDArray[np.float64]
+    light_curve: dict[str, NDArray[np.float64]]
+
+
+@dataclass(frozen=True)
+class Observation:
+    """A reproducible stack of frames of one scene over time.
+
+    Returned by :meth:`getframes.Camera.observe_series`. It is iterable and
+    indexable over its :attr:`frames`, so existing ``for frame in obs:`` style code
+    keeps working, while :attr:`truth`, :attr:`times_s`, and :attr:`offsets_pixels`
+    expose the time and pointing information.
+
+    Attributes
+    ----------
+    frames:
+        The realised science :class:`~getframes.frame.Frame` stack, in time order.
+    times_s:
+        Frame timestamps in seconds, shape ``(n_frames,)``.
+    offsets_pixels:
+        The realised pointing offset ``(dx, dy)`` applied to each frame, in pixels,
+        shape ``(n_frames, 2)``.
+    truth:
+        The :class:`ObservationTruth` light curve, or ``None`` when truth was not
+        requested.
+    """
+
+    frames: list[Frame]
+    times_s: NDArray[np.float64]
+    offsets_pixels: NDArray[np.float64]
+    truth: ObservationTruth | None = field(default=None)
+
+    def __iter__(self) -> Iterator[Frame]:
+        return iter(self.frames)
+
+    def __len__(self) -> int:
+        return len(self.frames)
+
+    def __getitem__(self, index: int) -> Frame:
+        return self.frames[index]
+
+    def __repr__(self) -> str:
+        cam = self.frames[0].metadata.get("camera", "?") if self.frames else "?"
+        return f"Observation(n_frames={len(self.frames)}, camera={cam!r})"
+
+
+__all__ = ["Observation", "ObservationTruth", "Pointing"]

getframes/presets/__init__.py

@@ -0,0 +1,90 @@
+# SPDX-License-Identifier: MIT
+"""Built-in library of camera/detector presets.
+
+Presets are stored as TOML files in :mod:`getframes.presets.data`. They are loaded
+lazily and cached. Add a new camera by dropping a ``<name>.toml`` file into that
+directory (see the existing files for the schema) — no code changes required.
+"""
+
+from __future__ import annotations
+
+import sys
+from functools import cache, lru_cache
+from typing import TYPE_CHECKING, Any
+
+if sys.version_info >= (3, 11):
+    import tomllib
+else:  # pragma: no cover - exercised only on 3.10
+    import tomli as tomllib
+
+from importlib import resources
+
+if TYPE_CHECKING:
+    from ..config import CameraConfig
+
+_DATA_PACKAGE = "getframes.presets.data"
+
+
+@lru_cache(maxsize=1)
+def _preset_files() -> dict[str, str]:
+    """Map preset slug -> resource filename for every bundled ``*.toml``."""
+    files: dict[str, str] = {}
+    for entry in resources.files(_DATA_PACKAGE).iterdir():
+        if entry.name.endswith(".toml"):
+            files[entry.name[: -len(".toml")]] = entry.name
+    return dict(sorted(files.items()))
+
+
+def available_presets() -> list[str]:
+    """Return the sorted list of available preset names.
+
+    >>> from getframes import available_presets
+    >>> "andor_ikon_m934" in available_presets()
+    True
+    """
+    return list(_preset_files())
+
+
+def preset_info() -> list[dict[str, Any]]:
+    """Return lightweight descriptors (name, manufacturer, model, sensor_type) for each preset."""
+    info: list[dict[str, Any]] = []
+    for slug in available_presets():
+        data = _read_preset(slug)
+        info.append(
+            {
+                "preset": slug,
+                "name": data.get("name", slug),
+                "manufacturer": data.get("manufacturer"),
+                "model": data.get("model"),
+                "sensor_type": data.get("sensor_type"),
+            }
+        )
+    return info
+
+
+@cache
+def _read_preset(name: str) -> dict[str, Any]:
+    files = _preset_files()
+    if name not in files:
+        available = ", ".join(available_presets()) or "(none found)"
+        raise KeyError(f"Unknown preset {name!r}. Available presets: {available}.")
+    raw = resources.files(_DATA_PACKAGE).joinpath(files[name]).read_bytes()
+    return tomllib.loads(raw.decode("utf-8"))
+
+
+def load_preset(name: str) -> CameraConfig:
+    """Load a preset by name and return a :class:`~getframes.config.CameraConfig`.
+
+    Parameters
+    ----------
+    name:
+        A preset slug, e.g. ``"andor_ikon_m934"``. See :func:`available_presets`.
+    """
+    from ..config import CameraConfig
+
+    data = dict(_read_preset(name))
+    data.setdefault("name", name)
+    return CameraConfig.from_dict(data)
+
+
+__all__ = ["available_presets", "load_preset", "preset_info"]

getframes/presets/data/__init__.py

@@ -0,0 +1,3 @@
+# SPDX-License-Identifier: MIT
+"""Bundled preset data files (TOML). This package exists so the ``*.toml`` files
+are importable via :mod:`importlib.resources`."""

getframes/presets/data/andor_ikon_m934.toml

@@ -0,0 +1,22 @@
+# Andor iKon-M 934 — deep-cooled scientific CCD
+# Values are representative of published specifications; verify against your
+# own characterisation for quantitative work.
+name = "Andor iKon-M 934"
+manufacturer = "Andor"
+model = "iKon-M 934"
+sensor_type = "CCD"
+resolution = [1024, 1024]            # (height, width) in pixels
+pixel_size_um = 13.0
+quantum_efficiency = 0.95            # peak QE (BV coating)
+full_well_e = 130000.0
+bit_depth = 16
+gain_e_per_adu = 2.0
+bias_offset_adu = 500.0
+read_noise_e = 2.9                   # at slow readout
+dark_current_e_per_s = 0.00012       # at the reference temperature below
+dark_current_ref_temp_c = -80.0
+dark_current_doubling_temp_c = 6.3
+dark_current_nonuniformity = 0.03
+hot_pixel_fraction = 0.0002
+hot_pixel_factor = 80.0
+notes = "Deep-cooled (-80 C) back-illuminated CCD for low-light spectroscopy/imaging."

getframes/presets/data/andor_ixon_ultra_888.toml

@@ -0,0 +1,22 @@
+# Andor iXon Ultra 888 — back-illuminated EMCCD
+name = "Andor iXon Ultra 888"
+manufacturer = "Andor"
+model = "iXon Ultra 888"
+sensor_type = "EMCCD"
+resolution = [1024, 1024]
+pixel_size_um = 13.0
+quantum_efficiency = 0.95
+full_well_e = 80000.0
+bit_depth = 16
+gain_e_per_adu = 4.0                  # system gain at the ADC
+bias_offset_adu = 500.0
+read_noise_e = 45.0                   # large at the output amplifier; EM gain overcomes it
+dark_current_e_per_s = 0.00025
+dark_current_ref_temp_c = -80.0
+dark_current_doubling_temp_c = 6.3
+em_gain = 300.0
+clock_induced_charge_e = 0.005        # spurious charge per pixel per frame
+dark_current_nonuniformity = 0.04
+hot_pixel_fraction = 0.0003
+hot_pixel_factor = 60.0
+notes = "EMCCD for single-photon-sensitive imaging; effective read noise <1 e- at high EM gain."

getframes/presets/data/generic_ccd.toml

@@ -0,0 +1,18 @@
+# A plain, well-behaved CCD for testing and teaching.
+name = "Generic CCD"
+sensor_type = "CCD"
+resolution = [512, 512]
+pixel_size_um = 15.0
+quantum_efficiency = 0.85
+full_well_e = 100000.0
+bit_depth = 16
+gain_e_per_adu = 1.5
+bias_offset_adu = 400.0
+read_noise_e = 5.0
+dark_current_e_per_s = 0.1
+dark_current_ref_temp_c = 20.0
+dark_current_doubling_temp_c = 6.3
+dark_current_nonuniformity = 0.05
+hot_pixel_fraction = 0.001
+hot_pixel_factor = 100.0
+notes = "Idealised CCD with typical parameters; good default for examples."

getframes/presets/data/generic_cmos.toml

@@ -0,0 +1,18 @@
+# A plain, well-behaved CMOS for testing and teaching.
+name = "Generic CMOS"
+sensor_type = "CMOS"
+resolution = [1080, 1920]
+pixel_size_um = 5.0
+quantum_efficiency = 0.80
+full_well_e = 15000.0
+bit_depth = 12
+gain_e_per_adu = 1.0
+bias_offset_adu = 200.0
+read_noise_e = 2.0
+dark_current_e_per_s = 2.0
+dark_current_ref_temp_c = 20.0
+dark_current_doubling_temp_c = 6.0
+dark_current_nonuniformity = 0.04
+hot_pixel_fraction = 0.002
+hot_pixel_factor = 150.0
+notes = "Idealised uncooled CMOS; higher dark current and lower full well than the CCD."

getframes/presets/data/generic_eapd.toml

@@ -0,0 +1,20 @@
+# A plain electron-avalanche photodiode (eAPD) array for testing and teaching.
+name = "Generic eAPD"
+sensor_type = "EAPD"
+resolution = [256, 256]
+pixel_size_um = 18.0
+quantum_efficiency = 0.85
+full_well_e = 80000.0
+bit_depth = 16
+gain_e_per_adu = 2.0
+bias_offset_adu = 800.0
+read_noise_e = 40.0                  # amplifier read noise before avalanche gain
+em_gain = 20.0                       # avalanche gain
+excess_noise_factor = 1.25
+dark_current_e_per_s = 2.0
+dark_current_ref_temp_c = -190.0
+dark_current_doubling_temp_c = 8.0
+dark_current_nonuniformity = 0.04
+hot_pixel_fraction = 0.0005
+hot_pixel_factor = 50.0
+notes = "Idealised eAPD for demonstrating avalanche gain with a low excess noise factor."

getframes/presets/data/generic_emccd.toml

@@ -0,0 +1,20 @@
+# A plain EMCCD for testing and teaching.
+name = "Generic EMCCD"
+sensor_type = "EMCCD"
+resolution = [512, 512]
+pixel_size_um = 16.0
+quantum_efficiency = 0.90
+full_well_e = 100000.0
+bit_depth = 16
+gain_e_per_adu = 5.0
+bias_offset_adu = 500.0
+read_noise_e = 50.0
+dark_current_e_per_s = 0.001
+dark_current_ref_temp_c = -70.0
+dark_current_doubling_temp_c = 6.3
+em_gain = 200.0
+clock_induced_charge_e = 0.01
+dark_current_nonuniformity = 0.05
+hot_pixel_fraction = 0.001
+hot_pixel_factor = 80.0
+notes = "Idealised EMCCD for demonstrating EM gain and clock-induced charge."

getframes/presets/data/generic_scmos.toml

@@ -0,0 +1,21 @@
+# A plain scientific CMOS (sCMOS) for testing and teaching.
+name = "Generic sCMOS"
+sensor_type = "SCMOS"
+resolution = [2048, 2048]
+pixel_size_um = 6.5
+quantum_efficiency = 0.82
+full_well_e = 30000.0
+bit_depth = 16
+gain_e_per_adu = 0.5
+bias_offset_adu = 100.0
+read_noise_e = 1.6                    # median read noise
+read_noise_nonuniformity = 0.3        # per-pixel spread
+dark_current_e_per_s = 0.5
+dark_current_ref_temp_c = -10.0
+dark_current_doubling_temp_c = 6.0
+prnu = 0.01
+nonlinearity = 0.01
+dark_current_nonuniformity = 0.03
+hot_pixel_fraction = 0.001
+hot_pixel_factor = 130.0
+notes = "Idealised sCMOS demonstrating per-pixel read noise and mild nonlinearity."

getframes/presets/data/hamamatsu_orca_fusion.toml

@@ -0,0 +1,25 @@
+# Hamamatsu ORCA-Fusion BT — back-thinned scientific CMOS (sCMOS).
+# Representative parameters; sCMOS read noise varies pixel-to-pixel, captured here
+# by read_noise_nonuniformity rather than a single RMS.
+name = "Hamamatsu ORCA-Fusion BT"
+manufacturer = "Hamamatsu"
+model = "ORCA-Fusion BT (C15440)"
+sensor_type = "SCMOS"
+resolution = [2304, 2304]
+pixel_size_um = 6.5
+quantum_efficiency = 0.95
+full_well_e = 18000.0
+bit_depth = 16
+gain_e_per_adu = 0.3
+bias_offset_adu = 100.0
+read_noise_e = 1.4                    # median; see spread below
+read_noise_nonuniformity = 0.35       # per-pixel read-noise spread (sCMOS)
+dark_current_e_per_s = 0.2
+dark_current_ref_temp_c = -10.0
+dark_current_doubling_temp_c = 6.0
+prnu = 0.01
+nonlinearity = 0.01
+dark_current_nonuniformity = 0.02
+hot_pixel_fraction = 0.0005
+hot_pixel_factor = 120.0
+notes = "Back-thinned sCMOS; very high QE and low median read noise with a per-pixel spread."

getframes/presets/data/leonardo_saphira.toml

@@ -0,0 +1,32 @@
+# Leonardo SAPHIRA — HgCdTe electron-avalanche photodiode (eAPD) IR array.
+# Widely used as an adaptive-optics wavefront-sensor and fringe-tracker detector.
+# Values are representative; the avalanche gain is user-tunable via the bias.
+name = "Leonardo SAPHIRA"
+manufacturer = "Leonardo"
+model = "SAPHIRA (Mark 13/14)"
+sensor_type = "EAPD"
+resolution = [256, 320]              # (height, width)
+pixel_size_um = 24.0
+quantum_efficiency = 0.90            # HgCdTe, broad near-IR response
+full_well_e = 100000.0
+bit_depth = 16
+gain_e_per_adu = 2.5                 # system gain at the ADC
+bias_offset_adu = 1000.0
+read_noise_e = 45.0                  # CDS read noise at the amplifier (pre-avalanche)
+em_gain = 50.0                       # avalanche gain M; effective read noise ~ 45/M ~ 1 e-
+excess_noise_factor = 1.3            # eAPDs are far quieter than EMCCDs (sqrt(2))
+dark_current_e_per_s = 5.0           # incl. dark-current avalanche / glow, cooled (~80 K)
+dark_current_ref_temp_c = -193.0
+dark_current_doubling_temp_c = 8.0
+clock_induced_charge_e = 0.0
+dark_current_nonuniformity = 0.05
+hot_pixel_fraction = 0.0005
+hot_pixel_factor = 50.0
+notes = "Sub-electron effective read noise at high avalanche gain; near-unity excess noise."
+
+# Wavelength-resolved quantum efficiency (HgCdTe, ~2.5 um cutoff). Optional; only
+# used in spectral mode (Camera.observe with a band that has a spectral response).
+# Representative shape --- supply a measured curve for quantitative IR work.
+[qe_curve]
+wavelength_nm = [800.0, 1000.0, 1500.0, 2000.0, 2400.0, 2500.0]
+qe = [0.45, 0.85, 0.90, 0.90, 0.80, 0.30]

getframes/presets/data/zwo_asi2600mm.toml

@@ -0,0 +1,20 @@
+# ZWO ASI2600MM Pro — Sony IMX571 back-illuminated CMOS
+name = "ZWO ASI2600MM Pro"
+manufacturer = "ZWO"
+model = "ASI2600MM Pro (IMX571)"
+sensor_type = "CMOS"
+resolution = [4176, 6248]
+pixel_size_um = 3.76
+quantum_efficiency = 0.91
+full_well_e = 50000.0
+bit_depth = 16
+gain_e_per_adu = 0.25                 # unity-gain regime; low-noise mode
+bias_offset_adu = 500.0
+read_noise_e = 1.5                    # at high conversion gain
+dark_current_e_per_s = 0.0022
+dark_current_ref_temp_c = -10.0
+dark_current_doubling_temp_c = 6.0
+dark_current_nonuniformity = 0.02
+hot_pixel_fraction = 0.0005
+hot_pixel_factor = 120.0
+notes = "Popular cooled astrophotography/scientific CMOS; very low read noise."

getframes/scene/__init__.py

@@ -0,0 +1,51 @@
+# SPDX-License-Identifier: MIT
+"""The scene/optics layer: turn astrophysical inputs into a photon-rate map.
+
+Build a :class:`Scene` from sources, a :class:`PSF`, and a :class:`Telescope`,
+then either call :meth:`Scene.photon_rate_map` yourself or hand the scene to
+:meth:`getframes.Camera.observe` to get a realistic frame.
+"""
+
+from __future__ import annotations
+
+from .optics import RadialDistortion, Telescope, Vignetting
+from .photometry import Bandpass, Extinction
+from .psf import PSF, AiryPSF, ArrayPSF, EllipticalGaussianPSF, GaussianPSF, MoffatPSF
+from .scene import Scene
+from .sources import (
+    Catalog,
+    CatalogEntry,
+    ExtendedSource,
+    LightCurve,
+    PointSource,
+    Sky,
+    Source,
+    UniformIllumination,
+)
+from .thermal import Thermal
+from .wcs import WCSInfo
+
+__all__ = [
+    "PSF",
+    "AiryPSF",
+    "ArrayPSF",
+    "Bandpass",
+    "Catalog",
+    "CatalogEntry",
+    "EllipticalGaussianPSF",
+    "ExtendedSource",
+    "Extinction",
+    "GaussianPSF",
+    "LightCurve",
+    "MoffatPSF",
+    "PointSource",
+    "RadialDistortion",
+    "Scene",
+    "Sky",
+    "Source",
+    "Telescope",
+    "Thermal",
+    "UniformIllumination",
+    "Vignetting",
+    "WCSInfo",
+]