watermedia 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.ocean_height_field(size, extent_m, wind_speed_mps, wind_dir_deg, t=0.0, seed=0, kind='pierson_moskowitz', directional='cos2', choppiness=0.0, depth_m=None, spreading_s=10.0, fetch_m=None, single_mode=None) -> 'dict' (die Implementierung direkt: import watermedia; watermedia.ocean_height_field(size, extent_m, wind_speed_mps, wind_dir_deg, t=0.0, seed=0, kind='pierson_moskowitz', directional='cos2', choppiness=0.0, depth_m=None, spreading_s=10.0, fetch_m=None, single_mode=None) -> 'dict'; aus dem Register: opsoptics.get("ocean_height_field"))
• GPU: nein (nur CPU-Referenzimplementierung)
FFT-Meeresoberfläche nach Tessendorf (2001) zum Zeitpunkt t -> dict (Höhe, Neigungen, Normalenkarte, Verschiebung).
> Die ausführliche Beschreibung unten ist der Originaltext — Zusammenfassung und Überschriften sind übersetzt.
The wave-number spectrum is the omnidirectional spectrum of ocean_spectrum carried to the plane, psi(k, theta) = S(omega) D(theta) (d omega / d k) / k, with the dispersion omega^2 = g k (deep water) or omega^2 = g k tanh(k h) when depth_m is given. D is cos2 (2/pi cos^2 within 90 degrees of the wind) or cos2s (cos^(2s)((theta - theta_w) / 2), s = spreading_s), both normalised to 1 over the circle. The random amplitudes are h0(k) = (xi_r + j xi_i)/sqrt(2) sqrt(psi / 2) dk and h(k, t) = h0(k) e^(-j omega t) + conj(h0(-k)) e^(+j omega t), which is Hermitian, so the height is real (imag_residual reports the largest imaginary part left by the transform). The mean, the Nyquist row and column are zeroed. seed fixes the amplitudes:
the same seed gives the same sea at every t. choppiness moves each point horizontally by choppiness times the Tessendorf displacement (0 gives exactly zero displacement). size is the number of points per side (the grid is size x size over extent_m metres, wrap-around); wind_dir_deg is the direction the waves travel, from +x towards +y. single_mode=(mx, my, amplitude_m) replaces the random sea with one travelling cosine wave. The table has height, slope_x, slope_y (dh/dx, dh/dy), normal (H, W, 3), displacement_x / displacement_y, x_m / y_m, extent_m, variance_expected_m2 and slope_variance_expected (the sums of the spectrum over the modes in use), cox_munk_slope_variance (0.003 + 0.00512 U, Cox & Munk 1954), slope_variance_with_tail and omega_mode (single mode only). A sea of this kind has no capillary waves, so its resolved slope variance is far below the Cox & Munk value; slope_variance_with_tail adds the saturation range alpha / 2 ln(k_c / k_nyquist) of the spectrum up to the gravity-capillary wave number k_c = 370 rad/m. That agrees with Cox & Munk at 5 m/s and falls 40 % short at 10 m/s (the constant alpha of the Pierson-Moskowitz range does not grow with the wind); both are shown in the PoC.
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
• poc_water_transparent_media — py -3.11 examples/poc_water_transparent_media.py
table als Eingabe)abcd_matrix · wavefront_stats · sfr_from_edge · paraxial_trace · seidel_coefficients · spot_stats · tolerance_analysis · wavefront_from_opd
watermedia)ocean_spectrum · fresnel_water_air · snell_window · refracted_view · water_attenuation · underwater_image · phase_function_hg · scattering_phase_petzold
*Provenance: watermedia.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.