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:
-
By setting the reference lon-lat coordinates in the projection
-
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
.
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
.
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.
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.
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.