This is an old revision of the document!
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 lacks 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 large files such as your Area Input files and the different databases, import and conversion options are given, so you do not need to re-built the big files. 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: General concept
The new ENVI-met EML (ENVI-met Markup Languge) 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.
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> 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>
Remark for ''color'' codes
Color codes like in this example are always stored in 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.
Special EML items
EML addes a number of special items required by ENVI-met to the XML syntax.
''matrix-data'' Tags
Modified:
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> <z-top type="matrix-data" X="40" Y="40"> (Example missing) </z-top> </buildings>
The matrix-data
tag allows the definition of a 2D element matrix in the EML file. The attribute required are:
- rows: Number of rows following in the matrix
- colums: Number of columns in the matrix
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 ways. 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
TODO: Store Format? (→ JPG Stream)
''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>
gets a series of 19 individual values which are comma-sepearated.
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 openeing and closing tag. For ENVI-met this was considered as an overload and therfore the mulit-Item tags have been introduced.