Skip to content

Native DREAM.3D File Format

DREAM.3D uses HDF5 as its native file format, which means that any software package capable of reading an HDF5 file can read a DREAM.3D file. HDF5 stores data in a hierarchical format with complete descriptors for the data stored in the file. HDF5 is open source and a number of tools exist that allow a user to view and manipulate HDF5 data files. One such tool from The HDF Group is the free HDFView, which is a Java based program that can view and edit HDF5 data files.

The version number for the .dream3d file format is incremented independently of the version number for the DREAM.3D applicaiton. The current .dream3d file format version is 7.0. The general layout of a version 7.0 .dream3d file is as follows:

  • DataContainerBundles (Group)
  • MetaAttributeMatrix (Group)
    • MetaData (Dataset)
  • MetaAttributeMatrix2 (Group)
  • .
  • .
  • MetaAttributeMatrixN (Group)
  • DataContainers (Group)
  • DataContainer1 (Group)
    • _SIMPL_GEOMETRY (Group)
    • DIMENSIONS (Dataset)
    • ORIGIN (Dataset)
    • RESOLUTION (Dataset)
    • AttributeMatrix1 (Group)
    • AttributeArray1 (Dataset)
    • AttributeArray2 (Dataset)
    • .
    • .
    • AttributeArrayN (Dataset)
    • AttributeMatrix2 (Group)
    • .
    • .
    • AttributeMatrixN (Group)
  • DataContainer2 (Group)
    • _SIMPL_GEOMETRY (Group)
    • SharedVertexList (Dataset)
    • SharedTriList (Dataset)
    • AttributeMatrix1 (Group)
    • AttributeArray1 (Dataset)
    • AttributeArray2 (Dataset)
    • .
    • .
    • AttributeArrayN (Dataset)
    • AttributeMatrix2 (Group)
    • .
    • .
    • AttributeMatrixN (Group)
  • .
  • .
  • DataContainerN (Group)
  • Pipline (Group)
  • Pipeline (Dataset)

File Format Details

  • DataContainerBundles: A Group that stores a information about collections of Data Containers called bundles. A bundle is a group of Data Containers that has been tagged as belonging to one another for a particular reason. For example, a Data Container Bundle may exist for a simulation through time, where each Data Container represents a simulation time step. There is only ever one DataContainerBundle Group at the top level of a .dream3d file.
  • MetaAttributeMatrix: A Group that stores a set of metainformation about why a particular bundle exists. A MetaAttributeMatrix will exist for each bundle in the data structure.
    • MetaData: A Dataset that stores the raw metainformation for the grouping rules behind a particular bundle. There may be more than one MetaData array for each MetaAttributeMatrix.
  • DataContainers: A series of Groups that correspond to the Data Containers of the data structure. These Groups hold the majority of the raw data from DREAM.3D, and include storage for the Geometry information. There is only ever one DataContainers Group at the top level of a .dream3d file.
  • DataContainer: A Group that holds a set of Attribute Matrices and a unique Geometry. There may be many DataContainer Groups within the DataContainers top level Group.
    • _SIMPL_GEOMETRY: A Group that stores the Geometry information for a Data Container. Only one _SIMPL_GEOMETRY Group will exists in a DataContainer.
    • GeometryInfo: A collection of Datasets that define the Geometry for the parent Data Container. For the case of an Image Geometry, these will only be the DIMENSIONS, ORIGIN, and RESOLUTION, each of which are 3-vectors. For other Geometries, there will always be a SharedVertexList that lists the vertex coordinates, and a SharedElementList that lists the primary unit element as indexing into the SharedVertexList. There may be additional arrays at this level as well, such as a SharedEdgeList or an ElementNeighbors list.
    • AttributeMatrix: A Group that stores Attribute Arrays. There may be many AttributeMatrix Groups in each DataContainer Group.
    • AttributeArray: A Dataset that holds raw data. These Datasets hold the actual array data of the data structure.
  • Pipeline: A Group that stores JSON information about the Pipeline that was run to produce the data structure present in the DataContainerBundles and DataContainers Groups. The information stored in this Group allows for the data provenance to be maintained. There is only ever one Pipeline Group at the top level of a .dream3d file.
  • FilterId: A Group that holds the FilterParameters for a given Filter in the Pipeline. This Group will be named a number that corresponds to the index of the Filter in the Pipeline.
    • FilterParameter: A Dataset that holds the information about the setting of a FilterParameter for its parent Filter.

Any Group or Dataset may also have HDF5 attributes stored on it as metadata. For example, the component dimensions are stored as an attribute on an AttributeArray Dataset. These attributes can be useful for determining additional information about the data structure. The attributes can be viewed in HDFView, which allows for users to determine how to read them using other programs, if necessary.