matlab-import-tracking-data

name: matlab-import-tracking-data description: "Import raw ground truth data (CSV, XLSX, TXT, or MATLAB tables) into formats used by Sensor Fusion and Tracking Toolbox: trackingScenarioRecording, tuning data timetable, truthlog struct array, or a clean converted table. Use when the user has recorded position/trajectory data and wants to: replay a tracking scenario from real data, tune tracking filters (EKF, UKF, IMM) with recorded truth, or assess tracker accuracy (GOSPA, OSPA, assignment metrics) against ground truth. Also use when the user mentions trackingDataImporter, importing flight logs, GPS logs, ADS-B data, AIS ship tracks, radar recordings, driving logs, or converting raw position data for use with trackers." license: MathWorks BSD-3-Clause metadata: author: MathWorks version: "1.0"

Tracking Data Import

Import raw ground truth data into MATLAB for use with Sensor Fusion and Tracking Toolbox. This skill drives an agent workflow that writes plain MATLAB code — no App or internal APIs needed.

When to Use

• User has recorded trajectory/position data (CSV, XLSX, TXT, or MATLAB table) and wants to bring it into MATLAB for tracking workflows
• User wants to replay a real-world scenario with trackingScenarioRecording
• User wants to tune tracking filters (EKF, UKF, IMM) using trackingFilterTuner and needs truth data in the right format
• User wants to evaluate tracker accuracy (GOSPA, OSPA, assignment metrics) and needs a truth log
• User mentions flight logs, GPS logs, ADS-B data, AIS ship tracks, radar recordings, or driving logs in the context of tracking
• User asks about trackingDataImporter or importing ground truth for trackers

When NOT to Use

• User is generating synthetic scenarios from scratch (use trackingScenario directly)
• User already has data in the correct SFTT format and just needs to run a tracker
• User needs to import sensor detections (not truth/ground-truth data)
• User is working with image/video data rather than position/trajectory data

Output Formats

Agent Workflow

Step 1: Ask the User (2 questions only)

1. What output do you need? (recording / tuning data / truth log / converted table)
2. Where is the data? (file path or workspace variable name)

Step 2: Inspect the Data

Read the data and display column names + sample rows. From this, infer the data model — do not ask the user yet:

• Geo vs Cartesian: lat/lon columns → geodetic; x/y/z → Cartesian
• Category: Flight log, GPS log, driving log, or custom (see references/interpreter-categories.md)
• Time column & format: name pattern + value magnitude (large → epoch, small → elapsed)
• Platform/Class ID columns: name patterns like "id", "pid", "object_id"
• Position, velocity, orientation, dimension columns: match by name
• Units: default to degrees/meters/m-per-s; adjust if names hint otherwise ("alt_ft", "speed_kts")

Step 3: Propose Mapping — Let User Confirm/Edit

Present a table of inferred mappings:

State Element	Column	Unit
Time (DateTime)	"timestamp"	sec (posix epoch)
Platform ID	"aircraft_id"	—
Latitude	"lat"	degree
...	...	...

Unmapped columns (ignored): "signal_strength", "battery"

Does this look right? Edit anything that's wrong.

Iterate until the user confirms.

Step 4: Ask About Output Frame (geo data only)

Requires Mapping Toolbox or Aerospace Toolbox for coordinate transforms (wgs84Ellipsoid, geodetic2ecef, ned2ecefv). If geodetic data is detected and neither toolbox is available, suggest that the user install one of these toolboxes.

Only for geodetic/earth-referenced data. Options:

• Cartesian ECEF
• Cartesian Fixed NED / ENU (requires origin lat/lon/alt)
• Geodetic Local NED / ENU

Default: same as input. Skip for Cartesian Scenario or Driving data.

Step 5: Generate and Run Code

Write MATLAB code following the patterns in references/code-patterns.md. Key steps:

1. Read data → extract columns → convert units → parse time
2. Remap platform IDs to sequential integers (1, 2, 3, ...)
3. Transform coordinates if needed (see references/coordinate-transforms.md)
4. Build the output structure (see references/output-formats.md)
5. Sort by time before building output

Step 6: Visualize

After conversion, offer to visualize. See references/visualization.md.

• Geo data → trackingGlobeViewer (globe with trajectories)
• Non-geo data → theaterPlot (3D axes with trajectories)

Offer interactive follow-ups: highlight a platform, show a time step, zoom in.

Reference Documents

Read these on-demand when you need the details:

• references/output-formats.md — Exact struct/table schemas for all four output types
• references/code-patterns.md — Complete end-to-end code examples (flight log, driving log, GPS log)
• references/coordinate-transforms.md — When and how to transform between frames
• references/visualization.md — trackingGlobeViewer and theaterPlot usage
• references/interpreter-categories.md — Data model categories, state elements, and units
• references/time-and-units.md — Time parsing and unit conversion reference

Copyright 2026 The MathWorks, Inc.