asteroidpipeline 0.2.1__tar.gz

asteroidpipeline-0.2.1/.gitignore

@@ -0,0 +1,49 @@
+Manifest.toml
+/data/
+*.fits
+*.jl.cov
+*.jl.*.cov
+*.jl.mem
+.vscode/
+result
+result-*
+.direnv/
+
+# docs/ — build output and DocumenterVitepress's own Node/Vitepress
+# tooling. docs/src/*.md are real, permanent, committed pages, not
+# generated — deliberately not listed here.
+docs/build/
+docs/node_modules/
+docs/package-lock.json
+docs/.vitepress/cache/
+docs/.vitepress/dist/
+docs/src/.vitepress/cache/
+docs/src/.vitepress/dist/
+
+# docs/src/assets/ — generated by docs/make_figures.jl on every build
+# (local and CI), so these would just be stale duplicates if committed;
+# not a blanket ignore of the whole assets/ directory in case a real,
+# hand-authored logo.png/favicon.ico is ever added there.
+docs/src/assets/systematic-error-floor-sweep.png
+docs/src/assets/iasc-match-radius-retuning.png
+docs/src/assets/pipeline-overview.png
+docs/src/assets/completeness.png
+docs/src/assets/set-quality.png
+docs/src/assets/background-excess.png
+docs/src/assets/astrometry-vs-astrometrica.png
+docs/src/assets/tracklets-to-vet.png
+docs/src/assets/nearby-geometry.png
+
+# Local-only notes about the GitHub mirror's own CI/Pages plumbing — not
+# part of the project (the wiki documents the pipeline, not its own
+# deploy infrastructure).
+PAGES_NOTES.md
+
+# Real API keys for local test runs (e.g. ASTROMETRY_API_KEY) — see
+# .env.example for the expected format.
+.env
+
+# Python packaging of the terminal app (pyproject.toml)
+dist/
+__pycache__/
+*.egg-info/

asteroidpipeline-0.2.1/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Alejandro
+
+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.

asteroidpipeline-0.2.1/PKG-INFO

@@ -0,0 +1,95 @@
+Metadata-Version: 2.5
+Name: asteroidpipeline
+Version: 0.2.1
+Summary: Find moving objects in astronomical image sets, check them, and write MPC reports — a terminal app on AsteroidPipeline.jl
+Project-URL: Documentation, https://richard7987.github.io/AsteroidPipeline.jl/stable/
+Project-URL: Source, https://github.com/Richard7987/AsteroidPipeline.jl
+Author: Alejandro
+License-Expression: MIT
+License-File: LICENSE
+Keywords: FITS,MPC,asteroids,astrometry,astronomy,minor planets,terminal
+Classifier: Environment :: Console
+Classifier: Intended Audience :: Science/Research
+Classifier: Operating System :: MacOS
+Classifier: Operating System :: POSIX :: Linux
+Classifier: Programming Language :: Python :: 3
+Classifier: Topic :: Scientific/Engineering :: Astronomy
+Requires-Python: >=3.11
+Requires-Dist: juliapkg>=0.1.13
+Requires-Dist: pillow>=10.1
+Requires-Dist: pyfiglet>=1.0
+Requires-Dist: textual-image>=0.13
+Requires-Dist: textual>=8.0
+Description-Content-Type: text/markdown
+
+# AsteroidPipeline.jl
+
+[![CI](https://github.com/Richard7987/AsteroidPipeline.jl/actions/workflows/CI.yml/badge.svg)](https://github.com/Richard7987/AsteroidPipeline.jl/actions/workflows/CI.yml)
+[![docs](https://img.shields.io/badge/docs-stable-blue.svg)](https://richard7987.github.io/AsteroidPipeline.jl/stable/)
+[![docs](https://img.shields.io/badge/docs-dev-blue.svg)](https://richard7987.github.io/AsteroidPipeline.jl/dev/)
+
+Find asteroids in astronomical images. Give it a few exposures of one field
+taken minutes apart — a `.zip`, a folder or FITS files, from any telescope —
+and it calibrates them against Gaia, finds what moves, tells known asteroids
+from new candidates, and writes the report for the Minor Planet Center.
+
+It comes two ways:
+
+- **`asteroidpipeline`**, a terminal app: open an image set, watch the images
+  animate with every object marked, confirm or reject each candidate, copy
+  the report. Every decision is saved, with the candidate's pixels, as
+  training data for a future classifier.
+- **AsteroidPipeline.jl**, the Julia library that does all the analysis —
+  for scripts, batches and anything the app doesn't do.
+
+**Documentation: <https://richard7987.github.io/AsteroidPipeline.jl/stable/>** (for the latest release; [dev](https://richard7987.github.io/AsteroidPipeline.jl/dev/) for `main`)
+
+## Install the app
+
+On any Linux (or macOS) with Python 3.11 or newer:
+
+```sh
+curl -fsSL https://raw.githubusercontent.com/Richard7987/AsteroidPipeline.jl/main/install.sh | sh
+asteroidpipeline
+```
+
+or with [pipx](https://pipx.pypa.io/) (or pip), from PyPI:
+
+```sh
+pipx install asteroidpipeline
+asteroidpipeline --setup      # optional: install the analysis engine now
+```
+
+The first run installs the analysis engine: Julia (downloaded if you don't
+have it) and its packages, several minutes once. Images are shown at full
+resolution in terminals with a graphics protocol (Kitty, WezTerm, Ghostty,
+foot…), as coloured blocks elsewhere. With Nix: `nix run github:Richard7987/AsteroidPipeline.jl`.
+
+## Use the library
+
+```julia
+using Pkg; Pkg.add(url="https://github.com/Richard7987/AsteroidPipeline.jl")
+
+using AsteroidPipeline
+result = analyze_set("images.zip"; observatory="F51", workdir="work")
+print(result.report)
+```
+
+Many sets at once: `julia --project=. examples/analyze_sets.jl <folder> <observatory code>`.
+Start with [Getting started](https://richard7987.github.io/AsteroidPipeline.jl/dev/getting-started).
+
+## Repository
+
+| Path | What |
+|:--|:--|
+| `src/` | the Julia library |
+| `test/` | its tests (`julia --project=. -e 'using Pkg; Pkg.test()'`) |
+| `docs/` | the documentation site (`julia --project=docs docs/make.jl`) |
+| `examples/` | scripts for real data, batches and completeness tests |
+| `ui/` | the terminal app (Python, [Textual](https://textual.textualize.io/)); see [ui/README.md](ui/README.md) |
+| `pyproject.toml`, `install.sh` | packaging of the app, with the library inside |
+| `flake.nix` | Nix: `nix develop` for a development shell, `nix build` for the app |
+
+## License
+
+MIT. See `LICENSE`.

asteroidpipeline-0.2.1/Project.toml

@@ -0,0 +1,53 @@
+name = "AsteroidPipeline"
+uuid = "1001636e-a0d1-496e-b23d-cef10bc3cdca"
+version = "0.2.1"
+authors = ["Alejandro <ale_bnes@nezzontli.xyz>"]
+
+[deps]
+CSV = "336ed68f-0bac-5ca0-87d4-7b16caf5d00b"
+CodecZlib = "944b1d66-785c-5afd-91f1-9de20f533193"
+Dates = "ade2ca70-3891-5945-98fb-dc099432e06a"
+Distributed = "8ba89e20-285c-5b6f-9357-94700520ee1b"
+FFTW = "7a1cc6ca-52ef-59f5-83cd-3a7055c09341"
+FITSIO = "525bcba6-941b-5504-bd06-fd0dc1a4d2eb"
+HTTP = "cd3eb016-35fb-5094-929b-558a96fad6f3"
+Interpolations = "a98d9a8b-a2ab-59e6-89dd-64a1c18fca59"
+JSON = "682c06a0-de6a-54ab-a142-c8b1cf79cde6"
+LombScargle = "fc60dff9-86e7-5f2f-a8a0-edeadbb75bd9"
+LsqFit = "2fda8390-95c7-5789-9bda-21331edee243"
+Photometry = "af68cb61-81ac-52ed-8703-edc140936be4"
+Printf = "de0858da-6303-5e67-8744-51eddeeeb8d7"
+Random = "9a3f8284-a2c9-5f02-9a11-845980a1fd5c"
+Reproject = "d1dcc2e6-806e-11e9-2897-3f99785db2ae"
+Statistics = "10745b16-79ce-11e8-11f9-7d13ad32a3b2"
+TypedTables = "9d95f2ec-7b3d-5a63-8d20-e2491e220bb9"
+WCS = "15f3aee2-9e10-537f-b834-a6fb8bdb944d"
+p7zip_jll = "3f19e933-33d8-53b3-aaab-bd5110c3b7a0"
+
+[compat]
+CSV = "0.10.16"
+CodecZlib = "0.7.8"
+Dates = "1.11.0"
+Distributed = "1.11.0"
+FFTW = "1.10.0"
+FITSIO = "0.17.5"
+HTTP = "2.6.4"
+Interpolations = "0.16.3"
+JSON = "1.7.1"
+LombScargle = "1.0.3"
+LsqFit = "0.16.1"
+Photometry = "0.9.8"
+Printf = "1.11.0"
+Random = "1.11.0"
+Reproject = "0.3.3"
+Statistics = "1.11.1"
+TypedTables = "1.4.6"
+WCS = "0.6.3"
+julia = "1.11"
+p7zip_jll = "17.7.0"
+
+[extras]
+Test = "8dfed614-e22c-5e08-85e1-65c5234f0b40"
+
+[targets]
+test = ["Test"]

asteroidpipeline-0.2.1/README.md

@@ -0,0 +1,71 @@
+# AsteroidPipeline.jl
+
+[![CI](https://github.com/Richard7987/AsteroidPipeline.jl/actions/workflows/CI.yml/badge.svg)](https://github.com/Richard7987/AsteroidPipeline.jl/actions/workflows/CI.yml)
+[![docs](https://img.shields.io/badge/docs-stable-blue.svg)](https://richard7987.github.io/AsteroidPipeline.jl/stable/)
+[![docs](https://img.shields.io/badge/docs-dev-blue.svg)](https://richard7987.github.io/AsteroidPipeline.jl/dev/)
+
+Find asteroids in astronomical images. Give it a few exposures of one field
+taken minutes apart — a `.zip`, a folder or FITS files, from any telescope —
+and it calibrates them against Gaia, finds what moves, tells known asteroids
+from new candidates, and writes the report for the Minor Planet Center.
+
+It comes two ways:
+
+- **`asteroidpipeline`**, a terminal app: open an image set, watch the images
+  animate with every object marked, confirm or reject each candidate, copy
+  the report. Every decision is saved, with the candidate's pixels, as
+  training data for a future classifier.
+- **AsteroidPipeline.jl**, the Julia library that does all the analysis —
+  for scripts, batches and anything the app doesn't do.
+
+**Documentation: <https://richard7987.github.io/AsteroidPipeline.jl/stable/>** (for the latest release; [dev](https://richard7987.github.io/AsteroidPipeline.jl/dev/) for `main`)
+
+## Install the app
+
+On any Linux (or macOS) with Python 3.11 or newer:
+
+```sh
+curl -fsSL https://raw.githubusercontent.com/Richard7987/AsteroidPipeline.jl/main/install.sh | sh
+asteroidpipeline
+```
+
+or with [pipx](https://pipx.pypa.io/) (or pip), from PyPI:
+
+```sh
+pipx install asteroidpipeline
+asteroidpipeline --setup      # optional: install the analysis engine now
+```
+
+The first run installs the analysis engine: Julia (downloaded if you don't
+have it) and its packages, several minutes once. Images are shown at full
+resolution in terminals with a graphics protocol (Kitty, WezTerm, Ghostty,
+foot…), as coloured blocks elsewhere. With Nix: `nix run github:Richard7987/AsteroidPipeline.jl`.
+
+## Use the library
+
+```julia
+using Pkg; Pkg.add(url="https://github.com/Richard7987/AsteroidPipeline.jl")
+
+using AsteroidPipeline
+result = analyze_set("images.zip"; observatory="F51", workdir="work")
+print(result.report)
+```
+
+Many sets at once: `julia --project=. examples/analyze_sets.jl <folder> <observatory code>`.
+Start with [Getting started](https://richard7987.github.io/AsteroidPipeline.jl/dev/getting-started).
+
+## Repository
+
+| Path | What |
+|:--|:--|
+| `src/` | the Julia library |
+| `test/` | its tests (`julia --project=. -e 'using Pkg; Pkg.test()'`) |
+| `docs/` | the documentation site (`julia --project=docs docs/make.jl`) |
+| `examples/` | scripts for real data, batches and completeness tests |
+| `ui/` | the terminal app (Python, [Textual](https://textual.textualize.io/)); see [ui/README.md](ui/README.md) |
+| `pyproject.toml`, `install.sh` | packaging of the app, with the library inside |
+| `flake.nix` | Nix: `nix develop` for a development shell, `nix build` for the app |
+
+## License
+
+MIT. See `LICENSE`.

asteroidpipeline-0.2.1/pyproject.toml

@@ -0,0 +1,62 @@
+# The terminal application: one installable program with the Julia library
+# inside it (the wheel bundles src/ and Project.toml as
+# asteroid_ui/julia/AsteroidPipeline). The interface's own code is ui/; the
+# analysis is all AsteroidPipeline.jl, set up on first run (see
+# ui/asteroid_ui/engine/__init__.py).
+#
+#   pip install asteroidpipeline       (or: pipx install asteroidpipeline)
+#   asteroidpipeline
+
+[build-system]
+requires = ["hatchling"]
+build-backend = "hatchling.build"
+
+[project]
+name = "asteroidpipeline"
+dynamic = ["version"]
+description = "Find moving objects in astronomical image sets, check them, and write MPC reports — a terminal app on AsteroidPipeline.jl"
+readme = "README.md"
+license = "MIT"
+license-files = ["LICENSE"]
+requires-python = ">=3.11"
+authors = [{ name = "Alejandro" }]
+keywords = ["astronomy", "asteroids", "minor planets", "MPC", "FITS", "astrometry", "terminal"]
+classifiers = [
+    "Environment :: Console",
+    "Intended Audience :: Science/Research",
+    "Operating System :: POSIX :: Linux",
+    "Operating System :: MacOS",
+    "Programming Language :: Python :: 3",
+    "Topic :: Scientific/Engineering :: Astronomy",
+]
+dependencies = [
+    "textual>=8.0",
+    "textual-image>=0.13",
+    "pillow>=10.1",
+    "pyfiglet>=1.0",
+    # Downloads Julia only when none is installed; see the engine module.
+    "juliapkg>=0.1.13",
+]
+
+[project.urls]
+Documentation = "https://richard7987.github.io/AsteroidPipeline.jl/stable/"
+Source = "https://github.com/Richard7987/AsteroidPipeline.jl"
+
+[project.scripts]
+asteroidpipeline = "asteroid_ui.app:main"
+
+[tool.hatch.version]
+path = "ui/asteroid_ui/__init__.py"
+
+[tool.hatch.build.targets.wheel]
+packages = ["ui/asteroid_ui"]
+exclude = ["**/__pycache__"]
+
+[tool.hatch.build.targets.wheel.force-include]
+"src" = "asteroid_ui/julia/AsteroidPipeline/src"
+"Project.toml" = "asteroid_ui/julia/AsteroidPipeline/Project.toml"
+"LICENSE" = "asteroid_ui/julia/AsteroidPipeline/LICENSE"
+
+[tool.hatch.build.targets.sdist]
+include = ["/ui/asteroid_ui", "/src", "/Project.toml", "/LICENSE", "/README.md", "/pyproject.toml"]
+exclude = ["**/__pycache__"]

asteroidpipeline-0.2.1/src/AsteroidPipeline.jl

@@ -0,0 +1,62 @@
+module AsteroidPipeline
+
+using FITSIO
+using Photometry
+using LombScargle
+using HTTP
+using CSV
+using JSON
+using TypedTables: Table
+using WCS
+using Printf
+using Reproject
+using Statistics
+using Interpolations
+using FFTW
+using LsqFit
+using Distributed
+using Dates: DateTime, datetime2julian
+import Dates
+using CodecZlib: GzipDecompressorStream
+import p7zip_jll
+using Random: AbstractRNG, default_rng
+
+include("detection.jl")
+include("linking.jl")
+include("linking_multinight.jl")
+include("variables.jl")
+include("astrometry.jl")
+include("platesolve.jl")
+include("crossmatch.jl")
+include("astrometric_refinement.jl")
+include("calibrated_photometry.jl")
+include("mpcorb.jl")
+include("campaign.jl")
+include("observatories.jl")
+include("known_nearby.jl")
+include("neocp.jl")
+include("injection.jl")
+include("reference.jl")
+include("psf.jl")
+include("zogy.jl")
+include("stack_difference.jl")
+include("pipeline.jl")
+include("rotation.jl")
+include("mpc_export.jl")
+include("digest2.jl")
+
+export detect_sources, fill_value_mask, link_candidates, load_wcs, pix_to_sky,
+       astrometric_calibrate, crossmatch_catalog, SkyBoTServiceError, run_pipeline,
+       build_reference, load_frame, estimate_psf, fit_moffat_psf, zogy_subtract, light_curve,
+       recover_rotation_period, plate_solve, search_field, find_variable_sources,
+       variability_chi2, photometric_scale, ades_psv, mpc80_report, julian_date_to_iso8601,
+       digest2_score, link_across_nights, gaia_reference_stars, refine_wcs, stack_difference,
+       aperture_flux, photometric_zeropoint, candidate_magnitudes, frame_epoch,
+       inject_movers, injection_recovery, read_mpcorb, set_quality,
+       extract_set, clean_blank_pixels, download_mpcorb, default_mpcorb_path, astrometrica_settings,
+       mpc_report_header, blank_mpc_report, mpc_report, pack_designation, check_mpc_report,
+       known_objects_in_field, frame_footprint, analyze_set, pipeline_config, IASC_PS1_CONFIG,
+       read_obscodes, download_obscodes, frame_site, observatory_candidates, tracklet_motion,
+       nearby_known_objects, neocp_objects, neocp_check
+
+end # module AsteroidPipeline

asteroidpipeline-0.2.1/src/astrometric_refinement.jl

@@ -0,0 +1,230 @@
+"""
+    gaia_reference_stars(ra, dec, radius_deg; epoch_jd::Real, mag_range=(12.0, 21.0)) -> Table
+
+Gaia DR3 stars within `radius_deg` of `(ra, dec)` (degrees), with G
+magnitude inside `mag_range` — a live network request, to the ESA Gaia
+archive's TAP service (`gaiadr3.gaia_source`), falling back to VizieR's
+copy (`I/355/gaiadr3`) if the archive fails with a network error, a
+timeout or a 5xx status. Two services because one did go down mid-run:
+VizieR's TAP answered 503 to every request for a sustained stretch while
+this was being validated, which would otherwise have stopped every
+`refine_astrometry` run cold.
+
+Positions are propagated by proper motion from Gaia DR3's own epoch
+(J2016.0) to `epoch_jd` (a Julian Date, normally the frame's own); stars
+without a proper motion keep their catalogued position. A decade of proper motion is easily a
+significant fraction of an arcsecond for nearby stars, which is the
+whole error budget [`refine_wcs`](@ref) is trying to beat.
+
+Returns a table with columns `ra`, `dec` (degrees, at `epoch_jd`) and
+`gmag`, ready to pass to [`refine_wcs`](@ref).
+"""
+function gaia_reference_stars(ra::Real, dec::Real, radius_deg::Real;
+                               epoch_jd::Real, mag_range=(12.0, 21.0))
+    0 < radius_deg <= 5 || throw(ArgumentError("radius_deg must be in (0, 5]"))
+    lo, hi = mag_range
+    # Both queries alias their columns to the same names, so one parser
+    # serves either service.
+    cone(racol, deccol) = "CONTAINS(POINT('ICRS', $racol, $deccol), " *
+                          "CIRCLE('ICRS', $ra, $dec, $radius_deg)) = 1"
+    esa = "SELECT ra AS ra_deg, dec AS dec_deg, pmra AS pm_ra, pmdec AS pm_dec, " *
+          "phot_g_mean_mag AS g FROM gaiadr3.gaia_source " *
+          "WHERE $(cone("ra", "dec")) AND phot_g_mean_mag BETWEEN $lo AND $hi"
+    vizier = "SELECT RA_ICRS AS ra_deg, DE_ICRS AS dec_deg, pmRA AS pm_ra, pmDE AS pm_dec, " *
+             "Gmag AS g FROM \"I/355/gaiadr3\" " *
+             "WHERE $(cone("RA_ICRS", "DE_ICRS")) AND Gmag BETWEEN $lo AND $hi"
+    rows = try
+        _tap_query(_GAIA_ARCHIVE_TAP_URL, esa)
+    catch e
+        _is_service_failure(e) || rethrow()
+        @warn "Gaia archive unavailable; falling back to VizieR" exception=e
+        _tap_query(_VIZIER_TAP_URL, vizier)
+    end
+
+    years = (epoch_jd - _GAIA_DR3_EPOCH_JD) / 365.25
+    out_ra = Float64[]; out_dec = Float64[]; gmag = Float64[]
+    for r in rows
+        (ismissing(r.ra_deg) || ismissing(r.dec_deg)) && continue
+        pmra = ismissing(r.pm_ra) ? 0.0 : Float64(r.pm_ra)   # mas/yr, already * cos(dec)
+        pmde = ismissing(r.pm_dec) ? 0.0 : Float64(r.pm_dec)
+        d = Float64(r.dec_deg) + pmde * years / 3.6e6
+        push!(out_ra, Float64(r.ra_deg) + pmra * years / 3.6e6 / cosd(d))
+        push!(out_dec, d)
+        push!(gmag, ismissing(r.g) ? NaN : Float64(r.g))
+    end
+    return Table(ra=out_ra, dec=out_dec, gmag=gmag)
+end
+
+const _GAIA_DR3_EPOCH_JD = 2457389.0   # J2016.0
+const _GAIA_ARCHIVE_TAP_URL = "https://gea.esac.esa.int/tap-server/tap/sync"
+
+"""
+    refine_wcs(image, wcs, stars; threshold=10.0, mask=nothing, max_offset=60.0,
+               match_radius=2.0, min_matches=6, clip_sigma=3.0)
+        -> (wcs, refined, n_matches, rms_arcsec, offset_px, n_detections)
+
+Re-derive a frame's astrometric solution from reference stars actually
+detected in it, rather than trusting the header's — the same job
+Astrometrica's "Data Reduction" does before any measurement is reported.
+
+`image` is in the `(y, x)` order [`detect_sources`](@ref) takes; `wcs`
+is the header's approximate solution; `stars` is a table of reference
+stars with `ra`, `dec` columns (degrees, at the frame's epoch), e.g. from
+[`gaia_reference_stars`](@ref). Stars are detected at `threshold` sigma
+(`mask` is forwarded to `detect_sources`), and every catalog star is
+projected through `wcs`. The header's error is found first as one
+global pixel offset — the peak of a vote over every detection/star pair
+within `max_offset` pixels — then each star is matched to the nearest
+detection within `match_radius` pixels of its offset-corrected position,
+and a linear tangent-plane (TAN) solution — 6 parameters: shift, scale,
+rotation, shear — is fitted by least squares to those matches, rejecting
+matches beyond `clip_sigma` times the residual RMS and refitting until
+none are rejected.
+
+Why this is needed rather than optional for real IASC/Pan-STARRS1 data:
+on a real 2025 practice set (field `XY54_p10`), matched against 38 Gaia
+stars, the header WCS was off by a near-constant ~26.6 px (6.8") — far
+beyond the <1" an MPC report needs, though PS1's own `CERROR` keyword
+claims 0.06". Refit this way, the residual RMS fell to ~0.17", and an
+unknown object's positions agreed with Astrometrica's own
+Gaia-calibrated measurement of it. The header's `PCA*` polynomial
+distortion terms were checked as the explanation first and ruled out:
+evaluated at the chip's corners they move a position by <0.5 px.
+
+Returns a named tuple: the refined `wcs` (a plain TAN `WCSTransform`,
+tangent point at `wcs`'s own `crval`), `refined` (`false` if fewer than
+`min_matches` stars matched — `wcs` is then the input, unchanged — so a
+caller can warn instead of failing outright), `n_matches`, `rms_arcsec`
+(the fit's residual RMS; `NaN` if not refined), and `offset_px` (the
+global `(dx, dy)` offset found, detected minus predicted), and `n_detections`
+(sources detected at `threshold` — compared with the catalog's star count it
+flags frames full of detector defects; see [`run_pipeline`](@ref)).
+"""
+function refine_wcs(image::AbstractMatrix{<:Real}, wcs::WCSTransform, stars;
+                    threshold::Real=10.0, mask::Union{Nothing,AbstractMatrix{Bool}}=nothing,
+                    max_offset::Real=60.0, match_radius::Real=2.0,
+                    min_matches::Integer=6, clip_sigma::Real=3.0)
+    unrefined(n, offset) = (wcs=wcs, refined=false, n_matches=n, rms_arcsec=NaN, offset_px=offset,
+                            n_detections=length(detections))
+
+    detections = detect_sources(image; threshold, mask)
+    det_xy = [(d.xcen, d.ycen) for d in detections]
+    n1, n2 = size(image)
+
+    predicted = Tuple{Float64,Float64,Float64,Float64}[]   # (x, y, ra, dec)
+    for s in stars
+        x, y = world_to_pix(wcs, Float64[s.ra, s.dec])
+        (-max_offset < x < n2 + max_offset && -max_offset < y < n1 + max_offset) || continue
+        push!(predicted, (x, y, Float64(s.ra), Float64(s.dec)))
+    end
+    (isempty(det_xy) || isempty(predicted)) && return unrefined(0, (NaN, NaN))
+
+    offset = _vote_offset(det_xy, predicted, max_offset)
+    matches = _match_stars(det_xy, predicted, offset, match_radius)
+    length(matches) < min_matches && return unrefined(length(matches), offset)
+
+    crval = (wcs.crval[1], wcs.crval[2])
+    fit = _fit_tan(matches, crval, clip_sigma)
+    fit.n < min_matches && return unrefined(fit.n, offset)
+    return (wcs=fit.wcs, refined=true, n_matches=fit.n, rms_arcsec=fit.rms_arcsec, offset_px=offset,
+            n_detections=length(detections))
+end
+
+"""
+    _vote_offset(det_xy, predicted, max_offset; bin=2.0) -> (dx, dy)
+
+The global pixel offset (detected minus predicted) most detection/star
+pairs agree on: every pair within `max_offset` votes for its own offset
+in `bin`-pixel cells, and the winning cell's pairs are averaged. Random
+pairings spread their votes thinly over the whole `max_offset` square;
+true pairings all land in one cell, so this finds the header's error
+without needing it to already be small.
+"""
+function _vote_offset(det_xy, predicted, max_offset::Real; bin::Real=2.0)
+    votes = Dict{Tuple{Int,Int},Vector{Tuple{Float64,Float64}}}()
+    for (px, py, _, _) in predicted, (dx_, dy_) in det_xy
+        ox, oy = dx_ - px, dy_ - py
+        (abs(ox) <= max_offset && abs(oy) <= max_offset) || continue
+        push!(get!(votes, (floor(Int, ox / bin), floor(Int, oy / bin)), Tuple{Float64,Float64}[]), (ox, oy))
+    end
+    isempty(votes) && return (0.0, 0.0)
+    # Count each cell together with its 8 neighbours, so a true offset
+    # sitting on a cell boundary isn't split across two cells.
+    neighbourhood(c) = (get(votes, (c[1] + a, c[2] + b), ()) for a in -1:1, b in -1:1)
+    best = argmax(c -> sum(length, neighbourhood(c)), collect(keys(votes)))
+    pairs = collect(Iterators.flatten(neighbourhood(best)))
+    return (median(first.(pairs)), median(last.(pairs)))
+end
+
+function _match_stars(det_xy, predicted, offset, match_radius::Real)
+    matches = Tuple{Float64,Float64,Float64,Float64}[]   # (x, y, ra, dec)
+    used = Set{Int}()
+    for (px, py, ra, dec) in predicted
+        tx, ty = px + offset[1], py + offset[2]
+        best, best_dist = 0, Float64(match_radius)
+        for (i, (x, y)) in enumerate(det_xy)
+            d = hypot(x - tx, y - ty)
+            d <= best_dist && ((best, best_dist) = (i, d))
+        end
+        (best == 0 || best in used) && continue
+        push!(used, best)
+        push!(matches, (det_xy[best]..., ra, dec))
+    end
+    return matches
+end
+
+"""
+    _gnomonic(ra, dec, crval) -> (xi, eta)
+
+Standard (tangent-plane) coordinates of `(ra, dec)` about tangent point
+`crval`, in degrees — FITS's intermediate world coordinates for a TAN
+projection, so a linear fit of pixels to these *is* a TAN WCS solution.
+"""
+function _gnomonic(ra::Real, dec::Real, crval)
+    a0, d0 = crval
+    cosc = sind(d0) * sind(dec) + cosd(d0) * cosd(dec) * cosd(ra - a0)
+    xi = cosd(dec) * sind(ra - a0) / cosc
+    eta = (cosd(d0) * sind(dec) - sind(d0) * cosd(dec) * cosd(ra - a0)) / cosc
+    return rad2deg(xi), rad2deg(eta)
+end
+
+function _fit_tan(matches, crval, clip_sigma::Real)
+    keep = trues(length(matches))
+    local a, b, rms
+    while true
+        m = matches[keep]
+        X = hcat(ones(length(m)), [p[1] for p in m], [p[2] for p in m])
+        std_coords = [_gnomonic(p[3], p[4], crval) for p in m]
+        a = X \ first.(std_coords)
+        b = X \ last.(std_coords)
+        all_X = hcat(ones(length(matches)), [p[1] for p in matches], [p[2] for p in matches])
+        all_std = [_gnomonic(p[3], p[4], crval) for p in matches]
+        resid = hypot.(all_X * a .- first.(all_std), all_X * b .- last.(all_std)) .* 3600
+        rms = sqrt(mean(resid[keep] .^ 2))
+        # Monotone: a rejected match never comes back, so each pass drops at
+        # least one or stops. Re-admitting them could oscillate forever on
+        # near-noiseless data, where residuals sit right at the threshold.
+        new_keep = keep .& (resid .<= max(clip_sigma * rms, 1e-3))
+        (new_keep == keep || count(new_keep) < 3) && break
+        keep = new_keep
+    end
+    cd = [a[2] a[3]; b[2] b[3]]
+    crpix = -(cd \ [a[1], b[1]])
+    wcs = WCSTransform(2; ctype=["RA---TAN", "DEC--TAN"], crval=[crval[1], crval[2]],
+                       crpix=crpix, cdelt=[1.0, 1.0], pc=cd)
+    return (wcs=wcs, n=count(keep), rms_arcsec=rms)
+end
+
+"""
+    _field_reference_stars(image, wcs, epoch_jd) -> Table
+
+[`gaia_reference_stars`](@ref) covering all of `image`'s footprint
+(through `wcs`), with a 10% margin for the header WCS's own error.
+"""
+function _field_reference_stars(image::AbstractMatrix, wcs::WCSTransform, epoch_jd::Real)
+    n1, n2 = size(image)
+    centre = pix_to_world(wcs, Float64[n2 / 2, n1 / 2])
+    corners = (pix_to_world(wcs, Float64[x, y]) for (x, y) in ((1, 1), (n2, 1), (1, n1), (n2, n1)))
+    radius = 1.1 * maximum(_angular_distance_arcsec(centre..., c...) for c in corners) / 3600
+    return gaia_reference_stars(centre[1], centre[2], radius; epoch_jd)
+end