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 自由版)：以 (p₀, v₀, ω, C_d) 的 10 個參數，用 Levenberg–Marquardt 將含阻力 + 馬格努斯的運動方程擬合到軌跡 (t_i, p_i)(不含彈跳的區間)(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(ω 兩個垂直分量中每個分量的標準差)。可讀的條件：同一模型線性化下，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 幾乎不變的條件下的結論，而不是“原理上無法從軌跡讀出”；快球和大幅减速的飛行是可以讀出的。雅可比矩陣降秩時(例如真空)cond 為 None 而不是 inf，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。
• 範例資料目錄(下載 URL / 授權) —— 2-D 用 skimage.data(BSD/公有領域)加合成圖,3-D 給出真實資料源(Stanford/PDS 等)的下載 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 運算子登記表。本條目由 tools/opdocs.py md 自動產生(請勿手動編輯)。*
© 2026 Kazufumi Furuse — Fullseye operator documentation. Licensed under Apache-2.0.