You must provide external volumetric data to STK 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-compatible HDF5 file (.h5). The following sections describe how to format your CSV file properly and how to convert your CSV file to HDF5 using MATLAB functions.
Ensure your CSV file 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,,,
|
An example of a valid format is:
0,1,1,1,5
|
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
|
‘Cartographic Map Projection’ requires the addition of the following parameters:
/VolumeGrid/SpatialReference
|
These two types are not compatible with the example file provided in the STK 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)
How to convert your CSV file
MATLAB provides built-in functions for reading, writing, and manipulating data from CSV files to produce HDF5 files.
Go to <STK install folder>\Data\Resources\stktraining\samples to find the ".m" files for these main functions, an example CSV file, and the final converted HDF5 file.
Converting your CSV file with a main function
A main function will perform the following steps to convert your file:
- Read the data from a CSV file into a five-column MATLAB matrix.
- Manipulate 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.
- Create the header information necessary for the STK-compatible HDF5 file, including reference epoch, units of coordinate, and units of volumetric data.
- Add the header, times, grid coordinates, and corresponding volumetric data in HDF5 format to the HDF5 file
What is a main function?
You can see an example of a main function by going to:
<STK install folder>\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-compatible HDF5 format.
This main function calls two other functions, which are ".m" files also located in the same "samples" folder. The two functions are:
csv2vmarr. Use this generic function to read any CSV file in which data is organized in columns such that the first column represents times in seconds since some reference epoch, the next three columns represent spatial coordinates, and 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. Use this generic function to write an STK-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.
You can adjust this example main function file to apply to your specific Volumetric type. You need to make sure that all ".m" files and data files are located in the same folder. You can copy all of the example files from <STK install folder>\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 (for the example, it would be 'volumetricExampleScenarioDynamicWeatherData.vmc.h5 ') into STK as described in Using External Volumetric Data in STK Tutorial.
Make sure that the number of points read into the grid from the Volumetric HDF5 file match the number of points you expect based on your *.csv file provided to the MATLAB script.
Example of calling the main function
Using the example main function called vmExampleWeatherCsv2Hdf5, you can accomplish the entire conversion process using a single call.
For the example, you can call the CSV file in the Samples folder called DynamicWeatherData easily. The call would look like this. Please be mindful to enter your correct file path:
vmExampleWeatherCsv2Hdf5('C:\<file path>DynamicWeatherData.csv','DynamicWeatherDataForSTK.h5')