Converting Volumetric Data from the CSV to the HDF5 (.h5) File Format

You must provide external volumetric data to the Ansys Systems Tool Kit® (STK®) application in the HDF5 file format. If you have volumetric data in an external CSV file, you can use MATLAB tools to read the CSV file, restructure its data, and write it to an STK application-compatible HDF5 file (.h5). The following sections describe how to format a CSV file properly and how to convert your CSV file to HDF5 using MATLAB functions. If you do not have access to the MATLAB programming platform, then any utility that can convert the data will work, and you can use this topic page as a guide for formatting.

Format your CSV file to ensure that it converts correctly

Before converting a CSV file to an HDF5 file, ensure that the CSV file follows these formatting requirements:

  • No extra commas after the data column (column 5)
  • No extra commas at the end of the file

An example of an invalid format is:

0,1,1,1,5,,,
0,1,2,1,6
,,,,,

An example of a valid format is:

0,1,1,1,5
0,1,2,1,6

vmGrid.type parameter requirements

The parameter vmGrid.type can be {'Cartesian', 'Cylindrical', 'Spherical', 'Cartographic', 'Surface Bearing', 'Cartographic Map Projection'}. The last two have additional data structure requirements.

For 'Surface Bearing', you must add the following data structure:

/VolumeGrid/SurfaceReference/Latitude
/VolumeGrid/SurfaceReference/Longitude
/VolumeGrid/SurfaceReference/Bearing

'Cartographic Map Projection' requires the addition of the following parameters:

/VolumeGrid/SpatialReference
/VolumeGrid/MapProjection/Type
/VolumeGrid/MapProjection/StringParameters/ (key/val)
/VolumeGrid/MapProjection/IntParameters/ (key/val)
/VolumeGrid/MapProjection/Parameters/Value
/VolumeGrid/MapProjection/Parameters/UnitType
/VolumeGrid/MapProjection/Parameters/Units

These two types are not compatible with the example HDF5 file provided in the STK-ODTK installation.

Coord.name parameter requirements

The coord.name parameter can be anything. However, the ordering of the coordinates is fixed, so you must provide data for each grid type in the following ordering:

  • Cartesian: X(1) (Distance), Y(2) (Distance) , Z(3) (Distance)
  • Spherical: Az (1) (Angle), El (2) (Angle) , Rng (3) (Distance)
  • Cylindrical: theta (1) (Angle) , rho (2) (Distance) , height (3) (Distance)
  • Cartographic: lat (1) (Angle) , lon (2) (Angle) , alt (3) (Distance)
  • Surface Bearing: along (1) (Distance) , cross (2) (Distance) , alt (3) (Distance)
  • Cartographic Map Projection: mapX (1) (Distance) , mapY (2) (Distance) , alt (3) (Distance)

Converting a CSV

MATLAB provides built-in functions for reading, writing, and manipulating data from CSV files to produce HDF5 files.

Go to <Install Dir>\Data\Resources\stktraining\samples to find these helpful items:

  • the MATLAB script (*.m) files for these main functions
  • an example CSV file
  • the final converted HDF5 file

Converting a CSV file with a main function

A main function performs the following steps to convert a file:

  1. Reads the data from a CSV file into a five-column MATLAB matrix
  2. Manipulates elements and corresponding indexes of this matrix to restructure it into individual time, coordinate arrays, and corresponding volumetric data assembled into a single four-dimensional array
  3. Creates the header information necessary for the STK application-compatible HDF5 file, including reference epoch, units of coordinate, and units of volumetric data
  4. Adds the header, times, grid coordinates, and corresponding volumetric data in the HDF5 format to the HDF5 file

What is a main function?

You can see an example of a main function by going to:

<Install Dir>\Data\Resources\stktraining\samples\vmExampleWeatherCsv2Hdf5.m

This specific example main function converts a CSV file containing columns of time, latitude, longitude, altitude, and corresponding temperature data to an STK application-compatible HDF5 format.

This main function calls three other functions, which are also MATLAB script files located in the same "samples" folder. The three functions are:

csv2vmarr: This generic function reads any CSV file in which data is organized in columns such that (1) the first column represents times in seconds since some reference epoch, (2) the next three columns represent spatial coordinates, and (3) the last column represents some volumetric data. The function produces four ordered arrays (without repeating elements), one for time and three for spatial coordinates, and a single four-dimensional array of corresponding volumetric data.
writevmhdf5: This generic function writes an STK application-compatible HDF5 file given the file name and structures containing information about the header, times, coordinates, and volumetric data. There is also an auxiliary local function defined inside the example vmExampleWeatherCsv2Hdf5.m file. This local function is called vmExampleWeatherWriteHdf5, and it demonstrates how you can prepare these structures for the header, times, coordinates, and volumetric data.
createvmgrid: This generic function creates a blank default structure describing a volumetric grid.

You can adjust this example main function file to apply to your specific Volumetric type. You need to make sure that all the script files and data files are located in the same folder. You can copy all of the example files from <Install Dir>\Data\Resources\stktraining\samples to your preferred folder and then set the current MATLAB path to this folder.

You can load the resulting HDF5 file into the STK application as described in Using External Volumetric Data tutorial.

Make sure that the number of points read into the grid from the Volumetric HDF5 file matches the number of points you expect based on your CSV file provided to the MATLAB script.