mdal.h: MDAL C API

Defines

MDAL_EXPORT

Typedefs

typedef void *MDAL_MeshH

typedef void *MDAL_MeshVertexIteratorH

typedef void *MDAL_MeshEdgeIteratorH

typedef void *MDAL_MeshFaceIteratorH

typedef void *MDAL_DatasetGroupH

typedef void *MDAL_DatasetH

typedef void *MDAL_DriverH

typedef void (*MDAL_LoggerCallback)(MDAL_LogLevel logLevel, MDAL_Status status, const char *message)

Enums

enum MDAL_Status

Statuses.

Values:

enumerator None

enumerator Err_NotEnoughMemory

enumerator Err_FileNotFound

enumerator Err_UnknownFormat

enumerator Err_IncompatibleMesh

enumerator Err_InvalidData

enumerator Err_IncompatibleDataset

enumerator Err_IncompatibleDatasetGroup

enumerator Err_MissingDriver

enumerator Err_MissingDriverCapability

enumerator Err_FailToWriteToDisk

enumerator Err_UnsupportedElement

enumerator Warn_InvalidElements

enumerator Warn_ElementWithInvalidNode

enumerator Warn_ElementNotUnique

enumerator Warn_NodeNotUnique

enumerator Warn_MultipleMeshesInFile

enum MDAL_LogLevel

Log levels.

Values:

enumerator Error

enumerator Warn

enumerator Info

enumerator Debug

enum MDAL_DataLocation

Specifies where the data is defined.

Values:

enumerator DataInvalidLocation: Unknown/Invalid location.

enumerator DataOnVertices: Data is defined on vertices of 1D or 2D mesh.

enumerator DataOnFaces: Data is defined on face centres of 2D mesh.

enumerator DataOnVolumes: Data is defined on volume centres of 3D mesh.

enumerator DataOnEdges

Data is defined on edges of 1D mesh.

Since: MDAL 0.6.0

enum MDAL_DataType

Data type to be returned by MDAL_D_data.

Values:

enumerator SCALAR_DOUBLE: Double value for scalar datasets (DataOnVertices or DataOnFaces or DataOnEdges)

enumerator VECTOR_2D_DOUBLE: Double, double value for vector datasets (DataOnVertices or DataOnFaces or DataOnEdges)

enumerator ACTIVE_INTEGER: Integer, active flag for dataset faces. Some formats support switching off the element for particular timestep (see MDAL_D_hasActiveFlagCapability)

enumerator VERTICAL_LEVEL_COUNT_INTEGER: Number of vertical level for particular mesh’s face in 3D Stacked Meshes (DataOnVolumes)

enumerator VERTICAL_LEVEL_DOUBLE: Vertical level extrusion for particular mesh’s face in 3D Stacked Meshes (DataOnVolumes)

enumerator FACE_INDEX_TO_VOLUME_INDEX_INTEGER: The first index of 3D volume for particular mesh’s face in 3D Stacked Meshes (DataOnVolumes)

enumerator SCALAR_VOLUMES_DOUBLE: Double scalar values for volumes in 3D Stacked Meshes (DataOnVolumes)

enumerator VECTOR_2D_VOLUMES_DOUBLE: Double, double value for volumes in 3D Stacked Meshes (DataOnVolumes)

Functions

const char *MDAL_Version(): Returns MDAL version.

MDAL_Status MDAL_LastStatus(): Returns last status message.

void MDAL_ResetStatus()

Resets the last status message.

Since: MDAL 0.9.0

void MDAL_SetStatus(MDAL_LogLevel Level, MDAL_Status status, const char *message)

Sets the last status message.

Since: MDAL 0.9.0

void MDAL_SetLoggerCallback(MDAL_LoggerCallback callback)

Sets custom callback for logging output.

By default standard stdout is used as output. Calling this method with nullptr dissables logger ( logs will not be shown anywhere ). MDAL_LoggerCallback is a function accepting MDAL_LogLevel, MDAL_Status and const char* string

Since: MDAL 0.6.0

void MDAL_SetLogVerbosity(MDAL_LogLevel verbosity)

Sets maximum log level (verbosity)

By default logger outputs errors. Log levels (low to high): Error, Warn, Info, Debug For example, if LogVerbosity is set to Warn, logger outputs errors and warnings.

Since: MDAL 0.6.0

int MDAL_driverCount()

DRIVERS.

Returns count of registed MDAL drivers

MDAL_DriverH MDAL_driverFromIndex(int index): Returns driver handle by index Do not free the returned pointer.

MDAL_DriverH MDAL_driverFromName(const char *name): Returns driver handle by name Do not free the returned pointer.

bool MDAL_DR_meshLoadCapability(MDAL_DriverH driver): Returns whether driver can be used to mesh if false, driver can be only used to load datasets to existing mesh.

bool MDAL_DR_writeDatasetsCapability(MDAL_DriverH driver, MDAL_DataLocation location): Returns whether driver has capability to write/edit dataset (groups)

const char *MDAL_DR_writeDatasetsSuffix(MDAL_DriverH driver)

Returns the file suffix used to write datasets on file not thread-safe and valid only till next call.

Since: MDAL 0.7.0

const char *MDAL_DR_saveMeshSuffix(MDAL_DriverH driver)

Returns the file suffix used to save mesh frame on file not thread-safe and valid only till next call.

Since: MDAL 0.9.0

bool MDAL_DR_saveMeshCapability(MDAL_DriverH driver): Returns whether driver has capability to save mesh.

const char *MDAL_DR_name(MDAL_DriverH driver): Returns name of MDAL driver not thread-safe and valid only till next call.

const char *MDAL_DR_longName(MDAL_DriverH driver): Returns long name of MDAL driver not thread-safe and valid only till next call.

const char *MDAL_DR_filters(MDAL_DriverH driver)

Returns file filters that MDAL driver recognizes Filters are separated by ;;, e.g.

*.abc;;*.def not thread-safe and valid only till next call

int MDAL_DR_faceVerticesMaximumCount(MDAL_DriverH driver)

Returns the maximum number of vertices per face supported by the driver.

Since: MDAL 0.9.0

MDAL_MeshH MDAL_LoadMesh(const char *uri)

MESH.

Loads mesh file. On error see MDAL_LastStatus for error type This may effectively load whole mesh in-memory for some providers Caller must free memory with MDAL_CloseMesh() afterwards

since MDAL 0.6.0 const char parameter is renamed to uri and might contain following: <DriverName>:”<MeshFilePath>”:<SpecificMeshName or Id> examples: Ugrid:”mesh.nc”:0, Ugrid:”mesh.nc”:mesh1d, “mesh.nc”:mesh1d, Ugrid:”mesh.nc”, “mesh.nc”, mesh.nc

const char *MDAL_MeshNames(const char *uri)

Returns uris that the resource contains (mesh names) Uris are separated by ;; and have form <DriverName>:”<MeshFilePath>”[:<SpecificMeshName>] not thread-safe and valid only till next call.

Parameter uri can be in format:

<drivername>:”meshfile” - function then returns uris with provided driver and meshfile
”meshfile” or meshfile - function then finds proper driver and returns uris with it

The uris can be used directly in MDAL_LoadMesh to load particular meshes

Since: MDAL 0.6.0

void MDAL_CloseMesh(MDAL_MeshH mesh): Closes mesh, frees the memory.

MDAL_MeshH MDAL_CreateMesh(MDAL_DriverH driver)

Creates a empty mesh in memory.

Since: MDAL 0.7

Note

the mesh is editable (vertices and faces can be added, see MDAL_M_addVertices() and MDAL_M_addFaces()), and can be saved with MDAL_SaveMesh()

void MDAL_SaveMesh(MDAL_MeshH mesh, const char *meshFile, const char *driver)

Saves mesh (only mesh structure) on a file with the specified driver.

On error see MDAL_LastStatus for error type.

void MDAL_SaveMeshWithUri(MDAL_MeshH mesh, const char *uri)

Saves mesh (only mesh structure) on a file with an uri.

On error see MDAL_LastStatus for error type.

uri has form <DriverName>:”<MeshFilePath>”[:<SpecificMeshName>] examples: Ugrid:”mesh.nc”:0, Ugrid:”mesh.nc”:mesh2d, Ugrid:”mesh.nc”

since MDAL 0.9

const char *MDAL_M_projection(MDAL_MeshH mesh): Returns mesh projection not thread-safe and valid only till next call.

void MDAL_M_setProjection(MDAL_MeshH mesh, const char *projection)

Sets mesh projection not thread-safe and valid only till next call.

Since: MDAL 0.7

void MDAL_M_extent(MDAL_MeshH mesh, double *minX, double *maxX, double *minY, double *maxY): Returns mesh extent in native projection Returns NaN on error.

void MDAL_M_addVertices(MDAL_MeshH mesh, int vertexCount, double *coordinates)

Adds vertices to the mesh.

Since: MDAL 0.7

Note

to avoid incompatible datasets, adding faces removes all the existing dataset group

Parameters

mesh – the mesh which the vertices are added
vertexCount – the count of vertices
coordinates – coordinates of vertices (x0,y0,z0,x1,y1,z1,…,xn,yn,zn)

void MDAL_M_addFaces(MDAL_MeshH mesh, int faceCount, int *faceSizes, int *vertexIndices)

Adds faces to the mesh.

Since: MDAL 0.7

Note

to avoid incompatible datasets, adding faces removes all the existing dataset group

Parameters

mesh – the mesh which the faces are added
faceCount – the count of faces
faceSizes – a pointer to an array of integer containing the number of vertices per each faces
vertexIndices – a pointer to an array of integer containing the indices of vertices of each faces

void MDAL_M_addEdges(MDAL_MeshH mesh, int edgesCount, int *startVertexIndices, int *endVertexIndices)

Adds edges to the mesh.

Since: MDAL 0.9.0

Note

to avoid incompatible datasets, adding edges removes all the existing dataset group

Parameters

mesh – the mesh which the faces are added
edgeCount – the count of edges
startVertexIndices – must be allocated to edgesCount items to store start vertex indices for edges
endVertexIndices – must be allocated to edgesCount items to store end vertex indices for edges

int MDAL_M_vertexCount(MDAL_MeshH mesh): Returns vertex count for the mesh.

int MDAL_M_edgeCount(MDAL_MeshH mesh)

Returns edge count for the mesh.

Since: MDAL 0.6.0

int MDAL_M_faceCount(MDAL_MeshH mesh): Returns face count for the mesh.

int MDAL_M_faceVerticesMaximumCount(MDAL_MeshH mesh)

Returns maximum number of vertices per face for this mesh, can consist of, e.g.

4 for regular quad mesh.

void MDAL_M_LoadDatasets(MDAL_MeshH mesh, const char *datasetFile)

Loads dataset file.

On error see MDAL_LastStatus for error type. This may effectively load whole dataset in-memory for some providers Datasets will be closed automatically on mesh destruction or memory can be freed manually with MDAL_CloseDataset if needed

int MDAL_M_metadataCount(MDAL_MeshH mesh)

Returns number of metadata values.

Since: MDAL 0.9.0

const char *MDAL_M_metadataKey(MDAL_MeshH mesh, int index)

Returns mesh metadata key not thread-safe and valid only till next call.

Since: MDAL 0.9.0

const char *MDAL_M_metadataValue(MDAL_MeshH mesh, int index)

Returns mesh metadata value not thread-safe and valid only till next call.

Since: MDAL 0.9.0

void MDAL_M_setMetadata(MDAL_MeshH mesh, const char *key, const char *val)

Adds new metadata to the mesh.

Since: MDAL 0.9.0

int MDAL_M_datasetGroupCount(MDAL_MeshH mesh): Returns dataset groups count.

MDAL_DatasetGroupH MDAL_M_datasetGroup(MDAL_MeshH mesh, int index): Returns dataset group handle.

MDAL_DatasetGroupH MDAL_M_addDatasetGroup(MDAL_MeshH mesh, const char *name, MDAL_DataLocation dataLocation, bool hasScalarData, MDAL_DriverH driver, const char *datasetGroupFile)

Adds empty (new) dataset group to the mesh This increases dataset group count MDAL_M_datasetGroupCount() by 1.

The Dataset Group is opened in edit mode. To persist dataset group, call MDAL_G_closeEditMode();

It is not possible to read and write to the same group at the same time. Finalize edits before reading.

Parameters

mesh – mesh handle
driver – the driver to use for storing the data
name – dataset group name
dataLocation – location of data (face, vertex, volume)
hasScalarData – whether data is scalar (false = vector data)
datasetGroupFile – file to store the new dataset group

Returns

empty pointer if not possible to create group, otherwise handle to new group

const char *MDAL_M_driverName(MDAL_MeshH mesh): Returns name of MDAL driver not thread-safe and valid only till next call.

MDAL_MeshVertexIteratorH MDAL_M_vertexIterator(MDAL_MeshH mesh)

MESH VERTICES.

Returns iterator to the mesh vertices For some formats this may effectively load all vertices in-memory until iterator is closed

int MDAL_VI_next(MDAL_MeshVertexIteratorH iterator, int verticesCount, double *coordinates)

Returns vertices from iterator for the mesh.

Parameters

iterator – mesh data iterator
verticesCount – maximum number or vertices to be written to buffer
coordinates – must be allocated to 3* verticesCount items to store x1, y1, z1, …, xN, yN, zN coordinates

Returns

number of vertices written in the buffer

void MDAL_VI_close(MDAL_MeshVertexIteratorH iterator): Closes mesh data iterator, frees the memory.

MDAL_MeshEdgeIteratorH MDAL_M_edgeIterator(MDAL_MeshH mesh)

MESH EDGES.

Returns iterator to the mesh edges For some formats this may effectively load all edges in-memory until iterator is closed

Since: MDAL 0.6.0

int MDAL_EI_next(MDAL_MeshEdgeIteratorH iterator, int edgesCount, int *startVertexIndices, int *endVertexIndices)

Returns edges from iterator for the mesh.

Since: MDAL 0.6.0

Parameters

iterator – mesh data iterator
edgesCount – maximum number or edges to be written to buffer
startVertexIndices – must be allocated to edgesCount items to store start vertex indices for edges
endVertexIndices – must be allocated to edgesCount items to store end vertex indices for edges

Returns

number of vertices written in the buffer

void MDAL_EI_close(MDAL_MeshEdgeIteratorH iterator)

Closes mesh data iterator, frees the memory.

Since: MDAL 0.6.0

MDAL_MeshFaceIteratorH MDAL_M_faceIterator(MDAL_MeshH mesh)

MESH FACES.

Returns iterator to the mesh faces For some formats this may effectively load all faces in-memory until iterator is closed

int MDAL_FI_next(MDAL_MeshFaceIteratorH iterator, int faceOffsetsBufferLen, int *faceOffsetsBuffer, int vertexIndicesBufferLen, int *vertexIndicesBuffer)

Returns next faces from iterator for the mesh.

Reading stops when vertexIndicesBuffer capacity is full / faceOffsetsBuffer capacity is full / end of faces is reached, whatever comes first

Parameters

iterator – mesh data iterator
faceOffsetsBufferLen – size of faceOffsetsBuffer, minimum 1
faceOffsetsBuffer – allocated array to store face offset in vertexIndicesBuffer for given face. To find number of vertices of face i, calculate faceOffsetsBuffer[i] - faceOffsetsBuffer[i-1]
vertexIndicesBufferLen – size of vertexIndicesBuffer, minimum is MDAL_M_faceVerticesMaximumCount()
vertexIndicesBuffer – writes vertex indexes for faces faceOffsetsBuffer[i-1] is index where the vertices for face i begins,

Returns

number of faces written in the buffer

void MDAL_FI_close(MDAL_MeshFaceIteratorH iterator): Closes mesh data iterator, frees the memory.

MDAL_MeshH MDAL_G_mesh(MDAL_DatasetGroupH group)

DATASET GROUPS.

Returns dataset parent mesh

int MDAL_G_datasetCount(MDAL_DatasetGroupH group): Returns dataset count in group.

MDAL_DatasetH MDAL_G_dataset(MDAL_DatasetGroupH group, int index): Returns dataset handle.

int MDAL_G_metadataCount(MDAL_DatasetGroupH group): Returns number of metadata values.

const char *MDAL_G_metadataKey(MDAL_DatasetGroupH group, int index): Returns dataset metadata key not thread-safe and valid only till next call.

const char *MDAL_G_metadataValue(MDAL_DatasetGroupH group, int index): Returns dataset metadata value not thread-safe and valid only till next call.

void MDAL_G_setMetadata(MDAL_DatasetGroupH group, const char *key, const char *val): Adds new metadata to the group Group must be in edit mode MDAL_G_isInEditMode()

const char *MDAL_G_name(MDAL_DatasetGroupH group): Returns dataset group name not thread-safe and valid only till next call.

const char *MDAL_G_driverName(MDAL_DatasetGroupH group): Returns name of MDAL driver not thread-safe and valid only till next call.

bool MDAL_G_hasScalarData(MDAL_DatasetGroupH group): Whether dataset has scalar data associated.

MDAL_DataLocation MDAL_G_dataLocation(MDAL_DatasetGroupH group): Whether dataset is on vertices.

int MDAL_G_maximumVerticalLevelCount(MDAL_DatasetGroupH group): Returns maximum number of vertical levels (for 3D meshes)

void MDAL_G_minimumMaximum(MDAL_DatasetGroupH group, double *min, double *max): Returns the minimum and maximum values of the group Returns NaN on error.

MDAL_DatasetH MDAL_G_addDataset(MDAL_DatasetGroupH group, double time, const double *values, const int *active)

Adds empty (new) dataset to the group This increases dataset group count MDAL_G_datasetCount() by 1.

The dataset is opened in edit mode. To persist dataset, call MDAL_G_closeEditMode() on parent group

Minimum and maximum dataset values are automatically calculated

Only for 2D datasets

Parameters

group – parent group handle
time – time for dataset (hours)
values – For scalar data on vertices, the size must be vertex count For scalar data on faces, the size must be faces count For scalar data on edges, the size must be edges count For vector data on vertices, the size must be vertex count * 2 (x1, y1, x2, y2, …, xN, yN) For vector data on faces, the size must be faces count * 2 (x1, y1, x2, y2, …, xN, yN) For vector data on edges, the size must be edges count * 2 (x1, y1, x2, y2, …, xN, yN)
active – if null pointer, MDAL_D_hasActiveFlagCapability returns false. Otherwise size must be equal to face count.

Returns

empty pointer if not possible to create dataset (e.g. group opened in read mode), otherwise handle to new dataset

MDAL_DatasetH MDAL_G_addDataset3D(MDAL_DatasetGroupH group, double time, const double *values, const int *verticalLevelCount, const double *verticalExtrusions)

Adds empty (new) 3D dataset to the group This increases dataset group count MDAL_G_datasetCount() by 1.

The dataset is opened in edit mode. To persist dataset, call MDAL_G_closeEditMode() on parent group

Minimum and maximum dataset values are automatically calculated

Only for 3D datasets

Since: MDAL 0.9.0

Parameters

group – parent group handle
time – time for dataset (hours)
values – For scalar data, the size must be volume count For vector data , the size must be volume count * 2 (x1, y1, x2, y2, …, xN, yN)
verticalLevelCount – Int Array holding the number of vertical levels for each face. Size must be the face count
verticalExtrusion – Double Array holding the vertical level values for the voxels Size must be Face count + Volume count

Returns

empty pointer if not possible to create dataset (e.g. group opened in read mode), otherwise handle to new dataset

bool MDAL_G_isInEditMode(MDAL_DatasetGroupH group): Returns whether dataset group is in edit mode.

void MDAL_G_closeEditMode(MDAL_DatasetGroupH group)

Close edit mode for group and all its datasets.

This may effectively write the data to the files and/or reopen the file in read-only mode

When closed, minimum and maximum dataset group values are automatically calculated

const char *MDAL_G_referenceTime(MDAL_DatasetGroupH group): Returns reference time for dataset group expressed in date with ISO8601 format, return “” if reference time is not defined.

void MDAL_G_setReferenceTime(MDAL_DatasetGroupH group, const char *referenceTimeISO8601): Sets reference time for dataset group expressed in date with ISO8601 format.

bool MDAL_G_isTemporal(MDAL_DatasetGroupH group)

Returns whether the dataset group is temporal, i.e.

has time-related datasets

Since: MDAL 0.6.0

const char *MDAL_G_uri(MDAL_DatasetGroupH group)

Returns dataset group uri not thread-safe and valid only till next call.

Since: MDAL 0.7.0

MDAL_DatasetGroupH MDAL_D_group(MDAL_DatasetH dataset)

DATASETS.

Returns dataset parent group

double MDAL_D_time(MDAL_DatasetH dataset): Returns dataset time (hours)

int MDAL_D_volumesCount(MDAL_DatasetH dataset): Returns volumes count for the mesh (for 3D meshes)

int MDAL_D_maximumVerticalLevelCount(MDAL_DatasetH dataset): Returns maximum number of vertical levels (for 3D meshes)

int MDAL_D_valueCount(MDAL_DatasetH dataset): Returns number of values For dataset with data location DataOnVertices returns vertex count For dataset with data location DataOnFaces returns face count For dataset with data location DataOnVolumes returns volumes count For dataset with data location DataOnEdges returns edges count.

bool MDAL_D_isValid(MDAL_DatasetH dataset): Returns whether dataset is valid.

bool MDAL_D_hasActiveFlagCapability(MDAL_DatasetH dataset): Returns whether dataset supports active flag for dataset faces.

int MDAL_D_data(MDAL_DatasetH dataset, int indexStart, int count, MDAL_DataType dataType, void *buffer)

Populates buffer with values from the dataset for nodata, returned is numeric_limits<double>::quiet_NaN.

Parameters

dataset – handle to dataset
indexStart – index of face/vertex to start reading of values to the buffer
count – number of values to be written to the buffer
dataType – type of values to be written to the buffer
buffer – output array to be populated with the values. must be already allocated For SCALAR_DOUBLE, the minimum size must be valuesCount * size_of(double) For VECTOR_2D_DOUBLE, the minimum size must be valuesCount * 2 * size_of(double). Values are returned as x1, y1, x2, y2, …, xN, yN For ACTIVE_INTEGER, the minimum size must be valuesCount * size_of(int) For VERTICAL_LEVEL_COUNT_INTEGER, the minimum size must be faceCount * size_of(int) For VERTICAL_LEVEL_DOUBLE, the minimum size must be (faceCount + volumesCount) * size_of(double) For FACE_INDEX_TO_VOLUME_INDEX_INTEGER, the minimum size must be faceCount * size_of(int) For SCALAR_VOLUMES_DOUBLE, the minimum size must be volumesCount * size_of(double) For VECTOR_2D_VOLUMES_DOUBLE, the minimum size must be 2 * volumesCount * size_of(double)

Returns

number of values written to buffer. If return value != count requested, see MDAL_LastStatus() for error type

void MDAL_D_minimumMaximum(MDAL_DatasetH dataset, double *min, double *max): Returns the minimum and maximum values of the dataset Returns NaN on error.