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.