watervision op• Data kinds: कोई नहीं → table (केवल arguments से तय होने वाला op — यह कोई image या data input नहीं लेता)
• Call: import fullseye as fs; fs.ledger.bottle_background_map(radius_mm, wall_mm, height_mm, fill_fraction, n_glass, n_liquid, background_distance_mm=150.0, camera_distance_mm=500.0, pixel_pitch_um=20.0, size=None, n_air=1.0) -> 'dict' (implementation को सीधे call करना हो तो import watervision; watervision.bottle_background_map(radius_mm, wall_mm, height_mm, fill_fraction, n_glass, n_liquid, background_distance_mm=150.0, camera_distance_mm=500.0, pixel_pitch_um=20.0, size=None, n_air=1.0) -> 'dict', registry से लेना हो तो opsoptics.get("bottle_background_map"))
• GPU: नहीं (केवल CPU reference implementation)
आंशिक रूप से भरी बोतल का प्रत्येक पिक्सेल एक समतल पैटर्न वाली पृष्ठभूमि पर कहाँ देखता है -> dict (पृष्ठभूमि निर्देशांक u का मानचित्र, mm में)।
> नीचे का विस्तृत विवरण मूल text में है — सारांश और headings का अनुवाद हो चुका है।
The same bottle and camera as bottle_image (outer radius radius_mm, glass wall wall_mm, height height_mm, axis vertical, base at z = 0, pinhole camera_distance_mm from the axis, rows are the horizontal sections, pixel_pitch_um in the plane of the axis, row j at z = height - (j + 0.5) pitch), but instead of a brightness it returns the coordinate u (mm, along the image rows) at which the ray of every pixel meets a flat pattern background_distance_mm behind the axis. A pattern drawn on that plane (stripes, a checkerboard) is then seen at pattern(u): that is the distortion the bottle imposes. The liquid (n_liquid) fills the bottle to fill_fraction * height_mm with a flat surface; no meniscus, no bubbles. The ray of every row is traced through the circles of the section (outer wall, inner wall) with the vector form of Snell's law; the vertical position on the background is the row's own height (the rows are independent, as in bottle_image: no refraction at the shoulder or the base, no tilt out of the section).
The table has u_mm (rows, cols; NaN where the pixel cannot be used), valid (True where u_mm is a number), weight (the Fresnel transmittance product of the ray, 1 outside the bottle; multiply the pattern contrast by it), u_straight_mm (the column coordinate without a bottle, x (dc + db) / dc), x_mm, z_mm, pixel_pitch_mm, fill_row_from_top, liquid_rows, fill_z_mm, the counts tir_rays (rays that met a total internal reflection), backward_rays and unresolved_rays (all of them left NaN, never a guess) and the inputs echoed. Rows of equal geometry are computed once, so they are bit identical. n_glass <= 1, n_liquid <= 1, n_air < 1 or not below both, a fill outside [0, 1], a wall not thinner than the radius, a background not behind the bottle and a camera not further than one diameter are refused.
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_bottle_pattern_inverse — py -3.11 examples/poc_bottle_pattern_inverse.py
table को input के रूप में लेते हैं)abcd_matrix · wavefront_stats · sfr_from_edge · paraxial_trace · seidel_coefficients · spot_stats · tolerance_analysis · wavefront_from_opd
watervision)caustic_irradiance · bottle_image · fill_level_from_image · bottle_fit_from_pattern · wet_surface_appearance · wet_dry_inspection_pair · underwater_inspection_image · caustic_floor_segmentation
*Provenance: watervision.py — OPTICS operator registry. यह per-op note tools/opdocs.py md से अपने-आप generate होता है (हाथ से edit न करें)।*
© 2026 Kazufumi Furuse — Fullseye operator documentation. Licensed under Apache-2.0.