seestar-photometry 0.2.0__tar.gz

seestar_photometry-0.2.0/.gitignore

@@ -0,0 +1,38 @@
+# Python
+__pycache__/
+*.py[cod]
+*.egg-info/
+build/
+dist/
+.pytest_cache/
+.coverage
+htmlcov/
+
+# uv
+.venv/
+
+# Editors
+.idea/
+.vscode/
+
+# Secrets -- ASTROMETRY_KEY lives in the environment, never in the repo
+.env
+
+# Derived products. Everything the pipeline writes goes to a project work_dir, which
+# should live outside the repo; these patterns are a backstop for a work_dir set to '.'
+frames.ecsv
+stars.ecsv
+measurements.ecsv
+catalogue_*.ecsv
+diagnostics/
+errors.log
+*.wcs
+
+# Build outputs
+dist/
+docs/_build/
+
+# Example data: built by tools/build_example_data.py and published as a GitHub
+# release asset, not committed. SHA256 is tracked so the checksum is reviewable.
+example_data/*
+!example_data/SHA256

seestar_photometry-0.2.0/.readthedocs.yaml

@@ -0,0 +1,23 @@
+version: 2
+
+build:
+  os: ubuntu-24.04
+  tools:
+    python: "3.12"
+
+sphinx:
+  configuration: docs/conf.py
+  fail_on_warning: false
+
+python:
+  install:
+    # Install the package itself so autodoc imports the real modules and picks up the
+    # version. `sep` and the stacking extras are mocked in conf.py, so they are not needed
+    # to build -- but the docs extra brings sphinx, myst-parser and the theme.
+    - method: pip
+      path: .
+      extra_requirements:
+        - docs
+
+formats:
+  - pdf

seestar_photometry-0.2.0/CHANGELOG.md

@@ -0,0 +1,51 @@
+# Changelog
+
+## 0.2.0 — 2026-08-05
+
+First release intended for publication.
+
+### Added
+
+- **Raw sub-exposure support.** `load_frame` now recognises the single-plane Bayer layout
+  (`BAYERPAT`) and demosaics it on load, so a raw 20 s sub is interchangeable with an
+  on-board stack everywhere downstream. The native mosaic is kept on `frame.bayer`.
+  New `debayer` module.
+- **Local stacking** (`stacking`, needs the `stack` extra): astroalign registration as a
+  similarity transform — rotation included, which alt-az frames require — plus a
+  footprint-weighted mean. `StackReport` records residual, field rotation, coverage and any
+  rejected sub. A local stack writes native-dialect exposure keywords, so `frame_metadata`
+  reads it exactly as it reads an on-board stack.
+- **Bundled example data** (`examples`): 1000×1000 cutouts of real MW Cam observations —
+  three on-board stacks, a CrowdSky multi-extension frame, five raw subs, solved `.wcs`
+  sidecars and a trimmed Gaia DR3 table. Every documented example and every real-data test
+  runs offline.
+- **Documentation** for Read the Docs: install, quickstart, six use-case pages driven by the
+  bundled data, an API reference, and the design-decision records.
+- 40 real-data tests alongside the existing synthetic suite (162 total).
+
+### Fixed
+
+- `wcs_cache_path` now strips a compression suffix, so `frame.fits.gz` caches its WCS to
+  `frame.wcs` rather than the unreachable `frame.fits.wcs`. Gzipped frames would otherwise
+  have been re-solved on every run.
+- An empty light curve keeps its full column schema, so a downstream call reports "no epochs"
+  instead of raising a bare `KeyError: 'dmag'`.
+- `pipeline` uses a thread pool when `workers == 1`; a single worker gained nothing from a
+  separate process and paid the full spawn cost. A dead process pool now raises a message
+  naming the usual Windows cause (a driver without an `if __name__ == "__main__"` guard)
+  instead of an opaque `BrokenProcessPool`.
+- `forced_photometry` no longer emits a divide warning for a fully off-frame aperture; the
+  SNR is `nan`, which is the right answer.
+- CrowdSky's `FWHM` header values are in **arcsec** while this package reports **pixels**.
+  `quality.onboard_quality` renames them `onboard_fwhm_*_arcsec` so the two are not compared
+  by accident — they looked 2.4× apart until the plate scale was applied, after which they
+  agree to 2%.
+
+## 0.1.0
+
+Initial extraction of the photometry engine from the MW Cam analysis repo, where it had
+existed as three diverging copies. See `docs/migration-from-mwcam.md`.
+
+Verified against the frozen results it replaced: zero point bit-identical on 20 of 22 frames
+(all 15 photometric-grade frames exactly 0.000 mmag apart), and forced photometry
+bit-identical across a 52-frame CrowdSky set.

seestar_photometry-0.2.0/CLAUDE.md

@@ -0,0 +1,82 @@
+# seestar-photometry — conventions
+
+Read this before changing code. The rationale for every numerical choice lives in
+`docs/`; this file is the shape of the package.
+
+## Names
+
+Distribution `seestar-photometry`, import package `seestar_photometry`. Python
+import names can't contain hyphens.
+
+## Hard conventions
+
+- **`BANDS = ("R", "G", "B")` is the canonical axis-0 order.** Every frame is a
+  `(3, ny, nx)` float32 array in that order. Every per-band array (`Extraction.rms`,
+  `.aperture`, `.fwhm`) is shape `(3,)` in that order. **Green is index 1 and is the
+  science band** (≈ Johnson V through the Seestar's IRCUT filter).
+
+- **Image shape comes from the data, never the header.** `frame.g.shape` gives
+  `(ny, nx)`. The CrowdSky multi-extension layout has an *empty* primary HDU with no
+  `NAXIS1`/`NAXIS2`, so any code reading the shape from a header is broken on half
+  the datasets.
+
+- **`SeestarFrame` and `Project` are thin data containers, not god objects.** All
+  analysis is module-level *functions* taking the object as their first argument
+  (`photometry.extract_sources(frame, ...)`). Methods that briefly lived on the
+  frame class were moved out on purpose.
+
+- **Optional dependencies are imported lazily**, inside the function that needs
+  them — never at module top. `matplotlib` in particular: `import
+  seestar_photometry` must work in a core install. `tests/test_imports.py` asserts
+  `matplotlib` is absent from `sys.modules` after import, so this can't rot.
+
+- **The standard photometry path and the cross-checks live in separate modules.**
+  `photometry` is what the science uses; `kron` (Kron/AUTO) is kept only for
+  star/galaxy separation and total-flux cross-checks. Do not promote it.
+
+- **Derived products never go into the data tree or the FITS headers.** Tables and
+  figures go to `Project.work_dir`. The one exception is the per-frame `.wcs`
+  sidecar, which lives next to its FITS file because it is expensive to recompute
+  and shared between projects.
+
+- **No defensive error handling in the measurement layer.** If a frame is broken,
+  let it raise; the batch runner in `pipeline` catches per-frame exceptions, records
+  a status, and keeps going. Don't scatter `try/except` through the science code.
+
+## Module layers
+
+Each module imports only from layers above it.
+
+| Layer | Modules |
+|---|---|
+| data | `frames` |
+| measure | `photometry`, `astrometry`, `catalogs` |
+| calibrate | `calibration`, `quality` |
+| science | `lightcurves`, `contamination`, `depth` |
+| orchestrate | `project`, `pipeline` |
+| inspect | `plots`, `report` |
+| cross-check | `kron` |
+
+## Two FITS layouts, two header dialects
+
+Both normalise to the same in-memory frame. See `docs/data-format.md`.
+
+| | `"cube"` — native Seestar | `"mef"` — CrowdSky |
+|---|---|---|
+| structure | 3-D primary HDU, FITS axes `(nx, ny, 3)` → numpy `(3, ny, nx)` | empty primary + `RED`/`GREEN`/`BLUE` ImageHDUs (+ `FOOTPRINT`, `STAR-TAB`) |
+| sub count | `STACKCNT` | `NIMAGES` |
+| `EXPTIME` | **per sub-exposure** (10 s) | **total on-sky** (e.g. 410 s) |
+| total on-sky | `TOTALEXP` | `EXPTIME` |
+| exposure span | `DATE-OBS` only | `OB-START` / `OB-END` (use these) |
+
+That `EXPTIME` collision is the trap: reading it naively gives a per-sub time of
+410 s and a mid-exposure timestamp ~5 minutes wrong. `frames.frame_metadata`
+resolves the dialect; never read these keywords directly.
+
+## Environment
+
+`uv` only. `uv sync --extra dev`, then `uv run pytest` / `uv run python ...`.
+Never `uv run --active`. Point PyCharm at `.venv`; don't let it make its own.
+
+`ASTROMETRY_KEY` (astrometry.net) is read from the environment and never stored in
+the repo — only needed for `solver="nova"`; the default ASTAP solver is offline.