OGR supports reading from 2D Selafin/Seraphin files. Selafin/Seraphin is the generic output and input format of geographical files in the open-source Telemac hydraulic model. The file format is suited to the description of numerical attributes for a set of point features at different time steps. Those features usually correspond to the nodes in a finite-element model. The file also holds a connectivity table which describes the elements formed by those nodes and which can also be read by the driver.
The driver supports the use of VSI virtual files as Selafin datasources.
The driver offers full read-write support on Selafin files. However, due to the particular nature of Selafin files where element (polygon) features and node (point) features are closely related, writing on Selafin layers can lead to counter-intuitive results. In a general way, writing on any layer of a Selafin data-source will cause side effects on all the other layers. Also, it is very important not to open the same datasource more than once in update mode. Having two processes write at the same time on a single datasource can lead to irreversible data corruption. The driver issues a warning each time a datasource is opened in update mode.
There is no generic extension to Selafin files. The adequate format is tested by looking at a dozen of magic bytes at the beginning of the file:
Files which match those two criteria are considered to be Selafin files and the driver will report it has opened them successfully.
Selafin format is designed to hold data structures in a portable and compact way, and to allow efficient random access to the data. To this purpose, Selafin files are binary files with a generic structure.
Selafin files are made of the juxtaposition of elements. Elements have one of the following types:
|Integers are stored on 4 bytes in big-endian format (most significant byte first). The value of the integer is 224.a+216.b+28.c+d.|
|Floating point values are stored on 4 bytes in IEEE 754 format and under big-endian convention (most significant byte first). Endianness is detected at run time only once when the first floating point value is read.|
|Strings are stored in three parts:
|Array of integers||
|Arrays of integers are stored in three parts:
|Array of floating point values||
|Arrays of floating point values are stored in three parts:
The header of a Selafin file holds the following elements in that exact order:
The rest of the file actually holds the data for each successive time step. A time step contains the following elements:
The Selafin driver accepts only Selafin files as data sources.
Each Selafin file can hold one or several time steps. All the time steps are read by the driver and two layers are generated for each time step:
Finally, either the number of the time step, or the calculated date of the time step (based on the starting date and the number of seconds elapsed), is added to the name. A data source in a file called Results may therefore be read as several layers:
Because of the format of the Selafin file, the layers in a single Selafin datasource are not independent from each other. Changing one layer will most certainly have side effects on all other layers. The driver updates all the layers to match the constraints:
As a single Selafin files may hold millions of layers, and the user is generally interested in only a few of them, the driver supports syntactic sugar to filter the layers before they are read.
When the datasource is specified, it may be followed immediately by a layer filtering specification., as in Results[0:10]. The effects of the layer filtering specification is to indicate which time steps shall be loaded from all Selafin files.
The layer filtering specification is a comma-separated sequence of range specifications, delimited by square brackets and maybe preceded by the character 'e' or 'p'. The effect of characters 'e' and 'p' is to select respectively either only elements or only nodes. If no character is added, both nodes and elements are selected. Each range specification is:
Some examples of layer filtering specifications:
|||First time step only, but return both points and elements|
|[e:9]||First 10 time steps only, and only layers with elements|
|[p-4:]||Last 4 time steps only, and only layers with nodes|
|[3,10,-2:-1]||4th, 11th, and last two time steps, for both nodes and elements|
Datasource creation options can be specified with the "-dsco" flag in ogr2ogr.
An example of datasource creation option is: -dsco TITLE="My simulation" -dsco DATE=2014-05-01_10:00:00.
Layer creation options can be specified with the "-lco" flag in ogr2ogr.
An example of datasource creation option is: -lco DATE=24000.
The driver supports creating and writing to Selafin datasources, but there are some caveats when doing so.
When a new datasource is created, it does not contain any layer, feature or attribute.
When a new layer is created, it automatically inherits the same number of features and attributes as the other layers of the same type (points or elements) already in the datasource. The features inherit the same geometry as their corresponding ones in other layers. The attributes are set to 0. If there was no layer in the datasource yet, the new layer is created with no feature and attribute.In any case, when a new layer is created, two layers are actually added: one for points and one for elements.
New features and attributes can be added to the layers or removed. The behaviour depends on the type of layer (points or elements). The following table explains the behaviour of the driver in the different cases.
|Operation||Points layers||Element layers|
|Change the geometry of a feature||The coordinates of the point are changed in the current layer and all other layers in the datasource.||The coordinates of all the vertices of the element are changed in the current layer and all other layers in the datasource. It is not possible to change the number of vertices. The order of the vertices matters.|
|Change the attributes of a feature||The attributes of the point are changed in the current layer only.||No effect.|
|Add a new feature||A new point is added at the end of the list of features, for this layer and all other layers. Its attributes are set to the values of the new feature.||The operation is only allowed if the new feature has the same number of vertices as the other features in the layer. The vertices are checked to see if they currently exist in the set of points. A vertex is considered equal to a point if its distance is less than some maximum distance, approximately equal to 1/1000th of the average distance between two points in the points layers. When a corresponding point is found, it is used as a vertex for the element. If no point is found, a new is created in all associated layers.|
|Delete a feature||The point is removed from the current layer and all point layers in the datasource. All elements using this point as a vertex are also removed from all element layers in the datasource.||The element is removed from the current layer and all element layers in the datasource.|
Typically, this implementation of operations is exactly what you'll expect. For example, ogr2ogr can be used to reproject the file without changing the inner link between points and elements.
It should be noted that update operations on Selafin datasources are very slow. This is because the format does no allow for quick insertions or deletion of features and the file must be recreated for each operation.
The driver supports reading and writing to files managed by VSI Virtual File System API, which include "regular" files, as well as files in the /vsizip/ (read-write) , /vsigzip/ (read-only) , /vsicurl/ (read-only) domains.
There is no SRS specification in the Selafin standard. The implementation of SRS is an addition of the driver and stores the SRS in an unused data field in the file. Future software using the Selafin standard may use this field and break the SRS specification. In this case, Selafin files will still be readable by the driver, but their writing will overwrite a value which may have another purpose.