Skip to content

DFS File Formats

This chapter describes each of the specialised file formats that are used within the MIKE software suite.

It is possible to open, read and modify all types of files using both the .NET/C# API and the native C API.

The C API has a set of generic methods that is used for all types of DFS files, and it is the responsibility of the user to use the API in a way that is consistent with a specific type of DFS file.

The .NET/C# API has a generic IDfsFile interface that can be used for all types of DFS files, and also here it is the responsibility of the user to use the API in a way that is consistent with a specific type of DFS file. The .NET/C# also contains a number of classes and interfaces that are specific for each type of DFS files, and makes sure that the DFS file is handled consistent with its type.

To open a file in one of the specific file format classes, use the DfsFileFactory. In the following sections, references to API methods is to the .NET/C# API.

DFS0 File

A dfs0 file is also called a time series file. A dfs0 file only contains items with the 0D equidistant spatial axis.

There are two ways of geo-referencing the individual time series in the file:

  1. By setting the reference lon-lat coordinates in the projection

  2. By setting the reference (x,y,z) coordinates in the dynamic item

Using the former case, all dynamic items must be situated at the same location. The latter case allows for having different locations for each dynamic item. However, many of the DHI tools assume the former. There are also many dfs0 files that are not geo-referenced at all.

A dfs0 file generally does not have any static items or custom blocks. If any are present, most tools ignore them.

To open/write a dfs0 file, the generic dfs API must be used. There is currently no dedicated API for handling dfs0 files, so it is the responsibility of the user to utilise the generic dfs API in a way that fulfils the requirements for a dfs0 file.

DFS1 File

A dfs1 file is also called a line series file. A dfs1 file only contains items with one of the 1D spatial axes. All values are instantaneous.

Use one of the static DfsFileFactory methods Dfs1FileOpen, Dfs1FileOpenEdit or Dfs1FileOpenAppend to open a dfs1 file. It will return an IDfs1File.

Dfs1File.png

The IDfs1File interface extends the IDfs123File, IDfsFileIO and IDfsFileStaticIO. It provides information on the header, the items and the spatial axis.

To create a new dfs1 file, use the Dfs1Builder class, see Section 4.5.

DFS2 File

A dfs2 file is also called a grid series file. A dfs2 file only contains static and dynamic items with one of the 2D spatial axes. All values are instantaneous.

Values in a dfs2 file are ‘element based’, i.e. values are defined in the centre of each grid cell.

The definition of the origin, which is set by the origin coordinates in the projection, depends (for historical reasons) on the projection being used. For the ‘NON-UTM’ projection, the origin is the lower left grid boundary (the lower left node). For all other projections the origin is the centre of the lower left element. The two definitions differ by half a grid cell.

Use one of the static DfsFileFactory methods Dfs2FileOpen, Dfs2FileOpenEdit or Dfs2FileOpenAppend to open a dfs2 file. It will return an IDfs2File.

Dfs2File.png

The IDfs2File interface extends the IDfs123File, IDfsFileIO and IDfsFileStaticIO. It provides information on the header, the items and the spatial axis. It overrides the read methods in IDfsFileIO to return IDfsItemData2D instead of IDfsItemData. The IDfsItemData2D provides 2D indexing into the data.

To create a new dfs2 file, use the Dfs2Builder class, see section 4.5.

DFS3 File

A dfs3 file is also called a grid series file. A dfs3 file only contains static and dynamic items with one of the 3D spatial axes. All values are instantaneous.

Values in a dfs3 file are ‘element based’, i.e. values are defined in the centre of each grid cell.

If the file is compressed, data in static items can choose to store only the compressed part of the data, and decompression is required. In that case it will have a dummy 1D axis of the compressed data size. You can use the DfsExtensions.dfsDecode() method and DfsExtensions.dfsEncode to decompress and compress data.

Use one of the static DfsFileFactory methods Dfs3FileOpen, Dfs3FileOpenEdit or Dfs3FileOpenAppend to open a dfs3 file. It will return an IDfs3File.

Dfs3File.png

The IDfs3File interface extends the IDfs123File, IDfsFileIO and IDfsFileStaticIO. It provides information on the header, the items and the spatial axis. It overrides the read methods in IDfsFileIO to return IDfsItemData3D instead of IDfsItemData. The IDfsItemData3D provides 3D indexing into the data.

To create a new dfs3 file, use the Dfs3Builder class, see section 4.5.

Creating DFS1, DFS2, DFS3 Files

To create a new file of type dfs1, dfs2 or dfs3, use one of the Dfs1Builder, Dfs2Builder or Dfs3Builder classes.

The difference between the builders is which spatial axis type that it accepts, and the type of file that it returns in the end.

The builders work together with the DfsFactory class which can create the objects to use as arguments for the builder methods

The following information must be provided

  • Map projection

  • Data type tag

  • Temporal axis

  • Spatial axis

The type of the spatial axis accepted by the builder depends on the builder. Example: The Dfs2Builder only accepts 2D axes valid for a dfs2 file, etc.

All the dynamic items must be added and specified correctly. For each dynamic item you must specify:

  • Name

  • Quantity

  • Type of data

  • Value type

When the header and the dynamic items are fully defined, i.e. no validation errors left, the CreateFile function can be called, and the builder will enter stage 2. In the second stage any number of static items can be added. For each static item the following information is required:

  • Name

  • Quantity

  • Data

If/when all static items have been added, the GetFile method is called which returns an IDfs1File, IDfs2File or IDfs3File depending on the builder. From that point the builder is no longer required (and is actually invalidated).

Dynamic item data is added by using the methods in the IDfsFileIO interface.

DFSU File

The DFSU file and its geometry is in detail described in the DHI Flexible File Formats specification (FM_FileSpecification.pdf).

The geometrical definition of a dfsu file is stored in one custom block and a number of static items. A dfsu file cannot have any other custom blocks or static items than those defining the geometry. These should not be hand edited, but edited through the IDfsuFile interface.

The temporal axis is always an equidistant calendar axis, with time unit in seconds.

The dfsu file stores all coordinates in the projected coordinate system and not the user defined coordinate system, as other dfs file types. Hence the reference longitude and latitude and orientation are not relevant for a dfsu file.

The mesh in a dfsu file consists of a number of nodes and a number of elements.

Each node has:

  • Node id

  • X,Y,Z coordinate

  • Code for the boundary

Each element has:

  • Element id

  • Element type; triangular, quadrilateral, prism etc.

  • Element table; specifies for each element the nodes that defines the element. The element table references a node by specifying the number in the list of nodes (not the index!). 2D elements specify their node in counter clockwise order. For details, see the FM_FileSpecification.pdf.

Use one of the static DfsFileFactory methods DfsuFileOpen, DfsuFileOpenEdit or DfsuFileOpenAppend to open a dfsu file. It will return an IDfsuFile.

DfsuFile.png

The IDfsuFile extends the IDfsFileIO. The geometry definition, header and item information is available directly from the IDfsuFile interface.

To create a new dfsu file, use the DfsuBuilder class. The following header information must be provided:

  • Projection information

  • Temporal information.

  • Node coordinates and code

  • Element table

Furthermore at least one dynamic item must be added. For each dynamic item the name and EUM quantity is required.

When the header and the dynamic items are fully defined, i.e. no validation errors left, the CreateFile function can be called, which will return an IDfsuFile. From that point the builder is no longer required (and is actually invalidated).

Dynamic item data is added by using the methods in the IDfsFileIO interface.