watervision op• 資料種類:rgbimage × image2d → table
• 呼叫: import fullseye as fs; fs.ledger.underwater_inspection_image(scene_albedo, distance_map_m, water_type, light='camera', lamp_power=1.0, camera_distance_m=None, depth_m=2.0, exposure_photons=10000.0, fov_deg=60.0, beam_exponent=6.0) -> 'dict'(要直接呼叫實作,import watervision; watervision.underwater_inspection_image(scene_albedo, distance_map_m, water_type, light='camera', lamp_power=1.0, camera_distance_m=None, depth_m=2.0, exposure_photons=10000.0, fov_deg=60.0, beam_exponent=6.0) -> 'dict';從台帳取用則 opsoptics.get("underwater_inspection_image"))
• GPU:無(僅 CPU 參考實作)
船體或管道檢測影像:位於相機處的燈穿過水照亮牆面 -> 字典(影像、逐像素信噪比)。
> 以下的詳細說明為原文 —— 摘要與標題已翻譯。
A thin layer over watermedia.underwater_image (the Akkaynak and Treibitz form: direct signal plus backscatter veil). scene_albedo is (H, W) or (H, W, 3) and distance_map_m (H, W) the camera-to-surface distance (> 0). light="camera": the only light is a lamp at the camera of lamp_power (relative power at 1 m); the wall is lit by lamp_power exp(-c r) / r^2 (beam attenuation c of the water at 0.61 / 0.54 / 0.465 um), reflects its albedo and the return path attenuates with Kd. The lamp also lights the water in front of the lens: the veil of the water type's single-scattering backscatter grows as 1 - exp(-Kd r) and is weighted by the lamp's beam pattern, cos(theta)^beam_exponent with theta the angle of the pixel from the axis (fov_deg across the width): strongest in the centre, where the lamp and the camera look at the same water. A baseline between lamp and camera, camera_distance_m (default
None: the lamp is at the camera), reduces the overlap of the lit and the seen water by 1 / (1 + (baseline / r)^2). light="ambient": daylight at depth_m and a veil of the daylight, uniform over the image (lamp_power is not used). light="both": the lamp and the daylight together (the signals and the veils add).
snr = sqrt(N) direct / sqrt(direct + backscatter + 1e-12) is the shot-noise limited signal to noise of the direct signal against its own shot noise and the shot noise of the veil (N = exposure_photons per unit radiance): it falls with distance because the direct term falls and the veil grows. snr_clear is the same expression for water that does not attenuate or scatter (equal to snr as the distance tends to 0). The table has image (H, W, 3), direct, backscatter, snr, snr_clear, snr_mean (over the three bands), veil_profile (H, W), transmission, beam_attenuation_c, kd, water_type and light. A zero or negative distance, an albedo outside [0, 1], an unknown water type and a bad light are refused.
optics 的每個運算子都先檢驗輸入再計算(不讓任何東西無聲通過):
• 單位寫進參數名 —— _mm / _um / _deg / _mrad。把 mm 和 µm 弄混不會當掉,而是給出「看似合理卻是錯的答案」,所以用命名來防。這裡絕不從數值大小去猜單位。
• 字串一律 ValueError —— float('50') 會成功,於是未解析的設定值會被當成長度混進來(實測:thin_lens('50', '200') 曾回傳看似合理的 66.667 mm)。bool 也按 True == 1 的隱式提升拒絕。
• complex / masked array 一律 ValueError(僅接受實數槽位;拒絕無聲丟棄虛部或剝掉遮罩)。所有輸入中的 NaN/Inf 一律 ValueError。但已宣告的缺測除外:bottle_fit_from_pattern 的 u_map 以 NaN 接收未能測得的像素(∞ 仍被拒絕)。
• 逐項點名拒絕除零及其近親:焦距 0、曲率半徑 0、折射率 <= 0、全不透明光闌(全為 0,正規化變成 0/0)、總和 <= 0 的 PSF、S0 = 0 的 Stokes 向量、物體位於前焦點(像在無窮遠)。
• 只有兩個運算子會回傳非有限值,而且都寫進了契約:depth_of_field 在超焦距以外回傳 far_mm = inf(這正是超焦距的定義),gaussian_beam 在束腰處回傳 wavefront_radius_mm = inf(平面波前的曲率半徑)。兩者都同時回傳一個有限的夥伴(far_is_infinite / curvature_per_mm)。除此之外的無聲 NaN/Inf 都在內部檢出並 ValueError ——「float64 溢位了」和「答案是無窮大」是兩種不同的主張,不能拿後者的臉去交付前者。但已宣告的缺測除外:bottle_background_map 對光線不可用的像素(全反射等)在 u_mm 中回傳 NaN,並同時回傳 valid 遮罩和數量。
• 尺寸上限:生成網格受 optics.MAX_GRID(4096)限制,傳入的場/PSF/光闌受 optics.MAX_FIELD_ELEMENTS(2^24),ABCD 元件序列受 optics.MAX_SYSTEM_ELEMENTS(1024),Zernike 受 MAX_ZERNIKE_TERMS(512)/ MAX_ZERNIKE_ORDER(40)/ MAX_ZERNIKE_BASIS(2^25)。以 fail-closed 堵住「小參數引發巨大內部配置」的路徑(實測:n_max=40 × 4096² 需要 108 GB)。
• 物理上不可能的狀態同樣拒絕:偏振度 > 1 的 Stokes 向量、負穿透率、負強度、n-|m| 為奇數等非法 Zernike 指標。
• 範例資料目錄(下載 URL / 授權) —— 2-D 用 skimage.data(BSD/公有領域)加合成圖,3-D 給出真實資料源(Stanford/PDS 等)的下載 URL。
• 運算子來歷與參考文獻 —— 該運算子族所依據的研究/方法出處。
• 演算法的正典(作者、年份)與用途見上面的族使用指南。
• poc_water_inspection_images — py -3.11 examples/poc_water_inspection_images.py
table 作為輸入)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 · bottle_fit_from_pattern · wet_surface_appearance · wet_dry_inspection_pair · caustic_floor_segmentation
*Provenance: watervision.py — OPTICS 運算子登記表。本條目由 tools/opdocs.py md 自動產生(請勿手動編輯)。*
© 2026 Kazufumi Furuse — Fullseye operator documentation. Licensed under Apache-2.0.