FastF1 v3.1 系列更新深度解读：赛道标注数据、Laps 选择方法升级与解析性能优化

FastF1 v3.1 系列更新深度解读赛道标注数据、Laps 选择方法升级与解析性能优化【免费下载链接】Fast-F1FastF1 is a python package for accessing and analyzing Formula 1 results, schedules, timing data and telemetry项目地址: https://gitcode.com/GitHub_Trending/fa/Fast-F1本文基于 FastF1 官方变更日志 docs/changelog/v3.1.x.rst系统解读 v3.1.0 至 v3.1.5 五个小版本的全部更新包括新增的赛道弯角/旗语灯标注数据Session.get_circuit_info、SessionInfo属性、Laps.pick_*系列圈速选择方法的重构、赛车数据与位置数据解析的大幅提速以及围绕pick_fastest的弃用路线。读完本文你将掌握 v3.1 系列每项新能力的调用方式、底层实现原理与升级时的注意事项可直接迁移到自己的 F1 数据分析项目中。一、v3.1.x 版本更新全景v3.1 系列从 2023 年 8 月 29 日发布 v3.1.0 起到 11 月 24 日发布 v3.1.5 止共经历 6 次发布覆盖新功能、性能、Bug 修复与弃用四条主线版本发布日期核心内容v3.1.02023-08-29新增赛道信息弯角/旗语灯/旗语区/地图旋转、SessionInfo属性、Laps.pick_*方法重构、解析性能大幅提升v3.1.12023-08-29热修复纠正错误的包定义恢复 FastF1 可导入性v3.1.22023-08-31临时将 Pandas 限制在2.1.0规避意外 API 变更v3.1.32023-10-07修复 2023 卡塔尔冲刺排位赛车手列表解析 BugPiastri 缺失v3.1.42023-10-26修复Telemetry.add_driver_ahead、圈数/发车圈进站时间等问题新增多位车手颜色v3.1.52023-11-24修复pick_fastest空结果行为与拉斯维加斯大奖赛加载问题并预告弃用路线其中 v3.1.0 是功能密度最高的大版本以下按主题逐一展开。二、赛道标注数据Session.get_circuit_info()v3.1.0 新功能2.1 功能定位v3.1.0 引入了全新的赛道附加信息包含弯角corners、旗语灯marshal lights、旗语区marshal sectors的位置以及赛道地图的旋转角度rotation。这些数据可通过Session.get_circuit_info()获取最典型的应用场景是为赛道图标注弯角编号、为速度/轨迹图添加视觉参考。该数据由 MultiViewer 提供通过其 API 提供FastF1 团队在变更日志中对此表示了致谢。需要注意官方说明明确指出这些数据为人工创建精度有限适合用于可视化标注而非高精度测量。2.2 源码实现与调用链从源码看调用链为Session.get_circuit_info() # fastf1/core.py#L2790 → mvapi.get_circuit_info(year, circuit_key) # fastf1/mvapi/data.py#L120 → mvapi.api.get_circuit(...) # MultiViewer API 请求 → CircuitInfo.add_marker_distance(reference_lap)在 core.py 中get_circuit_info首先从session_info中提取赛道的circuit_key随后调用 mvapi/data.py 中的get_circuit_info从 MultiViewer API 拉取原始数据并转换为CircuitInfo对象。实现中还包含一个特例处理当circuit_key 149且赛道短名为 Mugello 时会将 key 修正为 146以对齐正确的赛道数据。2.3CircuitInfo数据结构CircuitInfo是一个 dataclass定义于 fastf1/mvapi/data.py包含四个字段corners弯角位置DataFramemarshal_lights旗语灯位置DataFramemarshal_sectors旗语区位置DataFramerotation赛道地图旋转角度单位度float用于将遥测坐标旋转到与官方赛道图一致的方向前三类赛道标记共用相同的 DataFrame 列格式列名类型含义Xfloat赛道图上的 X 坐标Yfloat赛道图上的 Y 坐标Numberint弯角编号旗语灯/旗语区也有自己的编号Letterstr可选字母用于区分同编号的弯角如 2AAnglefloat角度度用于将标记在赛道图上以合理方向通常垂直于赛道做视觉偏移Distancefloat标记距起终线的距离米需要遥测数据作为参考计算加载遥测后才可用从 mvapi/data.py 的解析逻辑可以看到corners、marshalLights、marshalSectors三类数据均从 API 响应对应字段提取trackPosition.x/y、number、letter、angle而Distance初始为NaN等待后续计算填充。2.4Distance的计算原理Distance字段由CircuitInfo.add_marker_distance(reference_lap)计算mvapi/data.py该方法是私有辅助方法在get_circuit_info中被自动调用参考圈取自session.laps.pick_fastest()。其原理是最小二乘最佳拟合取参考圈的原始位置遥测限定Source pos以保证使用未插值的真实位置采样将每个标记的 XY 坐标与全部遥测 XY 样本逐一求平方误差取误差最小的遥测样本对应的Distance值作为该标记的距离。因此只有加载了位置遥测数据的会话才能得到有效的Distance若遥测未加载DataNotLoadedError或为空方法会记录 warning 并静默跳过Distance保持为NaN。2.5 实战示例绘制带弯角标注的赛道图仓库自带示例 examples/general/plot_annotate_corners.py 演示了完整用法import matplotlib.pyplot as plt import numpy as np import fastf1 session fastf1.get_session(2023, Silverstone, Q) session.load() lap session.laps.pick_fastest() pos lap.get_pos_data() circuit_info session.get_circuit_info() # 使用旋转矩阵将坐标旋转到与官方赛道图一致的方向 def rotate(xy, *, angle): rot_mat np.array([[np.cos(angle), np.sin(angle)], [-np.sin(angle), np.cos(angle)]]) return np.matmul(xy, rot_mat)示例脚本通过circuit_info.rotation旋转坐标系统再遍历circuit_info.corners的每一行用X/Y定位、Number/Letter标注弯角编号。同目录下的 plot_annotate_speed_trace.py 则展示了将弯角数据叠加到速度轨迹曲线上的另一种用法。核心要点是session.load()默认即加载位置遥测因此Distance通常可直接使用。三、Session.session_info直通 F1 官方实时 API 的会话元数据v3.1.0v3.1.0 将 F1 官方 livetiming API 的 SessionInfo 端点数据暴露为Session.session_info属性。从 core.py 的源码注释可知该属性包含会议Meeting、会话Session、国家与赛道名称及 id 键这些 id 是 F1 API 使用的唯一标识符。实际使用方式为import fastf1 session fastf1.get_session(2023, Silverstone, Q) session.load() # 直接访问原始 SessionInfo 字典 circuit_key session.session_info[Meeting][Circuit][Key] short_name session.session_info[Meeting][Circuit][ShortName]该属性与get_circuit_info存在依赖关系——后者正是从session_info中读取circuit_key来请求赛道标注数据的core.py。如果数据未加载访问该属性会通过_get_property_warn_not_loaded发出警告源码见 core.py。四、Laps.pick_*系列方法重构v3.1.0v3.1.0 对Laps的圈速选择方法做了系统性升级由 Casper-Guo 贡献issue #376核心思路是让方法接受单值或值列表并补齐此前缺失的筛选维度。4.1 新增pick_not_deleted用于筛出所有未被取消成绩的圈速。圈速可能因违反赛道限制等原因被赛会删除。该方法依赖比赛控制信息race control messages调用前需以Session.load(messagesTrue)加载数据否则抛出DataNotLoadedError。源码见 core.py。session fastf1.get_session(2023, Silverstone, Q) session.load(messagesTrue) valid_laps session.laps.pick_not_deleted()4.2 新方法替换旧版单值方法以下三组方法为升级版均接受单个值或可迭代列表并取代只接受单值的旧方法新方法取代的旧方法示例pick_laps(lap_numbers)pick_lapsession.laps.pick_laps(range(10, 21))pick_drivers(identifiers)pick_driversession.laps.pick_drivers([5, BOT, 7])缩写与车号可混用pick_compounds(compounds)pick_tyresession.laps.pick_compounds([SOFT, MEDIUM, HARD])从 core.py 的实现看pick_laps通过LapNumber.isin()过滤并会校验传入的浮点数必须是整数值pick_driverscore.py则自动将非数字输入转为大写缩写、数字输入转为车号字符串再分别对Driver与DriverNumber列做isin匹配pick_compoundscore.py会对化合物名称统一upper()处理可用的化合物取值包括SOFT、MEDIUM、HARD、INTERMEDIATE、WET、UNKNOWN、TEST_UNKNOWN。4.3 增强pick_track_status的how参数pick_track_status(status, howequals)新增了更多匹配模式core.py用于按赛道状态筛选圈速how取值行为说明equals精确相等status2只匹配2contains子串包含status2也会匹配267excludes排除包含该状态的圈速status26不匹配267但匹配27any匹配状态值中任意一位status26同时匹配含2或6的圈速none排除状态值中任意一位status26既不匹配12也不匹配16非法how值会抛出ValueError。contains/excludes基于str.contains非正则any/none基于按位正则匹配因此可用any一次排除/筛选多种赛道状态。4.4 弃用Deprecations以下旧方法在 v3.1.0 中被标记弃用调用时会触发FutureWarning并将在未来版本移除Laps.pick_lap→ 改用pick_lapsLaps.pick_driver→ 改用pick_driversLaps.pick_tyre→ 改用pick_compounds同类变化还包括pick_team→pick_teams支持单个或多个车队名见 core.py。建议在升级时同步迁移代码避免未来主版本破坏兼容性。五、性能优化与关键 Bug 修复5.1 性能赛车数据与位置数据解析大幅提速v3.1.0 显著提升了赛车数据car data与位置数据position data的解析速度。这两类数据是 F1 遥测分析中最庞大的数据集以毫秒级频率记录解析效率直接决定会话加载时间对大规模批量分析如整赛季回放影响明显。该优化对使用者透明无需改动代码即可受益。5.2 v3.1.4 的修复清单v3.1.42023-10-26集中修复了一批与数据解析和圈速边界相关的问题Telemetry.add_driver_ahead修复此前该方法仅在遥测数据与赛车数据采样时基匹配时才生效issue #430修复后兼容不同采样频率的遥测数据Ergast API 解析器健壮性提升避免因 API 响应中的空值导致崩溃issue #433由 harningle 贡献圈速编号错误修复部分由 FastF1 生成的圈速圈号不正确的问题发车圈进站时间修正比赛类会话的第一圈不再显示发车圈出站时间pit out time除非车手从维修区起步或在暖胎圈进站issue #467由 Casper-Guo 贡献赛程后端健壮性修复f1timing赛程后端因卡塔尔大奖赛部分错误数据导致的崩溃圈速精度标记修复此前若某一位车手的圈速精度校验无法执行会导致所有车手的圈速都被标记为不准确现已修正。5.3 其他版本修复v3.1.32023-10-07修复车手列表解析器 Bug此前导致 2023 卡塔尔冲刺排位赛Sprint Shootout结果中缺少 Piastriissue #460v3.1.52023-11-24修复部分拉斯维加斯大奖赛Las Vegas GP会话无法加载的问题issue #481v3.1.0修复split_qualifying_sessions返回错误结果、排位类会话成绩计算错误issue #429、圈速起止时间错位导致遥测对比偏移与发车位置计算错误issue #440、2020 迈阿密排位赛加载异常issue #431、红旗重启后圈速开始时间错误以及部分数据缺失时数据加载受阻的问题。5.4 圈速精度与split_qualifying_sessions与上述修复相关的两个常用能力值得了解Laps.pick_accurate()筛选所有通过精度校验IsAccurate True的圈速core.py可用于规避数据质量问题Laps.split_qualifying_sessions()将排位赛圈速拆分为 Q1/Q2/Q3 三个独立的Laps对象core.py。该方法的实现在 v3.1.0 中被修复优先使用计时数据解析器生成的官方分段时间否则回退到会话状态数据中的 Started 时间戳并正确处理红旗中断后重启的情况。被取消的排位赛段会返回None。q1, q2, q3 session.laps.split_qualifying_sessions() fastest q3.pick_fastest()六、pick_fastest行为变更与弃用路线v3.1.56.1 修复内容v3.1.5 修复了Laps.pick_fastest()在没有任何圈速满足条件时返回行为不一致的 Bugissue #476由 Casper-Guo 贡献。修复后当不存在满足最快圈条件的圈速时始终返回一个空的Lap对象。6.2 未来的行为变更变更日志同时明确了弃用路线自 v3.3 起pick_fastest()在无匹配圈速时将返回None而不是空Lap。这意味着依赖空Lap判空逻辑的代码需要在 v3.3 之前迁移。从 core.py 的当前实现看pick_fastest(only_by_timeFalse)的筛选逻辑是默认只考虑被标记为个人最快IsPersonalBest True的圈速——若某圈成绩因超出赛道限制被删除则不会被标记当only_by_timeTrue时则忽略个人最快标记直接返回圈速最低的一圈。当前版本在无候选圈速或LapTime全为 NaN 时返回None多个圈速并列最快时取先记录的一圈。七、车手颜色与绘图支持v3.1 系列多次为车手颜色表新增条目v3.1.0新增 Shwartzman 与 Lawson由 pesaventofilippo 贡献issue #441v3.1.4新增 VES、POU、HAD、DOO、BEAissue #471v3.1.5新增 OWA、DEN、OSU。从绘图模块源码看车手颜色的解析最终落到车队颜色fastf1.plotting.get_driver_color(identifier, session, colormap..., exact_match...)返回的是该车手在会话中所属车队的十六进制颜色plotting/_interface.py其注释明确指出与旧版 FastF1 不同现在没有为每位车手单独设色。因此这些新增条目实质上是为 2023 赛季的替补/新晋车手如自由练习赛的年轻车手补齐了到正确车队的颜色映射确保绘图 API 不会因未知车手而匹配失败。颜色数据集中维护在 fastf1/plotting/constants.json 中按年份组织每个车队条目包含short_name与official/fastf1两套配色。相关配色图览见 docs/_plots/colormap_overview.py。八、依赖约束与升级建议8.1 Pandas 版本约束v3.1.2v3.1.2 将 Pandas 临时限制在2.1.0原因是 Pandas 2.1.0 引入了意外的 API 变更。升级到 v3.1.2 及后续版本时请确保环境中的 Pandas 版本低于 2.1.0pip install pandas2.1.0 fastf13.1.2,3.28.2 升级检查清单从 v3.1 系列的变化看升级后建议做以下检查替换弃用方法将pick_lap/pick_driver/pick_tyre/pick_team全部迁移到复数版本pick_laps/pick_drivers/pick_compounds/pick_teams关注pick_fastest空结果语义避免依赖空Lap的判空逻辑为 v3.3 返回None做好准备检查遥测对比代码v3.1.0 修复了圈速起止时间错位问题修复前对比圈速遥测可能出现系统性偏移修复后对比结果可能发生变化注意发车圈 pit out 时间v3.1.4 起比赛首圈不再显示发车圈出站时间除非从维修区起步或暖胎圈进站相关统计脚本需相应调整确认测试通过仓库测试套件 fastf1/tests 中的 test_core.py、test_laps.py、test_input_data_handling.py、test_telemetry.py 等覆盖了pick_drivers、pick_laps、split_qualifying_sessions、pick_fastest等核心路径升级后可运行测试套件快速验证环境兼容性。九、总结FastF1 v3.1 系列是功能 稳健性并重的一次版本迭代get_circuit_info让赛道图标注从手动画点变为一行代码Laps.pick_*的列表化改造让圈速筛选组合更灵活赛车/位置数据解析提速让大批量分析更高效而pick_fastest的弃用路线则为 v3.3 的 API 收敛提前铺路。对于正在使用 v3.0 及更早版本的项目按本文第八节的清单完成迁移即可平滑升级。【免费下载链接】Fast-F1FastF1 is a python package for accessing and analyzing Formula 1 results, schedules, timing data and telemetry项目地址: https://gitcode.com/GitHub_Trending/fa/Fast-F1创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考