Text editor IFC authoring [1/3] : the basics

You may have heard, or been explicitly told, that IFC files should not be edited in text format. By the end of this blog, I hope to convince you otherwise.

The IFC (Industry Foundation Classes) format is an ISO standard (16739) designed to provide a common, open data model for the digital representation of buildings and infrastructure. This model is intended to be understandable by both machines and humans. It can be serialized (written) in various ways, including the STEP format (ISO 10303-21), which is simply a text file. With basic understanding of the fundamentals of the schema, this file extension is compact and can be easily readable and is the most widely exchanged.

By the end of this blog series, you will know how to "write" an IFC model using any text editor, relying on the officia IFC 4 ADD2 TC1 standard documentation.

We will briefly cover the following topics, and much more:

• Project definition
• Unit specification
• Definition of spatial hierarchy (site, building, levels, etc.)
• Creating 3D geometry
• Spatial containment
• Material assignment
• Data specification (properties, quantities, classifications)

An IFC model is made out of entities. An IFC entity is the most basic component, making it the lowest level information container. An entity can represent an element (physical or virtual), a relation, an abstract component or any other concept within an IFC model. There are 776 entities in the IFC4 schema (list), some of which are purely conceptual, like IfcRoot.

In an STEP file, each line represents an entity, beginning with # and ending with a semicolon ;

#id = entity(attr1; ?attr2;attr3; ….);

id: Unique number for each line (i.e., IFC entity); entity numbering can be discontinuous and unordered.

Attributes may be:

• **Explicit **: text (e.g., "Description"), numeric (e.g., 0.54), ...
• **Another entity **: (e.g., #34)
• **Derived **: from a predefined formula: *
• **List **: containing multiple values (value_1, value_2, …), or entities

An attribute can also be optional, that we will denote ?+attribute_name. If an optional value is undefined, the dollar sign $ is used.

IFC entities with unique semantic meanings (elements, relationships, etc.) have a GlobalId attribute, a 22-character unique identifier, allowing an entity to be tracked throughout the life cycle of an IFC model.

Before diving into writing IFC entities, in a blank text file, we will start by defining a header containing file metadata (name, date, originating software, etc.).

The rules for populating header information are outlined in the Implementation Guide for Header Data.

ISO-10303-21;
HEADER;
FILE_DESCRIPTION((),'2;1');
FILE_NAME('Demo_project[1].ifc','2024-12-29T14:57:05+02:00',(),(),'NOTEPAD','NOTEPAD',$);
FILE_SCHEMA(('IFC4'));
ENDSEC;
DATA;

#1 =();
...

ENDSEC;
END-ISO-10303-21;

As a starting point of our model, the entity IfcProject has the following attributes :

IFCPROJECT ( 
GlobalId,
?OwnerHistory,
?Name,
?Description,
?ObjectType,
?LongName,
?Phase,
?RepresentationContexts,
?UnitsInContext
)

GlobalId: Unique global identifier := '0kzsDsvILDb85OYhywTwjS'

?OwnerHistory: May capture creator history and origin (application) := $

?Name: Short name := '001'

?Description: Provides additional information about the entity := 'Demo project'

?ObjectType: Optional type := $

?LongName: Extended name for better context := 'Project 001'

?Phase: Current project phase := $

?RepresentationContexts: List of contexts (i.e., views) of the project

?UnitsInContext: Defines units used in the project

We define our project by adding the following line to our file.

/* PROJECT */
#1=IFCPROJECT('0kzsDsvILDb85OYhywTwjS',$,'001','Demo project',$,'Projet 001',$,(#6),#5);

It is essential to define the project units beforehand. Standard international system units can be specified with IfcSIUnit.

IFCSIUNIT ( Dimensions, UnitType, ?Prefix, Name)

Dimensions : * (derived attribute)

UnitType : Selected from the list of unit types defined by IfcUnitEnum

Name : Selected from SI units defined by IfcSIUnitName

We can then list the units used by adding the following lines.

/* UNITS */
#2=IFCSIUNIT(*,.LENGTHUNIT.,$,.METRE.);
#3=IFCSIUNIT(*,.AREAUNIT.,$,.SQUARE_METRE.);
#4=IFCSIUNIT(*,.VOLUMEUNIT.,$,.CUBIC_METRE.);

We then effectively assign the units (maximum one per type) to our project, the order is not critical.

#5=IFCUNITASSIGNMENT((#2,#3,#4));

IfcGeometricRepresentationContext defines the entry point to the views of the IFC model. It lays out the global context, attaching a coordinate system to it. Each IFC model requires at least one instance of IfcGeometricRepresentationContext defining the model's 3D view.

IFCGEOMETRICREPRESENTATIONCONTEXT(
?ContextIdentifier,
?ContextType,
CoordinateSpaceDimension,
?Precision,
WorldCoordinateSystem,
?TrueNorth
)

?ContextIdentifier: Optional identifier for the project's representation context, following the implementation agreement := $

?ContextType: Optional context type identifier, following implementation agreement := 'Model'

CoordinateSpaceDimension: Space dimensionality :=* 3*

?Precision: Modeling precision := 1.E-05

WorldCoordinateSystem: Coordinate system origin used by the representation context

?TrueNorth: Geographic north direction as an IFCDIRECTION [2D], default (0., 1.) if unspecified := $

IfcGeometricRepresentationSubContext allows finer granularity in view configuration (scale, 2D/3D, etc.) for specific object representations (e.g., wireframe, elevation, 2D plan view).

IFCGEOMETRICREPRESENTATIONSUBCONTEXT(
?ContextIdentifier,
?ContextType,
CoordinateSpaceDimension,
Precision,
WorldCoordinateSystem,
TrueNorth ,
ParentContext,
?TargetScale,
TargetView,
?UserDefinedTargetView
)

?ContextIdentifier := 'body'

?ContextType := 'Model'

CoordinateSpaceDimension := * derived from* *ParentContext

Precision := * *derived from *ParentContext

WorldCoordinateSystem := * derived from* *ParentContext

TrueNorth := * derived from ParentContext

ParentContext : Parent context

?TargetScale : Scale := $ (1:1 by default)

TargetView** **: Target view type for applicable representations, from IfcGeometricProjectionEnum := .MODEL_VIEW.

?UserDefinedTargetView: Custom type if ?TargetView = .USERDEFINED. := $

/* REPRESENSATION CONTEXTS */
#6=IFCGEOMETRICREPRESENTATIONCONTEXT($,'Model',3,1.E-05,#11,$);
#7=IFCGEOMETRICREPRESENTATIONSUBCONTEXT('Body','Model',*,*,*,*,#6,$,.MODEL_VIEW.,$);

In IFC, an element's position can be:

• Absolute, in the global project coordinate system
• Relative, to another element

The IfcAxis2Placement3D entity describes a position and orientation in 3D space.

IFCAXISTOPLACEMENT3D(Location, ?Axis, ?RefDirection)
IFCCARTESIANPOINT ((x))[1D] | ((x,y))[2D] | ((x,y,z)) [3D]
IFCDIRECTION ((x,y))[2D] | ((x,y,z)) [3D]

Location : Symbolic geometric position as a 3D point with coordinates (X, Y, Z) of type IfcCartesianPoint

Axis : Local Z axis, implicitly (0., 0., 1.) if unspecified ($), as a vector of type IfcDirection

RefDirection : Local X axis, implicitly (1., 0., 0.) if unspecified ($), as a vector of type IfcDirection

The third (Y) axis is implicitly derived.

By adding the following lines, we define the origin of the coordinates system used by the global representation context (attribute WorldCoordinateSystem of entity #6 := #11).

/* GLOBAL PALCEMENT COORDINATES */
#8=IFCCARTESIANPOINT((0.,0.,0.));
#9=IFCDIRECTION((0.,0.,1.));
#10=IFCDIRECTION((1.,0.,0.));
#11=IFCAXIS2PLACEMENT3D(#8,#9,#10);

The IfcLocalPlacement entity defines an element's local position in the global project coordinate system or relative to another element's local placement.

IFCLOCALPLACEMENT(?PlacementRelTo, RelativePlacement)

?PlacementRelTo : Host element frame of type IfcLocalPlacement, defaults to the project global coordinate system if unspecified ($)

RelativePlacement : Relative positioning of type IfcAxis2Placement3D

The graph below illustrates the relation with the previously defined entities to describe the location of an element.

IFC uses a conceptual decomposition to organize objects within a spatial hierarchy: Project** > Site(s) > Building(s) > **Level(s) > Space(s)

A site is represented through an instance of the entity IfcSite, having the following definition:

IFCSITE(
 GlobalId,
 ?OwnerHistory,
 ?Name,
 ?Description,
 ?ObjectType,
 ?ObjectPlacement,
 ?Representation,
 ?LongName,
 ?CompositionType,
 ?RefLatitude,
 ?RefLongitude,
 ?RefElevation,
 ?LandTitleNumber,
 ?SiteAddress)

… see previous definitions

?ObjectPlacement: Placement of the element in space

?Representation: Defines the geometry associated with an element

?CompositionType: Indicates if the element is simple (default), complex, or part of another element

?RefLatitude: Reference point latitude in WGS84 (GPS)

?RefLongitude: Reference point longitude in WGS84 (GPS)

?RefElevation: Reference point altitude relative to sea level

?LandTitleNumber: Parcel number

?SiteAddress : Postal address

/* SITE */
#12=IFCSITE('3APD6n_1v8iOZcZAM$f460',$,'DEMO SITE',$,$,#17,$,$,$,$,$,$,$,$);

/* SITE PLACEMENT */
#13=IFCCARTESIANPOINT((0.,0.,0.));
#14=IFCDIRECTION((0.,0.,1.));
#15=IFCDIRECTION((1.,0.,0.));
#16=IFCAXIS2PLACEMENT3D(#13,#14,#15);
#17=IFCLOCALPLACEMENT($,#16);

… See previous definitions

?ElevationOfRefHeight** **: Altitude of the building's "zero" level

?ElevationOfTerrain** **: Ground level altitude around the building

?BuildingAddress** **: Building's postal address

A building, or a building part, can be represented through an instance of the entity IfcBuilding, having the following definition:

IFCBUILDING(
 GlobalId,
 ?OwnerHistory,
 ?Name,
 ?Description,
 ?ObjectType,
 ?ObjectPlacement,
 ?Representation,
 ?LongName,
 ?CompositionType,
 ?ElevationOfRefHeight,
 ?ElevationOfTerrain,
 ?BuildingAddress
 )

… See previous definitions

?ElevationOfRefHeight** **: Building's "zero" level altitude

?ElevationOfTerrain** **: Ground level altitude around the building

?BuildingAddress** **: Building's postal address

/* BUILDING */
#18=IFCBUILDING('3Os7V4COj8F8hPG9h1Qas0',$,'DEMO BUILDING',$,$,#23,$,$,$,$,$,$);

/* BUILDING PLACEMENT */
#19=IFCCARTESIANPOINT((0.,0.,0.));
#20=IFCDIRECTION((0.,0.,1.));
#21=IFCDIRECTION((1.,0.,0.));
#22=IFCAXIS2PLACEMENT3D(#19,#20,#21);
#23=IFCLOCALPLACEMENT(#17,#22);

A building storey is defined with the entity IfcBuildingStorey, having the following definition :

IFCBUILDINGSTOREY(
 GlobalId,
 ?OwnerHistory,
 ?Name,
 ?Description,
 ?ObjectType,
 ?ObjectPlacement,
 ?Representation,
 ?LongName,
 ?CompositionType,
 ?Elevation
 )

… See previous definitions

?Elevation** **: Level altitude

/* BUILDING STOREY 0 */
#24=IFCBUILDINGSTOREY('0JWsMvgRX5dwpWREHcfkr3',$,'Storey_0',$,$,#29,$,$,$,$);

/* Storey_0 PLACEMENT */
#25=IFCCARTESIANPOINT((0.,0.,0.));
#26=IFCDIRECTION((0.,0.,1.));
#27=IFCDIRECTION((1.,0.,0.));
#28=IFCAXIS2PLACEMENT3D(#25,#26,#27);
#29=IFCLOCALPLACEMENT(#23,#28);

/* BUILDING SOTREY 1 */
#30=IFCBUILDINGSTOREY('0JWsMvgRX5dNBDREHcfUi$',$,'Storey_1',$,$,#35,$,$,$,$);

/* Storey_1 PLACEMENT */
#31=IFCCARTESIANPOINT((0.,0.,3.));
#32=IFCDIRECTION((0.,0.,1.));
#33=IFCDIRECTION((1.,0.,0.));
#34=IFCAXIS2PLACEMENT3D(#31,#32,#33);
#35=IFCLOCALPLACEMENT(#23,#34);

Spaces in IFC are represented through the IfcSpace entity. For our this demonstration no spaces will be used, see documentation for further details.

The ** **IfcRelAggregates entity is the relationship through which a physical or virtual element can be broken down to other elements. For example, a project is composed of one or more sites, a site is composed of one or more buildings, and so on.

IFCRELAGGREGATES(
 GlobalId,
 ?OwnerHistory,
 ?Name,
 ?Description,
 RelatingObject,
 RelatedObjects
)

… See previous definitions

RelatingObject : Composed element

RelatedObjects : List of composing elements

/* PROJECT => SITE */
#36=IFCRELAGGREGATES('1AT1M9v3T9PwTZRpjoKwki',$,$,$,#1,(#12));

/* SITE => BUILDING */
#37=IFCRELAGGREGATES('2H53DqIErDouOZBg0eoE5I',$,$,$,#12,(#18));

/* BUILDING => STOREY BUILDING */
#38=IFCRELAGGREGATES('0Eil2cDAHAgBBTLQzvjwHO',$,$,$,#18,(#24,#30));

So far, the file contains an IFC model with a spatial hierarchy. To be able to open it with an IFC viewer, save the text file under a .ifc extension instead of .txt.

If you've followed along, you should obtain an identical file to the one attached.

In the second part of this blog series, we will be creating a wall and getting into the details of defining an IFC geometry.