IM4 Documentation, Headers

<LandXML>				Transfer file
	<Units><Metric>			Units (Metric)
	<CoordinateSystem>			Coordinate and elevation system
		<Start>		Base point
		<Feature>		"IM_coordTransformation" extension coordinate tranformation
			<Feature>	"IM_controlPoint" extension transformation control point
	<Project>			Project
		<Feature>		"IM_codings" extension type coding systems
	<Application>			Application
		<Author>		Authors
	<FeatureDictionary>			Referenced feature dictionary
		<DocFileRef>		External reference documentation
	<im:LocalCoordinateTransformation>			Coordinate Transformation Definition
		<im:SourceCRS>		Source geographic coordinate system
			<im:Ellipsoid>
			<im:PrimeMeridian>
		<im:TargetCRS>		Target geographic coordinate system
			<im:Ellipsoid>
			<im:PrimeMeridian>
		<im:DatumTransformation>		Datum transformation from Source to Target datum
			<im:Helmert3D>
		<im:Projection>		Projection used for projecting the geographical coordinates to a plane
			<im:TransverseMercator>
		<im:LocalTransformation>		Transformation from the projected coordinates to the final local coordinates
			<im:Helmert2D>
			<im:FittedPlane>

1.1 Contents

The goal is that all plan information can be presented in the same file. If the content is composed of parts that employ different coordinate or unit systems, each of these parts is separated into its own file.

NB: even if the language of the file is set to "Finnish", scandic and special characters should not used in Inframodel content in names, e.g. "väylä 2" should be spelled "vayla 2".

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:

	The default namespace to be used without prefix for all LandXML elements specialized for Inframodel in schema inframodel.xsd shall is set in the root element as xmlns="http://buildingsmart.fi/inframodel/404"
	The namespace for elements in Inframodel extension schema im.xsd (if used in the file) to be used with prefix "im" shall is set in the root element as xmlns:im="http://buildingsmart.fi/im/404"
	The types in Inframodel enumerations schema inframodelEnumerations.xsd are included in the http://buildingsmart.fi/inframodel/404 namespace

Note: The namespace URI is not meant to be used to look up information. Its sole purpose is to give the namespace a unique name.

The schema locations may be set in an Inframodel transfer file, in which case XML Schema Instance namespace shall be set in the root element: xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance
The following schema locations can be set to access online:

	The schema location for the default namespace can be set in the root element as xsi:schemaLocation="http://buildingsmart.fi/inframodel/404 https://buildingsmart.fi/infra/schema/4.0.4/inframodel.xsd"
	Additionally, if elements from im namespace are used in the file, the schema location can be set in the root element as xsi:schemaLocation="http://buildingsmart.fi/inframodel/404 https://buildingsmart.fi/infra/schema/4.0.4/inframodel.xsd http://buildingsmart.fi/im/404 https://buildingsmart.fi/infra/schema/4.0.4/im.xsd"
	The Inframodel enumerations schema inframodelEnumerations.xsd location is set automatically by being included in the default schema

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 inframodel file transfers. It is possible to diverge from these recommendations if another unit is more appropriate for the content. The inframodel recommended units are bolded, and in some cases are not the same as the LandXML default units (underlined). 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 sewerage units in millimeters.

Inframodel file transfers use grads as default 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 is north. Defining the flowUnit is optional.

Numeric precision in Inframodel exchange: all measures shall be given with six decimals (regardless of the number of digits before decimal point.).

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>. At least one coordinate system must be defined:
Exactly one horizontal system shall defined using the European Petrol Survey Group (EPSG) naming system, or some other local system in current use; the Open Geospatial Consortium (OGC) naming system shall not be used in Inframodel from version 4.0 onward. The EPSG coordinate system is set in the attribute epsgCode as a valid code without prefix. If a local horizontal coordinate system is used instead of a EPSG system, it is set using the attribute horizontalCoordinateSystemName (and the desc attribute can provide informal information about the system used).
Optionally, one vertical coordinate system can be specified in the attribute verticalCoordinateSystemName; this can be either using a EPSG namimg system (EPSG prefix and code, to be given here also when it is the same as for horizontal system), or a local vertical coordinate system (and the desc attribute can be used to provide informal information about the system used).
It is also possible to set a rotationAngle for the coordinate system.
The name attribute should not be used in Inframodel version 4.0.4.

desc	optional informal information about vertical or horizintal system when identified by other than EPSG system code	e.g. [Vertical coordinate system: Maanmittauslaitos N 60] NB: Should not be used for EPSG coordinate system
name	name of the coordinate system	NB: Should not be used in Inframodel
epsgCode	EPSG code identifying horizontal system (or both horizontal and vertical, in which case the same code shall be given also in verticalCoordinateSystemName)	e.g. [3067]
horizontalCoordinateSystemName	name of the horizintal coordinate system when not using EPSG system	e.g. [KKJ / Finland zone 4] ATTN! Shall not be set when using EPSG system
rotationAngle	rotation angle of the coordinate system	in angular units, e.g. [0]
verticalCoordinateSystemName	name of the vertical coordinate system, even when the same system is used for horizontal	e.g. [EPSG:3900] when using code from EPSG system e.g. [MML:N60] when using other than code from EPSG system

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.

For transformation between source geographic coordinate system sourceCRS and target local system targetCRS, a set of control points may be given under "IM_coordTransformation" <Feature> extension as "IM_controlPoint" extensions, where each point has latitude, longitude and altitude values in source system, and corresponding local system northing, easting and elevation values.
More detailed coordinate transformation parameters may be transferred using the <LocalCoordinateTransformation> element as explaned below in 1.4.1.

name	optional name
code	code	["IM_coordTransformation"]
source	source	[inframodel]
Parameters <Property>
	label	[sourceCRSname]	name of the source geographic coordinate system	value	e.g. [WSG84]
	label	[sourceEPSGcode]	EPSG code of the source geographic coordinate system	value	e.g. [4326]
"IM_controlPoint" <Feature> - Control point 1
	name	optional name
	code	code	[IM_controlPoint]
	source	source	[inframodel]
Parameters <Property>
	label	[useHorizontal]	shall be set to [yes] if the point should be used for calculating the horizontal transformation	value	[yes \| no]
	label	[useVertical]	shall be set to [yes] if the point should be used for calculating the vertical transformation	value	[yes \| no]
	label	[latitude]	latitude value in source CRS in latLongAngularUnit	value
	label	[longitude]	longitude value in source CRS in latLongAngularUnit	value
	label	[altitude]	altitude value in source CRS in elevationUnit	value
	label	[northing]	northing coordinate value in target system in linearUnit	value
	label	[easting]	easting coordinate value in target system in linearUnit	value
	label	[elevation]	elevation value in source CRS in elevationUnit	value

1.4.1 Local Coordinate Transformation parameters

The exact parameters of a particular Local Coordinate Transformation are given using <im:LocalCoordinateTransformation> element in im-extension schema as <any> element under <LandXML>. The xml schema (im.xsd) for the extension schema elements is available at Inframodel schema page.

Coordinate systems use a reference ellipsoid, defined by the semi-major and semi-minor axis, to approximate the shape of the Earth. The datum is then defined by the ellipsoid and its location and orientation, i.e. different datums can use the same ellipsoid but its position varies.

For example, the WGS84 system uses a reference ellipsoid with a semi-major axis of 6 378 137m and a semi-minor axis of 6 356 752m. The ellipsoid center is located at the Earth's center of mass.

The <SourceCRS> has two child-elements: <im:Ellipsoid> and <im:PrimeMeridian>

The element <im:TargetCRS> has no attributes, but two child-elements: <im:Ellipsoid> and <im:PrimeMeridian>

Helmert3D <im:DatumTransformation>.<im:Helmert3D> performs a coordinate transformation from one datum to another.

	rotationX	counter-clockwise rotation with respect to x axis (seconds of arc)
	rotationY	counter-clockwise rotation with respect to y axis (seconds of arc)
	rotationZ	counter-clockwise rotation with respect to z axis (seconds of arc)
	translationX	shift in the direction of x axis (meters)
	translationY	shift in the direction of y axis (meters)
	translationZ	shift in the direction of z axis (meters)
	scale	uniform scaling factor for all axes (ppm)

Transverse Mercator Map projection <im:Projection>.<im:TransverseMercator> transforms geographical coordinates (latitude, longitude, altitude) to a plane (x, ,y, z). The grid origin is taken on the central latitude and longitude, and false easting and northing is then applied to prevent negative coordinates west or south of the origin.

	falseEasting	the distance of the true grid origin east of the false origin (meters)
	falseNorthing	the distance of the true grid origin north of the false origin (meters)
	longitude0	central longitude, i.e. offset from Greenwich prime meridian, positive to the east (decimal degrees)
	latitude0	central latitude, i.e. offset from the Equator, positive to the north (decimal degrees)
	scale0	unitless scaling factor for the projection, used as is

In LocalTransformation <im:LocalTransformation>, Helmert2D <im:Helmert2D> transforms the projected (x,y,z) coordinates to the local coordinate system. FittedPlane <im:FittedPlane> corrects height values using a plane as the geoid model. The corrected height at point (x,y,z) is z_corrected = z + (a*x + b*y +c).

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>:

1.6 Type coding systems

The meaning (semantic) of the points, lines and surfaces is defined in the file. The parties of the project agree on a type coding systems that are used in the data transfer and they are set in the "IM_codings" extension using <Feature> element under <Project> defining:

1) The terrain description coding system (source data points and breaklines)(terrainCoding)
2) The surface description coding system (surfaceCoding)
3) The coding system for planned infrastructure objects (including alignments and breaklines, pipe netweorks, plan features) (infraCoding)
4) Additional or alternative type coding systems used in the project (proprietaryInfraCoding)

The existing terrain description contains source data points and breaklines. The surface description consists of the individual surfaces of the base data (terrain and ground layers) or the planned route or areal structures as TIN surface model or string line model. In addtion to surfaces, planned objects may be described as alignment geometry, line strings or points. It is possible to set the same type coding system for more than one of these.

The recommended type coding system in Inframodel exchange for 1) terrain is the Finnish Transport Infrastructure Agency type coding [Infra]. For 2) surface and 3) infrastructure objects, the recommended type coding system is the general InfraBIM type coding [InfraBIM]. Examples are given in sections 2 Base data and 3 Route planning.
In addition to the three main systems, it is also possible to define additional or alternative type coding systems, named as proprietaryInfraCoding (the name given here shall be used as prefix in later usage, see e.g. 2.1.3 Type coding)

	name	optional name	e.g. [1]
	code	type code	[IM_codings]
	source	reference to source feature dictionary by name	[inframodel]
coding systems <Property>
	label	[terrainCoding]	type coding system name for terrain source data	value	[Infra]
	label	[terrainCodingSourceRef]	source of terrain type coding system	value	e.g. [terrainCodingSourceRef="vayla.fi"]
	label	[terrainCodingDesc]	description of terrain type coding system	value	e.g. [Finnish Transport Infrastructure Agency terrain coding]
	label	[surfaceCoding]	type coding system for surface model	value	[InfraBIM]
	label	[surfaceCodingSourceRef]	source of surface type coding system	value	e.g. [surfaceCodingSourceRef="buildingsmart.fi"]
	label	[surfaceCodingSourceDesc]	description of surface type coding system	value	e.g. [Finnish InfraBIM surface coding]
	label	[infraCoding]	type coding system for general structures	value	[InfraBIM]
	label	[InfraCodingSourceRef]	source of infra type coding system	value	e.g. [InfraCodingSourceRef="buildingsmart.fi"]
	label	[InfraCodingSourceDesc]	description of infra type coding system	value	e.g. [Finnish InfraBIM coding]
	label	[proprietaryInfraCoding]	name of proprietary type coding system	value	e.g. by software X [proprietaryInfraCoding="X"] e.g. by organisation Y [proprietaryInfraCoding="Y"]
	label	[proprietaryInfraCodingSourceRef]	source of proprietary type coding system	value	e.g. by organisation Y [proprietaryInfraCodingSourceRef="www.y.com"]
	label	[proprietaryInfraCodingSourceDesc]	description of proprietary type coding system	value	e.g. by organisation Y [Y infra-coding]

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.

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:

1.9 Feature Dictionary

The <FeatureDictionary> identifies the specification source of extensions used in the file, and the point of access to their documentation. The contents of <Feature> elements shall follow the source specification. LandXML-files in general may contain extensions from several different sources. In Inframodel file transfer, proper recognition and interpretation is required only for the extensions documented in this specification ( e.g. for the type coding systems used in an Inframodel file). The dictionary for Inframodel extensions shall be specified using <FeatureDictionary> element as shown in the table below. The name shall be unique, and always 'inframodel' for the dictionary of Inframodel extensions, and exactly the same value shall be set in every Inframodel <Feature> for attribute source (the <Feature> attribute code being labeled with IM_ -prefix). The <version> should match the version number of the Inframodel schema. Optional <DocFileRef> element can be used to provide the URI link to named external documentation where applicable feature code and property type values are described (EXTENSIONS page of this documentation, in the case of Inframodel feature dictionary).

Proprietary extensions can be used in addition to those specified in the Inframodel feature dictionary. Each source of such non-Inframodel extension specifications shall be identified as their own <FeatureDictionary> instance, with unique name. That name shall be set as the value of attribute source in every <Feature> according to that dictionary. Proprietary <Feature> instances should not have attribute code labeled with IM_ -prefix.

NB: When using proprietary extension for an <Element> that has a <Feature> in Inframodel schema using InframodelAbstractFeatureType (with annotation 'Inframodel'), an Inframodel <Feature> with the attribute code set to 'IM_proprietary' shall be first placed directly under the <Element>, and the proprietary <Feature> shall be placed under the Inframodel <Feature>.

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	[Finnish]
readOnly	write protection	off / on [false \| true]

		<LandXML>	schema documentation
		<LandXML>	root element short example

		<Units>	schema documentation
		<Units>	short example

	name	name of the source CRS	e.g. [WSG84]
	epsg	epsg code of the source CRS	e.g. [4326]

	name	name
	semiMajorAxis	the equatorial radius of the reference ellipsoid (meters)
	inverseFlattening	inverse flattening f is a unitless measure of how much the semi-minor axis b is compressed relative to the semi-major axis a, i.e. f = (a-b)/a

1 Headers

Description hierarchy