Import Flight Log Data Using Tracking Data Importer App

Since R2025a
Open Live Script

The Tracking Data Importer app enables you to process the truth data by identifying the data information, visualizing the data on a map, and ultimately exporting the data in formats compatible with Sensor Fusion and Tracking Toolbox™ functionalities.

Introduction

The Tracking Data Importer app enables you to import a truth data file for tracking purposes and export truth data in various formats. The general workflow is as follows:

  1. Import — Import a truth data file in the form of spreadsheet, text file, CSV file, table, or timetable.

  2. Convert — Convert the truth data to a standard format via modeling and mapping.

  3. Visualize — An optional step to validate the imported and converted data by visualizing the data on a map.

  4. Export — Export the data in a format of choice. You can also export a standalone TrackingTruthDataImporter object for processing similar truth data files outside of the app.

Launch Tracking Data Importer

To launch the application, use the command:

trackingDataImporter

After that, the app opens and prompts you to import truth data to start.

Import Log of Single Flight

Import the trajectory log of a flight from Los Angeles International Airport to Boston Logan International Airport, saved in the spreadsheet LAToBostonFlightLog.xlsx. The file has six columns:

  • time — Flight time, written in dd-MMM-yyyy HH:mm:ss format.

  • latitude — Flight latitude in degrees.

  • longitude — Flight longitude in degrees.

  • altitude — Flight altitude in feet.

  • speed — Flight speed in miles per hour.

  • climbrate: Flight climbrate in feet per minute.

Import File

To import the file, click the Import button and select the Import from file option.

Then, follow the prompts to import the LAToBostonFlightLog.xlsx file from the example folder. After the file has been imported, the truth data shows in the Imported Table document in the app.

Create Converter and Convert

To identify information in the imported table, you create a converter that contains a list of data elements expected by the toolbox and then map the imported table columns to these data elements.

Define New Converter

Click the New Converter button and choose Flight Log to interpret a common flight log.

After that, the app opens the converter definition dialog box.

You can modify these attributes in the converter:

  • Name — The dialog box provides a default converter name, FlightLog1. You can change the name.

  • Frame Type — In a flight log converter, you can choose between Local NED for North-East-Down or Local ENU for East-North-Up as the reference frame. Local indicates that the reference frame, used as the reference for velocity, acceleration, orientation, and so on, is local to the latitude, longitude, and altitude at each point.

  • Time Type — You can choose between datetime and duration. Date time represents points in time, whereas duration represents elapsed times in units of fixed length.

The table on the right lists all the data elements provided in this converter. The options you select on the left can affect the element list. For example, setting Time Type to Duration changes the first element in the table to Duration.

In the table, the elements with an asterisk are those you must map to from the imported table columns in the next step.

Since the flight log data is recorded in the local NED frame and the time type is described in terms of month, day, year, and so on, you use the default configuration by clicking the Confirm button. The the FlightLog1 converter now becomes the current converter and a mapping panel shows on the left. You can then map the raw data columns to the data elements.

Map Date Time Data Element

First, select time from the Match To dropdown. The date time mapping supports three data types.

  • Numeric — Use this option when the time column is in numeric values. For example, 110000000 seconds in posix or UNIX time.

  • Datetime String — Use this option when the time column is expressed in datetime strings, which is the case in this example. You can further specify the time string format by selecting an option from the Format dropdown box or by typing in the format. In this example, the default time format dd-MMM-yyyy HH:mm:ss is what the imported table has.

  • Datetime Object: Use this option when importing a table from the workspace and when the time column is in datetime objects.

Map Other Data Elements

The mapping of other data elements is straightforward. Simply match columns in the imported table with the corresponding data elements. After that, select the unit of the matched column. For example, match the altitude column to the Altitude data element and set its unit to ft. After you map all the required elements (Data Time, Latitude, and Longitude in the case of this example), the app enables the Convert button in the toolstrip. You can also click the Save Converter button to save the current converter for reusing it in this or other sessions of the app.

Convert Imported Table

Click the Convert button on the app toolstrip to convert the imported table into a converted table. Note that:

  • The converted Date Time column is a column of datetime objects.

  • The units of all other columns are standard units.

  • To examine the conversion, you can left-click any row or cell in the imported or converted table and observe that the corresponding row or cell is selected in the other table.

  • You can sort each column in the converted table by clicking the sort arrow in column header.

Visualize Data on Globe

After the conversion, you can optionally visualize the truth data on a map. Click the Visualize button in the toolstrip and the app displays the trajectory from Los Angeles to Boston on the globe. You can change camera direction and height of the view by using your mouse.

To inspect a specific truth data point on the map, you can click the row corresponding to that point in the imported or converted table. For example, clicking the first row in either table shows the first point in the flight trajectory when the flight is about to depart from the Los Angeles International airport.

Clicking the last row shows the last point in the flight trajectory when the flight is about to land at the Boston Logan International airport.

Export Truth Data

Once the data conversion is complete, the app enables the Export button on the toolstrip. Click the button and then click Truth Log.

The export dialog box appears and you can specify the name of the variable to be exported to MATLAB workspace. You can also change the coordinate frame for exportation. For example, you can change the output frame to the ECEF (Earth-Centered-Earth-Fixed) frame by selecting Coordinate Type to Cartesian and selecting Frame Type to ECEF. After that, click on the Export button to export the truth log to the workspace.

To learn how to evaluate metrics of tracking results against truth, see Introduction to Tracking Metrics.

Export TrackingTruthDataImporter

Alternatively, you can export a TrackingTruthDataImporter object that holds the core algorithms of the converter so that you can use the object to process similar files. This code loads a saved TrackingTruthDataImporter object and shows its display that contains essential information.

load truthImporterFile.mat;
truthImporter
truthImporter = 
TrackingTruthDataImporter with configurations:

Converter Name: FlightLog1
Input File Format: spreadsheet
Input Data Information: 
        Category:  Flight Log
      Frame Type:  Local NED

Elements and Mapping: 
     State Element     Unit       Original Column     Unit(Format)                         
     -------------     ------     ---------------     -------------------------------------     
     Date Time         sec        time                datetime string(dd-MMM-yyyy HH:mm:ss)
     Latitude          degree     latitude            degree                               
     Longitude         degree     longitude           degree                               
     Altitude          m          altitude            ft                                   
     Speed             m/s        speed               mi/h                                 
     Course            degree     course              degree                               
     Climb Rate        m/s        climbrate           ft/m                                 

Output Data Information: 
      Coordinate Type:  Cartesian
           Frame Type:  ECEF

Usage: 
      trackingScenarioRecording:  Export as a trackingScenarioRecording object for playing and metric evaluation
                       truthlog:  Export as a truth log structure for metric evaluation
                     tuningData:  Export as a tuning data structure for tracking filter turning
                 convertedTable:  Export converted table

Apply the importer object to the IncheonToNewYorkFlight.xlsx file to get a truth log.

truthlog(truthImporter,"IncheonToNewYorkFlight.xlsx")
ans=940×1 cell array
    {1×1 struct}
    {1×1 struct}
    {1×1 struct}
    {1×1 struct}
    {1×1 struct}
    {1×1 struct}
    {1×1 struct}
    {1×1 struct}
    {1×1 struct}
    {1×1 struct}
    {1×1 struct}
    {1×1 struct}
    {1×1 struct}
    {1×1 struct}
    {1×1 struct}
    {1×1 struct}
      ⋮

Import Log of Multiple Flights

Import a log of multiple flights saved in the MultiFlightsNearLoganAirport.xlsx file. This file contains the trajectory data for four flights near Boston Logan airport, with two flights departing and two flights approaching.

Importing a new file overwrites the data from the existing session. To prevent this, you can click the Save Session button in the toolstrip to save the session. Next, click on the Import button and import the new data file as follows. The data file has columns that are the same as the previous file, but it also has additional columns including yaw, pitch, roll, length, width, and height. It also has a flightNumber column used to distinguish between different flights.

At this point, you have a few options to proceed:

  • Directly make changes to the current converter to accommodate the newly imported table.

  • To avoid making changes to the current converter, you can duplicate this converter and modify the duplicated converter.

  • Create a new converter.

The following subsections demonstrate the second the third options.

Duplicate and Modify Converter

Click the Current Converter dropdown from the toolstrip and select Manage all converters.

A converter management dialog shows up. Click on the Duplicate button to create a duplicated converter automatically named as FlightLog1_Copy. After that, click on the Edit button to edit the converter.

In the converter editing dialog, rename the converter as FlightLog_MultiFlight. After that, click Confirm to proceed.

In the new FlightLog_MultiFlight converter, additionally map flightNumber, yaw, pitch, and row columns to Platform ID, Yaw, Pitch, and Row data elements, respectively. After that, you follow the previously demonstrated workflow to convert and visualize the data.

The map below shows that the truth data file contains four flight trajectories. Flight 1 and Flight 3 arrive at Logan airport, whereas Flight 2 and Flight 4 depart from Logan airport.

Using the converted table, you can click each row to explore each data point. You can also:

  • Right-click a time cell to highlight all platform poses at this time.

  • Right-click on a Platform ID cell to:

a) Show the platform ID conversion table

b) Highlight the trajectory of a particular platform by its ID

These data query options can provide you with finer scopes on the imported data and conversion.

New Custom Converter

You may have noticed the length, width, and height columns are not mapped. A flight log usually does not contain platform size information and therefore the flight log converter does not incorporate these data elements. However, if you need to map or visualize the platform extent for a flight log, you can use a custom converter.

Create a custom converter by clicking the New Converter dropdown gallery and selecting the Custom Converter item. After that, a custom converter dialog appears.

As always, you can specify a converter name. You can also configure the reference frame for the imported table and target extent information by selecting the model options. See the Converter Options section on Tracking Data Importer for more details on the definition of each option.

For the purpose of converting all the columns in the imported table, you change Target Extent from Point to Box. Notice that the table now contains size information.

Click Confirm and then map the raw table elements, convert the data, and visualize the data. After these steps, click row 68 in the converted table to highlight the corresponding data point in the globe visualization.

As shown, one benefit of having orientation and dimension information is the ability to inspect if the platform orientation follows along the trajectory. You can further double-click the platform label in the map to get a focused view on the platform. As shown, the platform is banking with the expected orientation.

Summary

In this example, you explored how to use the Tracking Truth Data Importer app to import truth logs of various formats. You learned the app's basic workflow, which includes importing, converting, visualizing, and exporting data. In particular, you learned how to create a new converter with desired data elements, map data elements, adjust export coordinate frames, and reuse a TrackingTruthDataImporter for processing similar files. Additionally, you discovered how to configure a custom converter when the built-in application converters do not meet your needs.