Introduction to GML

Open Geospatial Consortium’s (OGC) Geography Markup Language (GML) is an XML-based data format for describing, storing and exchanging geographical data. LuciadLightspeed provides support for several versions of the GML format. This article gives a short introduction to the GML format, and how to incorporate it in your LuciadLightspeed applications using the GML packages.

The GML packages allow you to:

  • Decode GML data files and import them into a LuciadLightspeed-based domain model

  • Encode LuciadLightspeed models to a GML data file

  • Customize the GML decoders, as well as the encoders, to generate or use custom-defined domain objects

LuciadLightspeed provides support for GML 2.x and GML 3.x data. There are three implementations provided, each based on one specific GML version, as shown in table Table 1, “Supported GML versions with their corresponding LuciadLightspeed package”. Other 2.x and 3.x versions are very similar to one of these versions, and most data files based on other 2.x/3.x versions can be handled by one of these three implementations.

Table 1. Supported GML versions with their corresponding LuciadLightspeed package
GML version Covered versions LuciadLightspeed package


GML 2.x


GML 3.1.1

GML 3.0.x, 3.1.x


GML 3.2.1

GML 3.2.x


All specifications can be found on the OGC website: The XML schemas can be found on the following location:

This article is not a course about GML or XML; it assumes you are already familiar with the basic concepts of these formats.

The GML package is built upon the LuciadLightspeed XML binding framework.

If you want to customize the GML decoder or encoder and you are not familiar with the XML binding framework, it is advised to read Integrating XML data into your application first.

The following packages also provide limited support for GML but are deprecated; it is advised not to use them anymore.

  • format.gml

  • format.gml3

The GML data model

The GML specifications contain an elaborate set of data types, grouped in a number of XML schemas. The three most important schema groups are:

  • The base schemas, containing some general XML types, used frequently by other schemas;

  • The feature schema, providing a framework for the creation of GML features and feature collections (base and feature schema are the same in case of GML 2);

  • The geometry schemas, providing a set of geometries to describe features.

Besides these schemas, a number of other schemas are available in GML 3.x for describing temporal features, topology, coordinate reference systems, and so on.

Features and Feature Collections

The basic element of a GML dataset is the feature, which is the GML representation of a real world entity (for example, a road, a lake, a building).

Do not confuse GML features with LuciadLightspeed features, provided by the ILcdFeatured interface. LuciadLightspeed features correspond to feature properties in GML. In this article, the word feature always refers to GML features, not to LuciadLightspeed features.

Each feature is defined by:

  • zero, one or more geometric properties, describing the spatial extent of the feature, and

  • zero, one or more non-geometric properties, describing all other characteristics of the feature.

GML offers a large set of geometric primitives, ranging from basic shapes such as points, polylines and polygons to complex structures such as Bezier curves and triangulated surfaces. GML also allows to define and use your own, custom-defined shapes.

Non-geometric properties are not defined by the GML standard, as they are specific to each application domain. These properties should be defined in a custom application schema that extends the GML schema.

Features can be grouped into feature collections comparable to the way the ILcdModel interface is used to group objects in LuciadLightspeed. Collections can also be nested themselves.

A GML dataset typically exists of a feature collection containing some features. Sample Program: Typical outline of a GML document summarizes the general structure of a GML document.

Program: Typical outline of a GML document

  <!-- the total bounds of the collection -->
  <gml:boundedBy> .. </gml:boundedBy>

      <!-- the feature's bounds -->
      <gml:boundedBy> ... <gml:boundedBy>

      <!-- geometric properties -->
        <gml:Polygon> ... </gml:Polygon>

      <!-- non-geometric properties -->



The Simple Features Profile (GML 3.1.1 only)

The Simple Features Profile was introduced as a subset of GML, to reduce the effort and time required for implementing and supporting GML in software applications. There are three different levels defined, the first one (Level 0) being the most restrictive, the third one (Level 2) the most flexible. These profiles mainly restrict:

  • which geometric primitives are allowed to appear in data, and

The complete list of primitives supported by this profile, can be found in the GML Simple Features Profile specification, section 7.2, which can be downloaded at the Open Geospatial Consortium’s website (

  • which non-geometric properties are allowed (in Level 0, for example, the properties may only be simple datatypes such as boolean, integer, double and a few others).

The LuciadLightspeed GML domain model

Domain model classes

LuciadLightspeed provides a dedicated domain model for each supported GML version (2, 3.1 and 3.2) in the respective packages com.luciad.format.gml2.model, com.luciad.format.gml31.model and com.luciad.format.gml32.model

For GML 3.x, only the most important schema groups (see The GML data model) are explicitly represented by domain classes; the other concepts (modeling temporal features, topologies, coordinate reference systems etc) are represented using a generic domain model based on ILcdDataObject.

All these domain classes provide accessors (getters and setters) to easily access the data contained in the objects. In addition, they also implement the ILcdDataObject interface; thereby providing generic access. You can find a detailed description of generic access in Unified domain access.

Finally, they also implement ILcdDeepCloneable. For reasons of backwards compatibility, the domain classes for GML 2 and GML 3.1 also implement ILcdSelfDescribedFeatured and ILcdFeatured.

LuciadLightspeed provides direct access to the GML data model and types in the TLcdGML2DataTypes, TLcdGML31DataTypes and TLcdGML32DataTypes classes.

The domain models are generated from the GML XML schema documents. Care has been taken to make the domain classes as easy to use as possible. XML implementation details such as element names and schema types are hidden as much as possible. The exact mapping rules for mapping XML Schema types on ILcdDataObject are described in detail in the package documentation of the com.luciad.format.xml.bind.schema.datamodel package, which provides support for binding XML Schema-based XML documents to ILcdDataObject domain models.

Some GML types, such as feature collections and geometries, are mapped on domain objects implementing additional interfaces to make them easier to integrate with other components in LuciadLightspeed. The following paragraphs describe these additional mappings in more detail. More information can be found in the class documentation of the GML model decoders.

Feature collection integration

Feature collections in GML correspond to models in LuciadLightspeed. The following GML types are considered feature collections and are thus mapped on domain objects implementing LuciadLightspeed model interfaces:

  • AbstractFeatureCollectionType and extensions

  • extensions of AbstractFeatureType: only if they are allowed to have child elements extending from AbstractFeatureMemberType (GML 3.x) or if they have child elements with name 'member' (GML 3.1).

Each of the domain objects for these types implements the following model interfaces:

  • ILcdModel: contains as elements all GML domain objects which are directly contained (through a feature member) in the parent collection, of which the type extends from AbstractFeatureType, and which are not feature collections themselves.

  • ILcd2DBoundsIndexedModel: the applyOnInteract methods only visit those elements of the model which have non-null bounds, that is, the GML features that have geometric content.

  • ILcdModelTreeNode: contains as submodels all feature collections which are directly contained (through a feature member) in the parent collection.

The model interfaces provided by a feature collection are all non-editable, that is, elements cannot be added to or removed from the models.

All GML models have as model descriptor a TLcdGML2ModelDescriptor, TLcdGML31ModelDescriptor, or TLcdGML32ModelDescriptor.

Feature integration

Features in GML correspond to model elements in LuciadLightspeed. All GML types extending from AbstractFeatureType are considered as features, except feature collections (see Feature collection integration). All relevant contents of a GML feature can be retrieved through the following interfaces:

  • ILcdDataObject: all properties of a feature, both geometric and non-geometric, are accessible through the ILcdDataObject interface.

  • ILcdBounded: returns as bounds the union of all geometries which are part of the feature.

  • ILcdShapeList: contains as shapes the set of geometries which are part of the feature. The default implementation for AbstractFeatureType recursively searches in all the properties of the feature, and collects all properties implementing ILcdShape.

The ILcdDataObject interface is editable, as with all domain objects.

Geometry integration

Geometries in GML correspond to shapes in LuciadLightspeed. All types extending from one of the following GML types are considered as geometries, and are mapped on domain objects implementing an ILcdShape interface:

Table 2. Mapping of GML geometry types on LuciadLightspeed interfaces
GML type LuciadLightspeed interface

















Refer to the documentation’s mapping table of the GML mapping library classes for a detailed overview of how other geometries extending from these types are mapped on ILcdShape interfaces.

Other integrations

Table Table 3, “Mapping of GML miscellaneous types on LuciadLightspeed interfaces” gives an overview of other GML types which are mapped on additional LuciadLightspeed interfaces.

Table 3. Mapping of GML miscellaneous types on LuciadLightspeed interfaces
GML type LuciadLightspeed interface



GML model decoders

Table Table 4, “Overview of GML model decoders” gives an overview of the GML model decoders provided by the LuciadLightspeed API and the GML versions they support.

Table 4. Overview of GML model decoders
Model decoder Supported GML versions




3.0.x, 3.1.x




2.x, 3.0.x, 3.1.x, 3.2.x

The TLcdGMLModelDecoder is provided as a convenience model decoder, which is capable of handling all GML formats. Its implementation analyzes the header of the documents to be decoded to detect which GML version they are, and then delegates the actual decoding to one of the other GML model decoders.

The TLcdGMLModelDecoder and TLcdGML3ModelDecoder are deprecated and should no longer be used.

XML integration

All non-deprecated GML decoders share a similar package structure, with similar classes (described here for GML 3.2):

The TLcdGML32ModelDecoder and TLcdGML32ModelEncoder classes can be used as a standalone, out-of-the-box model decoder and encoder for decoding and encoding GML 3.2 data.

The GML32 data model, accessible on the TLcdGML32DataTypes class, can be used to configure to a TLcdXMLSchemaBasedDecoder or TLcdXMLSchemaBasedEncoder for use with GML data. This is typically done by other XML-based formats that embed GML in them. The article on the XML binding framework provides more details on how to do this.

GML model encoders

Table Table 5, “Overview of GML model encoders” gives an overview of the GML model encoders provided by the LuciadLightspeed API and which GML versions they support.

Table 5. Overview of GML model encoders
Model encoder Supported GML versions




3.0.x, 3.1.x



The TLcdGMLModelEncoder, TLcdGML2ModelEncoder and TLcdGML3ModelEncoder are deprecated and should no longer be used.

GML model encoders can operate in two modes: save or export. Saving can only be done for GML data having the same version as the encoder; for example, the TLcdGML32ModelEncoder can only save data which was decoded by the TLcdGML32ModelDecoder. For all other data, export mode is used.

In saving mode, the data will be written in exactly the same way as it was read. The main application schema describing the data is copied next to the data, by default.

In export mode, the encoder automatically generates an application schema for the data being exported, based on its ILcdDataObject and ILcdShape structure and contents. This generated application schema is written next to the data file.


GML data are currently subject to the following requirements and limitations:


  • GML documents must be compliant with GML 2.0 or higher (up to 3.2.1).

  • Only the GML types listed in the mapping tables are mapped on specific LuciadLightspeed interfaces. Although other types could also be mapped on more specific interfaces than ILcdDataObject (for example, the GML EllipsoidType could be mapped on ILcdEllipsoid), this is currently not supported.

  • A valid XML application schema must be available for each GML document.

  • GML allows individual geometries to have their own, local coordinate reference system, different from their parent’s reference system. LuciadLightspeed ILcdModel objects can only have one model reference (all elements in an ILcdModel should be defined using the same reference system). The first reference system that is encountered in a GML document (typically the reference system of the feature collection’s envelope) is used as the model reference for the ILcdModel that is created. All geometries with local reference system different from the ILcdModel , will be transformed to the ILcdModel's reference system.

  • XLink references are currently not resolved yet.


  • Data cannot be encoded yet with XLINK references.