getframes 2.2.0__tar.gz → 2.3.0__tar.gz

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

@@ -6,6 +6,40 @@ to [Semantic Versioning](https://semver.org/spec/v2.0.0.html).
 
 ## [Unreleased]
 
+## [2.3.0] - 2026-10-07
+
+### Fixed
+
+- **`MoffatPSF`, `EllipticalGaussianPSF` and `AiryPSF` no longer put light that
+  falls off the frame back onto it.** They normalised their stamp *after*
+  clipping it to the frame, so a source on the edge column deposited its full
+  flux instead of the part that lands on the detector (a Moffat star centred on
+  column 0 kept 100% of its light, where `GaussianPSF` correctly keeps about
+  half). The stamp is now normalised before clipping, which follows the AO stack
+  convention that light lost at a detector edge is lost, not renormalised
+  (aocore CONVENTIONS 3.3). Sources wholly inside the frame are unchanged.
+
+### Changed
+
+- **Generic primitives now come from `aocore`.** getframes is part of an
+  adaptive-optics stack whose shared conventions and primitives live in
+  [`aocore`](https://github.com/jacotay7/aocore), now a core dependency
+  (`aocore>=0.1.2,<0.2`). `noise.block_sum` is `aocore.block_sum`, re-exported
+  so existing imports keep working; it accepts everything it did before and now
+  also takes a `(fy, fx)` factor and leading batch axes, and raises a clear
+  `ValueError` for a factor below 1 or a shape that does not divide (previously
+  a bare reshape error, or a `ZeroDivisionError` for a factor of 0).
+  `Frame.binned` sums through it. `AiryPSF` and `Thermal` take their radians per
+  arcsecond from `aocore.ARCSEC_TO_RAD`, and `Vignetting` its centred grid from
+  `aocore.coordinate_grid`. Every output is bit-for-bit unchanged.
+
+### Added
+
+- **Conformance tests** (`tests/test_conformance.py`) run the
+  `aocore.conformance` checks that apply to a detector package: every PSF model
+  deposits unit flux, a source at `(n - 1) / 2` and the vignetting pattern are
+  centred on the optical axis for odd and even windows.
+
 ## [2.2.0] - 2026-08-24
 
 ### Added
@@ -558,7 +592,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.2.0...HEAD
+[Unreleased]: https://github.com/jacotay7/getframes/compare/2.3.0...HEAD
+[2.3.0]: https://github.com/jacotay7/getframes/compare/2.2.0...2.3.0
 [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

{getframes-2.2.0 → getframes-2.3.0}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.5
 Name: getframes
-Version: 2.2.0
+Version: 2.3.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/
@@ -23,6 +23,7 @@ Classifier: Topic :: Scientific/Engineering :: Astronomy
 Classifier: Topic :: Scientific/Engineering :: Image Processing
 Classifier: Typing :: Typed
 Requires-Python: >=3.10
+Requires-Dist: aocore<0.2,>=0.1.2
 Requires-Dist: astropy>=5.0
 Requires-Dist: numpy>=1.23
 Requires-Dist: scipy>=1.10
@@ -72,7 +73,7 @@ switches to CUDA (via CuPy) with a single argument.
 ## Install
 
 ```bash
-pip install getframes            # CPU (NumPy + SciPy + astropy)
+pip install getframes            # CPU (NumPy + SciPy + astropy + aocore)
 pip install 'getframes[gpu]'     # + CuPy for CUDA 12.x
 pip install -e '.[dev]'          # from a clone, for development
 ```

{getframes-2.2.0 → getframes-2.3.0}/README.md

@@ -27,7 +27,7 @@ switches to CUDA (via CuPy) with a single argument.
 ## Install
 
 ```bash
-pip install getframes            # CPU (NumPy + SciPy + astropy)
+pip install getframes            # CPU (NumPy + SciPy + astropy + aocore)
 pip install 'getframes[gpu]'     # + CuPy for CUDA 12.x
 pip install -e '.[dev]'          # from a clone, for development
 ```

{getframes-2.2.0 → getframes-2.3.0}/pyproject.toml

@@ -36,6 +36,7 @@ classifiers = [
 ]
 dynamic = ["version"]
 dependencies = [
+    "aocore>=0.1.2,<0.2",
     "numpy>=1.23",
     "scipy>=1.10",
     "astropy>=5.0",

{getframes-2.2.0 → getframes-2.3.0}/src/getframes/__about__.py

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

{getframes-2.2.0 → getframes-2.3.0}/src/getframes/frame.py

@@ -7,6 +7,7 @@ from dataclasses import dataclass, field
 from typing import TYPE_CHECKING, Any
 
 import numpy as np
+from aocore import block_sum
 
 from .backend import get_array_module, to_numpy
 
@@ -128,8 +129,9 @@ class Frame:
         if factor == 1:
             binned = data.copy()
         else:
-            blocks = data.reshape(height // factor, factor, width // factor, factor)
-            binned = blocks.sum(axis=(1, 3)) if method == "sum" else blocks.mean(axis=(1, 3))
+            binned = block_sum(data, factor)
+            if method == "mean":
+                binned = binned / (factor * factor)
         metadata = dict(self.metadata)
         metadata["binning"] = int(metadata.get("binning", 1)) * factor
         return Frame(data=binned, metadata=metadata, truth=None)

{getframes-2.2.0 → getframes-2.3.0}/src/getframes/noise.py

@@ -37,6 +37,7 @@ from contextlib import contextmanager
 from typing import TYPE_CHECKING, Any, NamedTuple
 
 import numpy as np
+from aocore import block_sum
 
 from .backend import ArrayBackend, get_backend
 
@@ -1213,17 +1214,6 @@ def frame_electrons(
     return electrons
 
 
-def block_sum(array: Any, factor: int) -> Any:
-    """Sum an array into ``factor x factor`` super-pixel blocks (both dims divisible)."""
-    if factor == 1:
-        return array
-    height, width = array.shape
-    binned: NDArray[Any] = array.reshape(height // factor, factor, width // factor, factor).sum(
-        axis=(1, 3)
-    )
-    return binned
-
-
 def simulate_frame(
     config: CameraConfig,
     photon_rate: PhotonRate,

{getframes-2.2.0 → getframes-2.3.0}/src/getframes/scene/optics.py

@@ -9,6 +9,7 @@ from dataclasses import dataclass
 from typing import TYPE_CHECKING
 
 import numpy as np
+from aocore import coordinate_grid
 from numpy.typing import NDArray
 
 from .photometry import Bandpass
@@ -41,8 +42,8 @@ class Vignetting:
         """Relative illumination in ``[0, 1]`` for a frame of ``(height, width)``."""
         height, width = shape
         cy, cx = (height - 1) / 2.0, (width - 1) / 2.0
-        yy, xx = np.mgrid[0:height, 0:width]
-        r = np.hypot(xx - cx, yy - cy)
+        yy, xx = coordinate_grid((height, width))
+        r = np.hypot(xx, yy)
         r_corner = math.hypot(max(cx, width - 1 - cx), max(cy, height - 1 - cy))
         if r_corner == 0:
             return np.ones(shape, dtype=np.float64)

{getframes-2.2.0 → getframes-2.3.0}/src/getframes/scene/psf.py

@@ -11,9 +11,11 @@ sampled on a stamp and normalised.
 from __future__ import annotations
 
 import math
+from collections.abc import Callable
 from dataclasses import dataclass
 
 import numpy as np
+from aocore import ARCSEC_TO_RAD
 from numpy.typing import NDArray
 from scipy.ndimage import shift as _ndimage_shift
 from scipy.special import erf, j1
@@ -37,6 +39,33 @@ def _stamp_bounds(
     return x0, x1, y0, y1
 
 
+def _deposit_sampled(
+    image: NDArray[np.float64],
+    x: float,
+    y: float,
+    radius: int,
+    flux: float,
+    profile_at: Callable[[NDArray[np.float64], NDArray[np.float64]], NDArray[np.float64]],
+) -> None:
+    """Add a sampled, normalised stamp, losing whatever falls off the frame.
+
+    ``profile_at(dx, dy)`` evaluates the PSF at column/row offsets from the source.
+    The profile is normalised over the *whole* stamp before it is clipped to the
+    frame, so light off the edge is lost rather than renormalised back in.
+    """
+    x0, x1, y0, y1 = _stamp_bounds(x, y, radius, image.shape)
+    if x0 >= x1 or y0 >= y1:
+        return  # source falls entirely off the frame
+    ix, iy = round(x), round(y)
+    offsets = np.arange(-radius, radius + 1, dtype=np.float64)
+    profile = profile_at(offsets[None, :] + (ix - x), offsets[:, None] + (iy - y))
+    total = profile.sum()
+    if total > 0:
+        sx, sy = x0 - (ix - radius), y0 - (iy - radius)
+        stamp = profile[sy : sy + (y1 - y0), sx : sx + (x1 - x0)]
+        image[y0:y1, x0:x1] += flux * stamp / total
+
+
 class PSF:
     """Base class for point-spread functions."""
 
@@ -193,17 +222,12 @@ class MoffatPSF(PSF):
         alpha = fwhm_pix / (2.0 * np.sqrt(2.0 ** (1.0 / self.beta) - 1.0))
 
         radius = int(np.ceil(6.0 * alpha)) + 1
-        x0, x1, y0, y1 = _stamp_bounds(x, y, radius, image.shape)
-        if x0 >= x1 or y0 >= y1:
-            return
+        beta = self.beta
 
-        xs = np.arange(x0, x1) - x
-        ys = np.arange(y0, y1) - y
-        rr = xs[None, :] ** 2 + ys[:, None] ** 2
-        profile = (1.0 + rr / alpha**2) ** (-self.beta)
-        total = profile.sum()
-        if total > 0:
-            image[y0:y1, x0:x1] += flux * profile / total
+        def profile(dx: NDArray[np.float64], dy: NDArray[np.float64]) -> NDArray[np.float64]:
+            return np.asarray((1.0 + (dx**2 + dy**2) / alpha**2) ** (-beta))
+
+        _deposit_sampled(image, x, y, radius, flux, profile)
 
 
 @dataclass(frozen=True)
@@ -238,20 +262,15 @@ class EllipticalGaussianPSF(PSF):
             raise ValueError("PSF FWHM and plate scale must be positive.")
 
         radius = int(np.ceil(5.0 * sigma_major)) + 1
-        x0, x1, y0, y1 = _stamp_bounds(x, y, radius, image.shape)
-        if x0 >= x1 or y0 >= y1:
-            return
-
-        xs = np.arange(x0, x1) - x
-        ys = np.arange(y0, y1) - y
         theta = math.radians(self.position_angle_deg)
         cos_t, sin_t = math.cos(theta), math.sin(theta)
-        u = xs[None, :] * cos_t + ys[:, None] * sin_t
-        v = -xs[None, :] * sin_t + ys[:, None] * cos_t
-        profile = np.exp(-0.5 * ((u / sigma_major) ** 2 + (v / sigma_minor) ** 2))
-        total = profile.sum()
-        if total > 0:
-            image[y0:y1, x0:x1] += flux * profile / total
+
+        def profile(dx: NDArray[np.float64], dy: NDArray[np.float64]) -> NDArray[np.float64]:
+            u = dx * cos_t + dy * sin_t
+            v = -dx * sin_t + dy * cos_t
+            return np.exp(-0.5 * ((u / sigma_major) ** 2 + (v / sigma_minor) ** 2))
+
+        _deposit_sampled(image, x, y, radius, flux, profile)
 
 
 @dataclass(frozen=True)
@@ -293,23 +312,17 @@ class AiryPSF(PSF):
             raise ValueError("AiryPSF obstruction must be in [0, 1).")
 
         # Radians per pixel, then the argument scale x = pi D theta / lambda.
-        rad_per_pixel = plate_scale_arcsec_per_pixel * (math.pi / 180.0 / 3600.0)
+        rad_per_pixel = plate_scale_arcsec_per_pixel * ARCSEC_TO_RAD
         arg_per_pixel = math.pi * self.aperture_diameter_m / self.wavelength_m * rad_per_pixel
         # First null at 1.22 lambda / D; size the stamp to a few Airy rings.
         first_null_pix = 1.22 / (arg_per_pixel / math.pi) if arg_per_pixel > 0 else 1.0
         radius = int(np.ceil(5.0 * first_null_pix)) + 1
-        x0, x1, y0, y1 = _stamp_bounds(x, y, radius, image.shape)
-        if x0 >= x1 or y0 >= y1:
-            return
+        obstruction = self.obstruction
+
+        def profile(dx: NDArray[np.float64], dy: NDArray[np.float64]) -> NDArray[np.float64]:
+            return _airy_intensity(arg_per_pixel * np.hypot(dx, dy), obstruction)
 
-        xs = np.arange(x0, x1) - x
-        ys = np.arange(y0, y1) - y
-        rr = np.sqrt(xs[None, :] ** 2 + ys[:, None] ** 2)
-        arg = arg_per_pixel * rr
-        profile = _airy_intensity(arg, self.obstruction)
-        total = profile.sum()
-        if total > 0:
-            image[y0:y1, x0:x1] += flux * profile / total
+        _deposit_sampled(image, x, y, radius, flux, profile)
 
 
 def _airy_intensity(arg: NDArray[np.float64], obstruction: float) -> NDArray[np.float64]:

{getframes-2.2.0 → getframes-2.3.0}/src/getframes/scene/thermal.py

@@ -14,11 +14,11 @@ Pure NumPy, no randomness.
 
 from __future__ import annotations
 
-import math
 from dataclasses import dataclass
 from typing import TYPE_CHECKING
 
 import numpy as np
+from aocore import ARCSEC_TO_RAD
 from numpy.typing import NDArray
 
 from ..spectral import SED
@@ -34,9 +34,6 @@ _H_PLANCK = 6.62607015e-34  # J s
 _C_LIGHT = 2.99792458e8  # m / s
 _K_BOLTZMANN = 1.380649e-23  # J / K
 
-# Arcseconds to radians, for the per-pixel solid angle.
-_ARCSEC_TO_RAD = math.pi / (180.0 * 3600.0)
-
 
 def _photon_radiance(
     wavelength_m: NDArray[np.float64], temperature_k: float
@@ -96,7 +93,7 @@ class Thermal:
         wl_m = resp.wavelength_nm * 1e-9
         integrand = _photon_radiance(wl_m, self.temperature_k) * resp.value
         radiance = float(_trapezoid(integrand, wl_m))  # photons/s/m^2/sr
-        omega_sr = (optics.plate_scale_arcsec_per_pixel * _ARCSEC_TO_RAD) ** 2
+        omega_sr = (optics.plate_scale_arcsec_per_pixel * ARCSEC_TO_RAD) ** 2
         return self.emissivity * radiance * optics.collecting_area_m2 * omega_sr
 
     def photon_sed(

getframes-2.3.0/tests/test_conformance.py

@@ -0,0 +1,83 @@
+# SPDX-License-Identifier: MIT
+"""The AO stack conventions (aocore ``CONVENTIONS.md``) that apply to getframes.
+
+getframes owns detectors, not wavefronts: its PSFs are analytic profiles (or a
+user kernel), not images of an OPD map. So the OPD-driven checks (tilt direction,
+slope sign, wind motion, Zernike basis, RMS) do not apply. What does apply is the
+flat-wavefront case: where the optical axis sits in the image plane (rule 1.3) and
+that a normalized point-source image carries unit flux (rule 3.3). The callables
+below take the checks' OPD argument for its shape only.
+"""
+
+from __future__ import annotations
+
+from typing import Any
+
+import aocore
+import numpy as np
+import pytest
+from aocore import conformance
+
+from getframes.scene import (
+    AiryPSF,
+    ArrayPSF,
+    EllipticalGaussianPSF,
+    GaussianPSF,
+    MoffatPSF,
+    Vignetting,
+)
+from getframes.scene.psf import PSF
+
+PLATE_SCALE_ARCSEC = 0.01
+
+
+def _psfs() -> list[PSF]:
+    kernel = np.exp(-0.5 * ((np.arange(15.0) - 7.0) / 2.0) ** 2)
+    return [
+        GaussianPSF(fwhm_arcsec=0.04),
+        MoffatPSF(fwhm_arcsec=0.04, beta=3.0),
+        EllipticalGaussianPSF(fwhm_major_arcsec=0.05, fwhm_minor_arcsec=0.03),
+        # 8 m aperture at 1.6 um: lambda / D = 0.041 arcsec, about 4 pixels.
+        AiryPSF(aperture_diameter_m=8.0, wavelength_m=1.6e-6),
+        ArrayPSF(kernel=np.outer(kernel, kernel)),
+    ]
+
+
+def _on_axis_image(psf: PSF, shape: tuple[int, ...]) -> np.ndarray[Any, Any]:
+    """A unit-flux point source on the optical axis ``(n - 1) / 2`` (rule 1.3)."""
+    height, width = shape
+    image = np.zeros((height, width))
+    psf.add_source(image, (width - 1) / 2.0, (height - 1) / 2.0, 1.0, PLATE_SCALE_ARCSEC)
+    return image
+
+
+@pytest.mark.parametrize("psf", _psfs(), ids=lambda psf: type(psf).__name__)
+def test_point_source_image_carries_unit_flux(psf: PSF) -> None:
+    # Rule 3.3: the window holds all of the light, so the image sums to the flux.
+    conformance.check_unit_flux(lambda opd: _on_axis_image(psf, opd.shape), pupil_shape=(96, 96))
+
+
+@pytest.mark.parametrize("psf", _psfs(), ids=lambda psf: type(psf).__name__)
+@pytest.mark.parametrize("shape", [(64, 64), (65, 65), (64, 65)])
+def test_pixel_coordinates_put_the_axis_on_pixel_centres(psf: PSF, shape: tuple[int, int]) -> None:
+    # Rules 1.2-1.3: getframes positions are pixel-centre indices, so a source at
+    # ``(n - 1) / 2`` images to the window centre, between pixels for even n.
+    conformance.check_image_centring(lambda opd: _on_axis_image(psf, opd.shape), pupil_shape=shape)
+
+
+@pytest.mark.parametrize("shape", [(64, 64), (65, 65), (64, 65)])
+def test_vignetting_is_centred_on_the_optical_axis(shape: tuple[int, int]) -> None:
+    # Rule 1.3: the field-dependent illumination falls off about ``(n - 1) / 2``.
+    vignetting = Vignetting(strength=0.4, power=2.0)
+    conformance.check_image_centring(
+        lambda opd: vignetting.illumination_map(opd.shape), pupil_shape=shape
+    )
+
+
+def test_arcsecond_constant_is_the_shared_one() -> None:
+    # Rule 2.3: AiryPSF and the thermal background take their radians per
+    # arcsecond from aocore rather than a local literal.
+    from getframes.scene import psf, thermal
+
+    assert psf.ARCSEC_TO_RAD is aocore.ARCSEC_TO_RAD
+    assert thermal.ARCSEC_TO_RAD is aocore.ARCSEC_TO_RAD

{getframes-2.2.0 → getframes-2.3.0}/tests/test_scene.py

@@ -61,6 +61,29 @@ def test_psf_conserves_flux(psf, optics):
     assert img.sum() == pytest.approx(1000.0, rel=1e-3)
 
 
+@pytest.mark.parametrize(
+    "psf",
+    [
+        gf.GaussianPSF(fwhm_arcsec=1.2),
+        gf.MoffatPSF(fwhm_arcsec=1.2),
+        gf.EllipticalGaussianPSF(fwhm_major_arcsec=1.6, fwhm_minor_arcsec=0.8),
+        # lambda / D = 2 arcsec, five pixels.
+        gf.AiryPSF(aperture_diameter_m=0.1, wavelength_m=1.0e-6),
+    ],
+    ids=lambda psf: type(psf).__name__,
+)
+def test_psf_loses_the_flux_that_falls_off_the_frame(psf):
+    # Light beyond the detector edge is lost, never renormalised back in
+    # (aocore CONVENTIONS 3.3). A source on column 0 of a frame must deposit
+    # exactly the part of a fully captured image that lies at x >= 0.
+    full = np.zeros((128, 128))
+    psf.add_source(full, x=64.3, y=64.0, flux=1000.0, plate_scale_arcsec_per_pixel=0.4)
+    edge = np.zeros((128, 64))
+    psf.add_source(edge, x=0.3, y=64.0, flux=1000.0, plate_scale_arcsec_per_pixel=0.4)
+    assert edge.sum() == pytest.approx(full[:, 64:].sum(), rel=1e-9)
+    assert edge.sum() < 0.75 * full.sum()
+
+
 def test_psf_peaks_at_source_position(optics):
     img = np.zeros((64, 64))
     gf.GaussianPSF(1.0).add_source(