watervision op• Datenarten: image2d → table
• Aufruf: import fullseye as fs; fs.ledger.caustic_irradiance(height_field, extent_m, depth_m, light_dir, n_water=None, size=None, method='photon', ray_density=4, periodic=True, max_gain=20.0) -> 'dict' (die Implementierung direkt: import watervision; watervision.caustic_irradiance(height_field, extent_m, depth_m, light_dir, n_water=None, size=None, method='photon', ray_density=4, periodic=True, max_gain=20.0) -> 'dict'; aus dem Register: opsoptics.get("caustic_irradiance"))
• GPU: nein (nur CPU-Referenzimplementierung)
Die Beleuchtungsstärke, die ein paralleles Lichtbündel auf einem ebenen Boden unter einer welligen Wasseroberfläche erzeugt -> dict.
> Die ausführliche Beschreibung unten ist der Originaltext — Zusammenfassung und Überschriften sind übersetzt.
height_field (ny, nx) is the surface height (m) of a periodic patch of extent_m metres (a length, or (Lx, Ly)); it is treated as band limited (the Nyquist row and column are dropped) and sampled finer by an integer ray_density (rays per cell and axis; the default 4 is for the photon method, the wavefront method triangulates its landing points and is usually run with 1 or 2) with a Fourier interpolation that also gives the exact slopes. depth_m is the depth of the floor below the mean level (it must lie below every wave crest). light_dir is the direction the light travels, a 3-vector with a downward z or (zenith_deg, azimuth_deg). n_water defaults to the material-table index at 0.55 um. size is the floor grid (ny, nx) (default: that of the height field).
method="photon": one ray per fine cell leaves the surface, is refracted by the vector form of Snell's law with the normal of the local slope, carries the power the beam puts on that cell, E0 (d.(-grad h, 1)) dx dy, times the unpolarised Fresnel transmittance, lands on the floor and is binned by bilinear splatting (the weights add up exactly, so the energy is conserved). method="wavefront": the map surface to floor, (x, y) -> (x, y) + s t_xy, has the Jacobian J (spectral derivatives of the periodic displacement) and the irradiance at a landing point is the carried power over |det J|; it is interpolated linearly onto the floor grid. Where det J falls below 1 / max_gain or turns negative the map folds (a caustic: the geometric gain is unbounded and several sheets overlap), the wavefront result is inf there and fold_mask flags the pixels (dilated by one pixel). The unit is the irradiance of the beam, measured on the horizontal floor, so a flat surface gives exactly cos(theta_i) T(theta_i) everywhere (the refracted beam is narrower by cos(theta_i) / cos(theta_t) and meets the floor at cos(theta_t)).
The table has irradiance (ny, nx), fold_mask, x_m / y_m (floor nodes), incident_flux (the power of the beam through the patch, summed over the rays), incident_flux_analytic (cos(theta_i) Lx Ly), transmitted_flux (after Fresnel), floor_flux (the integral of the irradiance, photon only), lost_flux_fraction (photons that left a non-periodic patch), mean_transmittance, flat_irradiance (cos(theta_i) T), theta_i_deg, theta_t_deg, n_water and n_rays. Non-finite heights, a floor above a crest, a light not pointing down and a patch too large for the ray cap 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_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)bottle_image · 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.