freeform op• 데이터 종류: image2d × image2d × image2d → bspline_surface
• 호출: import fullseye as fs; fs.ledger.fit_bspline_surface(x, y, z, kx=3, ky=3, smooth=None)(구현을 직접 호출하려면 import bspline_surf; bspline_surf.fit_bspline_surface(x, y, z, kx=3, ky=3, smooth=None), 원장에서 가져오려면 ops3d.get("fit_bspline_surface"))
산포 (x, y, z) 에 이중 3 차(기본) B 스플라인 곡면을 최소제곱 적합(bisplrep).
x, y, z : array_like
같은 개수의 산포 샘플 좌표와 높이. 임의의 형상으로 주어도 되며 내부에서 1차원화한다.
kx, ky : int
x/y 방향의 B 스플라인 차수(1=선형, 3=삼차). 점 수가 (kx+1)*(ky+1)에
못 미치면 자동으로 낮춘다(축퇴 회피).
smooth : float or None
평활화 계수 s. None은 점 수 기반 자동값(_auto_surface_smooth).
0.0이면 모든 점 통과(보간 쪽=과적합되기 쉬움), 클수록 매끄럽다.
tck : list
[tx, ty, c, kx, ky]. eval_bspline_surface / surface_residual에 넘긴다.
ValueError
점 수가 선형 곡면에도 부족한 경우(m<4), x/y/z의 길이 불일치, 비유한값,
또는 공선·중복으로 인한 FITPACK 축퇴로 근사를 얻을 수 없는 경우.
보충(구현으로 확인):
• 좌표계는 자유: x, y는 임의의 평면 좌표(row/col이든 실치수든 가능), z는 높이. 3 배열은 ravel로 1차원화하므로 격자 입력이든 산포 입력이든 똑같이 다룬다.
• 차수의 자동 강등은 (kx+1)*(ky+1) > m인 동안 큰 쪽(같으면 kx)을 1씩 낮추고, 둘 다 1이 되면 멈춘다. 강등은 예외가 아니라 조용히 일어나므로, 실제 차수는 반환값 tck[3], tck[4]로 확인할 수 있다.
• smooth=None의 자동값은 max(0, m - sqrt(2m))(FITPACK 권장). z의 잡음 분산이 1 정도라는 전제의 식이므로, z 단위가 작고 잔차 제곱합이 작은 데이터에서는 과평활화되기 쉽다. 그런 경우에는 명시적으로 작은 smooth를 넘긴다.
• FITPACK의 경고(반복 중단 등)는 무시하고 tck를 반환한다. 예외는 모두 ValueError로 번역하며, 계수가 비었을 때도 ValueError.
• 결정론적(난수 없음).
• 후단은 eval_bspline_surface(평가)와 surface_residual(이탈량). 대역적인 저차 파상도만으로 충분하면 fit_poly_surface / eval_poly_surface가 있지만, tck와 다항식 dict는 호환되지 않는다.
• 샘플 데이터 카탈로그(DL URL / 라이선스) —— 2-D 는 skimage.data(BSD/public)+ 합성, 3-D 는 실데이터 소스(Stanford/PDS 등)의 DL URL.
• 연산자의 내력·참고문헌 —— 이 연산자 족의 바탕이 된 연구/기법의 출처.
• bspline_freeform — py -3.11 examples_3d/bspline_freeform.py
bspline_surface 를 입력으로 받는 것)fuse_to_voxel · eval_bspline_surface · surface_residual
freeform)eval_bspline_surface · surface_residual · fit_bspline_curve · eval_bspline_curve
*Provenance: bspline_surf.py — 3D 연산자 레지스트리. 이 op 노트는 tools/opdocs.py md 가 자동 생성합니다(직접 편집하지 마세요).*
© 2026 Kazufumi Furuse — Fullseye operator documentation. Licensed under Apache-2.0.