getframes 2.0.0__py3-none-any.whl

getframes/__about__.py

@@ -0,0 +1,4 @@
+# SPDX-License-Identifier: MIT
+"""Single source of truth for the package version."""
+
+__version__ = "2.0.0"

getframes/__init__.py

@@ -0,0 +1,91 @@
+# SPDX-License-Identifier: MIT
+"""getframes: realistic synthetic camera frames for scientific imaging pipelines.
+
+Quick start
+-----------
+>>> import getframes as gf
+>>> cam = gf.Camera.from_preset("andor_ikon_m934")
+>>> frame = cam.dark_frame(exposure=10.0, temperature=-60.0)
+>>> frame.data.shape
+(1024, 1024)
+"""
+
+from __future__ import annotations
+
+from . import analysis, dataset
+from .__about__ import __version__
+from .calibrate import calibrate, combine
+from .camera import Camera
+from .config import CameraConfig, SensorType
+from .frame import Frame, FrameTruth
+from .observation import Observation, ObservationTruth, Pointing
+from .presets import available_presets, load_preset
+from .scene import (
+    PSF,
+    AiryPSF,
+    ArrayPSF,
+    Bandpass,
+    Catalog,
+    CatalogEntry,
+    EllipticalGaussianPSF,
+    ExtendedSource,
+    Extinction,
+    GaussianPSF,
+    LightCurve,
+    MoffatPSF,
+    PointSource,
+    RadialDistortion,
+    Scene,
+    Sky,
+    Source,
+    Telescope,
+    Thermal,
+    UniformIllumination,
+    Vignetting,
+    WCSInfo,
+)
+from .spectral import QE, SED, SpectralBandpass, Spectrum
+
+__all__ = [
+    "PSF",
+    "QE",
+    "SED",
+    "AiryPSF",
+    "ArrayPSF",
+    "Bandpass",
+    "Camera",
+    "CameraConfig",
+    "Catalog",
+    "CatalogEntry",
+    "EllipticalGaussianPSF",
+    "ExtendedSource",
+    "Extinction",
+    "Frame",
+    "FrameTruth",
+    "GaussianPSF",
+    "LightCurve",
+    "MoffatPSF",
+    "Observation",
+    "ObservationTruth",
+    "PointSource",
+    "Pointing",
+    "RadialDistortion",
+    "Scene",
+    "SensorType",
+    "Sky",
+    "Source",
+    "SpectralBandpass",
+    "Spectrum",
+    "Telescope",
+    "Thermal",
+    "UniformIllumination",
+    "Vignetting",
+    "WCSInfo",
+    "__version__",
+    "analysis",
+    "available_presets",
+    "calibrate",
+    "combine",
+    "dataset",
+    "load_preset",
+]

getframes/analysis/__init__.py

@@ -0,0 +1,18 @@
+# SPDX-License-Identifier: MIT
+"""Lightweight analysis helpers (photometry, centroiding, photon transfer curve).
+
+These exist mainly so the bundled examples stay self-contained; they are pure
+NumPy and make no attempt to replace dedicated tools like ``photutils``.
+"""
+
+from __future__ import annotations
+
+from .apertures import aperture_sum, centroid
+from .ptc import PTCResult, photon_transfer_curve
+
+__all__ = [
+    "PTCResult",
+    "aperture_sum",
+    "centroid",
+    "photon_transfer_curve",
+]

getframes/analysis/apertures.py

@@ -0,0 +1,92 @@
+# SPDX-License-Identifier: MIT
+"""Lightweight photometry helpers used by the examples and for quick analysis.
+
+These are intentionally minimal (pure NumPy, no extra dependencies). For serious
+photometry on real pipelines, reach for ``photutils``; these exist so the bundled
+examples stay self-contained and readable.
+"""
+
+from __future__ import annotations
+
+from typing import Any
+
+import numpy as np
+from numpy.typing import NDArray
+
+
+def _radial_grid(shape: tuple[int, int], cx: float, cy: float) -> NDArray[np.float64]:
+    """Squared distance of every pixel from ``(cx, cy)``."""
+    yy, xx = np.mgrid[0 : shape[0], 0 : shape[1]]
+    grid: NDArray[np.float64] = (xx - cx) ** 2 + (yy - cy) ** 2
+    return grid
+
+
+def aperture_sum(
+    image: NDArray[np.floating[Any] | np.integer[Any]],
+    center: tuple[float, float],
+    r: float,
+    *,
+    annulus: tuple[float, float] | None = None,
+) -> float:
+    """Background-subtracted sum within radius ``r`` of ``center = (x, y)``.
+
+    The background level is the median of a surrounding annulus (default: from
+    ``r + 2`` to ``r + 5`` pixels), scaled to the number of aperture pixels. Pass
+    ``annulus=(inner, outer)`` to control it, or ``annulus=(0, 0)`` to skip
+    background subtraction.
+    """
+    data = np.asarray(image, dtype=np.float64)
+    cx, cy = center
+    dist2 = _radial_grid(data.shape, cx, cy)
+    in_aperture = dist2 <= r**2
+    total = float(data[in_aperture].sum())
+
+    inner, outer = annulus if annulus is not None else (r + 2.0, r + 5.0)
+    if outer > inner:
+        ring = (dist2 > inner**2) & (dist2 <= outer**2)
+        if np.any(ring):
+            background = float(np.median(data[ring]))
+            total -= background * float(in_aperture.sum())
+    return total
+
+
+def centroid(
+    image: NDArray[np.floating[Any] | np.integer[Any]],
+    *,
+    center: tuple[float, float] | None = None,
+    r: float | None = None,
+    background: float | None = None,
+) -> tuple[float, float]:
+    """Intensity-weighted centroid ``(x, y)`` of ``image`` (or a region of it).
+
+    Parameters
+    ----------
+    center, r:
+        If both are given, only pixels within radius ``r`` of ``center`` are used
+        (useful for isolating one spot). Otherwise the whole image is used.
+    background:
+        Level subtracted before weighting, so the pedestal doesn't bias the
+        centroid. Defaults to the image median, which works well for a small spot
+        on a flat background.
+
+    Returns
+    -------
+    (x, y):
+        Sub-pixel centroid. Returns the geometric centre if there is no positive
+        signal after background subtraction.
+    """
+    data = np.asarray(image, dtype=np.float64)
+    bg = float(np.median(data)) if background is None else background
+    weights = np.clip(data - bg, 0.0, None)
+
+    if center is not None and r is not None:
+        mask = _radial_grid(data.shape, *center) <= r**2
+        weights = weights * mask
+
+    total = float(weights.sum())
+    yy, xx = np.mgrid[0 : data.shape[0], 0 : data.shape[1]]
+    if total <= 0:
+        return (data.shape[1] - 1) / 2.0, (data.shape[0] - 1) / 2.0
+    cx = float((weights * xx).sum() / total)
+    cy = float((weights * yy).sum() / total)
+    return cx, cy

getframes/analysis/ptc.py

@@ -0,0 +1,109 @@
+# SPDX-License-Identifier: MIT
+"""Photon transfer curve (PTC): characterise a camera from synthetic flats.
+
+The PTC is the standard way to measure a detector's conversion gain. This module
+generates flat pairs at a range of light levels, builds the variance-vs-mean
+curve, and fits the gain --- turning the workflow in
+``examples/06_photon_transfer_curve.py`` into a one-liner.
+"""
+
+from __future__ import annotations
+
+from dataclasses import dataclass
+from typing import TYPE_CHECKING
+
+import numpy as np
+from numpy.typing import NDArray
+
+if TYPE_CHECKING:
+    from ..camera import Camera
+
+
+@dataclass(frozen=True)
+class PTCResult:
+    """The outcome of :func:`photon_transfer_curve`.
+
+    Attributes
+    ----------
+    mean_adu, variance_adu2:
+        The measured photon transfer curve: per-level mean signal and noise
+        variance, both in ADU.
+    gain_e_per_adu:
+        Conversion gain fitted from the shot-noise-limited region (slope = 1/gain).
+    read_noise_e:
+        Read noise measured from a pair of bias frames.
+    full_well_adu:
+        Mean signal at which the variance peaks (onset of saturation), or ``None``
+        if the curve never rolls over within the sampled levels.
+    """
+
+    mean_adu: NDArray[np.float64]
+    variance_adu2: NDArray[np.float64]
+    gain_e_per_adu: float
+    read_noise_e: float
+    full_well_adu: float | None
+
+
+def photon_transfer_curve(
+    camera: Camera,
+    levels: NDArray[np.float64],
+    exposure: float = 1.0,
+    *,
+    temperature: float | None = None,
+    seed: int = 0,
+) -> PTCResult:
+    """Measure a photon transfer curve for ``camera`` over the given flux ``levels``.
+
+    Parameters
+    ----------
+    camera:
+        The camera to characterise.
+    levels:
+        Incident photon rates (photons/s/pixel) to sample, ascending. Span from a
+        few electrons up past saturation to capture the full curve.
+    exposure:
+        Exposure time for each flat, in seconds.
+    temperature:
+        Sensor temperature; defaults to the camera's operating temperature.
+    seed:
+        Base seed; each flat uses a distinct derived seed for reproducibility.
+    """
+    levels = np.asarray(levels, dtype=np.float64)
+    means = np.empty(levels.size)
+    variances = np.empty(levels.size)
+    for i, flux in enumerate(levels):
+        # Two independent flats; differencing cancels fixed-pattern noise so the
+        # variance reflects shot + read noise only.
+        a = np.asarray(camera.flat_frame(flux, exposure, temperature, seed=seed + 2 * i), float)
+        b = np.asarray(camera.flat_frame(flux, exposure, temperature, seed=seed + 2 * i + 1), float)
+        means[i] = 0.5 * (a.mean() + b.mean())
+        variances[i] = 0.5 * (a - b).var()
+
+    gain = _fit_gain(camera, means, variances)
+
+    # Read noise from two bias frames: var(b1 - b2) = 2 * read_noise^2.
+    b1 = np.asarray(camera.bias_frame(temperature, seed=seed + 99991), float)
+    b2 = np.asarray(camera.bias_frame(temperature, seed=seed + 99992), float)
+    read_noise = float(np.sqrt(0.5 * (b1 - b2).var()) * gain)
+
+    full_well = _full_well(means, variances)
+    return PTCResult(means, variances, gain, read_noise, full_well)
+
+
+def _fit_gain(camera: Camera, means: NDArray[np.float64], variances: NDArray[np.float64]) -> float:
+    """Fit gain from the linear, unsaturated region (slope = 1 / gain)."""
+    lo = camera.config.bias_offset_adu + 50.0
+    hi = 0.7 * camera.config.max_adu
+    mask = (means > lo) & (means < hi)
+    if mask.sum() < 2:
+        mask = np.ones_like(means, dtype=bool)  # fall back to all points
+    slope, _ = np.polyfit(means[mask], variances[mask], 1)
+    return float(1.0 / slope)
+
+
+def _full_well(means: NDArray[np.float64], variances: NDArray[np.float64]) -> float | None:
+    """Mean signal where the variance peaks (saturation onset), if it rolls over."""
+    peak = int(np.argmax(variances))
+    if peak == variances.size - 1:
+        return None  # variance still rising at the last level: no rollover seen
+    return float(means[peak])

getframes/calibrate.py

@@ -0,0 +1,182 @@
+# SPDX-License-Identifier: MIT
+"""Calibration: combine frames into masters and reduce raw frames against them.
+
+These helpers close the loop the library is built for: generate raw frames (each
+optionally carrying :class:`~getframes.frame.FrameTruth`), then *reduce* them with
+master calibration frames and compare the result to the ground truth.
+
+The reduction follows the standard, exposure-matched CCD equation::
+
+    reduced = (raw - dark) / normalised(flat)
+
+where ``dark`` is an exposure-matched master dark (which still contains the bias
+pedestal, so subtracting it removes bias and dark current together) and ``flat`` is
+a pedestal-free master flat (see :meth:`getframes.Camera.master_flat`). Pass
+``bias`` instead of ``dark`` to subtract only the bias pedestal.
+"""
+
+from __future__ import annotations
+
+from collections.abc import Iterable
+from typing import TYPE_CHECKING, Any
+
+import numpy as np
+
+from .frame import Frame
+
+if TYPE_CHECKING:
+    from numpy.typing import NDArray
+
+    FrameLike = Frame | NDArray[np.floating[Any] | np.integer[Any]]
+
+_COMBINE_METHODS = ("mean", "median", "sigma_clip")
+
+
+def _as_array(frame: FrameLike) -> NDArray[np.float64]:
+    return np.asarray(frame, dtype=np.float64)
+
+
+def combine(
+    frames: Iterable[FrameLike],
+    *,
+    method: str = "median",
+    sigma: float = 3.0,
+) -> Frame:
+    """Combine a stack of frames pixel-wise into a single master frame.
+
+    Parameters
+    ----------
+    frames:
+        An iterable of :class:`~getframes.frame.Frame` (or plain 2-D arrays), all
+        the same shape. Averaging ``n`` independent frames reduces the random noise
+        by roughly ``sqrt(n)``.
+    method:
+        ``"median"`` (default, robust to outliers such as cosmic rays), ``"mean"``,
+        or ``"sigma_clip"`` (reject pixels more than ``sigma`` standard deviations
+        from the per-pixel median, then average the rest).
+    sigma:
+        Clipping threshold for ``method="sigma_clip"``.
+
+    Returns
+    -------
+    Frame
+        The master frame (ADU, ``float64``), with metadata recording the
+        combination. Metadata common to all inputs is preserved; ``frame_type`` is
+        prefixed with ``master_`` when the inputs agree.
+    """
+    if method not in _COMBINE_METHODS:
+        raise ValueError(f"method must be one of {_COMBINE_METHODS}, got {method!r}.")
+
+    frame_list = list(frames)
+    if not frame_list:
+        raise ValueError("combine() needs at least one frame.")
+    stack = np.stack([_as_array(f) for f in frame_list], axis=0)
+
+    if method == "mean":
+        data = stack.mean(axis=0)
+    elif method == "median":
+        data = np.median(stack, axis=0)
+    else:  # sigma_clip
+        median = np.median(stack, axis=0)
+        std = stack.std(axis=0)
+        # Keep pixels within sigma*std of the per-pixel median; where std == 0 every
+        # value is identical, so keep them all.
+        keep = (std == 0.0) | (np.abs(stack - median) <= sigma * std)
+        kept = np.where(keep, stack, np.nan)
+        with np.errstate(invalid="ignore"):
+            data = np.nanmean(kept, axis=0)
+        # Pixels with everything clipped (shouldn't happen) fall back to the median.
+        data = np.where(np.isnan(data), median, data)
+
+    metadata = _master_metadata(frame_list, method)
+    return Frame(data=np.asarray(data, dtype=np.float64), metadata=metadata)
+
+
+def _master_metadata(frames: list[FrameLike], method: str) -> dict[str, Any]:
+    """Provenance for a combined frame: shared input metadata plus combine info."""
+    metadata: dict[str, Any] = {}
+    frame_objs = [f for f in frames if isinstance(f, Frame)]
+    if frame_objs:
+        shared = dict(frame_objs[0].metadata)
+        for f in frame_objs[1:]:
+            shared = {k: v for k, v in shared.items() if f.metadata.get(k) == v}
+        metadata.update(shared)
+        # Per-frame keys are meaningless for a master.
+        metadata.pop("frame_index", None)
+        metadata.pop("seed", None)
+        ftype = frame_objs[0].metadata.get("frame_type")
+        if ftype is not None and all(f.metadata.get("frame_type") == ftype for f in frame_objs):
+            metadata["frame_type"] = f"master_{ftype}"
+    metadata["n_combined"] = len(frames)
+    metadata["combine_method"] = method
+    return metadata
+
+
+def calibrate(
+    raw: FrameLike,
+    *,
+    bias: FrameLike | None = None,
+    dark: FrameLike | None = None,
+    flat: FrameLike | None = None,
+    dark_scale: float = 1.0,
+) -> Frame:
+    """Reduce a raw frame with master calibration frames.
+
+    Performs, in order: subtract the additive pedestal (an exposure-matched master
+    ``dark`` if given, else a ``bias``), then divide by the normalised ``flat``::
+
+        out = raw - dark_scale * dark        # or raw - bias if no dark
+        out = out / (flat / mean(flat))
+
+    Parameters
+    ----------
+    raw:
+        The frame to reduce (a :class:`~getframes.frame.Frame` or array, in ADU).
+    bias:
+        Master bias. Subtracted only when ``dark`` is not given (a master dark
+        already contains the bias pedestal).
+    dark:
+        Exposure-matched master dark (including bias). Subtracted from ``raw``.
+    flat:
+        Pedestal-free master flat. Divided out after normalising it to unit mean,
+        so only its relative pixel-to-pixel response remains.
+    dark_scale:
+        Multiplier applied to ``dark`` before subtraction, to scale a master dark
+        to a different exposure (use with a separately subtracted ``bias`` for
+        strict correctness; ``1.0`` for the matched-exposure default).
+
+    Returns
+    -------
+    Frame
+        The reduced frame (``float64``, in ADU), with ``frame_type="reduced"`` and
+        provenance describing the steps applied.
+    """
+    out = _as_array(raw)
+    steps: list[str] = []
+
+    if dark is not None:
+        out = out - dark_scale * _as_array(dark)
+        steps.append("dark")
+    elif bias is not None:
+        out = out - _as_array(bias)
+        steps.append("bias")
+
+    if flat is not None:
+        flat_arr = _as_array(flat)
+        norm = float(flat_arr.mean())
+        if norm == 0.0:
+            raise ValueError("flat has zero mean; cannot normalise.")
+        # Guard against divide-by-zero in dead pixels: leave them unscaled.
+        safe = np.where(flat_arr != 0.0, flat_arr, norm)
+        out = out * (norm / safe)
+        steps.append("flat")
+
+    metadata: dict[str, Any] = {}
+    if isinstance(raw, Frame):
+        metadata.update(raw.metadata)
+    metadata["frame_type"] = "reduced"
+    metadata["calibration"] = steps
+    return Frame(data=out, metadata=metadata)
+
+
+__all__ = ["calibrate", "combine"]