The GDF domain model

The basic element of a GDF model is the Feature, which is the database representation of a real world geographic object (e.g. a road, a lake, a building). Each Feature must belong to exactly one Feature Class, identified by its Feature Class Code, and exactly one Feature Theme.

A GDF Feature has the same relationship with a GDF Feature Class as a Java object has with the class from which it was instantiated: a Feature Class represents the general type (e.g. a lake) while a Feature represents one concrete instance (e.g. the Titicaca lake).

A GDF Feature Theme is a group of Features/Feature Classes, that logically belong together. A river, a lake and a sea are features that all describe the same theme: waterways. GDF defines twelve Feature Themes, each containing a set of predefined Feature Classes. Although the predefined list is quite large, data providers are allowed to define their own additional Feature Classes.

Finally, each Feature belongs to one of four different Feature Categories, that describes the structural type of the feature. These Feature Categories are: Point, Line, Area and Complex Features.

GDF has a a three-level structure:

Each Feature can have a set of characteristics, called Attributes (e.g. a road can have a name, road type(highway, local way,…​), restrictions on what kind of vehicles are allowed, …​). Each Attribute consists of an Attribute Type, which is identified by a unique Attribute Type Code, and an associated Attribute Value, which can be a number, a text, a code, …​

GDF defines a set of Attribute Types, but data providers can add their own types.

Relationships allow to define characteristics of links between two or more Features. A turn restriction is an example of a relationship between two road elements. Each Relationship consists of a Relationship Type, identified by its Relationship Type Code, a set of Features involved in the relationship, and a set of Attributes describing the properties of the Relationship.

GDF defines a set of Relationship Types, but data providers can add their own types.

The format.gdf package is very similar to other LuciadLightspeed packages implementing data formats. Its basic components are:

GDF features are represented in format.gdf by the general interface ILcdGDFFeature. Each of the four different GDF feature categories (Point, Line, Area, Complex) is represented by a more specific GDF interface, as is shown in figure Figure 2, “GDF feature interfaces”. Each of these GDF interfaces extends an interface of the shape package, which allows to access its level-0 geometry. As a result, standard LuciadLightspeed painters can be used to draw ILcdGDFFeature objects.

Note that an ILcdGDFAreaFeature can consist of island and/or donut topologies (see figure Figure 3, “Donut (left) and island (right) topologies”), which is why it extends ILcdShapeList and not ILcdPolygon or ILcdComplexPolygon.

Figure Figure 4, “GDF class diagram” shows a more detailed class diagram of the main GDF classes and their most important methods.

As can be seen on the diagram, each ILcdGDFFeature has a set of ILcdGDFAttribute objects and is involved in a set of ILcdGDFRelationship. Each of these real-world representation objects has a link to its corresponding GDF type. These types contain a GDF type code and optionally some additional meta-data.

The ILcdGDFFeature interface extends the ILcdDataObject interface, attaching to each GDF feature a TLcdDataType, identifying the type of the feature (e.g. a road or railroad). Note that, since the GDF specification does not define attributes for the feature types, the data types also don’t expose any properties.

A ILcdGDFFeature is identified by a hierarchical organized TLcdGDFFeatureKey. (see article Model for more info about data management in GDF).

GDF data can be large, and therefore, the specification offers some extra functionality to structure the data spatially and/or according to the feature content.

GDF data are divided into one ore more Data Sets, each covering a certain areal subset of the total area covered by the database. Within a Data Set division according to the feature content takes place. Data Sets are divided into one or more Layers (not to be confused with LuciadLightspeed layers in a view), each containing all the feature instances for one or more feature classes. ^[1]

Layers, at last, can be subdivided into spatial areas, called Sections, which contain the actual GDF data objects.

This structure is preserved in the LuciadLightspeed GDF data model, as illustrated on figure Figure 5, “GDF model structure”. On each level, every ILcdModel has its own ILcdModelDescriptor, containing all meta data specific to that level.

Every ILcdModel has its own identifier, which is unique within its parent ILcdModel, and, together with the key of its parent, forms a unique key for that model within the world.

Every ILcdModel contained a GDF model implements the ILcd2DBoundsIndexedModel interface, which allows efficient painting or other operations onto its elements.

As a result of splitting data into sections, border issues will arise: features lying on the border of a section will point to features part of another section. The GDF specification takes into account these issues by adding some additional 'conversion data' to each section, which links internal features to external features.

The LuciadLightspeed GDF model decoder supports this conversion data and automatically resolves all border issues when a new model is loaded. In order to become connected, GDF models should be decoded with the same TLcdGDFModelDecoder instance. Models decoded with different model decoder instances will not become connected.

References to GDF features lying in a section that is not yet loaded, will remain null until that section is loaded into memory.

Level-0 geometry, attributes and relationships of Level-1 objects shall always be completely contained within the same section, and duplicated in multiple sections if necessary. Painting Level-1 features should thus never result into border issues, as long as the painter makes only use of the feature’s own geometry, attributes and relationship’s attributes.

Table Table 1, “methods subject to border issues” gives an overview of all methods in the GDF API that are subject to border issues (i.e. potentially resulting in null references due to border limitations).

The format.gdf package offers support for generating multileveled and tiled models, that allow for faster painting by reducing the level of detail when zooming out, and lazy loading of model data.

Multileveled/tiled models can be generated from normal GDF models by the TLcdGDFMultiLevelTiler. While the dataset.elements() enumeration will just return you the elements of the model, as in the original model, the dataset.applyOnInteract2DBounds() will take into account the accuracy level required, and the bounds in which the operation should be executed - potentially resulting in a much better performance.

The package also provides an encoder and decoder, which can store and read multilevel/tiled models to/from disk. Each tile is saved as a separate GDF-compatible file, while an additional file (with extension '.mtg'), contains the bounds of each of the tiles, and a reference to its corresponding file on disk, allowing for lazy tile loading.