watervision op• 데이터 종류: 없음 → table(인자만으로 정해지는 연산자 —— 이미지나 데이터 입력을 받지 않습니다)
• 호출: 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'(구현을 직접 호출하려면 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', 원장에서 가져오려면 opsoptics.get("bottle_image"))
• GPU: 없음(CPU 참조 구현만)
액체가 일부 채워진 원통형 병의 측면 이미지를 행 단위로 광선 추적한 결과 -> dict.
> 아래 상세 설명은 원문입니다 —— 요약과 제목은 번역되어 있습니다.
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.
optics 의 모든 연산자는 입력을 검증한 뒤에 계산합니다(조용히 통과시키지 않습니다):
• 단위는 인자 이름에 넣습니다 — _mm / _um / _deg / _mrad. mm 와 µm 를 혼동하면 crash 가 아니라 「그럴듯하게 틀린 답」이 나오므로 이름으로 막습니다. 크기로 단위를 추측하는 처리는 일절 하지 않습니다.
• 문자열은 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), 총합 <= 0 인 PSF, S0 = 0 인 스토크스 벡터, 물체가 앞쪽 초점에 있는 경우(상이 무한대).
• 비유한 값을 돌려주는 것은 2 개 연산자뿐이며, 둘 다 계약으로 명시: 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). 작은 인자에서 거대한 내부 할당이 일어나는 경로(실측: n_max=40 × 4096² 로 108 GB)를 fail-closed 로 막습니다.
• 물리적으로 불가능한 상태도 거부: 편광도 > 1 인 스토크스 벡터, 음의 투과율, 음의 강도, n-|m| 이 홀수인 잘못된 Zernike 첨자 등.
• 샘플 데이터 카탈로그(DL URL / 라이선스) —— 2-D 는 skimage.data(BSD/public)+ 합성, 3-D 는 실데이터 소스(Stanford/PDS 등)의 DL URL.
• 연산자의 내력·참고문헌 —— 이 연산자 족의 바탕이 된 연구/기법의 출처.
• 알고리즘의 정전(저자·연도)과 용도는 위의 패밀리 사용 가이드에 적혀 있습니다.
• 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 를 입력으로 받는 것)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 연산자 레지스트리. 이 op 노트는 tools/opdocs.py md 가 자동 생성합니다(직접 편집하지 마세요).*
© 2026 Kazufumi Furuse — Fullseye operator documentation. Licensed under Apache-2.0.