watermedia op• Data kinds: कोई नहीं → table (केवल arguments से तय होने वाला op — यह कोई image या data input नहीं लेता)
• Call: import fullseye as fs; fs.ledger.ocean_height_field(size, extent_m, wind_speed_mps, wind_dir_deg, t=0.0, seed=0, kind='pierson_moskowitz', directional='cos2', choppiness=0.0, depth_m=None, spreading_s=10.0, fetch_m=None, single_mode=None) -> 'dict' (implementation को सीधे call करना हो तो import watermedia; watermedia.ocean_height_field(size, extent_m, wind_speed_mps, wind_dir_deg, t=0.0, seed=0, kind='pierson_moskowitz', directional='cos2', choppiness=0.0, depth_m=None, spreading_s=10.0, fetch_m=None, single_mode=None) -> 'dict', registry से लेना हो तो opsoptics.get("ocean_height_field"))
• GPU: नहीं (केवल CPU reference implementation)
समय t पर Tessendorf (2001) FFT समुद्र-सतह -> dict (ऊँचाई, ढलान, normal map, विस्थापन)।
> नीचे का विस्तृत विवरण मूल text में है — सारांश और headings का अनुवाद हो चुका है।
The wave-number spectrum is the omnidirectional spectrum of ocean_spectrum carried to the plane, psi(k, theta) = S(omega) D(theta) (d omega / d k) / k, with the dispersion omega^2 = g k (deep water) or omega^2 = g k tanh(k h) when depth_m is given. D is cos2 (2/pi cos^2 within 90 degrees of the wind) or cos2s (cos^(2s)((theta - theta_w) / 2), s = spreading_s), both normalised to 1 over the circle. The random amplitudes are h0(k) = (xi_r + j xi_i)/sqrt(2) sqrt(psi / 2) dk and h(k, t) = h0(k) e^(-j omega t) + conj(h0(-k)) e^(+j omega t), which is Hermitian, so the height is real (imag_residual reports the largest imaginary part left by the transform). The mean, the Nyquist row and column are zeroed. seed fixes the amplitudes:
the same seed gives the same sea at every t. choppiness moves each point horizontally by choppiness times the Tessendorf displacement (0 gives exactly zero displacement). size is the number of points per side (the grid is size x size over extent_m metres, wrap-around); wind_dir_deg is the direction the waves travel, from +x towards +y. single_mode=(mx, my, amplitude_m) replaces the random sea with one travelling cosine wave. The table has height, slope_x, slope_y (dh/dx, dh/dy), normal (H, W, 3), displacement_x / displacement_y, x_m / y_m, extent_m, variance_expected_m2 and slope_variance_expected (the sums of the spectrum over the modes in use), cox_munk_slope_variance (0.003 + 0.00512 U, Cox & Munk 1954), slope_variance_with_tail and omega_mode (single mode only). A sea of this kind has no capillary waves, so its resolved slope variance is far below the Cox & Munk value; slope_variance_with_tail adds the saturation range alpha / 2 ln(k_c / k_nyquist) of the spectrum up to the gravity-capillary wave number k_c = 370 rad/m. That agrees with Cox & Munk at 5 m/s and falls 40 % short at 10 m/s (the constant alpha of the Pierson-Moskowitz range does not grow with the wind); both are shown in the PoC.
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_water_inspection_images — py -3.11 examples/poc_water_inspection_images.py
• poc_water_transparent_media — py -3.11 examples/poc_water_transparent_media.py
table को input के रूप में लेते हैं)abcd_matrix · wavefront_stats · sfr_from_edge · paraxial_trace · seidel_coefficients · spot_stats · tolerance_analysis · wavefront_from_opd
watermedia)ocean_spectrum · fresnel_water_air · snell_window · refracted_view · water_attenuation · underwater_image · phase_function_hg · scattering_phase_petzold
*Provenance: watermedia.py — OPTICS operator registry. यह per-op note tools/opdocs.py md से अपने-आप generate होता है (हाथ से edit न करें)।*
© 2026 Kazufumi Furuse — Fullseye operator documentation. Licensed under Apache-2.0.