scene op• 데이터 종류: table × image2d → table
• 호출: import fullseye as fs; fs.ledger.surface_defect(primitive: 'dict', field, mask=None, uv_size_mm=(20.0, 20.0), centre_mm=(0.0, 0.0), height_um: 'float' = 0.0, height_field=None, roughness_um: 'float' = 0.6) -> 'dict'(구현을 직접 호출하려면 import optscene; optscene.surface_defect(primitive: 'dict', field, mask=None, uv_size_mm=(20.0, 20.0), centre_mm=(0.0, 0.0), height_um: 'float' = 0.0, height_field=None, roughness_um: 'float' = 0.6) -> 'dict', 원장에서 가져오려면 opsoptics.get("surface_defect"))
2-D 결함 그림을 부품 면에 붙입니다(defectgen 의 출력을 그대로 먹습니다).
field는 밝기의 변조 (H, W)(0 = 변화 없음, −0.3 = 30% 어두운 흠집). height_um을 주면 같은 그림을 높이로도 해석하여, 기울기로부터 법선을 기울인다 ―― 이것이 있으면, 같은 흠집이 돔 조명에서는 사라지고 암시야 조명에서 빛난다는 조명을 바꾸는 의미가 재현된다(외관 검사 AI 학습 데이터는 여기가 본체).
height_field를 따로 넘기면, 색은 바뀌지 않고 요철만 있는 결함(타흔· 싱크 마크·얕은 긁힘)을 만들 수 있다. field를 전부 0으로 하면 순수한 지형(요철) 결함이 되어, 돔 조명에서는 사라지고 저각의 암시야 조명에서 빛난다 ―― 이 차이야말로 조명을 고르는 이유.
roughness_um은 결함 부분만 면이 거칠어지는 양(기본값 0.6 µm).
관점을 바꾸면, surface_finish의 가공 자국도 같은 것을 다른 입도로 갖고 있다 ―― 가공 자국은 표면 요철의 텍스처를 몇 옥타브의 잡음으로 압축한 표현이고, 여기서 말하는 거칠기는 "화소보다 미세해 해상할 수 없는 요철"을 1개의 수(σ)로 뭉갠 표현. 해상할 수 있는 요철은 법선으로, 해상할 수 없는 요철은 거칠기로 다루는 분담이다. 흠집은 재료를깎아낸 자국이므로, 건전한 면보다 반드시 거칠다. 이것이 있으면경면 비율 exp(-(4πσcosθ/λ)²)가 내려가 명시야에서 어두워지고, 동시에 산란이 늘어 암시야에서 밝아진다 ―― 교과서대로의 콘트라스트 반전은 법선의 기울기가 아니라이 거칠기에서 나온다(저각의 빛을 바로 위로 돌려보내려면 면이 39도 기울어야 하며, 흠집의 경사로는닿지 않기 때문. 2026-09-05에 실측으로 확인). 0으로 하면 거칠기를 바꾸지 않는 결함이 된다.
uv_size_mm은 붙이는 실치수 [mm], centre_mm은 면 좌표 위의 중심. mask를 넘기면 그 화소가 결함 라벨(optscene_defect_mask가 반환하는 참값).
반환값은 defect를 붙인 새 프리미티브(원본은 고쳐 쓰지 않는다).
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.
• 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 가 넘쳤다」와 「답이 무한대다」는 다른 주장이므로, 후자의 얼굴로 전자를 돌려주지 않습니다.
• 크기 상한: 생성 격자는 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 첨자 등.
• dataset_conventions — 학습 데이터셋 규약 지식 — COCO / YOLO / VOC와 외관 검사의 함정
• mv_cameras — 산업용 카메라 제조사(센서와의 대응·라인 스캔 / TDI)
• mv_illumination_practice — 조명 실무 지식 — 파장·편광·점등 방식·외광·안전
• mv_image_sensors — 산업용 이미지 센서(현행 제품 중심)
• virtual_machine_vision — 가상 머신 비전 — 파라미터 도출과 객체 모형
• 샘플 데이터 카탈로그(DL URL / 라이선스) —— 2-D 는 skimage.data(BSD/public)+ 합성, 3-D 는 실데이터 소스(Stanford/PDS 등)의 DL URL.
• 연산자의 내력·참고문헌 —— 이 연산자 족의 바탕이 된 연구/기법의 출처.
• 알고리즘의 정전(저자·연도)과 용도는 위의 패밀리 사용 가이드에 적혀 있습니다.
• studio_raytrace_scene — py -3.11 examples/studio_raytrace_scene.py
table 를 입력으로 받는 것)abcd_matrix · wavefront_stats · sfr_from_edge · paraxial_trace · seidel_coefficients · spot_stats · tolerance_analysis · wavefront_from_opd
scene)scene_material · scene_plane · scene_sphere · scene_box · scene_cylinder · surface_finish · random_defects · scene_difference
*Provenance: optscene.py — OPTICS 연산자 레지스트리. 이 op 노트는 tools/opdocs.py md 가 자동 생성합니다(직접 편집하지 마세요).*
© 2026 Kazufumi Furuse — Fullseye operator documentation. Licensed under Apache-2.0.