Fast-F1 CircuitInfo 赛道信息接口完全指南拐角标注、赛道旋转与可视化实战【免费下载链接】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 中与**赛道信息Circuit Information**相关的核心对象fastf1.mvapi.CircuitInfo展开讲解如何通过Session.get_circuit_info()获取一条赛道的拐角corners、裁判灯marshal lights、裁判区段marshal sectors位置以及赛道地图旋转角并将其用于速度曲线标注、赛道地图绘制等可视化任务。读完本文你将掌握 CircuitInfo 的数据结构、各字段语义、Distance列的生成原理以及如何用最短的代码把赛道信息叠加到自己的图表上。关联文档docs/api_reference/circuit_info.rst一、CircuitInfo 是什么API 参考页背后的对象在 API 参考中CircuitInfo被定义为用于可视化和标注数据时有用的赛道信息集合其完整定义位于 fastf1/mvapi/data.py是一个dataclassdataclass class CircuitInfo: corners: pd.DataFrame marshal_lights: pd.DataFrame marshal_sectors: pd.DataFrame rotation: float四个字段分别描述corners所有弯道的标注位置marshal_lights裁判灯的位置赛道旁用于指示黄旗等旗语状态的灯光点marshal_sectors裁判区段的位置用于裁决超车、检测赛道限制的分区点rotation赛道的旋转角度度用于把遥测坐标系的 XY 数据旋转到与官方赛道地图一致的方向。前三者都是结构完全相同的 DataFrame下面统称赛道标记 track markersrotation是标量。数据来源与准确性声明需要特别指出的是这份赛道数据是人工创建、由 MultiViewer 提供并非来自 F1 官方的精确实测数据。官方文档明确说明this data has been manually created and is not highly accurate but sufficient for visualization——即精度满足可视化标注需要但不适合做精确测量。这一点在使用时务必记住尤其当你把标注结果用于对外发布的精确分析时。数据通过网络请求获取入口在 fastf1/mvapi/api.py 的get_circuit()它会请求https://api.multiviewer.app/api/v1/circuits/{circuit_key}/{year}并把 JSON 响应交给上层解析。仓库内置了一份真实响应样例见 fastf1/testing/reference_data/2020_05_FP2/mvapi_circuits.raw其中每个拐角大致形如{angle: 153.79, length: 9070.40, number: 1, trackPosition: {x: -569.58, y: 8153.72}}trackPosition.x与trackPosition.y即最终进入 DataFrame 的X和Y。二、核心数据结构赛道标记 DataFrame 的六列语义corners、marshal_lights、marshal_sectors三个 DataFrame 共用同一套列结构官方文档给出的格式为X float, Y float, Number int, Letter str, Angle float, Distance float每一列的含义如下列名类型含义X/Yfloat标记点在赛道地图坐标系中的位置Numberint弯道编号对裁判灯 / 裁判区段同样使用编号区分Letterstr可选字母后缀用于区分同号弯例如 2AAnglefloat标注偏移角度度用于把标记文字沿合理方向通常垂直赛道偏移摆放Distancefloat标记点距发车线start/finish line的里程需要借助车载遥测计算只有加载了遥测数据才可用Distance 列为什么依赖遥测数据官方文档强调Distance的值needs to be computed using car telemetry as a reference因此只有加载了遥测数据才会填充。其计算逻辑实现在CircuitInfo.add_marker_distance()fastf1/mvapi/data.py原理是最小二乘最近邻匹配取参考圈的遥测并用frequencyoriginal获取原始频率数据只保留Source pos的采样点即 GPS 定位源不含插值点对每一个赛道标记计算其 XY 坐标与所有遥测 XY 采样点之间的平方误差取误差最小的那个采样点的Distance作为标记的里程。对应源码核心片段diff xy_array - marker_xy_array.reshape((-1, 1, 2)) e diff[..., 0] ** 2 diff[..., 1] ** 2 indices np.nanargmin(e, axis1) distances tel.iloc[indices][Distance].to_list() df[Distance] distances从源码结构看若参考圈的遥测未加载或为空该方法会记录一条 warningFailed to generate marker distance information: ...并直接返回此时 DataFrame 中Distance保持NaN。这正是测试 fastf1/tests/test_mvapi.pytest_get_circuit_info_warns_no_telemetry所验证的行为会话以telemetryFalse加载后调用get_circuit_info()日志中会出现上述警告。从 JSON 到 DataFrame 的字段映射get_circuit_info()fastf1/mvapi/data.py依次读取 JSON 中的corners、marshalLights、marshalSectors三组数组并做如下转换trackPosition.x、trackPosition.y→X、Yfloatnumber→Numberintletter→Letterstrangle→AnglefloatDistance统一先填np.nan等add_marker_distance()用遥测回填。顶层字段rotation直接映射为CircuitInfo.rotation。测试 fastf1/tests/test_mvapi.py 确认了六列的列名与数据类型X/Y/Angle/Distance为 float64Number为 int64Letter为 object。三、如何获取 CircuitInfoSession.get_circuit_info()日常使用中你不需要直接调用get_circuit_info()函数而是通过会话对象import fastf1 session fastf1.get_session(2021, Spanish Grand Prix, Q) session.load() # 加载会话数据含遥测 circuit_info session.get_circuit_info()Session.get_circuit_info()fastf1/core.py的内部流程是从session.session_info[Meeting][Circuit][Key]取出赛道的circuit_key调用get_circuit_info(year..., circuit_key...)从 MultiViewer API 获取数据并构建CircuitInfo自动以self.laps.pick_fastest()全场最快圈为参考圈调用add_marker_distance()回填Distance列。因此只要会话加载了遥测数据拿到的circuit_info.corners等 DataFrame 的Distance列就是已填充的可以直接用于按里程定位的图表例如横轴为距离、在弯道处画竖线。需要注意的边界情况若加载会话时telemetryFalseDistance列将保持NaN并产生一条 warning见上文若 API 请求失败或返回无效数据get_circuit_info()会记录Failed to load circuit info警告并返回None测试test_get_circuit_info_invalid_key验证了这一点Mugello 特例源码中对 circuit_key 149 且 ShortName 为 Mugello 的赛道做了特殊处理将 key 改写为 146 再请求。这是从源码可见的实现细节属于对 API 数据缺陷的兼容修正。四、实战一在速度曲线图上标注弯道这是circuit_info最典型的用法之一完整示例见 examples/telemetry/plot_annotate_speed_trace.py。核心思路以Distance为横轴画速度曲线在每个弯道的Distance处画竖直虚线并在线的下方标注弯道编号。import fastf1 import fastf1.plotting import matplotlib.pyplot as plt fastf1.plotting.setup_mpl(mpl_timedelta_supportTrue, color_schemefastf1) session fastf1.get_session(2021, Spanish Grand Prix, Q) session.load() fastest_lap session.laps.pick_fastest() car_data fastest_lap.get_car_data().add_distance() # 获取赛道信息含各弯道里程 circuit_info session.get_circuit_info() team_color fastf1.plotting.get_team_color(fastest_lap[Team], sessionsession) fig, ax plt.subplots() ax.plot(car_data[Distance], car_data[Speed], colorteam_color, labelfastest_lap[Driver]) # 在每个弯道处画竖直虚线范围略超出速度曲线的上下限 v_min car_data[Speed].min() v_max car_data[Speed].max() ax.vlines(xcircuit_info.corners[Distance], yminv_min - 20, ymaxv_max 20, linestylesdotted, colorsgrey) # 在每个弯道下方标注编号含字母后缀如 2A for _, corner in circuit_info.corners.iterrows(): txt f{corner[Number]}{corner[Letter]} ax.text(corner[Distance], v_min - 30, txt, vacenter_baseline, hacenter, sizesmall) ax.set_xlabel(Distance in m) ax.set_ylabel(Speed in km/h) ax.legend() ax.set_ylim([v_min - 40, v_max 20]) plt.show()关键点弯道文字由Number与Letter拼接得到恰好覆盖 2A 这类同号弯场景手动扩展 y 轴下限因为 Matplotlib 不会自动为手工添加的文字预留空间相邻弯道距离很近时文字可能重叠官方示例也注明这是简化方案的已知局限。五、实战二绘制带弯道编号的赛道地图第二个经典场景是用位置遥测画赛道地图并旋转到官方地图方向后标注弯道。完整示例见 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() # 位置遥测X/Y 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) # 1) 用 rotation 把整条赛道旋转到官方地图朝向 track pos.loc[:, (X, Y)].to_numpy() track_angle circuit_info.rotation / 180 * np.pi rotated_track rotate(track, angletrack_angle) plt.plot(rotated_track[:, 0], rotated_track[:, 1]) # 2) 用每个弯道的 Angle 做文字偏移避免文字压在赛道上 offset_vector [500, 0] for _, corner in circuit_info.corners.iterrows(): txt f{corner[Number]}{corner[Letter]} offset_angle corner[Angle] / 180 * np.pi offset_x, offset_y rotate(offset_vector, angleoffset_angle) text_x, text_y rotate([corner[X] offset_x, corner[Y] offset_y], angletrack_angle) track_x, track_y rotate([corner[X], corner[Y]], angletrack_angle) plt.scatter(text_x, text_y, colorgrey, s140) # 圆形气泡 plt.plot([track_x, text_x], [track_y, text_y], colorgrey) # 引线 plt.text(text_x, text_y, txt, vacenter_baseline, hacenter, sizesmall, colorwhite) plt.xticks([]); plt.yticks([]) plt.axis(equal) plt.show()这段代码同时用到了CircuitInfo的两个能力rotation用于旋转遥测坐标系让地图朝向与官方赛道地图一致每个标记的Angle用于把文字气泡沿垂直赛道的方向偏移出去。Angle以度为单位源码中需要先转成弧度再乘旋转矩阵。说明Angle的参考方向为正上方偏移向量初始为[500, 0]具体方向语义以 MultiViewer 提供的数据为准示例中的 500 米偏移量是视觉效果上的经验取值。六、进阶直接使用 get_circuit_info() 与底层数据流如果你不通过Session而是想了解/复用底层能力也可以直接调用模块级函数from fastf1.mvapi import get_circuit_info circuit_info get_circuit_info(year2020, circuit_key39)返回的CircuitInfo中Distance列为NaN需要自己调用add_marker_distance(reference_lap...)回填参考圈可以是任意fastf1.core.Lap且该圈必须已加载位置遥测。测试 fastf1/tests/test_mvapi.py 展示了这条直接调用路径的验证方式。完整的数据流可以概括为Session.get_circuit_info() └─ 读取 session_info 中的 circuit_key含 Mugello 特例修正 └─ get_circuit_info(year, circuit_key) # fastf1/mvapi/data.py ├─ get_circuit() # fastf1/mvapi/api.py │ └─ GET https://api.multiviewer.app/api/v1/circuits/{key}/{year} └─ 解析 JSON → corners / marshalLights / marshalSectors / rotation └─ CircuitInfo.add_marker_distance(pick_fastest()) └─ 最近邻匹配遥测 XY → 回填 Distance由于请求走的是公共 HTTP API同一circuit_key year的数据会被 FastF1 的请求缓存机制Cache.requests_get缓存重复获取不会反复产生网络开销。七、字段速查与使用建议速查表字段类型用途是否依赖遥测cornersDataFrame弯道标注X/Y/Number/Letter/Angle/DistanceDistance 依赖marshal_lightsDataFrame裁判灯位置结构同上Distance 依赖marshal_sectorsDataFrame裁判区段位置结构同上Distance 依赖rotationfloat赛道地图旋转角度否实操建议先session.load()再取get_circuit_info()否则Distance为空且伴随警告横轴为距离的图速度曲线、刹车点分布用corners[Distance]定位画赛道地图时用rotation旋转坐标用每行的Angle偏移标注文字记住数据为人工整理、精度有限适合可视化标注而不适合做毫米级测量想要更深入的源码细节可继续阅读 fastf1/mvapi/data.py、fastf1/mvapi/api.py 以及两个官方示例 plot_annotate_corners.py 与 plot_annotate_speed_trace.py。结语CircuitInfo是 FastF1 中把数据变成图的关键一环它把弯道、裁判灯、裁判区段和地图旋转角打包成统一结构的 DataFrame配合遥测数据自动补全里程信息从而支撑起速度曲线标注、赛道地图绘制等一系列可视化能力。掌握它的数据结构与获取流程你就能在自己的分析脚本里快速叠加赛道语义标注让图表信息量提升一个档次。【免费下载链接】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），仅供参考