Table of Contents

Editor: CSV Table Reading

CSV Tables

A comma-separated file (CSV) is a common format for storing data in a file. This is the standard file type used in Excel and is common to read. The Unreal Engine natively does not have Blueprint functions to read and write to CSV files. However, Nominal has provided helper functions to work with CSV files. This particular document will demonstrate how to read from a CSV file with particular data. A CSV file object can be created in a level blueprint by first using the Construct Object from Class node. The class to use is CSVTable and the Outer should be set to the level blueprint.

Untitled

Note

There is a class called CSVFile that already exists. This is a deprecated class and does not have all the functions required. Make sure to use CSVTable when dealing with reading and writing these files.

For examples of using a CSV table in Nominal Editor, see the demo level found in Orbits/Demo_AircraftTrajectory which reads the data and prints additional information to the screen about the context of the aircraft. The CSV table object is also used in the back end when loading spacecraft/aircraft trajectories.

Loading a File

The first step after creating the CSV table object is to load a CSV file into the data. This will read from the CSV table and load the text into a cache. The object itself does not keep the CSV file open and only opens it once before copying the file. This is done by calling the Load function which takes in a few properties.

Untitled

  • File: The full path to the file or a relative path to one of the anchor points. An anchor point may include one of the following locations and the file, provided it exists, can be written here as a relative path to that location:
    • Content/Nominal/Data
    • Assets
    • Content
  • Separator: The character in the CSV file that splits each of the cell's data. Most CSV files created use a comma to separate each of the columns but this may be different based on the file.
  • Header: This field tells the table whether the first row includes a header with the column names. If this is false, it is assumed that the file does not include a header row and data can only be referenced by index.

The return value of this function will return whether the file exists and was loaded correctly. If the file cannot be found or there is an issue with reading the file, then the load function will return a false. It will not throw an error or cause the program to break if there is an issue.

Reading Cells

Once the data has loaded, the data within the cells can be read. This is done with the Get Cell functions which include a double or string option. The double option will return the data from the cell as a number (in double floating-point precision form) and the string option returns the text as a string. Additionally, each of these functions can include the Column as an index (starting from 0) or a name. If there are no headers included in the CSV table, the name option cannot be used. The name is also case-insensitive.

Untitled

Additionally, to fetch all of the data from a particular row or column, these functions are also available. They work with the same system as above, where the index for a column will be the index starting from 0 and the name will only work if the table is loaded with a valid header row.

Untitled

Looking Up Data

The get-cell functions that were previously described will return the data based on a particular known cell index. However, this will not return data that matches a particular row value. Instead, the Lookup functions will return the value from a specific column that matches a value from another column. The Lookup function, including the index and name options, will look up the value Value in the Lookup Column and attempt to return the value from the Output Column where that value matches. The Lerp flag will indicate whether to perform a Linear Interpolation between the values that match. For example, take the following CSV file:

Time, Data
0.0,  10.0
1.0,  30.0
2.0,  60.0

In the case above, if the Lookup function was called with the example Lookup("Time", "Data", 1.5), the result if the Lerp is enabled will be 45, whereas the result if Lerp is disabled will be 30. This only performs a linear interpolation and not a more accurate quadratic or higher-order interpolation function.

Untitled

Note

To edit the Value parameter, as it is a double, right-click on the value node and select Split Struct Pin which allows for floating data to be added to the parameter.

The Lookup Row function will look up a value within a particular row exactly and is typically used for CSV files with text-based values (rather than numeric-based values). This will return an array of strings that exists within the row that matches. If no row is found, then no data will be returned.

Mathematical Functions

There exist some helper functions that can compute the average, maximum, minimum and sum of all of the values in a particular column of the CSV table. Provided that the data is numeric, this will calculate the value as a double value and return it. In each case, the column name can be entered as an index (starting in the first column as an index of 0) or a name, provided that the headers exist.

Untitled

CSV Metadata

The CSV contains some functions and variables that return some standard parameters about the CSV file. This includes the number of rows and columns the CSV has as well as some functions for returning whether a column exists and what its index is. More functions are available under the Nominal Systems | CSV | Metadata category.

Untitled

Printing the Data

If the data has been loaded into the CSV file, the data can be turned into a string with a table format. This can be exported to a text file or printed on the screen. Although the data is not formatted properly when printed on the Unreal viewport, the spaces line up the columns when printing the data in a terminal or output log.

Untitled

Untitled