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_fit_from_pattern(u_map, x_mm, pixel_pitch_um, camera_distance_mm, background_distance_mm, known=None, free_background=False, rows_per_section=None, restarts=3) -> 'dict' (die Implementierung direkt: import watervision; watervision.bottle_fit_from_pattern(u_map, x_mm, pixel_pitch_um, camera_distance_mm, background_distance_mm, known=None, free_background=False, rows_per_section=None, restarts=3) -> 'dict'; aus dem Register: opsoptics.get("bottle_fit_from_pattern"))
• GPU: nein (nur CPU-Referenzimplementierung)
Die Flasche aus der Verzerrung eines Hintergrundmusters zurücklesen -> dict (Radius, Wandstärke, Brechzahlen, Füllstand und wie gut jede Größe bestimmt ist).
> Die ausführliche Beschreibung unten ist der Originaltext — Zusammenfassung und Überschriften sind übersetzt.
u_map (rows, cols) is the background coordinate (mm) each pixel looks at (the u_mm of bottle_background_map, or a phase-shifting measurement of it; NaN where unusable); x_mm the column positions in the plane of the axis, pixel_pitch_um the pitch, the camera and the pattern are camera_distance_mm and background_distance_mm from the axis (known from the set-up). The fill line is found first, from the jump of the map between rows (the liquid and the air bend the pattern differently): rows above it are the empty section, rows below the filled one (level_mm as in fill_level_from_image: (rows below the boundary) * pitch). Each section is reduced to one profile (the median over its rows, rows_per_section of them if given, the two rows next to the boundary left out) and a closed-form model of concentric circles, written without the tracer (an angle and an impact parameter per ray), is fitted by Levenberg-Marquardt over radius_mm, wall_mm, n_glass and n_liquid (the filled section; a bottle with no fill line is one section whose core index is fitted). known is a dict of values held fixed ("radius_mm", "wall_mm", "n_glass", "n_liquid"); free_background=True also fits the distance of the pattern. The start is a scan of the radius from the silhouette (where the map leaves the straight line) with restarts (1 to 3) different index starts; the table reports how far the starts that reach the same cost disagree (start_spread).
The table has radius_mm, wall_mm, n_glass, n_liquid, background_distance_mm, free (the fitted names), sigma (1 sigma of each free name from the Gauss-Newton covariance with the residual scatter as the noise, None if not free), corr (correlation matrix of the free names) with corr_names, cond (condition number of the Jacobian with unit-length
columns: a large value means some combination of the parameters is hardly seen), singular_values, weak_direction (the combination with the smallest singular value, one number per free name) and weak_rel_sigma (the 1 sigma relative change along it), residual_rms_mm, n_columns and columns_rejected (resolved pixels the model calls blocked), converged, iterations, level_found / level_mm / level_row / level_jump_mm (False and None when the rows do not
jump: an empty or a full bottle has no fill line to read; level_mm is then None), fill_state ("partial" or "uniform"). poorly_determined lists the fitted names whose 1 sigma exceeds 1 % of the value or that sit on a bound, and separated is True only when the fit converged and that list is empty. This is a rule of thumb for the error of the noise, not a guarantee: the 1 % was chosen after measuring (at 25 % the flag called 15-20 % of the wrong wall estimates, and 73-76 % of the trials with n_glass off by more than 0.02, separated; at 1 % none of 535 wrong trials in two disjoint seed sets), the covariance assumes the model is exact, and a model error such as an off-centre inner wall changes the estimates without changing the residual, the sigma or this flag. n_liquid is None when no row of the map is left in the filled section. Quantities that barely move the pattern (a thin wall against the glass index when the edge pixels are lost, the pattern distance against the liquid index) come back there, with a large sigma and cond; they are not separated, and the table says so rather than giving a number without it. The model assumes concentric circles with a uniform wall, a horizontal 2-D section, an ideal pinhole, a flat background, exactly known distances and pitch, no dispersion and a flat liquid surface; the maps of bottle_background_map obey the same assumptions, so a test on them proves consistency, not that a real bottle is recovered. A map with fewer than 12 usable columns, a wrong shape, an unknown known name or a camera not beyond one diameter 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
table als Eingabe)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_background_map · 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.