History

Release Notes »

citygml4j 1.0 - Release Notes

Welcome to the release notes for citygml4j 1.0. I am happy to announce that citygml4j has finally reached version 1.0 after almost two years of development and its first release back in 2008.

What's new?

citygml4j 1.0 is built on top of the previous early access release citygml4j 1.0ea which has been published seven months ago. Thus, the most notable changes between citygml4j 1.0 and any previous 0.x release are already described in the release notes of the early access release:

Nevertheless, there are changes between the final citygml4j 1.0 release and its early access version which are worth mentioning. Please keep reading.

Simple access to all geometry representations of city objects in all LODs

Every city object (i.e., descendants of org.citygml4j.model.citygml.core.AbstractCityObject) now provides a getLodRepresentation() method which returns an instance of org.citygml4j.model.citygml.core.LodRepresentation. An LodRepresentation makes it easy to access all geometry representations of its city object in all levels of detail.

For this purpose, LodRepresentation declares the following six getter methods:

1 List<GeometryProperty<? extends AbstractGeometry>> getLod0Geometry()
2 List<GeometryProperty<? extends AbstractGeometry>> getLod1Geometry()
3 List<GeometryProperty<? extends AbstractGeometry>> getLod2Geometry()
4 List<GeometryProperty<? extends AbstractGeometry>> getLod3Geometry()
5 List<GeometryProperty<? extends AbstractGeometry>> getLod4Geometry()
6 List<GeometryProperty<? extends AbstractGeometry>> getLodGeometry(int lod)

Each method returns a List of GeometryProperty objects which contain all geometries that represent the city object within a specific LOD. Since the geometry property elements are returned (and not the geometries themselves), you can easily detect and follow XLink references.

LodRepresentation is especially helpful if your application needs quick access to the geometries contained in a CityGML instance document, e.g. in case of a viewer application. And because every citygml4j content object knows its direct parent element within the CityGML object tree, you can still access the city object and its semantics for a given geometry in LodRepresentation. The class org.citygml4j.util.child.ChildInfo provides utility methods such as getParentCityObject(Child child) which help in making such queries really simple. Simply feed this method with the geometry resp. geometry property and get back the city object for which it is modeled.

Moreover, LodRepresentation can be visited by a GeometryWalker. For example, if you are only interested in processing solid geometries of your city objects, implement a corresponding geometry walker by deriving it from the pre-defined abstract walker class org.citygml4j.util.walker.GeometryWalker and override its visit(AbstractSolid abstractSolid) method. Afterwards, let your geometry walker visit the geometries contained in the LodRepresentation of your city object. See the following code snippet:

 1 GeometryWalker walker = new GeometryWalker() {
 2 
 3     @Override
 4     public void visit(AbstractSolid abstractSolid) {
 5         // do something reasonable with the solid geometries here...
 6 
 7         ...
 8     }
 9 
10 };
11 
12 walker.visit(building.getLodRepresentation());

Support for gml:RectifiedGridCoverage

The GML feature gml:RectifiedGridCoverage is now supported by citygml4j. A gml:RectifiedGridCoverage is required when using the element <dem:RasterRelief> from the CityGML Relief module.

Access to <app:Appearance> elements of parent CityGML features when reading a CityGML document chunk-wise

Starting from the early access release of citygml4j 1.0, it is possible to parse a CityGML instance document chunk-wise, e.g. feature by feature. Processing only one chunk at a time reduces memory consumption and, thus, allows for handling CityGML files of arbitrary file size.

This chunk-wise approach faces one big challenge: Both for GML3 and CityGML, the processing of a chunk sometimes requires to access information which is modeled for a (transitive) parent element within the XML tree. However, traversing up the tree to the chunk's parent is not possible if only the chunk is held in memory.

For example, a GML geometry may denote its spatial reference system (SRS) using its gml:srsName attribute or it may inherit the SRS from its (transitive) parent geometry element. In order to specify a common SRS for all geometries of a single feature, the SRS can also be given on the level of the feature element itself (usually using its <gml:boundedBy> property). Even more, a nested feature (and thus its geometries) can inherit the SRS information from its (transitive) parent feature. For this reason it might be necessary to check parent features for SRS information.

The previous early access release already provides a solution to this: org.citygml4j.xml.io.reader.ParentInfo. When reading a CityGML document chunk-wise, ParentInfo gives access to the most important properties modeled for the parent feature of the current chunk within the XML tree. Moreover, you can access the ParentInfo for a given ParentInfo object enabling to recursively traverse up the entire XML tree. ParentInfo, of course, does not provide a full view of the parent feature (otherwise the chunk-wise approach would be broken...).

Similar to the SRS information, also CityGML appearance information modeled for a feature is inherited by its nested features. Whereas ParentInfo could already be used to retrieve the SRS from parent features, the current citygml4j release augments ParentInfo to additionally access <app:Appearance> elements of parent features.

Abstract walker classes implementing the functor interfaces for visiting geometries, features, and GML objects

The citygml4j content classes provide support for the visitor pattern. Two different visitor types are supported: One is a visitor that returns void, and the other is a functor that returns a generic type. The previous citygml4j release additionally comes with abstract tree-walker classes implementing the former type of visitor interfaces (see the early access release notes for further information).

With version 1.0 of citygml4j, abstract tree-walker implementations for the functor interfaces have been added. You can now choose between pre-implemented abstract walker classes for both visitor types - simply derive your own walker class in order to visit the nodes of a citygml4j object tree and to implement actions on these nodes.

Common root interface ModelObject for the citygml4j data model

The citygml4j interfaces representing CityGML, GML, and xAL elements are modeled in three individual hierarchies. Each hierarchy has its own root interface: org.citygml4j.model.citygml.CityGML for CityGML content, org.citygml4j.model.gml.GML for GML content, and org.citygml4j.model.xal.XAL for xAL content. For previous releases of citygml4j, these three hierarchies did not have a common root interface. As consequence, methods which may possibly return an element from either hierachy or which take such an element as parameter had to choose java.lang.Object as proper data type.

With this version of citygml4j, org.citygml4j.model.common.base.ModelObject is introduced as common root interface of the citygml4j data model. Wherever possible, methods have been re-written to return a ModelObject or to take a ModelObject as parameter instead of java.lang.Object. ModelObject provides the method getModelType() which allows for querying the hierarchy the object belongs to.

Reduced memory consumption when reading a CityGML document chunk-wise

When parsing a CityGML instance document chunk-wise, citygml4j uses an internal buffer to cache parsed XML elements. As soon as a chunk is read, the corresponding cached elements are forwarded to JAXB in order to construct a citygml4j content object and are released from the buffer afterwards. XML elements belonging to parent features of the current chunk remain in the buffer.

Put simply, the buffer size plus the memory used by JAXB mainly determine the overall memory consumption needed for reading a chunk and for creating a corresponding citygml4j content object. For the early access release, the memory consumption of citygml4j was even higher than the DOM representation of the same chunk.

The buffer implementation has been reworked for this release of citygml4j. Although citygml4j will always require more memory than a pure JAXB-based approach (at least as long as it is built on JAXB), it now uses less memory for reading and representing a chunk than a comparable DOM representation.

Minor bug fixes

  • Fixed bug in CityGML writer classes which caused invalid XML structure when writing empty XML elements (see r441)

Why your version 1.0ea code might get broken when switching to version 1.0

Some of the changes from the previous early access release of citygml4j to version 1.0 might break your exisiting 1.0ea-based code. Please keep reading for a list of possible reasons and corresponding fixes.

Consistent naming of interfaces representing abstract complex type definitions

All interfaces in org.citygml4j.model representing an abstract complex type definition from both the CityGML and GML XML schemas are now consistently prefixed with "Abstract". For example, org.citygml4j.model.citygml.core.CityObject has been renamed to org.citygml4j.model.citygml.core.AbstractCityObject. The same applies to implementing classes in org.citygml4j.impl (which, however, should not be used directly in your code).

Please adapt the interface names in your source code accordingly.

Mix-up of accept and visit methods in visitor pattern support fixed

The implementation of the visitor pattern accidentally confused the method names for visit and accept methods. This mix-up has been corrected with the current release.

Please swap the method names of visit and accept methods at places where you invoke or override these methods in your source code.

Changes to the values of the enum types CityGMLClass, GMLClass, and XALClass

The enum types CityGMLClass, GMLClass, and XALClass in org.citygml4j.model have been cleaned from values for abstract classes such as GMLClass.ABSTRACTGEOMETRY. The values of these enum types are returned from the methods getGMLClass(), getCityGMLClass(), and getXALClass() all of which are inherited from abstract classes but are overriden in concrete child classes.

Furthermore, underscores have been added as word delimiter to the values of the enum types in order to increase the readability of source code. For example, GMLClass.LINESTRINGSEGMENTARRAYPROPERTY has been renamed to GMLClass.LINE_STRING_SEGMENT_ARRAY_PROPERTY.

If you use these enum types in your source code, please adapt the values manually.

Changes to the package structure of the citygml4j source code files

The package structure of the citygml4j source code files has been rearranged. This might result in broken import statements inside your source code.

Please adapt any broken import statement to meet the new package structure. Depending on your development environment, this can even be done automatically.

Feedback wanted!

Are you using citygml4j? Please contact us through if you are using citygml4j in your software developments no matter whether you are building commercial, scientific, or any other type of application. We are also interested in code snippets showing how citygml4j can be used to solve a specific problem. We are happy about your feedback! Optionally, we can add a link to your web page and developments on the citygml4j site.

Have fun...!