itof op• Data kinds: table → table
• Call: import fullseye as fs; fs.ledger.itof_unwrap_multifreq(phase, frequencies_hz=None, weights=None, max_range_m=None, method='ml') (implementation को सीधे call करना हो तो import itof; itof.itof_unwrap_multifreq(phase, frequencies_hz=None, weights=None, max_range_m=None, method='ml'), registry से लेना हो तो opsoptics.get("itof_unwrap_multifreq"))
कई frequency की phase → depth (multi-frequency unwrapping)। table लौटाता है।
> नीचे का विस्तृत विवरण मूल text में है — सारांश और headings का अनुवाद हो चुका है।
周波数 f_i の位相 φ_i は距離を周期 p_i = c/(2 f_i) の剰余 r_i = φ_i p_i / (2π) で教える。周期の最小公倍数 U = c / (2·gcd f) までが一意(非曖昧距離)。
• method="ml"(既定)—— 最も高い周波数(距離の誤差が最も小さい帯)の剰余を錨にして、その次数の仮説 v = r_hi + k p_hi(k = 0 … U/p_hi)を全部、フェーザの一致 Σ w_i cos(2π(v − r_i)/p_i) で採点し、最良の仮説を逆分散の重み平均で精密化する(仮説を全部試す最尤の復号。位相雑音が帯ごとに同じなら、錨の誤差が最も小さい)。
• method="crt" —— residue.residue_crt(重みつきの頑健な中国剰余定理)にそのまま渡す。★residue_crt は Wang–Xia(2010)の錨の選び方 —— 雑音の分散 p²/w が最小の帯、同分散なら剰余 mod Γ が円上の最小二乗の共通剰余に最も近い帯 —— で錨を選ぶので、位相雑音が帯ごとに同じ iToF でも "ml" と同等になる(PoC の合成 0.1161 対 0.1160、実データ 0.131 対 0.131。以前の、常に最も長い周期を錨にする実装は 0.556 / 0.293 と大きく誤った)。保証(itof_unwrap_error_rate の guaranteed_phase_rad)の外の画素があると residue.ResidueBoundWarning を出す(値は返す)。
• method="beat" —— 2 周波だけ。うなりの位相 φ_1 − φ_2 で粗い距離(周期 c/(2|f_1 − f_2|))を出し、各周波数の次数をそれに最も近く丸めて重み平均する(教科書の古典的な方法)。
*weights* の既定は、itof_phase_amplitude の表なら A²/B(∝ 1/σ_φ²)、配列なら全帯 1。*max_range_m* で探す範囲 [0, max_range_m) を狭められる(非曖昧距離より広くは拒否)。
返す dict: depth、order (F, ...)(各周波数で何周目か)、margin(最良と次点の採点の差。小さい = 次数が際どい)、score、residual (F, ...) [m]、unambiguous_range、periods、method。
Raises ValueError: 周波数・位相の形が合わない / 周期が通約できない(非曖昧距離が有限でない)/ max_range_m が非曖昧距離より広い / beat で 2 周波でない / method が不正 / 仮説 × 画素が上限を超える。
optics के सभी ops गणना से पहले input की जाँच करते हैं (कुछ भी चुपचाप पास नहीं होता):
• Unit argument के नाम में ही लिखी होती है — _mm / _um / _deg / _mrad। mm और µm की गड़बड़ी crash नहीं करती, बल्कि "सही दिखने वाला पर गलत उत्तर" देती है, इसलिए नाम से इसे रोका जाता है। मान के आकार से unit का अनुमान बिल्कुल नहीं लगाया जाता।
• String से ValueError — float('50') सफल हो जाता है, इसलिए बिना parse किया config value length के रूप में निकल जाता (मापा गया: thin_lens('50', '200') सही दिखने वाला 66.667 mm लौटा रहा था)। bool को भी True == 1 वाले implicit promotion के रूप में अस्वीकार किया जाता है।
• complex / masked array से ValueError (केवल real-valued slots; imaginary part को चुपचाप छोड़ना या mask हटाना अस्वीकार)। हर input पर NaN/Inf से ValueError।
• शून्य से भाग और उससे जुड़े मामलों को नाम लेकर अस्वीकार किया जाता है: focal length 0, radius of curvature 0, refractive index <= 0, पूरी तरह opaque aperture (सब 0, इसलिए normalisation 0/0), ऐसा PSF जिसका योग <= 0 हो, S0 = 0 वाला Stokes vector, और front focal point पर रखा object (image अनंत पर)।
• केवल 2 ops non-finite value लौटाते हैं, और वह भी contract के रूप में लिखा हुआ: depth_of_field hyperfocal distance से आगे far_mm = inf (hyperfocal distance की परिभाषा यही है) और gaussian_beam waist पर wavefront_radius_mm = inf (plane wavefront की radius of curvature)। दोनों साथ में एक finite साथी (far_is_infinite / curvature_per_mm) भी लौटाते हैं। इसके अलावा कोई भी चुपचाप आया NaN/Inf अंदर ही पकड़ा जाता है और ValueError देता है — "float64 overflow हुआ" और "उत्तर अनंत है" अलग-अलग दावे हैं, इसलिए पहले को दूसरे का चेहरा पहनाकर नहीं लौटाया जाता।
• Size की सीमा: generate होने वाले grid के लिए optics.MAX_GRID (4096), दिए गए field/PSF/aperture के लिए optics.MAX_FIELD_ELEMENTS (2^24), ABCD element chain के लिए optics.MAX_SYSTEM_ELEMENTS (1024), Zernike के लिए MAX_ZERNIKE_TERMS (512) / MAX_ZERNIKE_ORDER (40) / MAX_ZERNIKE_BASIS (2^25)। छोटे argument से बहुत बड़ा internal allocation होने वाले रास्तों (मापा गया: n_max=40 × 4096² पर 108 GB) को fail-closed ढंग से बंद किया गया है।
• भौतिक रूप से असंभव states भी अस्वीकार: degree of polarisation > 1 वाला Stokes vector, ऋणात्मक transmittance, ऋणात्मक intensity, और n-|m| odd जैसे अमान्य Zernike indices।
• Sample data catalog (DL URL / license) — 2-D के लिए skimage.data (BSD/public) + synthetic, 3-D के लिए real data sources (Stanford/PDS आदि) के DL URL।
• Operators का स्रोत और संदर्भ — इस op family के मूल research/methods के स्रोत।
• Algorithm का मानक स्रोत (लेखक, वर्ष) और उपयोग ऊपर की family usage guide में दिए गए हैं।
• poc_itof_multifreq — py -3.11 examples/poc_itof_multifreq.py
table को input के रूप में लेते हैं)abcd_matrix · wavefront_stats · sfr_from_edge · paraxial_trace · seidel_coefficients · spot_stats · tolerance_analysis · wavefront_from_opd
itof)itof_capture · itof_phase_amplitude · itof_noise_budget · itof_unwrap_error_rate · itof_multipath_separate · itof_flying_pixel_mask · itof_wiggling_correct
*Provenance: itof.py — OPTICS operator registry. यह per-op note tools/opdocs.py md से अपने-आप generate होता है (हाथ से edit न करें)।*
© 2026 Kazufumi Furuse — Fullseye operator documentation. Licensed under Apache-2.0.