watervision op• Data kinds: none → table (an op determined by its arguments alone — it takes no image or data input)
• Call: import fullseye as fs; fs.ledger.bottle_image(radius_mm, wall_mm, height_mm, fill_fraction, n_glass, n_liquid, meniscus_mm=0.0, bubbles=None, camera_distance_mm=500.0, pixel_pitch_um=20.0, size=None, light='backlight', n_air=1.0) -> 'dict' (to call the implementation directly, import watervision; watervision.bottle_image(radius_mm, wall_mm, height_mm, fill_fraction, n_glass, n_liquid, meniscus_mm=0.0, bubbles=None, camera_distance_mm=500.0, pixel_pitch_um=20.0, size=None, light='backlight', n_air=1.0) -> 'dict'; from the registry, opsoptics.get("bottle_image"))
• GPU: none (CPU reference implementation only)
A side view of a cylindrical bottle, part filled with a liquid, ray-cast row by row -> dict.
The bottle (outer radius radius_mm, glass wall wall_mm, height height_mm, axis vertical, base at z = 0) is looked at by a pinhole camera camera_distance_mm from the axis. Every image row is the horizontal cross-section at its height: the ray of a pixel is traced through the circles of the section (outer wall, inner wall, the edge of the liquid in a meniscus row, bubbles) with the vector form of Snell's law and the unpolarised Fresnel transmittance at each interface. Total internal reflection reflects the ray (at most 24 interface events are followed; a ray still wandering then is counted in unresolved_rays and left dark). The liquid (n_liquid) fills the bottle up to fill_fraction * height_mm; meniscus_mm lets it climb the wall by that much as (rho / r_inner)^6. bubbles is a list of (x_mm, z_mm, r_mm) (or with a fourth y_mm along the viewing axis; default 0): air spheres in the liquid, drawn as their circle in each row they cross. pixel_pitch_um is the sampling pitch in the plane of the axis, so 1000 / pixel_pitch_um pixels are 1 mm there; size is (rows, cols) (default: the rows exactly cover the height, the width is 1.15 times the diameter); row j is at z = height - (j + 0.5) pitch.
light="backlight": a diffuse panel of radiance 1 behind the bottle that emits only within +-8 degrees of the viewing axis (soft edge 1 degree): a pixel is lit when its ray leaves the bottle inside that cone, times the product of the Fresnel transmittances. The empty bottle bends rays little and is lit to near the edges; the filled one is a cylindrical lens, so only a central band (half width alpha / (1/f - 1/dc) with the paraxial focal length f of watermedia.cylinder_lens_caustic) is lit and the flanks go dark; an air bubble in the liquid is a diverging lens and shows as a dark ring. light="frontlight": a matt wall of radiance 0.8 behind, a dim dome plus a soft box at 35 degrees, and the first Fresnel reflection of the outer wall (R times the environment radiance), which gives the glint and the bright rim at grazing view. Interior reflections other than total internal reflection are not followed, the rows are independent (no vertical refraction at the shoulder or the base), and rows without bubbles or meniscus are computed once per kind (the empty and the full section), so rows of equal geometry are bit identical.
The table has image (rows, cols; no pixel exceeds 1), x_mm, z_mm, pixel_pitch_mm, magnification_px_per_mm, fill_row_from_top (the first liquid row), liquid_rows (rows with liquid; about fill_fraction height / pitch), fill_z_mm, paraxial_efl_mm and band_half_width_mm_paraxial (the predicted half width of the lit band of the filled bottle, inf when the lens does not converge within the camera distance), central_transmittance_empty / ..._filled (the product of the normal-incidence Fresnel transmittances of the four interfaces on the axis), unresolved_rays and the inputs echoed. 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 meniscus that does not fit and a bubble outside the liquid are refused.
Every optics op validates its input before computing (nothing slips through silently):
• Units are baked into the argument name — _mm / _um / _deg / _mrad. Confusing mm with µm does not crash; it yields a plausible-looking wrong answer, so the name prevents it. Nothing here guesses the unit from the magnitude.
• Strings raise ValueError — float('50') succeeds, so an unparsed configuration value would slip through as a length (measured: thin_lens('50', '200') returned a plausible 66.667 mm). bool is refused too, as the implicit promotion True == 1.
• complex / masked arrays raise ValueError (real-valued slots only; silently dropping the imaginary part or peeling off the mask is refused). NaN/Inf raises ValueError on every input.
• Division by zero and its relatives are refused by name: focal length 0, radius of curvature 0, refractive index <= 0, a fully opaque aperture (all zeros, so the normalisation is 0/0), a PSF whose sum is <= 0, a Stokes vector with S0 = 0, and an object sitting at the front focal point (the image is at infinity).
• Only two ops return a non-finite value, and both state it as a contract: depth_of_field returns far_mm = inf beyond the hyperfocal distance (that is what the hyperfocal distance means), and gaussian_beam returns wavefront_radius_mm = inf at the waist (the radius of curvature of a plane wavefront). Both also return a finite companion (far_is_infinite / curvature_per_mm). Any other silent NaN/Inf is detected internally and raises ValueError — "float64 overflowed" and "the answer is infinite" are different claims, so the first is never returned wearing the face of the second.
• Size caps: generated grids are capped by optics.MAX_GRID (4096); supplied fields/PSFs/apertures by optics.MAX_FIELD_ELEMENTS (2^24); ABCD element chains by optics.MAX_SYSTEM_ELEMENTS (1024); Zernike by MAX_ZERNIKE_TERMS (512) / MAX_ZERNIKE_ORDER (40) / MAX_ZERNIKE_BASIS (2^25). This closes, fail-closed, the paths where a small argument triggers a huge internal allocation (measured: n_max=40 × 4096² needs 108 GB).
• Physically impossible states are refused too: a Stokes vector with degree of polarisation > 1, negative transmittance, negative intensity, and invalid Zernike indices such as n-|m| odd.
• Sample-data catalog (download URLs / licences) — 2-D uses skimage.data (BSD/public domain) plus synthetic images; 3-D lists download URLs for real data sources (Stanford, PDS, …).
• Operator provenance and references — the sources of the research/methods this op family came from.
• The canonical algorithm (author, year) and its uses are named in the family usage guide above.
• poc_water_inspection_images — py -3.11 examples/poc_water_inspection_images.py
table as input)abcd_matrix · wavefront_stats · sfr_from_edge · paraxial_trace · seidel_coefficients · spot_stats · tolerance_analysis · wavefront_from_opd
watervision)caustic_irradiance · fill_level_from_image · wet_surface_appearance · wet_dry_inspection_pair · underwater_inspection_image · caustic_floor_segmentation
*Provenance: watervision.py — OPTICS operator registry. This per-op note is generated by tools/opdocs.py md (do not hand-edit).*
© 2026 Kazufumi Furuse — Fullseye operator documentation. Licensed under Apache-2.0.