---

name: matlab-import-tracking-data description: "Import raw data (CSV, XLSX, TXT, or MATLAB tables) into formats used by Sensor Fusion and Tracking Toolbox. Handles both ground truth trajectories and sensor detection data. For truth: builds trackingScenarioRecording, tuning timetable, truthlog, or converted table. For sensor data: builds task-oriented dataFormat structs (preferred) or objectDetection arrays (legacy). Use when importing flight logs, GPS logs, radar detections, IR measurements, lidar/camera bounding boxes, ADS-B data, AIS ship tracks, or any recorded data for use with trackers, filter tuning, or tracker evaluation." license: https://www.mathworks.com/content/dam/mathworks/license/pmrl/license.md metadata: author: MathWorks version: "1.1"

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') | | Aerospace bistatic radar | trackerSensorSpec('aerospace','radar','bistatic') | | ESM / direction finder | trackerSensorSpec('aerospace','radar','direction-finder') | | Aerospace IR (angle-only) | trackerSensorSpec('aerospace','infrared','angle-only') | | Automotive radar (clustered detections) | trackerSensorSpec('automotive','radar','clustered-points') | | Automotive camera (2D bounding boxes) | trackerSensorSpec('automotive','camera','bounding-boxes') | | Automotive lidar (3D bounding boxes) | trackerSensorSpec('automotive','lidar','bounding-boxes') | | Other standard measurements | trackerSensorSpec('custom') — see Step 2b |

Step 2a: Configure spec properties from the data

Inspect the user's data and set properties that affect dataFormat:

Aerospace monostatic / ESM / IR:

• HasElevation — does data have elevation measurements?
• HasRangeRate — does data have range-rate / Doppler? (radar only)
• IsPlatformStationary — is sensor position fixed or moving? (false adds PlatformPosition/Orientation/Velocity per look)
• MaxNumLooksPerUpdate — max scan dwells per update in the data
• MaxNumMeasurementsPerUpdate — max detections per update in the data

Aerospace bistatic:

• HasElevation, HasRangeRate — as above
• MeasurementMode — "range-angle" or "range-only"
• IsReceiverStationary, IsEmitterStationary — adds platform fields when false

Automotive radar:

• HasElevation, MaxNumMeasurements
• ReferenceFrame — 'ego' (measurements in body frame) or 'global' (ego pose in global frame available)

Automotive camera / lidar:

• MaxNumMeasurements
• ReferenceFrame — 'ego' or 'global'

Step 2b: Custom sensor spec (when no prebuilt fits)

For sensors with standard measurement types but no prebuilt spec (e.g., marine radar, sonar):

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

See references/sensor-data-formats.md for the complete model catalogs and property details.

For moving sensors, set UpdateModels = true — this adds Time, TimeVaryingModelData, and MeasurementVaryingModelData to the dataFormat.

Step 3: Inspect data — infer units, time, and reference frame

Read the user's actual file — never generate synthetic data when the user provides a file path. Determine:

1. Time column & format — detect using the same heuristics as truth pathway (see references/time-and-units.md). Convert to elapsed seconds from first timestamp.
2. Measurement units — infer from column name suffixes (_deg, _rad, _km, _kts, etc.) or ask. Target units for the dataFormat:
   • Angles: degrees
   • Ranges: meters
   • Range-rate: m/s
   • Position: meters
   • Velocity: m/s
3. Reference frame — if measurements are NOT in the sensor's native frame, plan a transform:
   • Sensor-native = the frame the sensor naturally reports in (spherical for radar/ESM/IR, body-relative for automotive, image pixels for camera)
   • If user's data is in a world frame (e.g., Cartesian NED positions from a fused tracker) but the sensor spec expects spherical measurements, convert back to sensor-native using sensor pose
   • If user's data is in a different body frame convention (e.g., NED vs ENU), rotate accordingly
   • If already in sensor-native frame (the common case), no transform needed

Step 4: Query dataFormat and propose mapping

fmt = dataFormat(sensorSpec);
disp(fmt)

Present a mapping table for user confirmation:

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)

Include unit conversions and frame transforms in the "Action" column. Show unmapped columns. Iterate until user confirms.

Step 5: Configure sensor performance properties

Set from user input or use defaults: MountingLocation, MountingAngles, FieldOfView, RangeLimits, DetectionProbability, FalseAlarmRate/NumFalsePositivesPerScan.

Step 6: Generate code

Write code that populates the dataFormat struct per timestep in a loop. The output is an array of structs (one per update) ready to be passed to a tracker. Stop here — do NOT create or run a tracker. Tell the user their data is ready and show them the calling convention: tracker = multiSensorTargetTracker(targetSpec, sensorSpec, algorithm); tracks = tracker(sensorData(iUpdate)).

Rotation matrices from Euler angles: When data has yaw/pitch/roll and you need a 3×3 rotation matrix (e.g., for PlatformOrientation), build it from a quaternion:

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

Preprocessing flags

|