watervision op• 데이터 종류: 없음 → table(인자만으로 정해지는 연산자 —— 이미지나 데이터 입력을 받지 않습니다)
• 호출: 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'(구현을 직접 호출하려면 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', 원장에서 가져오려면 opsoptics.get("bottle_fit_from_pattern"))
• GPU: 없음(CPU 참조 구현만)
배경 무늬의 왜곡에서 병을 역으로 읽어 낸다 -> dict(반지름, 벽 두께, 굴절률, 액면, 그리고 각각이 얼마나 정해지는지).
> 아래 상세 설명은 원문입니다 —— 요약과 제목은 번역되어 있습니다.
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.
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
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 · 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.