matlab-import-tracking-data

# Tracking Data Import

Import raw data into MATLAB for use with Sensor Fusion and Tracking Toolbox. Handles ground truth trajectories and sensor detection data. Writes plain MATLAB code.

## When to Use

- User has recorded trajectory/position data and wants to replay, tune filters, or evaluate trackers
- User has sensor measurements (radar, IR, lidar, camera, sonar) and wants to feed them to a tracker
- User mentions flight logs, GPS logs, ADS-B, AIS, radar recordings, lidar point clouds, camera detections
- User asks about `trackingDataImporter`, `objectDetection`, `trackerSensorSpec`, `dataFormat`, or importing data for trackers

## When NOT to Use

- User is generating synthetic scenarios from scratch (use `trackingScenario`)
- User already has data in the correct SFTT format
- User needs to design a tracker or write tracking algorithms (use the multi-object-tracking skill)
- User is working with raw signal processing (waveform design, range-Doppler maps)

---

## Routing: What Kind of Data?

### Step 1: Determine data type

Ask: "What kind of data are you importing?"

| User's data | Route |
|---|---|
| Recorded positions/trajectories (truth, GPS, flight logs) | **Truth pathway** |
| Sensor measurements (radar detections, IR bearings, lidar boxes, camera boxes) | **Sensor pathway** |

Inference signals from column inspection:
- Truth-like: continuous position per object ID over time, no noise/accuracy columns
- Sensor-like: measurement quantities (range, azimuth, RCS), accuracy columns, multiple detections per timestep without guaranteed ID continuity

### Step 2 (sensor data only): Identify sensor type and target application

**Important:** If Step 1 determined the data is truth/trajectory (positions per platform over time), stay in the Truth Pathway. Do NOT enter this step just because the user mentions IMM, UKF, or filter tuning — those refer to what the tuner will produce, not how to format the input data. Truth data → timetable. Sensor data → objectDetection or dataFormat struct.

Ask: "What sensor produced this data?" and "What are you tracking?"

Then decide the API internally (do NOT ask the user about APIs):

**Use task-oriented path (preferred) when:**
- A prebuilt `trackerSensorSpec` matches, OR
- Measurements fit a `sensorMeasurementModel` (any combo of az/el/range/rr, position, position-velocity)
- AND user does not need TOMHT/PHD/GridRFS tracker or non-EKF filters

**Use legacy objectDetection path when:**
- User needs TOMHT, PHD, or GridRFS tracker (task-oriented only supports GNN/JIPDA)
- User needs UKF, CKF, IMM, particle filter (task-oriented uses EKF internally)
- Measurements don't fit any `sensorMeasurementModel` (TDOA, custom geometry)
- User explicitly requests objectDetection (for `trackingFilterTuner` or existing code)

---

## Truth Pathway

Truth/trajectory data (positions, velocities per platform over time) **always** produces timetables or struct arrays — never objectDetection. This applies even when the user mentions filter tuning, IMM, UKF, or other filter types. For tuning, the truth pathway produces timetables with `Time` (duration) and `Position`, `Velocity` columns (or a single `State` vector). The tuner's *detection* input must come from separate sensor measurement data — do NOT fabricate objectDetection from truth positions.

### 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 user's actual file** — never generate synthetic data when the user provides a file path. Use `readtable` or equivalent to load the file, then display columns + sample rows. Infer the data model — do not ask yet:
- Geo vs Cartesian, category, time column & format, platform/class ID columns
- Position, velocity, orientation, dimension columns
- Units (default degrees/meters/m-per-s; adjust if names hint otherwise)

See `references/interpreter-categories.md` for category selection and column name patterns.

### Step 3: Propose Mapping — Let User Confirm/Edit

**Always present a data summary before writing any conversion code**, even when the mapping is obvious. Include ALL of:
- Column names found in the data
- Detected units (from column name hints or defaults)
- Number of platforms/objects
- Time span (first/last timestamp, total duration)
- Proposed column-to-field mapping table (show unmapped columns)

Present inferred mappings as a table. Iterate until confirmed.

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

Options: Cartesian ECEF, Cartesian Fixed NED/ENU (needs origin), Geodetic Local NED/ENU. Default: same as input. See `references/coordinate-transforms.md`.

### Step 5: Generate and Run Code

**Read `references/output-formats.md`** before generating code — it defines required fields and defaults for missing states. Follow patterns in `references/code-patterns.md`. Key steps:
1. Read data → extract columns → convert units → parse time
2. Remap platform IDs to sequential integers
3. Transform coordinates if needed
4. Build output structure (see `references/output-formats.md`)
5. Sort by time before building output

### Step 6: Visualize

See `references/visualization.md`. Geo → `trackingGlobeViewer`; Non-geo → `theaterPlot`.

**Stop here — do NOT run downstream tools** (trackers, `trackOSPAMetric`, `trackingFilterTuner`, etc.). The user's data is now in the correct format. Tell the user what they have and show the calling convention for their intended use case.

---

## Sensor Pathway: Task-Oriented (Preferred)

Use when measurements fit a prebuilt or custom `trackerSensorSpec`. The key insight: **`dataFormat` is dynamic** — it changes based on sensor spec properties. Never hardcode the struct; always query it.

### Step 1: Select sensor spec

| Sensor description | Spec |
|---|---|
| Aerospace monostatic radar | `trackerSensorSpec('aerospace','radar','monostatic')` |
| Aerosp