1 Headers


Mandatory / Optional Elements
<LandXML> Root element of transfer file

 <Units> Unit assignments
<Metric> Metric unit assignments

 <CoordinateSystem> Coordinate and height system
- <Start> Base point

 <Project> Project
- <Feature> "bSI_codings" extension
type coding systems

 <Application> Application
<Author> Authors

 <FeatureDictionary> Extension definition dictionary


1.1 Contents

The following concepts are defined in the header:

the exchange file, the root element
default units of measurement
coordinate and height systems and base point
project, as overall context of information
type coding or classification systems for the design content
application and author of the file
source of the extension definitions


All project information may be presented in one single exchange file (theoretically), but in practical situations most likely will be divided into appropriate packages. In particular, in cases where the content is composed of parts employing different coordinate or unit systems, these parts should be exchanged in separate files.

1.2 Transfer file

The root element <LandXML> of the transfer file is used by software to check the validity of the file structure. It shall have the following attributes set:

- date date
 [yyyy-mm-dd]
- time time [hh:mm:ss]
- version the schema version used in the file
 [1.2]
- language the language of the content
 e.g. [Finnish]
- readOnly write protection
 off / on [false | true]



1.3 Units

The units used in the file are defined by the <Units> element. When using a metric unit system the units are defined under the sub-element <Units>.<Metric>. The following table lists recommended units for file transfers. It is possible to diverge from these recommendations if another unit is more appropriate for the content. The recommended units are bolded, and in some cases are not the same as the LandXML default units. If some part of the plan employs different units from the rest of the project, it is recommended that either the divergent units be converted to common units or that the divergent part is presented as a separate file with its own units. Please see the example of descriping water supply and sewage units in millimeters.

Recommended file transfers use grads as direction (directionUnit) and angular (angularUnit) units. These are defined counter-clockwise from the base direction. In angular definitions the base direction is east and in direction definitions it the base direction is north. Defining the flowUnit is optional.

Metric units <Units>.<Metric>:

- areaUnit area units
 [hectare | squareMeter | squareMillimeter | squareCentimeter]
- linearUnit distance
 [millimeter | centimeter | meter | kilometer]
- volumeUnit volume
 [cubicMeter | liter | hectareMeter]
- temperatureUnit temperature
 [celsius | kelvin]
- pressureUnit pressure
 [HPA | milliBars | mmHG | millimeterHG]
- diameterUnit diameter
 [millimeter | centimeter | meter | kilometer]
- widthUnit width
 [millimeter | centimeter | meter | kilometer]
- heightUnit height
 [millimeter | centimeter | meter | kilometer]
- velocityUnit velocity
 [metersPerSecond | kilometersPerHour]
- flowUnit flow
 [cubicMeterSecond | literPerSecond | literPerMinute]
- angularUnit angle
 [radians | grads | decimal degrees | decimal dd.mm.ss]
- directionUnit direction
 [radians | grads |  decimal degrees | decimal dd.mm.ss]
- latLongAngularUnit angles of latitude and longitude
 [radians | grads |  decimal degrees | decimal dd.mm.ss]
- elevationUnit elevation unit
 [meter | kilometer |  feet | miles]


1.4 Coordinate and height systems

The height and coordinate system information is defined in the element <CoordinateSystem>. Exactly one coordinate system shall can be defined using the European Petrol Survey Group (EPSG), Open Geospatial Consortium (OGC) naming systems, or some other system in current use. In the EPSG and OGC systems the coordianate system is set with the name attribute and the corresponding code is described either in terms of a epsgCode or ogcWktCode. If the file employs a local coordinate system, it is set using the attribute horizontalCoordinateSystemName. If the horizontal coordinate system is different from the one customarily used with the horizontal coordinate system, it is set using the attribute verticalCoordinateSystemName. It is possible to set a rotationAngle for the coordinate system.

Attributes of <CoordinateSystem>:

- desc description a description of the system
- name name of the coordinate system
 ATTN! Name must be set when using EPSG or OGC coordinate systems. The name that corresponds to the code in the system:
1) EPSG name (see below)
2) OGC name
- epsgCode EPSG code ATTN! must be set when using an EPSG coordinate system. System code, range 0 - 32767
e.g. [23035] = ED50 / UTM zone 35N
e.g. [3067]= ETRS89 / ETRS-TM35FIN
e.g. [25835]= ETRS89 / UTM zone 35N
e.g. [7409]= EVRF2000
e.g. [4123]= KKJ
e.g. [2393]= KKJ / Finland Uniform Coordinate System
e.g. [3386]= KKJ / Finland zone 0
e.g. [2391]= KKJ / Finland zone 1
e.g. [2392]= KKJ / Finland zone 2
e.g. [2394]= KKJ / Finland
e.g. [32235]= WGS 72 / UTM zone 35N
e.g. [32435]= WGS 72BE / UTM zone 35N
e.g. [3263] = 84 / UTM zone 35N
- ogcWktCode OGC code ATTN! must be set when using an OGC coordinate system. System code
- horizontalCoordinateSystemName name of the coordinate system
 ATTN! must be set when using a coordinate system other than a EPSG or OGC one. The name of the employed coordinate system. (Attn! name, EPSG tai OGC code fields must be left blank)
- rotationAngle rotation angle of the coordinate system
 in angular units , e.g. [0]
- verticalCoordinateSystemName name of the horizontal coordinate system
 ATTN! Must be set when using a different coordinate system for horizontal and vertical coordinates.
e.g. Maanmittauslaitos N60 [N60]


The optional base point of the coordinate system is given using the element <CoordinateSystem>.<Start>. The point is given as a 3D coordinate point, with three space delimited values.

<Start>northing easting elevation</Start>


1.5 Project

It is mandatory to define a name and a description desc for the <Project>. The description can e.g. contain the project long name or code. The optional state attribute can be used to describe the state of the project and its content.

Attributes of <Project>:

- name name e.g. [example]
- desc description
 project description, long name or code, e.g. [12345]
- state state
 [abandoned]
[demolished]
[existing]
[proposed]


1.6 Type coding systems

The semantic meaning of the elements (points, lines and surfaces) can be defined using type coding or classification systems that are employed in the project and set in the bSI_codings extension using <Feature> elements under <Project> (one bSI_codings <Feature> instance for each employed system). Each system shall be given name, description and source. The name given here shall be used as prefix in later usage, see e.g. 2.1.3 Type coding. Additionally, a reference to source documentation may be given.

bSI_codings <Feature>

- name optional name
 e.g. [1]
- code feature type code
 [bSI_codings]
- source reference to source feature dictionary by name
 [bSI_LandMVD]
<Property>
- label [name] type coding system unique name
 value e.g. [TIEL]
- label [description] type coding system description
 value e.g. [Finnish Road Administration type coding for terrain model]
- label [source] Origin of the system
 value e.g. [FTA]
<DocFileRef>
- name [FTA TIEL] Documentation name
 location e.g.[http://www2.liikennevirasto.fi/julkaisut/pdf3/lo_2011-18_tie-_ja_ratahankkeiden_web.pdf]



1.7 Application

The <Application> element describes what software was used to create the file. If the file has been created using several different applications, all are described by their own <Application> element.

<Application> definitions:

- name name e.g. [XML Spy]
- desc description
 e.g. [XML development environment]
- manufacturer manufacturer
 e.g. [Altova]
- version version e.g. [2006]
- manufacturerURL manufacturer homepage
e.g. [http://www.altova.com]
- timeStamp time stamp of last save
 date time [yyyy-mm-ddThh:mm:ss],
e.g. [2009-10-19T17:21:05]



1.8 Authors

Information of the author of the file is recorded in the sub-element <Application>.<Author>. It is possible to define several authors as separate <Author>-elements, each with the following information:

- createdBy author name
 e.g. [Dave Designer]
- createdByEmail author e-mail
 e.g. [dave.designer@company.com]
- company company
 e.g. [Company]
- companyURL company homepage
 e.g. [http://www.company.com]
- timeStamp time stamp of last save date time [yyyy-mm-ddThh:mm:ss],
e.g. [2009-10-19T17:21:05]



1.9 Feature Dictionary

The <FeatureDictionary> documents the sources of the extensions used in the file. The contents of <Feature> elements follow the source specifications. LandXML-files may contain extensions from several different sources. In file transfers, proper recognition and interpretation is required only for the extensions documented in this specification, unless further agreements are made for e.g national application. The documentation is used to recognize e.g. the type coding systems used in the file.

- name unique name of dictionary [bSI_LandMVD]
- version current version number [0.5]
Document reference <DocFileRef>
- name doc file name
 [buildingSMART LandXML v1.2 Model View Definition]
- location documentation location
 [http://cic.vtt.fi/bSI_LandMVD]