Click or drag to resize

DHI.Generic.MikeZero.DFS Namespace

The DHI.Generic.MikeZero.DFS is the .NET API for reading the DHI binary file formats, the DFS (Data file system) files.

The DFS file format is a general file format for handling time dependent data, ranging from measurements of temperature at a single point, to water levels in the North Sea in a 2D grid generated by DHI's flow models.

See the SDK Userguide for an introduction to the content of the DFS file.

To load/edit a DFS file, use the methods in the DfsFileFactory.

To create a new file, use one of the builders: Dfs1Builder, Dfs2Builder, Dfs3Builder, DfsuBuilder. If none of those are adequate, you can use the generic DfsBuilder.

Classes
  ClassDescription
Public classDfsAbstractFile
Base class implementation of the different DFS file types. Currently only the DfsFile is extending this, but if some day support for DFS is extended to some of the other file types as FileType, this will be required.
Public classDfsAbstractItemBuilder
Item builder that handles common functionality for the static and the dynamic items.

The following functions must be set: Set(String, eumQuantity, DfsSimpleType), SetAxis(IDfsSpatialAxis).

Public classDfsBuilder
Builder for dfs files.

The builder works in two stages. The first stage all header information and information of the dynamic items are provided. In the second stage static items are added. Then a dfs file is ready, and data for the dynamic items can be added.

To go from the first to the second stage by calling CreateFile(String), which will actually create a file on the disc.

To get the final file, call GetFile. After GetFile has been called, no more static items can be added to the file.

Stage 1: The following must be set during stage 1: SetGeographicalProjection(IDfsProjection), SetDataType(Int32), SetTemporalAxis(IDfsTemporalAxis). Furthermore, a number of dynamic items must be added.

Stage 2: Any number of static items can be added. Create the item by using one of the AddStaticItem(String, Array) functions. To create a new static item from scratch, use CreateStaticItemBuilder together with AddStaticItem(IDfsStaticItem).

Public classDfsComHelper
Helper class for using component through COM.

Translates generic lists to non-generic lists that can be used through COM

Public classCode exampleDfsDateTimeLazyList
This class is a wrapper around the IDfsFile, extracting DateTimes of timestep on request: When requesting a DateTime in [!:Item(int)], the timestep at that index is being read, stored for later use and returned.

This is usefull if performing operations that only accesses a fraction of the DateTimes in the file, e.g. when performing a binary search for a given date.

This should only be used when reading from file, not when writing/modifying timesteps, since this will move the file pointer (for files with non-equidistant time axis), and updates to the file will not be reflected in this object.

Public classDfsDLLAccess
Static class providing one-to-one access to the ufs.dll. For documentation, see the ufs documentation. Methods supporting array arguments with each of the ufs simple types exists in versions for each type, as e.g., dfsReadItemTimeStep(IntPtr, IntPtr, Double, IntPtr). The types are: float[], double[], byte[], int[], uint[], short[], ushort[].
Public classDfsDLLWrapper
Static class providing one-to-one access to the ufs.dll, using C# calling conventions and marshalling. Compared to the DfsDLLAccess class the following has changed: - Methods with an error return code now throws an exception on error - Methods with just one return argument now returns the value - Methods working with enum arguments/returns use these enums instead of int's - Unmanaged arrays (strings) are Marshalled

With any

ref IntPtr
argument, which are all return arguments, null can be used and the argument is ignored.

Public classDfsDLLWrapperUtil
Utilities related to the DfsDLLWrapper
Public classDfsDynamicItemBuilder
Builder to configure an existing dynamic item structure.

The following functions must be set: Set(String, eumQuantity, DfsSimpleType), SetAxis(IDfsSpatialAxis), SetValueType(DataValueType).

Public classDfsDynamicItemDecoratorBase
Class for decorating an IDfsDynamicItemInfo. If used as is, it returns exactly what the decorated DynamicItemInfo does.

All methods are implemented virtual. Hence you can override just one method, if just that is to be changed, and the remainder will work as always.

Public classDfsException
Custom exception thrown when a DFS error occurs
Public classDfsExtensions
Set of extension methods for different interfaces and classes.
Public classDfsFactory
Factory class for creating Dfs classes.

It contains functionality for creating classes that are to be used when building a new file, e.g. the DfsBuilder.

Public classDfsFile
Base implementation of a dfs file.

This dfs file is of the type: all items, fixed space.

Public classDfsFileConverter
Class wrapping an DfsFile, applying a number of IDfsDataConverters to the DfsFile methods.
Public classDfsFileFactory
Factory class for opening different file types.
Public classDfsFileInfo
File info class, containing information for/from the dfs file header.
Public classDfsItemData
Item data class, base class (abstract) that are used as base by generic item data classes.
Public classDfsItemDataT
Item data.
Public classDfsItemData2DT
Item data for a 2D data set.
Public classDfsItemData3DT
Item data for a 3D data set.
Public classDfsItemDecoratorBase
Abstract class for decorating an IDfsItemInfo. If used as is, it returns exactly what the decorated ItemInfo does.

All methods are implemented virtual. Hence you can override just one method, if just that is to be changed, and the remainder will work as always.

Used by DfsDynamicItemDecoratorBase and Used by DfsStaticItemDecoratorBase and

Public classDfsParameters
Default implementation of IDfsParameters
Public classDfsProjection
Projection class implementing IDfsProjection
Public classDfsStaticItemBuilder
Builder to configure an existing dynamic item structure.

The following functions must be set: Set(String, eumQuantity, DfsSimpleType), SetAxis(IDfsSpatialAxis), SetData(Array).

Public classDfsStaticItemDecoratorBase
Class for decorating an IDfsStaticItem. If used as is, it returns exactly what the decorated StaticItem does.

All methods are implemented virtual. Hence you can override just one method, if just that is to be changed, and the remainder will work as always.

Public classDfsStreamBufferReader
Stream buffer class. This class is used in dfsStreamRead(DfsStreamBufferReader, IntPtr, IntPtr).

It is important to keep this class in scope until file reading is done (i.e. when calling dfsFileClose(IntPtr, IntPtr)).

When done reading the file (i.e. when calling dfsFileClose(IntPtr, IntPtr)), this object must be disposed. Disposing will free unmanaged resources. Disposing will not close/dispose of the stream.

This class provides interaction between managed (.NET) and unmanaged (C/C++) memory.

Public classDfsStreamBufferWriter
Stream buffer class. This class is used in dfsStreamRead(DfsStreamBufferReader, IntPtr, IntPtr).

It is important to keep this class in scope until file reading is done (i.e. when calling dfsFileClose(IntPtr, IntPtr)).

When done reading the file (i.e. when calling dfsFileClose(IntPtr, IntPtr)), this object must be disposed. Disposing will free unmanaged resources. Disposing will not close/dispose of the stream.

This class provides interaction between managed (.NET) and unmanaged (C/C++) memory.

Public classDfsTypeConverter
The type converter is required for supporting using the Dfs by COM in Matlab. Matlabs support for COM is not full, and COM in general does not support generics.

Matlab issue: If having an IDfsFile then you can not cast that to IDfsFileIO in Matlab. You can only cast if having the COM class but not if having the COM interface.

Structures
  StructureDescription
Public structureCoords
Coordinates triplet (x, y, z)
Interfaces
  InterfaceDescription
Public interfaceIDfsAxisCurveLinearD2
Axis description of a 2-dimensional curvelinear structured grid.

The number of coordinates in each dimension is one larger than the number of data values, i.e. datavalue[i,j] belongs within the element xy(i,j)-xy(i,j+1)-xy(i+1,j)-xy(i+1,j+1) (element values)

Public interfaceIDfsAxisCurveLinearD3
Axis description of a 3-dimensional curvelinear structured grid.

The number of coordinates in each dimension is one larger than the number of data values, i.e. datavalue[i,j,k] belongs within the cubic element with corners xyz(i,j,k)-xy(i+1,j+1,k+1) (element values)

Public interfaceIDfsAxisEqD0
Axis description of a 0-dimensional "equidistant" axis
Public interfaceIDfsAxisEqD1
Axis description of a 1-dimensional equidistant axis.

The user must know whether the data values are based on the coordinates (node values) or between coordinates (element values)

Public interfaceIDfsAxisEqD2
Axis description of a 2-dimensional equidistant structured grid.

The user must know whether the data values are based on the coordinates (node values) or between coordinates (element values)

Public interfaceIDfsAxisEqD3
Axis description of a 3-dimensional equidistant structured grid.

The user must know whether the data values are based on the coordinates (node values) or between coordinates (element values)

Public interfaceIDfsAxisEqD4
Axis description of a 4-dimensional equidistant structured grid

The user must know whether the data values are based on the coordinates (node values) or between coordinates (element values)

Public interfaceIDfsAxisNeqD1
Axis description of a 1-dimensional non-equidistant curvelinear axis.

The number of coordinates is the same as the number of data values, i.e. each data value belongs on the coordinate (node values).

Public interfaceIDfsAxisNeqD2
Axis description of a 2-dimensional non-equidistant, orthogonal structured grid.

The number of coordinates in each dimension is one larger than the number of data values, i.e. datavalue[i,j] belongs within the element x[i]-x[i+1] and y[j]-y[j+1] (element values)

Public interfaceIDfsAxisNeqD3
Axis description of a 3-dimensional non-equidistant, orthogonal structured grid.

The number of coordinates in each dimension is one larger than the number of data values, i.e. datavalue[i,j,k] belongs within the element x[i]-x[i+1], y[j]-y[j+1], z[k]-z[k+1] (element values)

Public interfaceIDfsAxisTvarD1
Axis description of a 1-dimensional time-varying curvelinear structured grid. The axis coordinates are retrieved together with the values for a given timestep.
Public interfaceIDfsAxisTvarD2
Axis description of a 2-dimensional time-varying curvelinear structured grid The axis coordinates are retrieved together with the values for a given timestep.
Public interfaceIDfsAxisTvarD3
Axis description of a 2-dimensional time-varying curvelinear structured grid The axis coordinates are retrieved together with the values for a given timestep.
Public interfaceIDfsComHelper
Interface for DfsComHelper
Public interfaceIDfsCoordinate
Interface for a coordinate in x-y-z space
Public interfaceIDfsCustomBlock
A custom block is a (small) array of a certain type, identified by its Name
Public interfaceIDfsCustomBlockT
Typed generic version of IDfsCustomBlock
Public interfaceIDfsDataConverter
Interface for converting static and dynamic items and their data.
Public interfaceIDfsDynamicItemInfo
Information of a Dynamic item,
Public interfaceIDfsEqCalendarAxis
Equidistant calendar axis.
Public interfaceIDfsEqTimeAxis
Equidistant time axis.
Public interfaceIDfsFile
Interface handling generic access to Dfs file.

The functionality is based on a file pointer pointing into the file on the disk.

Whenever calling one of the read or write methods, the file pointer will move to the next static item or dynamic item-timestep in the file.

The methods reading the next static or dynamic item will depend on previous calls to any of the read and write methods.

The two ReadStaticItemNext and ReadItemTimeStepNext are the most efficient way of iterating through the data in the file. If iterating in another way, for example over all the time steps of one item, and then the next item, this will imply a performance hit, since the file pointer needs to be repositioned at each read. Especially fro dfs0 files this is noticable; not very much data is being read for one item timestep, and it is faster reading data sequentially than moving the file pointer.

Public interfaceIDfsFileBuilder
Builder for dfs files.

See DfsBuilder for details

Public interfaceIDfsFileFactory
Factory interface for opening different file types.
Public interfaceIDfsFileInfo
File info, containing header data.
Public interfaceIDfsFileIO

Interface containing the raw read and write functions of the dynamic items in a dfs file.

The functionality is based on a file pointer pointing into the file on the disk.

Whenever calling one of the read or write methods, the file pointer will move to the next static item or dynamic item-timestep in the file.

The methods reading the next static or dynamic item will depend on previous calls to any of the read and write methods.

The ReadItemTimeStepNext is the most efficient way of iterating through the data in the file. If iterating in another way, for example over all the time steps of one item, and then the next item, this will imply a performance hit, since the file pointer needs to be repositioned at each read.

Public interfaceIDfsFileStaticIO
Interface containing the raw read and write functions of the static items in a dfs file.
Public interfaceIDfsItemData
Data for one item and timestep.

Depending on the DataType this can be cast to a similar IDfsItemDataT and the Data can be cast to its raw array data type.

Public interfaceIDfsItemDataT
Data for one item and timestep. This is the generic extension of IDfsItemData
Public interfaceIDfsItemData2D
Data for one item and timestep, wrapped with some 2D functionality.

The underlying data is still stored as a 1D array and returned by the Data

Depending on the DataType this can be cast to a similar IDfsItemData2DT and the Data can be cast to its raw array data type.

Public interfaceIDfsItemData2DT
Data for one item and timestep, wrapped with some 2D functionality.

The underlying data is still stored as a 1D array and returned by the Data

Public interfaceIDfsItemData3D
Data for one item and timestep, wrapped with some 3D functionality.

The underlying data is still stored as a 1D array and returned by the Data

Depending on the DataType this can be cast to a similar IDfsItemData3DT and the Data can be cast to its raw array data type.

Public interfaceIDfsItemData3DT
Data for one item and timestep, wrapped with some 3D functionality.

The underlying data is still stored as a 1D array and returned by the Data

Public interfaceIDfsItemInfo
Common information for static and dynamic items.
Public interfaceIDfsNonEqCalendarAxis
Non-equidistant calendar axis.
Public interfaceIDfsNonEqTimeAxis
Non-equdistant time axis.
Public interfaceIDfsParameters
Parameters that can be set for a dfs file.
Public interfaceIDfsProjection
Defines a projection and its coordinate transforms.

You can use the

DHI.Projections
to handle the difference coordinate systems involved in a dfs file. Also see there for detailed documentation.

The WKTString is a WKT string for a spatial reference system. A number of abbreviated strings also exists, i.e., "UTM-33" for a WGS-84 UTM zone 33 projection, and "LONG/LAT" for WGS-84 geographical coordinates.

There are 3 levels of coordinates: Geographical coordinates (longitude, latitude) in degrees, projection coordinates (easting, northing), and model/user defined coordinates (x,y).

All coordinates in a dfs file are stored in model coordinates.

The WKTString defines which ellipsoid the geographical coordinates use (example: WGS-84).

The WKTString defines the mapping from geographical coordinates to projection coordinates.

The Longitude, Latitude and Orientation defines the origin and the orientation of the model coordinates. It is used to move and rotate the model coordinates, i.e., a dfs2 file with a 2D equidistant axis defines its model coordinate origin and orientation here (and not in its axis definition, though that would also be possible).

See Orientation for the definition of the orientation. The model coordinates are rotated around its origin.

If Orientation is zero, and Longitude and Latitude matches the origin of the projection coordinate system, then projection coordinates equals model coordinates. Example: UTM-31 has projection origin at (lon,lat) = (3,0).

Public interfaceIDfsSimpleDynamicItemInfo
Interface that contains item information for dynamic items where you are not allowed to access/modify the spatial axis and associated static items.
Public interfaceIDfsSimpleItemInfo
Interface that contains item information for items where you are not allowed to access/modify the spatial axis and associated static items.
Public interfaceIDfsSpatialAxis
Basic "abstract" spatial axis description. Based on the AxisType the class must implement the corresponding IDfsAxisXXX types.
Public interfaceIDfsStaticItem
Static item, includes array of data. The array of data can be cast to one of the basic array types, depending on DataType
Public interfaceIDfsTemporalAxis
Interface specifying the temporal axis of the file.

Use the TimeAxisType to get the exact type. Depending on this type, the temporal axis can be cast to one of: IDfsNonEqCalendarAxisIDfsEqCalendarAxisIDfsNonEqTimeAxisIDfsEqTimeAxis

If the time axis in the file is Undefined indicates an illegally written file, and should not happen. An exception will/should be thrown when reading the file.

The unit of the time axis can vary. To convert between a time value in the unit of the time axis and a time value in seconds, there is a number of convenience static extension methods in the DfsExtensions class, as e.g. the method ToSecondsFactor(IDfsTemporalAxis) will return a factor to use when converting a value from the specified unit to seconds.

Public interfaceIDfsTypeConverter
Public interfaceIProjectionConverter
Facade for objects that can convert conversions from DHI to other system
Public interfaceIStreamBuffer
Common functionality interface for stream buffer.
Delegates
  DelegateDescription
Public delegateFillBufferCallback
Callback function to fill up the buffer from storage,
Public delegateWriteBufferCallback
Callback function for writing the content of the buffer to storage,
Enumerations
  EnumerationDescription
Public enumerationDataValueType
Data value type defines how one value is interpreted in time. Numerically same as in TSObject ItemValueType
Public enumerationDfsFileMode
Mode that file was opened in.
Public enumerationDfsSimpleType
Enum for data types. Compatible with TSobject, TimeSeries.idl (see comments on enum members)
Public enumerationFileType
File type enum.

Currently only the EqtimeFixedspaceAllitems and the NeqtimeFixedspaceAllitems is supported.

Public enumerationProjectionType
Projection type. All newer files has a projection defined, though there exists older files which does not have a projection defined.
Public enumerationSpaceAxisType
Type of spatial axis. Eq: Equidistant. Neq: Non-equidistant. Tvar: Time varying axis.
Public enumerationStatType
Type of statistics stored in file.
Public enumerationTimeAxisType
Type of the time axis
Public enumerationUnitConversionType
Type of unit conversion, when reading item data and axis.