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.
GML version | Covered versions | LuciadLightspeed package |
---|---|---|
GML 2.1.2.1 |
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: http://www.opengeospatial.org/standards/. The XML schemas can be found on the following location: http://schemas.opengis.net/gml/.
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 |
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.
<gml:FeatureCollection>
<!-- the total bounds of the collection -->
<gml:boundedBy> .. </gml:boundedBy>
<gml:featureMember>
<myns:MyFeature>
<!-- the feature's bounds -->
<gml:boundedBy> ... <gml:boundedBy>
<!-- geometric properties -->
<myns:geomProperty>
<gml:Polygon> ... </gml:Polygon>
</myns:geomProperty>
...
<!-- non-geometric properties -->
<myns:customProperty>customValue</myns:customProperty>
...
</myns:MyFeature>
</gml:featureMember>
...
</gml:FeatureCollection>
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 (http://www.opengeospatial.org/standards/). |
-
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 |
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 fromAbstractFeatureMemberType
(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 fromAbstractFeatureType
, and which are not feature collections themselves. -
ILcd2DBoundsIndexedModel
: theapplyOnInteract
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 theILcdDataObject
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 implementingILcdShape
.
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:
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.
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.
Model decoder | Supported GML versions |
---|---|
2.x |
|
3.0.x, 3.1.x |
|
3.2.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 |
XML integration
All non-deprecated GML decoders share a similar package structure, with similar classes (described here for GML 3.2):
-
TLcdGML32ModelDecoder
: model decoder, can decode GML 3.2 data -
TLcdGML32ModelEncoder
: model encoder, can encode GML 3.2 data and export other models to 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.
Model encoder | Supported GML versions |
---|---|
2.x |
|
3.0.x, 3.1.x |
|
3.2.x |
The |
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.
Limitations
GML data are currently subject to the following requirements and limitations:
Decoding
-
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 GMLEllipsoidType
could be mapped onILcdEllipsoid
), 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 anILcdModel
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 theILcdModel
that is created. All geometries with local reference system different from theILcdModel
, will be transformed to theILcdModel
's reference system. -
XLink references are currently not resolved yet.