fpm op• 資料種類:table → table
• 呼叫: import fullseye as fs; fs.ledger.fp_reconstruct(stack, upsample=None, n_iter=200, pupil_update=True, pupil_start=2, alpha=1.0, beta=1.0, led_correction=False, led_start=3, stall_tol=0.01, stall_window=10, agree_tol=0.08, starts=2, margin_px=None, intensity_correction=False, pupil_degree=4, on_fail='raise')(要直接呼叫實作,import fourierptycho; fourierptycho.fp_reconstruct(stack, upsample=None, n_iter=200, pupil_update=True, pupil_start=2, alpha=1.0, beta=1.0, led_correction=False, led_start=3, stall_tol=0.01, stall_window=10, agree_tol=0.08, starts=2, margin_px=None, intensity_correction=False, pupil_degree=4, on_fail='raise');從台帳取用則 opsoptics.get("fp_reconstruct"))
• GPU:無(僅 CPU 參考實作)
從一組低解析度影像恢復高解析度的振幅與相位(table,kind="fp_result")。不收斂則拒絕。
逐次相位還原(Ou 等人 2014 的 EPRY,與 ePIE 形式相同):依照明 NA 由小到大逐張處理,將估計的低解析度場的振幅替換為量測到的振幅,以其差值用步長 alpha 修正物體頻譜、用步長 beta 修正光瞳(光瞳從第 pupil_start 次起修正,圓外保持為 0)。
• pupil_degree(預設 4):將光瞳相位的更新投影到在圓上正交化的 2–4 階多項式(12 個;離焦、像散、彗差、球差等低階像差),振幅保持為 1。None 為逐像素自由的 EPRY(原論文的形式)—— ★自由光瞳會吸收雜訊,殘差持續下降而不停滯(32 像素、25 張的合成資料中,200 次後每 10 次仍超過 1 %)。
• upsample:高解析度網格的倍率。為 None 時取能容納照明 NA 且像素不大於 λ/(2 NA_syn) 的最小整數。
• led_correction:從第 led_start 次起,對每張影像在 ±1 像素的 9 種光瞳中心上試算並取殘差最小者(平手時以捨入後的值比較,取候選宣告順序中較前者),接著以最小平方法將 LED 陣列的幾何(偏移 x、y,旋轉,高度)擬合到表中的 led_xyz_mm,並把中心重設為其預測值(將 Sun 等人 2016 的模擬退火替換為確定性的局部搜尋)。
• intensity_correction:從第 3 次起將各影像的亮度比對齊到估計的平均值(針對 LED 亮度未知的真實資料)。照明 NA 最小的影像作為基準不動 —— ★若全部都動,估計變亮時量測影像也會被重新調亮,形成正回饋,在真實資料上殘差 200 次內發散到 2 萬倍(光瞳投影到多項式時)。
• 收斂:振幅相對殘差達到不動點 且 初值不同的 2 條(starts=2)在 agree_tol 以內一致。殘差不下降、次數用盡、2 條到達不同答案,任一情況皆視為「不收斂」。on_fail="raise"(預設)拋出 FPNotConvergedError(MetricContractError,記錄於 record), "record" 傳回記錄(converged=False)。
• starts=1 不經過唯一性的門(僅憑停滯就可能 converged=True):uniqueness_checked 為 False, 並在 reason 中附加「uniqueness not checked」。
• 殘差的上限:收斂判定只看殘差的變化。最終殘差超過 RESIDUAL_WARN(0.1)時, 設 residual_warning=True 並在 reason 中附加警告(判定不變)。合成資料實測:收斂的復原為 0.004〜0.03 (含 rms 0.12 波的像差),與照明 k 無關的隨機影像在單一初值下停滯於 0.17。
傳回值:dict(kind="fp_result", converged, reason, n_iter, residual, residual_history, residual_history_starts, step_history(每一輪物體頻譜的相對變化), start_disagreement, field_second_start, amplitude, phase, field, pupil, pupil_support, na_synthetic (= NA_obj + 所用照明 NA 的最大值,含對角 LED), na_synthetic_axis(取 x、y 方向餘弦最大值得到的值 = 決定沿軸向線條解析度的值), pixel_um, upsample, margin_px, led_centres, led_geometry, intensity_scale, uniqueness_checked, residual_warning, residual_ceiling)。
Raises: ValueError(表不完整或值超出範圍、影像能量為 0(除以曝光後、去掉邊緣的全部影像之和)、LED 校正擬合的幾何把光瞳中心放到了高解析度網格之外)。
optics 的每個運算子都先檢驗輸入再計算(不讓任何東西無聲通過):
• 單位寫進參數名 —— _mm / _um / _deg / _mrad。把 mm 和 µm 弄混不會當掉,而是給出「看似合理卻是錯的答案」,所以用命名來防。這裡絕不從數值大小去猜單位。
• 字串一律 ValueError —— float('50') 會成功,於是未解析的設定值會被當成長度混進來(實測:thin_lens('50', '200') 曾回傳看似合理的 66.667 mm)。bool 也按 True == 1 的隱式提升拒絕。
• complex / masked array 一律 ValueError(僅接受實數槽位;拒絕無聲丟棄虛部或剝掉遮罩)。所有輸入中的 NaN/Inf 一律 ValueError。
• 逐項點名拒絕除零及其近親:焦距 0、曲率半徑 0、折射率 <= 0、全不透明光闌(全為 0,正規化變成 0/0)、總和 <= 0 的 PSF、S0 = 0 的 Stokes 向量、物體位於前焦點(像在無窮遠)。
• 只有兩個運算子會回傳非有限值,而且都寫進了契約:depth_of_field 在超焦距以外回傳 far_mm = inf(這正是超焦距的定義),gaussian_beam 在束腰處回傳 wavefront_radius_mm = inf(平面波前的曲率半徑)。兩者都同時回傳一個有限的夥伴(far_is_infinite / curvature_per_mm)。除此之外的無聲 NaN/Inf 都在內部檢出並 ValueError ——「float64 溢位了」和「答案是無窮大」是兩種不同的主張,不能拿後者的臉去交付前者。
• 尺寸上限:生成網格受 optics.MAX_GRID(4096)限制,傳入的場/PSF/光闌受 optics.MAX_FIELD_ELEMENTS(2^24),ABCD 元件序列受 optics.MAX_SYSTEM_ELEMENTS(1024),Zernike 受 MAX_ZERNIKE_TERMS(512)/ MAX_ZERNIKE_ORDER(40)/ MAX_ZERNIKE_BASIS(2^25)。以 fail-closed 堵住「小參數引發巨大內部配置」的路徑(實測:n_max=40 × 4096² 需要 108 GB)。
• 物理上不可能的狀態同樣拒絕:偏振度 > 1 的 Stokes 向量、負穿透率、負強度、n-|m| 為奇數等非法 Zernike 指標。
• 範例資料目錄(下載 URL / 授權) —— 2-D 用 skimage.data(BSD/公有領域)加合成圖,3-D 給出真實資料源(Stanford/PDS 等)的下載 URL。
• 運算子來歷與參考文獻 —— 該運算子族所依據的研究/方法出處。
• 演算法的正典(作者、年份)與用途見上面的族使用指南。
• poc_fourier_ptychography — py -3.11 examples/poc_fourier_ptychography.py
table 作為輸入)abcd_matrix · wavefront_stats · sfr_from_edge · paraxial_trace · seidel_coefficients · spot_stats · tolerance_analysis · wavefront_from_opd
fpm)fp_design · fp_usaf_target · fp_capture · fp_stack_from_images · fp_element_contrast
*Provenance: fourierptycho.py — OPTICS 運算子登記表。本條目由 tools/opdocs.py md 自動產生(請勿手動編輯)。*
© 2026 Kazufumi Furuse — Fullseye operator documentation. Licensed under Apache-2.0.