The EML fileformat
ENVI-met Markup Language EML format: General concept
The ENVI-met EML (ENVI-met Markup Language) format introduced with V4 is an XML-like self-describing file format. It can handle missing information by automatically adding default settings where possible.
As the term “XML-like” suggests, it uses the concept of XML, but only supports a limited sub-set of XML features and file options. In addition, EML introduces a number of extra features (e.g. matrix tags) which are not defined in general XML. So you might be able to generate EML files in some external XML-editor, but it is not for sure that the result will be accepted by ENVI-met. Therefore we suggest to use the provided software to handle the files.
ENVI-met EML-based files will be, step-by-step. replaced by JSON formatted ASCII files. These do provide more efficient data handling for large files and also full compatibility with the data world outside of ENVI-met.
Whenever possible, ENVI-met will convert your files on-the-fly, means: once it is opened in the old format, it will be saved in the new format while keeping a copy of your original file with the extension .old
.
File Header
Each EML file contains a header with a number of basic information about the file encapsulated in the <Header> tag. EML does not use the classic XML header and the root node is “<ENVI-MET_Datafile>”.
<ENVI-MET_Datafile> <Header> <filetype> "DATA" </filetype> <version> 1 </version> <revisiondate> 30.10.2012 </revisiondate> <remark> Envi-Data </remark> <encryptionlevel> 0 </encryptionlevel> </Header> <SOME_ITEM> <TAG1> XX </TAG1> <TAG2> YY </TAG2> (...) </SOME_ITEM> </ENVI-MET_Datafile>
The items inside the header are:
- filetype: Identifies the type of the EML file to prevent loading EML files into the wrong places.
- version: A version ID
- revisiondate: Last time the file was modified
- remark: a general information on the file, mostly including name and version of the software that has created the file.
- encryptionlevel: Flag if the file is encrypted
After the header, the items describing the information stored in the file are following in any sequence.
General File items
Items in EML file follow the XML-conventions. Shortcut syntax for empty tags is not allowed. Element nesting is not supported at the moment. The following example shows the definition of a soil type used in the database as an example for a standard EML database entry.
<SOIL> <ID> 00MM00AK </ID> <Description> Asphalt (with Gravel </Description> <versiegelung> 1 </versiegelung> <ns> 0.00000 </ns> <nfc> 0.00000 </nfc> <nwilt> 0.00000 </nwilt> <matpot> 0.00000 </matpot> <hydro_lf> 0.00000 </hydro_lf> <volumenw> 2.21400 </volumenw> <b> 0.00000 </b> <waerme_lf> 1.16000 </waerme_lf> <Group> </Group> <Color> 65280 </Color> </SOIL>
Special EML items
EML addes a number of special items required by ENVI-met to the XML syntax.
''matrix-data'' Tags
Matrix-data
tags hold a comma-seperated set of 2D data. It is similar to the original ENVI-met Matrix-Format but has some important changes:
- Each line represents one set of X-data (Data with the same Y-index). Line breaks are not allowed (and are not neccessary any more since lines can get as long as they need to get)
- The data are now comma-seperated in contrast to the original ENVI-met matrix with a fixed character width. Spaces and commas are not allowed inside the data field former times.
<buildings> <zTop type="matrix-data" dataI="15" dataJ="15"> 0,0,0,0,0,0,0,0,0,0,0,0,0,0,0 0,20,20,0,0,0,0,0,0,0,0,0,20,20,0 (...) </zTop> </buildings>
The matrix-data
tag allows the definition of a 2D element matrix in the EML file. The attribute required are:
- dataI: Number of elements in each row (=one x-row)
- dataJ: Number of rows to come (=number of y-elements)
No line-breaks are alowed within one row of data.
''spare-matrix-3D'' Tags
The spare-matrix-3D
tags are used to store 3D data in an efficient way. It uses the fact, that in most cases the majority of X-Y-Z data in a 3D data grid are defined through a common default value, e.g. 0. The spare-matrix-3D
only stores those values which are different to the default value.
To reconstruct the original matrix, several parameters are given in the type
options:
X
: Numer of X-cells the matrix should haveY
: Number of Y-cells the matrix should haveZ
: Number of Z-cells the matrix should havedefaultValue
: The base value with which the whole matrix will be filled. The X-Y-Z data in this section will only define data which are different to the default value.
<LAD-Profile type="sparematrix-3D" X="5" Y="5" Z="6" defaultValue="0.00000"> 2, 2, 2, 2.00000 3, 2, 2, 2.00000 2, 3, 2, 2.00000 3, 3, 2, 2.00000 (...) 3, 4, 4, 2.00000 4, 4, 4, 2.00000 2, 2, 5, 2.00000 3, 2, 5, 2.00000 2, 3, 5, 2.00000 3, 3, 5, 2.00000 </LAD-Profile>
''bitmap'' Tags
Including bitmaps is not foressen for the moment.
''collections'' Tag
<soilprofil> BR,BR,BR,SD,LE,LE,LE,LE,LE,LE,LE,LE,LE,LE,LE,LE,LE,LE,LE </soilprofil>
Collections
are Multi-Item tags stored as normal item tags. In the example above, the item <soilprofil>
holds a series of 19 individual values (sub-items) which are stored in a comma-sepearated list (to keep it readable we used only 2 instead of 6 chars for the IDs).
These kind of tags only work with items that have explicit defined number of subitems to follow. They will only be interpeted correctly with programs understanding the meaning of such a comma-seperated list. In standard XML, this collection would have been splitted into 19 sub-items, one for each soil layer. Each of these sub-items would have its own opening and closing tag. For ENVI-met this was considered as an overkill. Therefor the Multi-Item tags have been introduced.
Color encoding
Color codes like in the example above are always stored in plain RGB data. To understand the concept, the decimal value needs to be converted into a hexadecimal value. In hexadecimal, the colors are coded $RRGGBB
where RR
, GG
and BB
are the intensities for the red, green and blue component of the color. Each intensity ranges from $00
(not present) to $FF
(full presence). For example $00FF00
is a full red and in decimal this would be '#65280' like in the example above which gives no clue which color this might be.