ball op• 데이터 종류: signal × points × table → table
• 호출: import fullseye as fs; fs.ledger.fit_spin_aero(t, p, bp: 'dict', *, omega0=None, fit_cl: 'bool' = False, omega_max: 'float' = 1000.0, iters: 'int' = 25, dt: 'float' = 0.001) -> 'dict'(구현을 직접 호출하려면 import ballistics; ballistics.fit_spin_aero(t, p, bp: 'dict', *, omega0=None, fit_cl: 'bool' = False, omega_max: 'float' = 1000.0, iters: 'int' = 25, dt: 'float' = 0.001) -> 'dict', 원장에서 가져오려면 opsdrive.get("fit_spin_aero"))
• GPU: 없음(CPU 참조 구현만)
항력과 회전을 동시에 읽습니다(fit_spin의 C_d 자유 버전): 궤적 (t_i, p_i)(바운드를 포함하지 않는 구간)에 항력 + 마그누스의 운동 방정식을 (p₀, v₀, ω, C_d)의 10개 매개변수로 Levenberg–Marquardt로 피팅합니다(fit_cl=True이면 양력 계수의 배율 κ도 자유롭게 하여 11개 매개변수).
피팅 모델의 C_d는 상수(Re 의존성은 피팅하지 않음)이고, 양력은 회전비의 경험식 C_L = κ·S/(1 + 2S)(S = rω/|v|)이며 배율 κ의 기본값은 1입니다. ★C_L을 수치(상수)로 한 bp는 받지 않습니다(ValueError): 상수 C_L의 마그누스 힘은 크기가 ω와 무관하여 |ω|의 열이 0이 되고, 회전의 크기를 읽을 수 없습니다(실측: 참값 150 rad/s의 궤적에 상수 C_L의 fit_spin을 적용해도 |ω|는 10.3 rad/s까지만 움직임).
읽을 수 없는 것은 반환값에 내보냅니다: 항력은 −v 방향, 마그누스는 ω × v(v에 수직) 방향이므로 힘의 방향은 직교하여 분리되지만, (a) 비행이 짧아 속도가 거의 줄지 않으면 C_d가 v₀와 얽히고, (b) 비행 중 스핀비 S의 변화 폭이 좁으면 ω와 양력 배율 κ를 분리할 수 없으며(S가 작은 영역에서 C_L ≈ κS이므로 힘은 곱 κ·ω에 가깝고, S가 14 %만 움직이는 느린 공 S = 0.49~0.56에서는 C_L(S)를 사실상 한 점에서만 봄), (c) v에 평행한 ω 성분은 힘을 만들지 않습니다. 이는 cond(스케일 후 야코비안의 조건수), corr(추정량의 상관 행렬, param_names 순서), cov_unit(위치 잡음 1 m당 추정량의 공분산 = 선형화한 크라메르–라오 하한. 잡음 σ [m]이면 σ² 배), corr_cd_omega(C_d와 ω⊥ 크기의 상관), corr_cd_v0(C_d와 초속 크기의 상관), omega_axial_std_unit(ω의 평행 성분의 표준편차, 잡음 1 m당), omega_perp_std_unit(ω의 수직 2성분 각각의 표준편차)로 알 수 있습니다. 읽을 수 있는 조건: 같은 모델의 선형화에서 fit_cl=True의 ω⊥ 표준편차(잡음 1.5 mm)는 v₀ = 6 m/s에서 628 rad/s(419 %), 15 m/s에서 76(50 %), 25 m/s·ω = 300 rad/s에서 35(12 %)입니다: 퇴화는 S가 거의 움직이지 않는 조건의 결론이지 '궤적만으로는 원리적으로 읽을 수 없다'가 아니며, 빠른 공이나 크게 감속하는 비행에서는 읽을 수 있습니다. 야코비안의 계수(rank)가 떨어지면(예: 진공) cond는 inf가 아니라 None이고 rank_deficient가 True입니다. ω⊥ = 0이면 방향이 정해지지 않아 corr_cd_omega는 None입니다(NaN은 반환하지 않음). 반환값 {"p0", "v0", "omega", "omega_perp", "cd", "cl_scale", "rms", "cond", "rank_deficient", "corr", "param_names", "cov_unit", "corr_cd_omega", "corr_cd_v0", "omega_axial_std_unit", "omega_perp_std_unit", "iters", "t0", "at_bound"}. 같은 모델로 만든 궤적은 1e-6으로 복원됩니다(게이트). ★세계가 다른 모델(C_d가 Re 의존, C_L에 골이 있음)이면 상수로 피팅한 C_d·ω·C_L은 그 구간의 유효값이 되어 치우칩니다(치우침은 PoC에서 측정해 제시). 치우침은 골에 한정되지 않습니다: 피팅한 C_L 모델이 세계의 계수를 빗나가면 ω가 끌려가며 계수 오차의 1.5~2.7배로 증폭됩니다(골 없는 세계에서 계수를 0.6 / 0.8 / 1.2배로 하면 κ = 1 피팅은 ω를 58 / 34 / +53 % 빗나감). 피팅이 어긋났는지는 rms에 나타납니다. omega_max는 fit_spin과 같습니다(회전 크기의 상한). omega0가 참값에서 멀거나 궤적이 짧거나 fit_cl=True이면 수렴이 느리고, 평평한 골에서 iters에 도달하지 못하는 표본이 있습니다(반환된 iters가 인수와 같으면 중단된 것).
한계: 비행 중 스핀비 S의 변화 폭이 좁으면 fit_cl=True에서 |ω|와 κ의 열이 거의 평행합니다(cond가 크고 corr ≈ ±1; S = 0.49~0.56의 느린 공은 ω⊥ 표준편차가 ω의 419 %, v₀ = 25 m/s의 빠른 공은 12 %) — 그때는 ω를 공의 무늬에서 읽고(balltrack.spin_from_markers) 양력 배율은 궤적에서 구하십시오(ω를 알 때의 fit_aero). 상수 C_L의 bp와 12개 미만의 표본은 ValueError를 일으키고, 야코비안의 계수가 떨어지면 cond는 None(inf를 반환하지 않음), ω⊥ = 0이면 corr_cd_omega는 None입니다.
• 샘플 데이터 카탈로그(DL URL / 라이선스) —— 2-D 는 skimage.data(BSD/public)+ 합성, 3-D 는 실데이터 소스(Stanford/PDS 등)의 DL URL.
• 연산자의 내력·참고문헌 —— 이 연산자 족의 바탕이 된 연구/기법의 출처.
• 알고리즘의 정전(저자·연도)과 용도는 위의 패밀리 사용 가이드에 적혀 있습니다.
• poc_cd_spin_joint — py -3.11 examples/poc_cd_spin_joint.py
table 를 입력으로 받는 것)course_layout · course_occupancy · course_contains · world_build · world_camera · world_move · lidar_scan · rss_longitudinal_same
ball)ball_params · impact_params · flight_vacuum · flight_ode · flight_simulate · flight_state_at · magnus_lift_coefficient · drag_coefficient_sphere
*Provenance: ballistics.py — DRIVE 연산자 레지스트리. 이 op 노트는 tools/opdocs.py md 가 자동 생성합니다(직접 편집하지 마세요).*
© 2026 Kazufumi Furuse — Fullseye operator documentation. Licensed under Apache-2.0.