matlab-import-tracking-data

# 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

| Output | Type | Use With |
|---|---|---|
| **Scenario Recording** | `trackingScenarioRecording` | `play`, scenario replay |
| **Tuning Data** | timetable / cell of timetables | `trackingFilterTuner` |
| **Truth Log** | cell array of struct arrays | `trackGOSPAMetric`, `trackAssignmentMetrics` |
| **Converted Table** | `table` | General inspection |

## 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.