itof op• Data kinds: table → table
• Call: import fullseye as fs; fs.ledger.itof_phase_amplitude(samples, frequencies_hz=None, phase_offsets_rad=None, read_noise_e=None) (implementation को सीधे call करना हो तो import itof; itof.itof_phase_amplitude(samples, frequencies_hz=None, phase_offsets_rad=None, read_noise_e=None), registry से लेना हो तो opsoptics.get("itof_phase_amplitude"))
• GPU: नहीं (केवल CPU reference implementation)
K-step raw signal → phase, amplitude, offset, wrapped depth और हर pixel के depth noise का अनुमान (table)।
> नीचे का विस्तृत विवरण मूल text में है — सारांश और headings का अनुवाद हो चुका है।
*samples* は itof_capture の dict、または (F, K, ...) の配列(周波数 F、段 K が先頭。1 周波なら samples[None])。段 k のバケットを m_k = B + A·cos(φ − θ_k) とみなし、[1, cos θ_k, sin θ_k] の最小二乗で B・A cos φ・A sin φ を解く(θ_k が等間隔 2πk/K なら DFT と同じ。4 段なら φ = atan2(m1 − m3, m0 − m2)、A = ½√((m0 − m2)² + (m1 − m3)²)、B = Σm_k / 4)。θ_k は *phase_offsets_rad*(既定は等間隔、dict ならその値)。
距離の雑音の見積もり: 各バケットの分散を B + read_noise²(ショット雑音は平均に等しい)とみなすと、最小二乗の共分散から位相の標準偏差 σ_φ が出る(4 段・等間隔なら σ_φ = √((B + σ_r²)/2) / A)。σ_d = c σ_φ / (4π f)。★小さい雑音の近似で、A ≈ √B 程度まで SNR が落ちると実際の散らばりはこれより大きい。
返す dict: kind("itof_phase")、phase (F, ...) [0, 2π)、amplitude、offset、phasor (A·e^{iφ}、複素)、frequencies_hz(分かれば)、wrapped_depth と ambiguity_range(周波数が分かれば)、phase_sigma、depth_sigma(周波数が分かれば)。
★振幅が無い画素・飽和の印(2026-11-09):
• A ≤ 1e-9 · max_k |m_k|(その画素のバケットの大きさに対して丸め屑)の画素は A = 0 と同じに扱い、phase 0・phase_sigma / depth_sigma は inf。全バケットが等しい(完全に飽和した) 画素は A が丸め屑 6e-13 で A > 0 を通り、位相 0.49 rad・距離 0.59 m というでたらめの値を有限の depth_sigma(1e14)つきで返していた。
• offset B ≤ 0 で読み出し雑音が 0 の画素(暗電流を引いたデータ)は分散を見積もれないので phase_sigma inf(以前は 0 =「雑音ゼロ」と主張していた)。
• saturated (F, ...) bool: その画素のどれかのバケットが配列全体の最大値と等しく、かつその最大値に 2 つ以上の標本が並ぶ(= 天井がある)。full well を知らないので天井から推す印で、valid は無い(値は変えない)。バケットの 40 % がクリップされた画素は距離が最大 12 cm ずれても depth_sigma は 3.3 cm のまま(式は飽和を知らない)—— この印を見て捨てる。★雑音のない整数の画像で、飽和していないのに最大値がたまたま 2 回出ると誤って印が付く(雑音ありの 240×320 で 10 枚中 1 枚・2 画素)。★見逃しは黙る(独立レビュー 2026-11-09): クリップの後に画素ごとの暗電流を引いたデータは天井が 1 つの値でなくなり、5 画素中 1 画素にしか印が付かない。天井より明るい画素が 1 つでもある(露光を合成した HDR など)と最大値が天井でなくなり、印は全部消える。どちらも飽和の判定は補正前の生データ(または full well を知る呼び手)でする。
Raises ValueError: 配列が 2 次元未満・非有限 / 段の数が 3〜32 でない / 段の位相が退化 / 周波数の数が F と合わない・範囲外 / dict が生信号でない。
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। घोषित अपवाद: bottle_fit_from_pattern का u_map न मापे जा सके पिक्सेल को NaN के रूप में लेता है (अनंत अब भी अस्वीकार)।
• शून्य से भाग और उससे जुड़े मामलों को नाम लेकर अस्वीकार किया जाता है: 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 हुआ" और "उत्तर अनंत है" अलग-अलग दावे हैं, इसलिए पहले को दूसरे का चेहरा पहनाकर नहीं लौटाया जाता। घोषित अपवाद: bottle_background_map जिन पिक्सेल की किरण अनुपयोगी है (पूर्ण आंतरिक परावर्तन आदि) उनके लिए u_mm में NaN लौटाता है, साथ में valid मास्क और गिनती भी।
• 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_3d_sensor_modalities — py -3.11 examples/poc_3d_sensor_modalities.py
• 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_noise_budget · itof_unwrap_multifreq · 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.