OPALS Format Definition

When importing/exporting data from/to files, OPALS uses certain default values (e.g. file format version on export). To override the default values, an OPALS Format Definition File (OFD) must be specified. Additionally, OPALS allows for the import/export of generic text (ASCII) and binary formats, which may also be specified via an OFD. OFD files can be used with Module Import and Module Export.

Supported Formats

OFD files are XML files where the root element is named <opalsFormatDefinition>. Within this root element, exactly one of the elements denoting a certain file format must be specified:

Supported File Formats
File Format XML element tag
Generic ASCII <ascii>
Generic Binary <binary>
LAS <las>

Supported Data Types

As described here, the OPALS Datamanager supports a wide range of different data types. When specifying data types in OFD files, the following names are to be used. The same names must be used when explicitly defining the data types of custom attributes with the Generic filter's assignment operator.

Supported data types and their names
name ODM Type Size
int64 64bit integer 64 Bit
int integer 32 Bit
unsignedInt unsigned integer 32 Bit
short short 16 Bit
unsignedShort unsigned short 16 Bit
byte byte 8 Bit
unsignedByte unsigned byte 8 Bit
boolean boolean 8 Bit
float float 32 Bit
double double 64 Bit
char(n) fixed length string n Bytes
string unlimited string variable

OFD Schema file

OFD files must adhere to the OFD XML Schema, which can be found at $OPALS_ROOT/addons/formatdef/opalsFormatDefinition_1_0.xsd .

<?xml version="1.0" encoding="ISO-8859-1" ?>
<xs:schema xmlns:xs="http://www.w3.org/2001/XMLSchema">
<!--
OPALS format definition schema.
Do not edit!
For a quick start, have a look at the end of this file and / or the exemplary format definitions that come with OPALS.
-->
<!-- Definition of various simple types -->
<xs:simpleType name='char_type'>
<xs:restriction base='xs:string'>
<xs:length value='1'/>
</xs:restriction>
</xs:simpleType>
<xs:simpleType name = "column_type">
<xs:union>
<xs:simpleType>
<xs:restriction base = "xs:string">
<xs:enumeration value = "double"/>
<xs:enumeration value = "float"/>
<xs:enumeration value = "int"/>
<xs:enumeration value = "unsignedInt"/>
<xs:enumeration value = "short"/>
<xs:enumeration value = "unsignedShort"/>
<xs:enumeration value = "byte"/>
<xs:enumeration value = "unsignedByte"/>
<xs:enumeration value = "int64"/>
<xs:enumeration value = "string"/>
<xs:enumeration value = "boolean"/>
</xs:restriction>
</xs:simpleType>
<xs:simpleType>
<xs:restriction base = "xs:string">
<xs:pattern value = "char\([0-9]+\)"/>
</xs:restriction>
</xs:simpleType>
</xs:union>
</xs:simpleType>
<xs:simpleType name = "endian_type">
<xs:restriction base = "xs:string">
<xs:enumeration value = "little"/> <!-- force little endian byte order -->
<xs:enumeration value = "big"/> <!-- force big endian byte order -->
</xs:restriction>
</xs:simpleType>
<!-- Definition of various complex types for better readability -->
<xs:complexType name='char_def'>
<xs:attribute name="val" type="char_type" use="required" />
</xs:complexType>
<xs:complexType name='string_def'>
<xs:attribute name="val" type="xs:string" use="required" />
</xs:complexType>
<xs:complexType name='uint_def'>
<xs:attribute name="val" type="xs:nonNegativeInteger" use="required" />
</xs:complexType>
<xs:complexType name='bool_def'>
<xs:attribute name="val" type="xs:boolean" use="required" />
</xs:complexType>
<!-- Schema of a coordinate or attribute to be im-/exported. -->
<xs:complexType name='entry_def'>
<!-- The name of the entity: 'x', 'y', 'z', or the name of a predefined or custom attribute. -->
<xs:attribute name="val" type="xs:string" use="required" />
<!-- Import of custom attributes only: the data type to be used internally (ODM). -->
<xs:attribute name="internalType" type="column_type" use="optional" />
<!-- The data type to be used externally/on disk (default: internal data type). -->
<xs:attribute name="externalType" type="column_type" use="optional" />
<!-- Ascii export only: the format to use for numeric data types. Syntax: <width>.<precision> (default: .6) -->
<xs:attribute name="format" type="xs:decimal" use="optional" />
<!-- The value to be considered as invalid. Must be convertible to the external data type.
Import: not supported yet!
Export: use invalidValue if the attribute is not defined or not present.
Concerning numeric types, there exist strings that are interpreted specially:
'Max' -> maximum finite representable value
'Min' -> minimum finite representable value (for real number types: minimum positive value)
'NaN' -> quiet (non-signaling) not-a-number (real number types only)
'Inf' -> infinity (real number types only) -->
<xs:attribute name="invalidValue" type="xs:string" use="optional" />
<!-- Transformation of read (external) values before storing them internally (ODM).
Useful for applying unit changes: e.g. angles within the ODM are expected to be in radians.
Must follow the generic filter grammar, accessing the external values via 'x'.
Example:
'x*Pi/180' (Converting from degrees to radians)
-->
<xs:attribute name="toInternal" type="xs:string" use="optional" />
<!-- Transformation of internal (ODM) values before writing them to disk (external).
Useful for applying unit changes: e.g. angles should be stored in radians within the ODM.
Must follow the generic filter grammar, accessing the internal values via 'x'.
Example:
'x/Pi*180' (Converting from radians to degrees)
-->
<xs:attribute name="toExternal" type="xs:string" use="optional" />
</xs:complexType>
<xs:complexType name='endian_def'>
<xs:attribute name="val" type="endian_type" use="required" />
</xs:complexType>
<!-- Schema of an opals format definition -->
<xs:element name="opalsFormatDefinition">
<xs:complexType>
<xs:sequence>
<!-- Optional textual description of file format -->
<xs:element name="description" type="xs:string" minOccurs="0" />
<!-- Choose the format to be one of text/ascii, binary, or LAS -->
<xs:choice>
<xs:element name="ascii"> <!-- begin of ascii section ================================ -->
<xs:complexType>
<xs:all>
<!-- Specify the decimal separator (default: '.'). -->
<xs:element name="decimalSeparator" type="char_def" minOccurs="0" />
<!-- Specify the character set to be considered as separating data entries (default: white space or horizonal tabulator).
Import: match any.
Export: use first character. -->
<xs:element name="columnSeparators" type="string_def" minOccurs="0" />
<!-- Import only: skip lines that begin with commentInitiator (default: none). -->
<xs:element name="commentInitiator" type="string_def" minOccurs="0" />
<!-- Import only: ignore white space. (default: true). -->
<xs:element name="skipWhiteSpace" type="bool_def" minOccurs="0" />
<!-- Optional header section -->
<xs:element name="header" minOccurs="0">
<xs:complexType>
<xs:choice>
<!-- Import only: skip the first skipLines lines (default: number of lines defined by 'text'). -->
<xs:element name="skipLines" type="uint_def" />
<!-- Export only: start files with this string (default: empty). -->
<xs:element name="text" type="string_def" />
</xs:choice>
</xs:complexType>
</xs:element>
<!-- Required: the sequence of coordinates and attributes to be imported. The order is relevant! -->
<xs:element name="data">
<xs:complexType>
<xs:choice maxOccurs="unbounded">
<!-- A coordinate or attribute to be im-/exported. See definition of entry_def above. -->
<xs:element name="entry" type="entry_def" />
<!-- Import only: skip/ignore skipColumns columns at this point -->
<xs:element name="skipColumns" type="uint_def" />
</xs:choice>
</xs:complexType>
</xs:element>
</xs:all>
</xs:complexType>
</xs:element> <!-- end of ascii section -->
<xs:element name="binary"> <!-- begin of binary section =============================== -->
<xs:complexType>
<xs:all>
<!-- Advanced feature: assume the data to be im-/exported to be present in its little or big endian representation (default: native). -->
<xs:element name="endian" type="endian_def" minOccurs="0" />
<!-- Optional header section -->
<xs:element name="header" minOccurs="0">
<xs:complexType>
<xs:choice>
<!-- Import only: skip/ignore the first skipBytes bytes (default: length of 'text') -->
<xs:element name="skipBytes" type="uint_def" />
<!-- Export only: start files with this string (default: empty) -->
<xs:element name="text" type="string_def" />
</xs:choice>
</xs:complexType>
</xs:element>
<!-- Required: the sequence of coordinates and attributes to be imported. The order is relevant! -->
<xs:element name="data">
<xs:complexType>
<xs:choice maxOccurs="unbounded">
<!-- A coordinate or attribute to be im-/exported. See definition of entry_def above. -->
<xs:element name="entry" type="entry_def" />
<!-- Import only: skip/ignore skipBytes bytes at this point -->
<xs:element name="skipBytes" type="uint_def" />
</xs:choice>
</xs:complexType>
</xs:element>
</xs:all>
</xs:complexType>
</xs:element> <!-- end of binary section -->
<xs:element name="las"> <!-- begin of LAS section =============================== -->
<xs:complexType>
<xs:all>
<!-- Export only: set the LAS minor version. -->
<xs:element name="versionMinor" minOccurs="0"> <xs:complexType>
<xs:attribute name="val" use="required"> <xs:simpleType>
<xs:restriction base="xs:nonNegativeInteger"> <xs:maxInclusive value="4"/> </xs:restriction>
</xs:simpleType> </xs:attribute>
</xs:complexType> </xs:element>
<!-- Export only: set the LAS point data record format. -->
<xs:element name="pointDataRecordFormat" minOccurs="0"> <xs:complexType>
<xs:attribute name="val" use="required"> <xs:simpleType>
<xs:restriction base="xs:nonNegativeInteger"> <xs:maxInclusive value="10"/> </xs:restriction>
</xs:simpleType> </xs:attribute>
</xs:complexType> </xs:element>
<!-- Export only: set the scale of LAS point coordinates. -->
<xs:element name="coordinateScale" minOccurs="0"> <xs:complexType>
<xs:attribute name="val" use="required">
<xs:simpleType>
<xs:union memberTypes="xs:decimal">
<xs:simpleType>
<xs:restriction base="xs:string">
<xs:enumeration value="Min"/>
</xs:restriction>
</xs:simpleType>
</xs:union>
</xs:simpleType>
</xs:attribute>
</xs:complexType> </xs:element>
<!-- Specification of extraBytes in the LAS-file. -->
<xs:element name="extraBytes" minOccurs="0">
<xs:complexType>
<xs:sequence>
<xs:element name="entry" minOccurs="1" maxOccurs="unbounded">
<xs:complexType>
<!-- The name of the extraBytes-entry in the LAS-file. -->
<xs:attribute name="lasName" use="optional">
<xs:simpleType>
<xs:restriction base="xs:string"> <xs:maxLength value="32"/> </xs:restriction>
</xs:simpleType>
</xs:attribute>
<!-- Export only: The description of the extraBytes-entry in the LAS-file. -->
<xs:attribute name="lasDescription" use="optional">
<xs:simpleType>
<xs:restriction base="xs:string"> <xs:maxLength value="32"/> </xs:restriction>
</xs:simpleType>
</xs:attribute>
<!-- Export only: the data type to be used in the LAS file. default: internal type -->
<xs:attribute name="lasType" type="column_type" use="optional" />
<!-- The internal name of (the first element of) the extraBytes-entry: the name of a predefined or custom attribute. -->
<xs:attribute name="internalName" type="xs:string" use="required" />
<!-- The internal names of eventual 2nd and 3rd elements of the extraBytes-entry: the names of predefined or custom attributes. -->
<xs:attribute name="internalName2" type="xs:string" use="optional" />
<xs:attribute name="internalName3" type="xs:string" use="optional" />
<!-- Import of custom attributes only: the data type to be used internally. Default: LAS type -->
<xs:attribute name="internalType" type="column_type" use="optional" />
<!-- Export only: the scale to be used. Default: 1.0 -->
<xs:attribute name="scale" type="xs:decimal" use="optional" />
<!-- Export only: the offset to be used. Default: 0.0 -->
<xs:attribute name="offset" type="xs:decimal" use="optional" />
<!-- Export only: the (numeric) value to be written to file if the attribute is not present (ignoring scale and offset).
There exist strings that are interpreted specially:
'Max' -> maximum finite representable value
'Min' -> minimum finite representable value (for real number types: minimum positive value)
'NaN' -> quiet (non-signaling) not-a-number (real number types only)
'Inf' -> infinity (real number types only) -->
<xs:attribute name="invalidValue" use="optional">
<xs:simpleType>
<xs:union memberTypes="xs:decimal">
<xs:simpleType>
<xs:restriction base="xs:string">
<xs:enumeration value="Max"/>
<xs:enumeration value="Min"/>
<xs:enumeration value="NaN"/>
<xs:enumeration value="Inf"/>
</xs:restriction>
</xs:simpleType>
</xs:union>
</xs:simpleType>
</xs:attribute>
</xs:complexType>
</xs:element>
</xs:sequence>
</xs:complexType>
</xs:element>
</xs:all>
</xs:complexType>
</xs:element> <!-- end of LAS section -->
</xs:choice>
</xs:sequence>
<xs:attribute name="version" type="xs:string" fixed="1.0" />
</xs:complexType>
</xs:element>
</xs:schema>
Author
wk
Date
05.03.2012