watermedia op• Data kinds: कोई नहीं → table (केवल arguments से तय होने वाला op — यह कोई image या data input नहीं लेता)
• Call: import fullseye as fs; fs.ledger.refracted_view(points_xyz, eye_xyz, surface='flat', n_water=None, wavelength_um=0.55) -> 'dict' (implementation को सीधे call करना हो तो import watermedia; watermedia.refracted_view(points_xyz, eye_xyz, surface='flat', n_water=None, wavelength_um=0.55) -> 'dict', registry से लेना हो तो opsoptics.get("refracted_view"))
समतल या लहरदार सतह के ऊपर रखे camera को जल के भीतर का बिंदु कहाँ दिखता है (Fermat का सिद्धांत) -> dict।
> नीचे का विस्तृत विवरण मूल text में है — सारांश और headings का अनुवाद हो चुका है।
points_xyz is (M, 3) (or one point), z up and the mean water level z = 0; eye_xyz is the camera, above the surface. A point with z >= surface height is in the air and is returned unchanged (in_air True, no refraction point). For an underwater point the path from the point to the eye is the one of stationary optical length n |R - P| + |E - R| over the crossing point R on the surface; at that point Snell's law n sin(theta_w) = sin(theta_a) holds. Flat surface: the crossing lies in the vertical plane through the point and the eye and is the unique root of the Snell condition (found by bisection to machine precision); the apparent position is the point seen along the eye ray continued below the surface to the horizontal position of the true point: its depth is x h / (s - x) and tends to d / n for a camera straight above. Wavy surface: surface is a table with height (square, periodic) and extent_m, as returned by ocean_height_field; the crossing is found by Newton iteration on the gradient of the optical path with bicubic heights and normals, started from the flat solution; the vector Snell condition n (d_w x N) = d_a x N is verified at the result and a point that fails it (or does not converge) is returned as NaN with converged False. The table has apparent (M, 3), refraction_point (M, 3), converged, in_air, snell_residual (flat: |n sin(theta_w) - sin(theta_a)|, wavy: the norm of the vector residual), apparent_depth_m and n_water. A caustic can make several paths possible; the one found is the stationary point nearest the flat solution, or (when the Newton iteration fails on steep ripples) the shortest optical path on a local grid.
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_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 · ocean_height_field · fresnel_water_air · snell_window · 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.