Copyright: CC BY-NC-SA 3.

0 DE (cc) 2013 Eike Tauscher and Michael Theiler

All provided material including the provided software packages are licensed under:
Creative Commons Attribution-Non-Commercial-Share Alike 3.0 Germany
If you are using the package or parts of it in any commercial way, a commercial license is required.
Visit http://www.ifctoolsproject.com for more information or contact us directly: [email protected]

Getting Started – Java Toolbox IFC2x3/IFC4

Version 2.0 - 2013-05-30
Content
About the IFC TOOLS PROJECT ...................................................................................................... 3
Getting Access ..................................................................................................................................... 3
Service ................................................................................................................................................. 3
Prerequisites ................................................................................................................................ 4
Java Version ......................................................................................................................................... 4
Performance Issues ............................................................................................................................. 4
The IFC JAVA TOOLBOX ................................................................................................................ 5
Toolbox Versions ................................................................................................................................. 5
Integration into your Software Project ............................................................................................... 5
Design of the IFC JAVA Toolbox ........................................................................................................... 5
Reading IFC Files .................................................................................................................................. 7
Writing IFC Files ................................................................................................................................... 8
Getting specific IFC Entities ................................................................................................................. 8
Access to the Attributes of an IFC Entity ........................................................................................... 10
Data Types ......................................................................................................................................... 11
Adding new IFC Entity Instances to the Model ................................................................................. 12
IFC Header Information ..................................................................................................................... 12
Listen to Model Changes ................................................................................................................... 13
Listen to Step Parser Progress ........................................................................................................... 14
Type Set Caching ............................................................................................................................... 14

Getting Started – Java Toolbox IFC2x3/IFC4 – Version 2.0 2013-05-30 2

About the IFC TOOLS PROJECT

The IFC TOOLS PROJECT provides a framework for accessing and visualizing IFC based Building
Information Models (BIM). Developers of such software can easily integrate the libraries into their
products. End-users may use our viewers to visualize and check their models.

The IFC TOOLS PROJECT framework is a fork of the former OPEN IFC TOOLS project that is no longer
maintained. The project has been forked in 2010 and has been fully revised within the last three
years. The framework offers the possibility to develop IFC-based applications quickly in order to
support complex business processes in the building industry. The provided tools are already in use by
thousands of developers and users worldwide.

Getting Access

The tools are free for research and also available for prototype development. Please contact us, if
you are interested to get access to the research version or if you want to use it in any commercial
way.

Service

On request, we can also quickly implement other Toolboxes besides the provided IFC Toolboxes
based on any EXPRESS scheme, you pretend, e.g. extended schemes like IFC-BRIDGE or standardized
schemes like any of the STEP Application Protocols (AP). We also provide individual consulting,
further developer support, and software development on hourly, daily, monthly or on a project basis.
Training courses at your location are also possible (in English or German). Please ask for a certain
quote by explaining your expectations.

If you have further questions relating the framework or in general to IFC, BIM or EXPRESS/STEP feel
free to contact us.

Getting Started – Java Toolbox IFC2x3/IFC4 – Version 2.0 2013-05-30 3

Prerequisites

Please consider the up following notes to get the best possible introduction.

Java Version

The toolbox is developed and tested with the latest officially released Java Development Kit (JDK),
currently Java 7. There is no guarantee that it will work properly with older versions. However, there
are no known incompatibilities, with one exception:

 Reading of IFCZIP files, where the name of the zipped IFC file entry contains special
characters (e.g. German Umlauts or French Accents), will fail using Java 6 and earlier.

Performance Issues

For better performance - even if you want to load huge IFC STEP files - it is strongly recommended to
configure the JVM memory settings. The memory settings depend on your hardware and operating
system (OS). Using a 32Bit OS, there is typically a limit of around 1.3GB memory for the -Xmx switch.
If you have a 64Bit OS, the maximum available amount of physical memory of your machine limits
the JVM. For best performance, give your JVM as much memory as you can maintain.

Example: java -Xms512m -Xmx3000m MyProgram

Getting Started – Java Toolbox IFC2x3/IFC4 – Version 2.0 2013-05-30 4

The IFC JAVA TOOLBOX

Using the IFC Java Toolbox you have full access to IFC based BIM models. This means you can easily
read, write, modify or create IFC files. The toolbox is implemented in Java. Furthermore, it is fully
object oriented and early binding is used to handle the IFC entities. A corresponding Java class with
its attributes represents each IFC entity. In this sense, it is possible to instantiate and to handle any
object, as you know it from any object oriented programming language.

The IFC Java Toolbox supports any explicit and inverse attribute of all entities specified in the
IFC scheme. Derived attributes, functions and rules are not yet supported. Supported file formats for
exchanging IFC models are:

 STEP (according to ISO 10303-21), and

 IFCZIP (according to buildingSMART implementer agreement CV-2x3-154).

Toolbox Versions

Due to different versions of the IFC scheme, we provide toolboxes for the most recent IFC versions:

 IFC2X3 Java Toolbox for accessing and creating IFC2x3 files

 IFC4 Java Toolbox for accessing and creating IFC4 files

Besides, it is possible for us to implement quickly other Toolboxes besides the provided IFC
Toolboxes based on any EXPRESS scheme, you pretend, e.g. extended schemes or standardized
schemes like any of the STEP Application Protocols (AP).

Integration into your Software Project

If you want to integrate the toolbox into your software project, just add the binary file of the toolbox
to the build path of your project. Additionally, you can import the sources of the toolbox to get a
deeper insight, what’s happening in the respective Java classes. However, it is not recommended to
modify any of the provided classes, since in this way your project may become incompatible with
newer versions of the toolbox. For a better overview of the methods, classes and interfaces of the
toolbox have a look into the provided documentation.

Design of the IFC JAVA Toolbox

The IFC JAVA Toolbox consists of three main parts:

 the Java classes for each IFC entity,

 a parser for reading IFC STEP files and
 a model for accessing all available IFC objects.

The Java classes representing the IFC entities provide access methods for getting and setting any
explicit attribute that is specified in the respective IFC scheme. Inverse relations, as far as specified,

Getting Started – Java Toolbox IFC2x3/IFC4 – Version 2.0 2013-05-30 5

are resolved automatically and can be read analogously to the explicit attributes. Moreover, if any
change to the model or the objects occurs, the inverse attributes will stay consistent.

The inheritance structure specified in the IFC scheme is modeled within the Java classes (e.g. an
IfcWall is an instance of IfcProduct). The root interface of any IFC entity is the
ClassInterface. Select types and other defined types in the IFC scheme are mapped via
respective interfaces.

The parser provides methods to read IFC STEP files and IFCZIP files. However, you will not have to
deal too much with the parser. This will run in background and you can concentrate on your actual
task.

The last part of the toolbox contains a central model for collecting and accessing the created IFC
objects. It is called the IfcModel and provides methods:

 to read and write IFC files,

 to access contained IFC objects and
 to add and remove IFC objects.

Besides the three main parts, there is another part for creating and compressing GUIDs according to
the algorithms used by the Industry Foundation Classes (IFC) called GuidCompressor. This part is
developed by Jan Tulke. The algorithm is based on an implementation in C from Jim Forester,
implemented previously by Jeremy Tammik, Peter Muigg and Janos Maros. It is open source and can
be found here:

http://www.buildingsmart-tech.org/implementation/get-started/ifc-guid/ifc-guid-summary

Getting Started – Java Toolbox IFC2x3/IFC4 – Version 2.0 2013-05-30 6

Reading IFC Files

The IFC JAVA Toolbox can read IFC STEP files and IFCZIP files from any data source that implements
java.io.InputStream (e.g. a local file from the file system, a remote file on a web server or a
file stored in a database). After calling one of the following read-methods, the toolbox loads the IFC
file and initializes the described IFC entities. Those objects can be accessed and manipulated using
the IfcModel’s methods. The following lines of code demonstrate how to read IFC STEP files from
different data sources:

//create a new instance of IfcModel

IfcModel ifcModel = new IfcModel();

//load an IFC STEP file from the file system

File stepFile = new File("C:\\myfile.ifc");
ifcModel.readStepFile(stepFile);

//... or load an IFC STEP file from a web server

URL stepURL = new URL("http://www.myifchomepage.com/myifcstepfile");
ifcModel.readStepFile(stepURL);

//... or load an IFC STEP file from any other data source,
//that implements java.io.InputStream (e.g. database connection)
InputStream stepStream = myDBconnection.getStepFile("1234");
ifcModel.readStepFile(stepStream);

Analogous reading of IFCZIP files:

//create a new instance of IfcModel

IfcModel ifcModel = new IfcModel();

//load an IFCZIP file from the file system

File ifczipFile = new File("C:\\myfile.ifczip");
ifcModel.readIfcZipFile(ifczipFile);

//... or load an IFCZIP file from a web server

URL ifczipURL = new URL("http://www.myifchomepage.com/myifczipfile");
ifcModel.readIfcZipFile(ifczipURL);

//... or load an IFCZIP file from any other data source,

//that implements java.io.InputStream (e.g. database connection)
InputStream ifczipStream = myDBconnection.getIfcZipFile("1234");
ifcModel.readIfcZipFile(ifczipStream);

Getting Started – Java Toolbox IFC2x3/IFC4 – Version 2.0 2013-05-30 7

Writing IFC Files

The IFC JAVA Toolbox can write IFC STEP files and IFCZIP files. If you want to export the current
IfcModel’s content, call one of the respective write-methods. The following lines of code
demonstrate how to write IFC STEP files to different data sinks:

//write an IFC STEP file to the file system

File stepFile = new File("C:\\myfile.ifc");
ifcModel.writeStepfile(stepFile);

//... or write an IFC STEP file to a web server

URL stepURL = new URL("http://www.myifchomepage.com/myifcstepfile");
ifcModel.writeStepfile(stepURL);

//... or write an IFC STEP file to any other data sink,

//that implements java.io.OutputStream (e.g. database connection)
OutputStream stepStream = myDBconnection.getStepFile("1234");
ifcModel.writeStepfile(stepStream);

Analogous writing of IFCZIP files:

//write an IFCZIP file to the file system

File ifczipFile = new File("C:\\myfile.ifczip");
ifcModel.writeIfcZipFile(ifczipFile);

//... or write an IFCZIP file to a web server

URL ifczipURL = new URL("http://www.myifchomepage.com/myifczipfile");
ifcModel.writeIfcZipFile(ifczipURL);

//... or write an IFCZIP file to any other data sink,

//that implements java.io.OutputStream (e.g. database connection)
OutputStream ifczipStream = myDBconnection.getIfcZipFile("1234");
ifcModel.writeIfcZipFile(ifczipStream);

Getting specific IFC Entities

After you have loaded an IFC file, you may want to have access to the objects. In IFC there is a root
entity that could be the starting point for your code, the so-called IfcProject represents the root
of any decomposition tree. You have access to this entity as shown below:

IfcProject ifcProject = ifcModel.getIfcProject();

If you want to get a collection with all instances of IFC entities contained in the model, call:

Collection<ClassInterface> ifcObjects = ifcModel.getIfcObjects();

Getting Started – Java Toolbox IFC2x3/IFC4 – Version 2.0 2013-05-30 8

Often, you need only objects of a specific type. Therefore, you can call the
getCollections(Class classType) method of the IfcModel. It will return a collection
with all instances of the specified type. This includes instances from subtypes of the specified type
(e.g. IfcWall is a subtype of IfcProduct):

//get all IfcWall instances contained in the model

Collection<IfcWall> walls = ifcModel.getCollection(IfcWall.class);

//get all IfcProduct instances contained in the model (includes all walls)
Collection<IfcProduct> products = ifcModel.getCollection(IfcProduct.class);

Sometimes, it is useful to find entities by their entity instance name (aka STEP line number). You can
ask the model for a specific instance or you can get all objects sorted by their entity instance name as
follows:

//get the object with the specified entity instance name

//(e.g. #123 in STEP physical file).
ClassInterface ifcObject = ifcModel.getIfcObjectByEntityInstanceName(123);

//get a map of all IFC entities sorted by their entity instance names
SortedMap<Integer, ClassInterface> ifcObjectMap =
ifcModel.getIfcObjectsSortedByEntityInstanceName();

Some objects in IFC have a globally unique ID (GUID). These objects are instances of IfcRoot. You
can ask the model to get such entities with a certain GUID as follows:

//get the object with the specified GUID

IfcRoot ifcObject = ifcModel.getIfcObjectByID("23j$pkdXqHseOb00sJH0zG");

//multiple query: get the objects with the specified GUIDs

String[] ids = {"23j$pkdXqHseOb00", "56k3xydXqHseOb95", "49l5xydXqHokOb12"};
Collection<String> idList = Arrays.asList(ids);
Map<String, IfcRoot> ifcObjectsMap = ifcModel.getIfcObjectsByIDs(idList);

Getting Started – Java Toolbox IFC2x3/IFC4 – Version 2.0 2013-05-30 9

Access to the Attributes of an IFC Entity

For each explicit attribute of an IFC entity there is a respective get- and set-method in the Java class.
With these methods you can read or modify the value of this attribute:

//read the product representation

IfcWall ifcWall = ...
IfcProductRepresentation representation = ifcWall.getRepresentation();

//set a new product representation

IfcProductRepresentation newRep = new IfcProductRepresentation();
newRep.setName(new IfcLabel(new STRING("myRepresentation", true)));
ifcWall.setRepresentation(newRep);

If the attribute is a collection, then there are additional methods to add or remove entries to or from
this collection:

IfcProductRepresentation representation = new IfcProductRepresentation();

IfcRepresentation rep1 = new IfcRepresentation();
//add a new representation to the product representation
representation.addRepresentations(rep1);
//or remove it
representation.removeRepresentations(rep1);

Sometimes, it is necessary to cast an entity to a specific type to get access to the attributes of this
type:

ClassInterface ifcObject = ...

if(ifcObject instanceof IfcWall)
{
//cast ifcObject to IfcWall
IfcWall ifcWall = (IfcWall) ifcObject;
IfcProductRepresentation representation = ifcWall.getRepresentation();
...
}

Some attributes of IFC entities are optional (see official documentation of IFC scheme). If these
attributes are not specified, they will be null in the toolbox. Consequently, you have to take notice
of these attributes to avoid NullPointerException’s! This means that you have to check that
these attributes are not null, before you continue with your code:

if(ifcProject.getName() != null)
{
IfcLabel name = ifcProject.getName();
...
}

Getting Started – Java Toolbox IFC2x3/IFC4 – Version 2.0 2013-05-30 10

Inverse attributes of an IFC entity can be accessed via a respective get-method. Set-methods are not
necessary, since they are resolved automatically.

SET<IfcRelDecomposes> ifcRelDecomposesSet = ifcProject.getIsDecomposedBy_Inverse();

Data Types

The data type of an attribute of an IFC entity may be:

 an IFC class or type

 a basic data type (numerical, logical, alphanumerical)
 an enumeration
 a collection of an IFC class or a basic data type
 a collection of a collection (of a collection…)

The following basic data types are provided within the toolbox:

 BINARY
 BOOLEAN
 DOUBLE
 INTEGER
 LOGICAL
 REAL
 ENUM
 STRING

The following collections are provided within the toolbox:

 SET<?>
 LIST<?>

To get the value of a logical or numerical data type or of an enumeration, you have to call the public
attribute value of the respective data type:

IfcQuantityArea ifcQuantityArea = ...

IfcAreaMeasure ifcAreaMeasure = ifcQuantityArea.getAreaValue();
double area = ifcAreaMeasure.value;

IfcFaceBound ifcFaceBound = ...

boolean orientation = ifcFaceBound.getOrientation().value;

To get the value of a STRING object, you have to call either the getDecodedValue() method or
the getEncodedValue() method, since Strings are encoded in STEP format. The first method

Getting Started – Java Toolbox IFC2x3/IFC4 – Version 2.0 2013-05-30 11

returns the value of this object as decoded String according to ISO-10303-21 (§6.3.3.1-§6.3.3.3), e.g.
"T\s\|r"  "Tür".

IfcProject ifcProject = ...

IfcLabel ifcLabel = ifcProject.getName();
String name = ifcLabel.getDecodedValue();

Adding new IFC Entity Instances to the Model

Within the last sections, it was already shown, how to create new IFC entities and how to change
their attributes. However, these objects must been added to the IfcModel instance, since
otherwise the export to an IFC file will not work properly or views related to the model will not work
correctly, since they will not be informed about the model change!

The first step is to create a new instance of an entity. Each IFC class has two constructor methods:
one standard constructor and one constructor, where you have to specify each attribute. Afterwards,
you have to add this new object to the model:

IfcWall myNewWall = new IfcWall();

ifcModel.addIfcObject(myNewWall);

Alternatively, you can add also a collection of new entities to the model that might be more efficient:

Collection<ClassInterface> newObjects = new ArrayList<>();

IfcWall wall1 = new IfcWall();
newObjects.add(wall1);
IfcWall wall2 = new IfcWall();
newObjects.add(wall2);
ifcModel.addIfcObjects(newObjects);

IFC Header Information

Besides the IFC entities description, a STEP file contains general information contained in a header.
With the help of the toolbox, you have access to this header information that contains:

 the File Description attribute (View Definitions, Implementation Level),

 the File Name attribute (File Path, Time Stamp, Author, Organization, Toolbox, Application,
Authorizing Person) and
 the File Schema attribute (Schema Identifiers).

See also:

http://www.buildingsmart-tech.org/implementation/ifc-implementation/ifc-header

Getting Started – Java Toolbox IFC2x3/IFC4 – Version 2.0 2013-05-30 12

You can read the header information as follows:

File_Description description = ifcModel.getFile_Description();

File_Name fileName = ifcModel.getFile_Name();
STRING authorization = fileName.getauthorization();
STRING name = fileName.getname();
...
File_Schema schema = ifcModel.getFile_Schema();

If you want to write IFC files, you can specify or modify most of these header attributes using the
respective set methods in the model or in the header classes. However, some of the attributes will be
ignored and replaced by corresponding values before the export (e.g. file path, creation date, used
toolbox).

Listen to Model Changes

Sometimes, it is necessary to get informed when a change to the model occurs (e.g. when IFC entities
were added to the model). Then, for example, a view has to be updated. Therefore, you can add a
listener to the model, where you can define, how to handle this event:

ifcModel.addIfcModelListener(new IfcModelListener() {
public void modelObjectsRemoved(Collection<ClassInterface> objects) {...}
public void modelObjectsAdded(Collection<ClassInterface> objects) {...}
public void modelObjectRemoved(ClassInterface object) {...}
public void modelObjectAdded(ClassInterface object) {...}
public void modelContentChanged() {...}
});

This listener will get informed, when:

 IFC entities have been added to the model

 IFC entities have been removed from the model
 the model content has changed completely or fundamental

Besides listening to model changes, it is also possible that attributes of IFC entities may change and
you want to get informed, if such event occurs. Therefore, you have to add a listener to each IFC
object, where such an event has to be processed:

IfcWall wall = ...

wall.addObjectChangeListener(new ObjectChangeListener() {
public void ifcModelObjectChange(ClassInterface ifcObject) {...}
});

Getting Started – Java Toolbox IFC2x3/IFC4 – Version 2.0 2013-05-30 13

Listen to Step Parser Progress

Since the loading process of large IFC files may take a while, it is a good idea to inform the user of
your application about the loading progress. Therefore, you can add a listener to the model, where
you can to define, how to handle the progress (e.g. showing the progress in a progress bar, etc.):

ifcModel.addStepParserProgressListener(new StepParserProgressListener() {
public void progressActionPerformed(ProgressEvent event) {}
});

The progress event contains information about the current loading action step and the progress of
this step in percent.

Type Set Caching

The IfcModel class provides a caching option that might be useful, if you often use the method
getCollection(Class classType) for getting a collection of a specific type of objects (e.g.
IfcWall.class). This caching is only useful, if and only if you need to have repeatedly fast access
to specific object types! Otherwise, it will only consume memory. By default this caching is disabled.
You can enable the caching using the respective constructor of the IfcModel class or by calling the
setTypeCacheEnabled() method:

//enable type caching at model construction

IfcModel ifcModel = new IfcModel(true);

//enable type caching at runtime

ifcModel.setTypeCacheEnabled(true);

You should disable the caching to save memory, if you don’t need the caching any longer. However, a
SoftReference is used for the implementation of this cache. This means that the cache’s
memory will be deallocated when free memory is low. In this case, the cache will be rebuilt when
you call the getCollection method.

Getting Started – Java Toolbox IFC2x3/IFC4 – Version 2.0 2013-05-30 14