matlab-import-tracking-data

跟踪数据导入

将原始数据导入 MATLAB，以便用于 Sensor Fusion and Tracking Toolbox。支持地面真值轨迹和传感器检测数据，并生成纯 MATLAB 代码。

适用场景

• 用户已记录轨迹／位置数据，想要回放、调整滤波器或评估跟踪器
• 用户拥有传感器测量数据（雷达、红外、激光雷达、相机、声呐），想要将其输入跟踪器
• 用户提到飞行日志、GPS 日志、ADS-B、AIS、雷达录制数据、激光雷达点云或相机检测结果
• 用户询问 trackingDataImporter、objectDetection、trackerSensorSpec、dataFormat 或跟踪器数据导入

不适用场景

• 用户要从头生成合成场景（使用 trackingScenario）
• 用户的数据已符合 SFTT 格式
• 用户需要设计跟踪器或编写跟踪算法（使用 multi-object-tracking skill）
• 用户正在处理原始信号（波形设计、距离-多普勒图）

---

路由：数据类型是什么？

步骤 1：确定数据类型

询问：“你要导入哪种数据？”

用户的数据	路由
记录的位置／轨迹（真值、GPS、飞行日志）	真值路径
传感器测量数据（雷达检测、红外方位、激光雷达框、相机框）	传感器路径

可根据列检查结果进行判断：

• 类似真值的数据：随时间记录每个对象 ID 的连续位置，没有噪声／精度列
• 类似传感器的数据：测量量（距离、方位角、RCS）、精度列、每个时间步有多个检测结果且无法保证 ID 连续性

步骤 2（仅限传感器数据）：确定传感器类型和目标应用

**重要：**如果步骤 1 确定数据属于真值／轨迹数据（随时间记录各平台的位置），请停留在真值路径。即使用户提到 IMM、UKF 或滤波器调整，也不要进入此步骤——这些是调整工具将生成的内容，与输入数据的格式无关。真值数据 → 时间表。传感器数据 → objectDetection 或 dataFormat 结构体。

询问：“是什么传感器生成了这些数据？”以及“你要跟踪什么？”

然后在内部决定 API（不要询问用户使用哪种 API）：

在以下情况下优先使用面向任务的路径：

• 存在匹配的预构建 trackerSensorSpec，或
• 测量数据符合某个 sensorMeasurementModel（az/el/range/rr、位置、位置-速度的任意组合）
• 并且用户不需要 TOMHT/PHD/GridRFS 跟踪器或非 EKF 滤波器

在以下情况下使用旧版 objectDetection 路径：

• 用户需要 TOMHT、PHD 或 GridRFS 跟踪器（面向任务的路径仅支持 GNN/JIPDA）
• 用户需要 UKF、CKF、IMM 或粒子滤波器（面向任务的路径内部使用 EKF）
• 测量数据不符合任何 sensorMeasurementModel（TDOA、自定义几何）
• 用户明确要求使用 objectDetection（用于 trackingFilterTuner 或现有代码）

---

真值路径

真值／轨迹数据（各平台随时间记录的位置、速度）始终生成时间表或结构体数组，绝不生成 objectDetection。即使用户提到滤波器调整、IMM、UKF 或其他滤波器类型，也同样适用。用于调整时，真值路径会生成包含 Time（duration）和 Position、Velocity 列（或单个 State 向量）的时间表。调整工具的检测输入必须来自单独的传感器测量数据——不要根据真值位置伪造 objectDetection。

步骤 1：询问用户（仅 2 个问题）

1. 你需要什么输出？（记录数据／调整数据／真值日志／转换后的表格）
2. 数据在哪里？（文件路径或工作区变量名）

步骤 2：检查数据

读取用户的实际文件——用户提供文件路径时，切勿生成合成数据。使用 readtable 或等效方式加载文件，然后显示列名和示例行。推断数据模型——暂时不要提问：

• 地理坐标还是笛卡尔坐标、类别、时间列及格式、平台／类别 ID 列
• 位置、速度、方向、尺寸列
• 单位（默认度／米／米每秒；如果列名暗示其他单位，则相应调整）

类别选择和列名模式请参阅 references/interpreter-categories.md。

步骤 3：提出映射方案——让用户确认／编辑

编写任何转换代码前，始终先提供数据摘要，即使映射显而易见也不例外。摘要必须包含以下所有内容：

• 在数据中找到的列名
• 检测到的单位（根据列名提示或默认值）
• 平台／对象数量
• 时间范围（第一个／最后一个时间戳、总时长）
• 建议的列到字段映射表（显示未映射的列）

以表格形式展示推断的映射。反复调整，直到用户确认。

步骤 4：询问输出坐标系（仅限地理数据）

选项：笛卡尔 ECEF、笛卡尔固定 NED/ENU（需要原点）、大地坐标局部 NED/ENU。默认与输入相同。请参阅 references/coordinate-transforms.md。

步骤 5：生成并运行代码

生成代码前阅读 references/output-formats.md——其中定义了缺失状态所需的字段和默认值。遵循 references/code-patterns.md 中的模式。关键步骤：

1. 读取数据 → 提取列 → 转换单位 → 解析时间
2. 将平台 ID 重新映射为连续整数
3. 按需转换坐标
4. 构建输出结构（请参阅 references/output-formats.md）
5. 构建输出前按时间排序

步骤 6：可视化

请参阅 references/visualization.md。地理数据 → trackingGlobeViewer；非地理数据 → theaterPlot。

到此为止——不要运行下游工具（跟踪器、trackOSPAMetric、trackingFilterTuner 等）。用户的数据现在已是正确格式。告知用户他们现在拥有的数据，并展示其预期用例的调用方式。

---

传感器流程：面向任务（首选）

当测量数据适用于预构建或自定义的 trackerSensorSpec 时使用。关键点：dataFormat 是动态的——它会随传感器规范属性而变化。切勿对结构体进行硬编码；始终查询它。

步骤 1：选择传感器规范

传感器描述	规范
航空航天单基地雷达	trackerSensorSpec('aerospace','radar','monostatic')
航空航天双基地雷达	trackerSensorSpec('aerospace','radar','bistatic')
ESM／测向仪	trackerSensorSpec('aerospace','radar','direction-finder')
航空航天红外（仅角度）	trackerSensorSpec('aerospace','infrared','angle-only')
汽车雷达（聚类检测）	trackerSensorSpec('automotive','radar','clustered-points')
汽车摄像头（2D 边界框）	trackerSensorSpec('automotive','camera','bounding-boxes')
汽车激光雷达（3D 边界框）	trackerSensorSpec('automotive','lidar','bounding-boxes')
其他标准测量数据	trackerSensorSpec('custom')——请参阅步骤 2b

第 2a 步：根据数据配置规格属性

检查用户的数据，并设置会影响 dataFormat 的属性：

航空航天单站 / ESM / IR：

• HasElevation — 数据是否包含仰角测量？
• HasRangeRate — 数据是否包含距离率 / 多普勒？（仅雷达）
• IsPlatformStationary — 传感器位置是固定还是移动？（设为 false 时，每次观测都会添加 PlatformPosition/Orientation/Velocity）
• MaxNumLooksPerUpdate — 数据中每次更新的最大扫描驻留数
• MaxNumMeasurementsPerUpdate — 数据中每次更新的最大检测数

航空航天双基地：

• HasElevation、HasRangeRate — 同上
• MeasurementMode — "range-angle" 或 "range-only"
• IsReceiverStationary、IsEmitterStationary — 设为 false 时会添加平台字段

汽车雷达：

• HasElevation、MaxNumMeasurements
• ReferenceFrame — 'ego'（测量值在车体坐标系中）或 'global'（可获取自车在全局坐标系中的姿态）

汽车摄像头 / 激光雷达：

• MaxNumMeasurements
• ReferenceFrame — 'ego' 或 'global'

第 2b 步：自定义传感器规格（无合适的预构建规格时）

对于具有标准测量类型但没有预构建规格的传感器（例如海上雷达、声纳）：

sensorSpec = trackerSensorSpec('custom');
sensorSpec.MeasurementModel = sensorMeasurementModel('<modelName>');
sensorSpec.DetectabilityModel = sensorDetectabilityModel('<modelName>');
sensorSpec.ClutterModel = sensorClutterModel('<modelName>');
sensorSpec.BirthModel = sensorBirthModel('<modelName>');

有关完整的模型目录和属性详情，请参阅 references/sensor-data-formats.md。

对于移动传感器，设置 UpdateModels = true — 这会向 dataFormat 添加 Time、TimeVaryingModelData 和 MeasurementVaryingModelData。

第 3 步：检查数据 — 推断单位、时间和参考坐标系

读取用户的实际文件 — 用户提供文件路径时，绝不要生成合成数据。确定以下内容：

1. 时间列和格式 — 使用与真值路径相同的启发式方法进行检测（参阅 references/time-and-units.md）。将时间转换为从第一个时间戳开始的经过秒数。
2. 测量单位 — 根据列名后缀（_deg、_rad、_km、_kts 等）推断，或向用户询问。dataFormat 的目标单位：
   • 角度：度
   • 距离：米
   • 距离率：m/s
   • 位置：米
   • 速度：m/s
3. 参考坐标系 — 如果测量值不在传感器的原生坐标系中，则规划坐标变换：
   • 传感器原生坐标系 = 传感器自然报告测量值所用的坐标系（雷达 / ESM / IR 使用球坐标系，汽车使用车体相对坐标系，摄像头使用图像像素坐标系）
   • 如果用户的数据采用世界坐标系（例如来自融合跟踪器的笛卡尔 NED 位置），而传感器规格要求球坐标测量值，则使用传感器姿态反向转换为传感器原生坐标系
   • 如果用户的数据采用不同的车体坐标系约定（例如 NED 与 ENU），则进行相应旋转
   • 如果数据已经在传感器原生坐标系中（常见情况），则无需转换

第 4 步：查询 dataFormat 并提出映射方案

fmt = dataFormat(sensorSpec);
disp(fmt)

提供映射表供用户确认：

Your column          →  dataFormat field        Action
"azimuth_deg"        →  LookAzimuth (1×N)      direct (deg→deg)
"range_km"           →  Range (M×N)            convert km→m (×1000)
"doppler_mps"        →  RangeRate (M×N)        direct
"timestamp_epoch"    →  MeasurementTime (1×N)  parse epoch→elapsed sec
"elev_rad"           →  LookElevation (1×N)    convert rad→deg
[unmapped: "snr"]    →  (not used)

在“操作”列中注明单位转换和坐标系变换。显示未映射的列。反复调整，直到用户确认。

第 5 步：配置传感器性能属性

根据用户输入设置，或使用默认值：MountingLocation、MountingAngles、FieldOfView、RangeLimits、DetectionProbability、FalseAlarmRate/NumFalsePositivesPerScan。

第 6 步：生成代码

编写代码，在循环中按时间步填充 dataFormat 结构体。输出为一个结构体数组（每次更新一个），可直接传递给跟踪器。到此为止 — 不要创建或运行跟踪器。 告知用户数据已就绪，并展示调用约定：tracker = multiSensorTargetTracker(targetSpec, sensorSpec, algorithm); tracks = tracker(sensorData(iUpdate))

根据欧拉角构建旋转矩阵： 当数据包含偏航角 / 俯仰角 / 横滚角，且需要 3×3 旋转矩阵时（例如用于 PlatformOrientation），请根据四元数构建：

R = rotmat(quaternion([yaw pitch roll], 'eulerd', 'ZYX', 'frame'), 'frame');

预处理标记

数据看起来像……	操作
原始雷达点云（每次扫描包含大量点，没有目标关联）	标记：需要聚类。工具：dbscan、clusterDBSCAN（Radar Toolbox）、partitionDetections。提出创建一个可运行示例。
原始激光雷达 XYZ 点（没有边界框）	标记：需要提取边界框。提出示例。
原始相机图像（没有检测结果）	不在范围内——需要先使用目标检测器。

---

传感器路径：Legacy objectDetection

当面向任务的 API 不适用时使用（TOMHT/PHD 跟踪器、非 EKF 滤波器、自定义测量，或用户明确提出需要）。

标准子路径（内置测量模型）

适用于符合 cvmeas/cameas/ctmeas 的测量——球坐标系下任意组合的方位角/仰角/距离/径向速度，或直角坐标系下的位置/速度。

工作流：

1. 从数据列中识别测量元素
2. 推断单位、时间和参考坐标系（与面向任务的第 3 步相同）：
   • 解析时间列 → 已用秒数（参见 references/time-and-units.md）
   • 从列名检测单位 → 将角度转换为度、距离转换为米、速度转换为 m/s
   • 如果测量值处于世界坐标系，但需要转换为传感器本地坐标系（相对于传感器的球坐标系或直角坐标系），则使用传感器姿态进行转换
3. 设置 Has* 标志：HasAzimuth、HasElevation、HasRange、HasVelocity
4. 确定 Frame：'spherical' 或 'rectangular'
5. 获取每个时间步的传感器姿态（位置、速度、方向）——若传感器静止，则使用固定值
6. 提出映射表——展示数据列到 objectDetection 字段的映射，以及单位/坐标系处理方式。迭代至用户确认。
7. 构建标准 MeasurementParameters 结构体（参见 references/objectDetection-patterns.md）
8. 按正确顺序构造测量向量：
   • 球坐标系：[az, el, range, rr]，移除缺失元素
   • 直角坐标系：[x, y, z, vx, vy, vz]，移除缺失元素
9. 根据精度列或用户指定的值设置 MeasurementNoise
10. 生成 objectDetection 元胞数组
11. **滤波器调优数据（当用户有用于 trackingFilterTuner 的传感器测量数据时）：**调优器需要检测结果与目标的关联。如果传感器数据包含目标 ID 列（例如 TargetID、PlatformID、ObjectID）：
    • 按目标分离检测结果。生成检测日志元胞数组（每个平台一个）。
    • 调优器还需要真值时间表——但这些数据来自通过真值路径获取的独立真值数据源。不要根据传感器测量数据伪造真值，反之亦然。
    • 如果没有目标 ID 列：告知用户 trackingFilterTuner 需要检测结果与目标的关联，并询问他们想如何继续（提供 ID，或使用单目标子集）
12. **到此为止——不要创建或运行跟踪器。**告诉用户：“这些检测结果可与内置滤波器初始化函数配合使用：initcvekf、initcaukf、initctekf、initcvukf 等。”

自定义子路径（非标准测量）

对于不适用于内置模型的测量（TDOA、自定义几何等）：

1. 确认测量具有非标准性质
2. 推断单位、时间和参考坐标系 — 解析时间、转换单位，并在需要时转换到传感器原生坐标系（遵循上述相同规则）
3. 询问：你的状态向量是什么？运动模型是什么？
4. 设计自定义 MeasurementParameters — 必须包含测量函数所需的信息；如果有多个传感器，还必须包含一个判别字段
5. 编写自定义 measurementFcn(state, mp)，将状态映射为预期测量值
6. 使用逆测量模型编写自定义 filterInitFcn(detection)
7. 生成带有自定义 MeasurementParameters 的 objectDetection 数组
8. 将测量函数和滤波器初始化函数作为一对匹配函数交付
9. 到此为止 — 请勿创建或运行跟踪器。 告知用户其检测数据已准备就绪。

请参阅 references/objectDetection-patterns.md，了解标准结构体、测量顺序和多传感器设计模式。请参阅 references/custom-measurement-models.md，了解自定义函数模板。

---

参考文档

需要详细信息时，按需阅读：

• references/output-formats.md — Truth 输出结构体/表格架构（recording、tuning、truthlog）
• references/code-patterns.md — 端到端 Truth 导入代码示例
• references/coordinate-transforms.md — 坐标系转换（LLA→ECEF、NED→ECEF 等）
• references/visualization.md — trackingGlobeViewer 和 theaterPlot 的用法
• references/interpreter-categories.md — Truth 数据类别、状态元素、列名模式
• references/time-and-units.md — 时间解析和单位转换
• references/sensor-data-formats.md — 面向任务的内容：所有预构建/自定义传感器规格属性、模型目录、dataFormat 行为
• references/objectDetection-patterns.md — 旧版内容：MeasurementParameters 结构体、测量向量顺序、多传感器模式
• references/custom-measurement-models.md — 自定义 measurementFcn + filterInitFcn 模板

---

版权所有 2026 The MathWorks, Inc.