HDF5 (.h5) File Format for STK Volumetric Data

HDF5 is a hierarchical data format that includes both large multidimensional arrays called Datasets and small pieces of varied data called Attributes. Both Datasets and Attributes can be placed in hierarchical Groups using folder paths.

Coordinate values that are specified in external .h5 files and used by Volumetric objects must be listed in ascending order.

For more detailed information about the HDF5 format, see the HDF5 website.

Top Level Group

The Top Level Group is always accessed from the top level path, / . The STK format includes the following attributes in the Top Level Group:

Attribute Required? Description
FileType Yes Set this textual attribute to the following GUID:
d55fa3b3-6e28-49f2-8b5b-5c0301ae9607

This GUID identifies the file as an STK volumetric data file.

Authority No This is a textual attribute that includes the person or software that created the file; if the value is STK, you know that STK created the file.
Version No This is a textual value that identifies the version of the file structure supported by STK that the file used.
Description No This is a textual attribute that contains any relevant information added by the creator of the file. For example, the text in the Description property of the Volumetric object.
CreationDate(LocalTime) No This is a textual attribute that contains a date and time stamp identifying when this data was created.

AnalysisTimes Group

The AnalysisTimes Group is accessed via the /AnalysisTimes path. It contains the following optional attributes:

Attribute Description
Epoch(UTC) This is a textual attribute that contains the epoch in UTC Gregorian format, e.g., 11 May 2015 16:00:00.000000000, used as a reference for all other times measured in seconds.
Start(UTC) This is a textual attribute that contains the start time in UTC Gregorian format, e.g., 11 May 2015 16:00:00.000000000, of the overall interval of time covered by the data in the file.
Stop(UTC) This is a textual attribute that contains the stop time in UTC Gregorian format, e.g., 13 May 2015 16:00:00.000000000, of the overall interval of time covered by the data in the file.
Span This is a numerical attribute that contains the span of time, in seconds, covered by the data in the file. Span is used to readily communicate the length of time covered by the data in the file.

AnalysisTimes Group Dataset

The AnalysisTimes Group also contains a Dataset called Times that contains a single array of sample times, in seconds, since the reference epoch specified in Epoch(UTC) attribute.

Including Times Dataset

If the Times Dataset is included, then Epoch is required. If Start and Stop are omitted, then Start and Stop are set based on the first and last times from the Dataset, respectively.

Omitting Times Dataset

If the Times Dataset is omitted, the volumetric data is presumed to be static. If Start and Stop are omitted, then Volumetric data is static and is considered always available. If Start and Stop are included, then Volumetric data is static but is considered available only within that interval.

SpatialCalculation Group

You can access the SpatialCalculation Group via the /SpatialCalculation path. It contains the following optional attributes:

Attribute Description
Name This is a textual attribute that contains the name of the Spatial Calculation used to generate this volumetric data, e.g., Altitude.
Parent This is a textual attribute that contains the name of the parent of the Spatial Calculation, e.g., Aircraft/Aircraft1.
Description This is a textual attribute that describes the Spatial Calculation, e.g., Altitudes at selected locations in space measured from specified reference.

VolumetricData Group

The SpatialCalculation Group contains the VolumetricData Group, which is accessible via the /SpatialCalculation/VolumetricData path. It has the following attributes:

Attribute Description
CoordinateOrder Optional integer attribute specifying the order in which three spatial coordinates are indexing volumetric data. Default order if omitted is 123.
InvalidValueIndicator Optional numerical attribute specifying the value to be used in cases when no meaningful value can be assigned. Default value if omitted is -9999.999.
Dimensions Required attribute that contains an array of three integers specifying dimensions of volumetric data in each of three spatial coordinates.
ValueRange Optional attribute that contains an array of two values, the lowest and highest values encountered throughout the volumetric data (excluding invalid value indicators). If omitted, this information can be recovered by examining volumetric data.

VolumetricData Group Dataset

The VolumetricData Group contains a Values Dataset. The Dataset contains either 4- or 3-dimensional array of values representing volumetric data. In the 4-dimensional array, the first dimension corresponds to sample times defined in Times Dataset from the AnalysisTimes Group. The 3-dimensional array corresponds to the case of static volumetric data for which the Times Dataset is omitted.

VolumeGrid Group

The VolumeGrid Group is accessible via the path /VolumeGrid path. It includes the following attributes:

AttributeDescription
NameOptional textual attribute that contains the name of the Volume Grid used to generate the volumetric data; e.g. MySphere.
ParentOptional textual attribute that contains the name of the parent of the named Volume Grid; e.g., Aircraft/Aircraft1. It is required if the grid is named.

Having Name and Parent attributes indicates a link to the Volume Grid. If the Volumetric HDF5 file is loaded into STK, the Volume Grid must exist in the scenario.

DescriptionOptional textual attribute that describes the Volume Grid; e.g., 10 km sphere around the aircraft.
TypeOptional textual attribute (required if Name and Parent are omitted) that indicates that the Volume Grid definition is embedded in the file. Possible values are Cartesian, Spherical, Cylindrical, Cartographic, and Surface Bearing.

VolumeGrid Group Dataset

If the grid definition is embedded, then the VolumeGrid Group must also contain three Datasets, one for each coordinate. These Datasets are Coordinate1, Coordinate2, and Coordinate3. Each one contains an array of coordinate values. The Datasets also include their own attributes:

Attribute Description
Name Optional textual attribute specifying coordinate name; e.g., X or Latitude.
UnitType Optional textual attribute specifying type of unit; e.g., Distance or Angle.
<unit abbreviation> Optional textual attribute that must have the same name as the value of UnitType. For example, the Distance attribute unit abbreviation can be Au, Re, ft, fur, kft, km, sqrtm, m, nm, or mi. If omitted, SI units are used.

For a list of valid abbreviations, go to Scenario-->Basic-->Units property page.

Sample file

For a sample HDF5 file, go to <STK install folder>\Data\Resources\stktraining\samples\my_volumetricExampleScenarioDynamicWeatherData.vmc.h5. You will need an HDF5 Viewer to view the file.

Learn more about Volumetric HDF5 files

To learn how to convert large data files to the HDF5 file type as well as properly format object properties within the HDF5 file, see Using MATLAB to Convert Volumetric Data from CSV to HDF5 File (.h5).

To learn how to use .hdf5 files with STK, see Using External Volumetric Data in STK Tutorial.