synth op• 数据种类:无 → image2d(仅由参数决定的算子 —— 不接受图像或数据输入)
• 调用: import fullseye as fs; fs.ledger.synth_starfield(shape=(128, 128), n_stars=30, flux_min=400.0, flux_max=9000.0, fwhm_px=3.2, psf='gaussian', moffat_beta=2.5, sky=60.0, read_sigma=6.0, shift_row=0.0, shift_col=0.0, n_cosmic=0, cosmic_flux=4000.0, margin_px=6.0, seed=0, field_seed=None, noise=True)(要直接调用实现,import astrostack; astrostack.synth_starfield(shape=(128, 128), n_stars=30, flux_min=400.0, flux_max=9000.0, fwhm_px=3.2, psf='gaussian', moffat_beta=2.5, sky=60.0, read_sigma=6.0, shift_row=0.0, shift_col=0.0, n_cosmic=0, cosmic_flux=4000.0, margin_px=6.0, seed=0, field_seed=None, noise=True);从台账取用则 opsastrostack.get("synth_starfield"))
• 经台账调用的返回值: fullseye.ledger.synth_starfield(...) 只返回声明的 out 类型 image2d 的值(底层函数还会返回辅助信息)。需要被丢弃的部分时,使用 fullseye.ledger.synth_starfield.raw(...),或直接调用 astrostack.synth_starfield。
• 底层返回: (frame, truth) -> image2d
合成一张已知的星场 —— 这一族真值的来源。
每颗星从 flux_min〜flux_max 的对数均匀分布中抽取总通量(电子)，均匀放在距图像边缘 margin_px 以上的内侧。*psf* 为 "gaussian"
时是用 scipy.special.erf 做的像素精确积分，所以 1 颗星的总和与给定通量(除去落到图像外的部分)严格一致。"moffat" 是 Moffat, *A Theoretical Investigation of Focal Stellar Images*, A&A 3, 455 (1969) 的 (1 + (r/alpha)^2)^(-beta)，是由地面大气主导的星像标准模型(衍射极限的兄弟是 optics.airy_pattern)。
噪声只遵循 1 种理论 —— 在 Poisson(星 + sky)(以 photons_per_unit=1.0 调用 photoncount.photon_sample)上，之后加上宇宙线，最后 加上加性高斯读出噪声 read_sigma。顺序与物理一致，宇宙线不是光子(不经过 Poisson 采样)。宇宙线的位置交给 defectgen.defect_pits 的均匀点过程 —— “稀少、小而尖锐、位置随机的附着”与点蚀是同一种随机几何，没有理由再写第二个模型。
*shift_row* / *shift_col* 以亚像素移动整个星场(抖动)。合成的真值坐标也随之移动，所以可用于配准和 drizzle 的验算。
Returns (frame, truth)：
• frame —— (H, W) float64，单位为电子。
• truth —— dict。rows / cols (N,) 为星的真实中心(整数坐标为像素中心的约定)，fluxes (N,) 为真实总通量，fwhm_px / sigma_px / alpha_px / beta 为 PSF，sky / read_sigma 为噪声，cosmic_mask (H, W) bool 为宇宙线像素，noiseless (H, W) 为加噪声前的期望值(用于验算)。
seed 有 2 个。 field_seed 决定星场(坐标与通量)，seed 决定那一次的观测(散粒噪声、读出噪声、宇宙线位置)。field_seed=None 时取与 seed 相同的值。分开的理由是
实测中发现的事故：在只有 1 个 seed 的最初版本中，synth_frame_series 每帧改变 seed，结果 星场本身每帧都不同，配准只找到 1 个对应(frame_align 正确地 fail-closed(失败即拒绝)了)，帧间的宇宙线去除返回了“全部像素都是离群值”。重拍同一片天空与拍另一片天空，只差 1 个参数就会混淆 —— 所以不是靠类型而是靠名字来区分。两者的随机数都是 numpy.random.default_rng，所以相同的 seed 对在任何机器上都得到相同的帧。
Ground truth it reproduces(由 tests/test_astrostack.py 固定)：在 noise=False、sky=0、fwhm_px=3.0 的 1 星帧(64x64、通量 5000 e-)中，整幅图像的总和与给定通量的相对误差为 1.8e-16 —— 相当于 float64 的 1 次舍入，不是“几乎守恒”而是守恒。半径 r 的圆形孔径收集的比例为 1 - exp(-r^2/(2 sigma^2))，r = 2 sigma 时为 0.8647，r = 3 sigma 时为 0.98889。
Raises ValueError：*shape* 太小 / *n_stars* 不是非负整数 / flux_min > flux_max / *psf* 不在 PSF_MODELS 中 / moffat_beta <= 1(积分发散)/ margin_px 大于图像 / *seed* 不是非负整数时。
• 示例数据目录(下载 URL / 许可证) —— 2-D 用 skimage.data(BSD/公有领域)加合成图,3-D 给出真实数据源(Stanford/PDS 等)的下载 URL。
• 算子来历与参考文献 —— 该算子族所依据的研究/方法出处。
• 算法的正典(作者、年份)与用途见上面的族使用指南。
• astro_stacking — py -3.11 examples/astro_stacking.py
• poc_astro_photometry — py -3.11 examples/poc_astro_photometry.py
image2d 作为输入)frame_quality · noise_sigma · cosmic_ray_reject · star_detect · psf_fit · aperture_photometry · frame_align
synth)*Provenance: astrostack.py — ASTROSTACK 算子登记表。本条目由 tools/opdocs.py md 自动生成(请勿手工编辑)。*
© 2026 Kazufumi Furuse — Fullseye operator documentation. Licensed under Apache-2.0.