fourier_plane_filter — OPTICS `wave` op

• 資料種類:無 → cimage(僅由參數決定的運算子 —— 不接受影像或資料輸入)

• 呼叫: import fullseye as fs; fs.ledger.fourier_plane_filter(size=64, kind='derivative_x', order=1, charge=1, radius_frac=0.25, pixel_pitch_um=1.0)(要直接呼叫實作,import optics; optics.fourier_plane_filter(size=64, kind='derivative_x', order=1, charge=1, radius_frac=0.25, pixel_pitch_um=1.0);從台帳取用則 opsoptics.get("fourier_plane_filter"))

用法

置於 4f 系統傅立葉面上的複數穿透函數 H(fx, fy)。

回傳 numpy.fft.fftfreq 排列(不做 fftshift)的 complex128 (size, size)，可直接傳給 four_f_filter。空間頻率的單位為 cycles/um(fftfreq(size, d=pixel_pitch_um))。

*kind*：

identity

H = 1。4f 系統只成像 —— 輸出為輸入的 180 度旋轉。

block

H = 0。輸出嚴格為零(傅立葉面被遮擋的狀態)。

derivative_x / derivative_y

H = (i*2*pi*f)**order。輸出為 *order* 階空間導數。透鏡計算導數就是這 1 行，是光學運算的核心。

laplacian

H = -(2*pi)**2 * (fx**2 + fy**2)。等向性的 2 階導數。

lowpass / highpass

|f| <= radius_frac * f_nyquist 的圓形孔徑(及其補集)。

f_nyquist = 1/(2*pixel_pitch_um)。空間濾波的教科書範例。

hilbert_x

H = -i*sign(fx)(fx = 0 以及偶數長度時的奈奎斯特頻點為 0)。

單側相位使邊緣凸顯 —— 紋影法的數值版。★將奈奎斯特設為 0

是因為 fftfreq 在偶數長度時只回傳 -1/2，沒有成對的 +1/2，

若保留，實偶函數的輸出將不嚴格滿足奇對稱

(實測 1.6e-09 → 設為 0 後 2.3e-16)。這是離散希爾伯特轉換的標準處理。

vortex

H = exp(i*charge*phi) 的渦旋相位板。*charge* 是相位的纏繞數，

沿傅立葉面的封閉路徑繞 1 圈，相位嚴格前進 2*pi*charge

—— 這是整數不變量，因此可作為門檻。★DC 項設為 0(因為 phi 在

原點無定義)。結果平均值被去除，所以此板發揮

等向性邊緣增強(徑向希爾伯特轉換)的作用。

真值(本 op 所重現的內容)：

• identity 經過 four_f_filter 後與輸入的 180 度旋轉一致 —— 實測最大絕對差 3.4e-16(64x64 高斯，pixel_pitch_um=1)。並非逐位元一致：FFT 的往返會帶入 1e-16 的碎屑。若像零距離傳播那樣短路處理即可做到嚴格，但那就成了只對 identity 的特殊處理。

• derivative_x order=1 作用於高斯 exp(-x**2/w**2) 時與 -2x/w**2 * exp(-x**2/w**2) 一致(在頻帶限制範圍內)。

• vortex 的纏繞數：封閉路徑上相位差之和除以 2*pi 嚴格等於 *charge*。

• lowpass + highpass = identity(相同 *radius_frac* 下嚴格為 1)。

Raises ValueError：*kind* 不在上述列表中 / *size* 小於 2 或超過 MAX_GRID / *order* 在 0..8 之外 / *charge* 在 -32..32 之外 / *radius_frac* 為 0 以下或超過 1 / *pixel_pitch_um* 非正、非有限。

該族通用的輸入契約(fail-closed)

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 指標。

詳細使用指南

• optics_imaging 族使用指南

參考(範例資料、文獻)

• 範例資料目錄(下載 URL / 授權) —— 2-D 用 skimage.data(BSD/公有領域)加合成圖,3-D 給出真實資料源(Stanford/PDS 等)的下載 URL。

• 運算子來歷與參考文獻 —— 該運算子族所依據的研究/方法出處。

• 演算法的正典(作者、年份)與用途見上面的族使用指南。

可執行的範例(實際呼叫該運算子並已驗證的樣例)

• optics_four_f_processor — py -3.11 examples/optics_four_f_processor.py

型別可銜接的下一個運算子(可接受 `cimage` 作為輸入)

angular_spectrum_propagate · four_f_filter · jones_apply

同類別(`wave`)

airy_pattern · angular_spectrum_propagate · fraunhofer_pattern · four_f_filter · gaussian_beam · defocus_from_shift · pupil_psf · pupil_blur

*Provenance: optics.py — OPTICS 運算子登記表。本條目由 tools/opdocs.py md 自動產生(請勿手動編輯)。*

fourier_plane_filter — OPTICS wave op

用法