Add this page to your book
Remove this page from your book
The new EML fileformat
Why is there a new format?
With version 4, ENVI-met has changed the format of ALL system files, databasefiles and input/ output files to the new EML format. There are several reasons for that: First, with V4 a huge amount of new features have been introduced in ENVI-met. In any case, this required a complete redesign of the data structure and the contents of all input and output files. Moreover, the old format lacked versioning information and was very unflexible concering the data sequenzes and the way the data was stored (fixed sign intervalls, all information in a fixed order). Hence, there was no way but to break with the old format and design a new one.
For the Area Input files, import and conversion options are given through the editor, so you do not need to re-built them. For the smaller files (e.g. the files formerly known as Configuration Files .CF), you will need to re-compose them. That makes also sense as the new files also reflect the new model options in ENVI-met.
ENVI-met Markup Language EML format: General concept
The new ENVI-met EML (ENVI-met Markup Language) format is an XML-based self-describing file format. It can handle missing information by automatically adding default settings where possible. Therefore there will be almost no (or very few) version conflicts with old, recent and future files and the information they (not) provide.
As the term “XML-based” 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.
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> AK </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 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>
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 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
X: Numer of X-cells the matrix should have
Y: Number of Y-cells the matrix should have
Z: Number of Z-cells the matrix should have
defaultValue: 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>
TODO: Store Format? (→ JPG Stream)
<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.
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 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
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.