watervision op• Datenarten: keine → table (ein Operator, der allein durch seine Argumente bestimmt ist — er nimmt kein Bild und keine Daten entgegen)
• Aufruf: 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' (die Implementierung direkt: 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'; aus dem Register: opsoptics.get("bottle_image"))
• GPU: nein (nur CPU-Referenzimplementierung)
Seitenansicht einer teilweise mit Flüssigkeit gefüllten zylindrischen Flasche, zeilenweise per Strahlverfolgung berechnet -> dict.
> Die ausführliche Beschreibung unten ist der Originaltext — Zusammenfassung und Überschriften sind übersetzt.
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.
Jeder optics-Operator prüft seine Eingabe vor der Berechnung (nichts rutscht stillschweigend durch):
• Einheiten stecken im Argumentnamen — _mm / _um / _deg / _mrad. Eine Verwechslung von mm und µm stürzt nicht ab, sondern liefert eine plausibel aussehende falsche Antwort; der Name verhindert das. Aus der Größenordnung wird nie auf die Einheit geschlossen.
• Strings lösen ValueError aus — float('50') gelingt, sodass ein ungeparster Konfigurationswert als Länge durchrutschen würde (gemessen: thin_lens('50', '200') lieferte plausible 66,667 mm). bool wird als implizite Hochstufung True == 1 ebenfalls abgelehnt.
• complex / Masked Arrays lösen ValueError aus (nur reelle Slots; das stille Verwerfen des Imaginärteils bzw. Abstreifen der Maske wird abgelehnt). NaN/Inf löst bei jeder Eingabe ValueError aus. Ausnahme, ausdrücklich erklärt: Das u_map von bottle_fit_from_pattern nimmt nicht gemessene Pixel als NaN entgegen (Unendlich wird weiterhin abgelehnt).
• Division durch null und Verwandtes wird namentlich abgelehnt: Brennweite 0, Krümmungsradius 0, Brechzahl <= 0, undurchlässige Blende (alles 0, die Normierung wird 0/0), PSF mit Summe <= 0, Stokes-Vektor mit S0 = 0 und ein Objekt im vorderen Brennpunkt (Bild im Unendlichen).
• Nur zwei Operatoren liefern einen nicht-endlichen Wert, und beide halten das vertraglich fest: depth_of_field liefert jenseits der hyperfokalen Distanz far_mm = inf (genau das bedeutet die hyperfokale Distanz), und gaussian_beam liefert an der Taille wavefront_radius_mm = inf (der Krümmungsradius einer ebenen Wellenfront). Beide liefern zusätzlich einen endlichen Partner (far_is_infinite / curvature_per_mm). Jedes andere stille NaN/Inf wird intern erkannt und löst ValueError aus — "float64 ist übergelaufen" und "die Antwort ist unendlich" sind verschiedene Aussagen; die erste wird nie im Gewand der zweiten geliefert. Ausnahme, ausdrücklich erklärt: bottle_background_map liefert für Pixel mit unbrauchbarem Strahl (Totalreflexion u. Ä.) NaN in u_mm, zusammen mit einer valid-Maske und den Anzahlen.
• Größenobergrenzen: erzeugte Gitter durch optics.MAX_GRID (4096), übergebene Felder/PSFs/Blenden durch optics.MAX_FIELD_ELEMENTS (2^24), ABCD-Elementketten durch optics.MAX_SYSTEM_ELEMENTS (1024), Zernike durch MAX_ZERNIKE_TERMS (512) / MAX_ZERNIKE_ORDER (40) / MAX_ZERNIKE_BASIS (2^25). Damit werden Pfade fail-closed geschlossen, in denen ein kleines Argument eine riesige interne Allokation auslöst (gemessen: n_max=40 × 4096² braucht 108 GB).
• Physikalisch unmögliche Zustände werden ebenfalls abgelehnt: Stokes-Vektor mit Polarisationsgrad > 1, negative Transmission, negative Intensität und ungültige Zernike-Indizes wie ungerades n-|m|.
• Leitfaden zur Familie optics_imaging
• Katalog der Beispieldaten (Download-URLs / Lizenzen) — 2-D nutzt skimage.data (BSD/Public Domain) plus synthetische Bilder, 3-D nennt Download-URLs echter Datenquellen (Stanford, PDS, …).
• Herkunft und Literatur der Operatoren — die Quellen der Forschung/Verfahren, auf denen diese Operatorfamilie beruht.
• Der kanonische Algorithmus (Autor, Jahr) und seine Anwendungen stehen im Familienleitfaden oben.
• poc_bottle_pattern_inverse — py -3.11 examples/poc_bottle_pattern_inverse.py
• poc_water_inspection_images — py -3.11 examples/poc_water_inspection_images.py
table als Eingabe)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 · bottle_background_map · bottle_fit_from_pattern · wet_surface_appearance · wet_dry_inspection_pair · underwater_inspection_image · caustic_floor_segmentation
*Provenance: watervision.py — OPTICS Operator-Registry. Diese Notiz wird von tools/opdocs.py md erzeugt (nicht von Hand bearbeiten).*
© 2026 Kazufumi Furuse — Fullseye operator documentation. Licensed under Apache-2.0.