IfcDoc User Guide
The IfcDoc tool was developed for buildingSMART International to improve the consistent and computer-interpretable definition of Model View Definitions (MVD) as true subsets of the IFC Specification with enhanced definition of concepts. Development and use of the of the tool is based on the mvdXML specification. The tool and methodology can be applied to all IFC releases, we currently provide the baseline for IFC2x3 and for IFC4.
Further info can be found on the buildingSMART Technical Resources site: https://technical.buildingsmart.org/resources/ifcdoc/
The latest version of the IfcDoc software can be downloaded here.
When you launch the IFCDOC program, the application will initially be empty, appearing as the following.
While it is entirely possible to build all content from scratch, most users will want to start with an existing IFC release and/or model view definitions found here.
To open existing content, click File / Open and choose a file with the ".ifcdoc" extension. The window will then look similar to the following.
To use a specific model view definition (other than one included in the baseline file opened), click File / Import, set the filter to ".mvdxml" and browse for the MVDXML file.
To validate an IFC file against a particular model view, click Tools / Validate, and browse for an ".ifc" file. The user interface will then display a pane on the right side containing object instances within the file matching definitions selected in the tree view. Additionally, a report will be generated in HTML format indicating if the file is valid according to the specified model view, and detailing what passes or fails.
To achieve the fastest possible execution (particularly useful for files containing large buildings in detail), validation works by generating a .NET DLL in the background containing all data definitions and rule logic, for which the Windows operating system then compiles into machine code before executing.
Colors are used to indicate validation status and are indicated at definitions in the tree on the left, instances in the pane on the right, concepts in the diagram view, and parameters in the Concept tab.
Color / Description
- No Color / Test did not apply to the item - either the test is out of scope of the specified exchange, no instances exist of the current type, or a conditional parameter excludes the test.
- Green / Test passes an item and all items within.
- Red / Test fails on one or more items within.
To view validation results for templates overall, select a Concept Template (underneath the fourth section "Fundamental Concepts") to view all tests using a particular template.
To view validation results for a specific object type, select a Concept (underneath an entity within any of the schema sections 5-8).
To generate documentation, click Tools / Generate Documentation, choose any options in the resulting dialog box, and click OK.
One or more publications must be checked -- publications may be defined within the tree view of the main program. Each publication defines the exact configuration for documentation output (aside from environment-specific settings in this dialog box), along with the set of model view definitions to be included.
The complete documentation will be generated within the Output directory specified. Any images referenced within the HTML-based documentation will be copied from the Input directories specified, or else errors will be reported if they cannot be found.
After generating documentation, the default web browser will launch pointed to the starting index page for each generated publication. The generated documentation will appear similar in format to the IFC4 specification referenced here.
The application is divided into two panes: a tree on the left, and a workspace on the right reflecting what is selected in the tree. The tree is organized based on the resulting documentation format (matching structure required of ISO standards), where the top level indicates sections as follows:
- Scope: this is where Model Views and contained exchanges are defined.
- Normative References: for documentation purposes, contains links to other documents
- Terms: for documentation purposes, contains terms and abbreviations for which hyperlinks are automatically generated when in italics.
- Concepts: this is where Concept Template are defined that may be re-used for particular model views.
- Data Schemas (Core, Shared, Domain, Resource): within these four sections is where the schema is defined.
- Computer interpretable listings: Automatically generated XSD, EXPRESS, MVD-XML.
- Alphabetical listings: Automatically generated listings of data types by name.
- Inheritance listings: Automatically generated listings of entities according to inheritance.
- Diagrams: Automatically generated EXPRESS-G and instance diagrams for model views.
- Examples: Sample For documentation purposes, sample files that may be added.
- Change Logs: Comparisons against previous versions for automatically generating logs of changes.
- Publications: Configuration settings for documentation output, along with introductory pages.
The File menu contains commands for opening, saving, importing, exporting, and merging data.
Merge: combines content from another .ifcdoc file, correlating objects according to their unique ID (UUID). A dialog box will be displayed showing merge conflicts to be resolved.
Import files: imports files from various formats (File Type / Description):
- vex / Schemas may be imported from Visual Express, capturing data definitions and diagram layout information. Any existing definitions will be replaced according to their name. Visual Express was used for authoring previous IFC versions; it is no longer required as all schema information may now be edited directly within the IfcDoc tool.
- xsd / Schemas may be imported from XML Schema Definition files, capturing data definitions but no diagram information. This may be useful for documenting external schemas and relating them to IFC or other schemas. XSD schemas may be authored using well-known software development tools such as Microsoft Visual Studio and Eclipse.
- mvdxml / Model View Definitions may be imported, capturing concept templates, model views, exchange requirements, and concept usages. IfcDoc also exports this format with full round-trip capability.
- xml / IFC Property Sets and Quantity Sets may be imported from this format. Custom Excel macros were used for authoring previous IFC versions, which are no longer required as all property sets and quantity sets may now be edited directly within the IfcDoc tool. IfcDoc also exports this format with full round-trip capability. Express XSD Configurations may be imported, which indicate how schema definitions are mapped to XML structures.
- ifc / IFC SPF instance files may be imported, capturing instance content for examples.
- txt / Tab-delimited text files may be imported, capturing translations for definitions in a particular language. IfcDoc also exports this format with full round-trip capability.
- ifd / Imports GUID mappings from the BuildingSmart Data Dictionary.
Patch files: patches existing .vex files by updating descriptions at definitions.
Export file: exports files to various formats, where a dialog may prompt to filter the content to be exported according to a particular model view or language (File Type / Description):
- mvdxml / Model View Definitions may be exported, capturing concept templates, model views, exchange requirements, and concept usages.
- ifc / IFC SPF instance files may be exported, capturing property set and quantity set templates.
- ifcxml / IFC XML instance files may be exported, capturing property set and quantity set templates.
- exp / EXPRESS schema files (ISO 10303-11) may be exported, and filtered according to a particular model view.
- xml / EXPRESS XSD Configurations may be exported, and filtered according to a particular model view.
- xsd / XML schema files may be exported, and filtered according to a particular model view.
- txt / Tab-delimited text files may be exported, capturing translations for definitions in a particular language.
- cs / C# source code may be exported, capturing data definitions in C# source code. Such source is not intended to do anything by itself, but must be integrated with the implementer's source code.
Export folder: exports property sets within a folder as multiple files.
Download: download a file from a URL (HTTP GET).
Upload: publish a file to a URL (HTTP POST).
The Edit menu contains commands for manipulating the object selected in the tree (and if diagram is visible, then also corresponding to object selected in the diagram).
- Cut/copy/paste are available for moving or duplicating certain types of objects.
- Delete may be used to remove an object and clear any dependencies on the object.
- Rename may be used to change the name of an object; for objects requiring unique names (property sets, concept templates, schema definitions, etc.).
- Move Up/Down is available for re-ordering items defined in a particular order such as properties.
- Move In/Out is available for promoting or demoting items in hierarchies such as concept templates and examples.
- Model View Definition becomes available when selecting a Model View. Configure Schema reads an EXPRESS file (exp) and includes any definitions within the model view. Build Concepts generates Concept rules from property sets.
The View menu allows switching among three different view modes within the right pane: Web View, Text View, and Diagram View.
- Web View displays documentation for the selected item as it will appear in a web browser.
- Text View allows editing of documentation in HTML format.
- Diagram View displays a diagram of the current object where applicable: for schema definitions it displays EXPRESS-G diagrams; for model view concept templates it displays instance diagrams; for model view concepts and exchanges it displays requirement tables.
The Insert menu allows new content to be created, typically relative to the selected item in the tree. It is divided into four submenus as follows.
- Documentation: Content only affecting documentation output such as terms, references, and examples
- Schema: Content describing underlying data structures such as entities, enumerations, selects, and defined types added within a schema (sections 5-8).
- User Data: Content describing dynamic data structures such as property sets and quantity sets, added within a Schema (underneath sections 5-8).
- Model Views: Content describing model view definitions such as templates (section 4), model views and exchanges (section 1), and concepts (underneath entities within sections 5-8).
The Diagram menu provides functions for editing diagrams while in Diagram View. Several tool modes are available that impact mouse operations within the diagram.
- Select: allows objects to be selected within the diagram.
- Place: allows objects to be placed, moved, and resized by clicking and dragging.
- Link: allows objects to be connected (such as entities to attributes) by clicking from a source object and dragging to a target object.
In addition to tool modes, several formatting features are available in the Diagram menu.
- Use Tree: organizes (or removes if unchecked) lines originating from the selected object (subtypes of an entity, subtypes of an entity reference, or select items) into a tree hierarchy to achieve a structured layout. The tree may be moved by clicking and dragging the point at the root of the tree.
- Use Page Reference: generates (or removes if unchecked) a page reference label for the selected object and converts all references to the selected object into page references.
- Align: positions the selected objects (2 or more) such that the left, right, top, or bottom edge is aligned at the same position as the last selected object.
- Make Same Size: resizes the selected objects (2 or more) such that the width, height, or both are the same size as the last selected object.
- Space Horizontally: moves the selected objects (3 or more) such that the horizontal spacing between them is made equal, incremented, decremented, or removed.
- Space Vertically: moves the selected objects (3 or more) such that the vertical spacing between them is made equal, incremented, decremented, or removed.
The Tools menu allows content to be generated of various forms.
- Validate File: loads an IFC file, checks it against a specified model view, and generates a report in HTML indicating status of passing or failing.
- Generate Documentation: produces documentation in the form of HTML pages conforming to ISO HTML format.
- Generate Report: produces documentation within a single HTML file conforming to the U.S. National BIM Standard V3.
- Generate Source Code: produces boilerplate software code for C# or Java languages.
- Generate Module: creates a .NET assembly as a .dll file that includes all data definitions within the schema, or filtered and annotated with rules according to a model view.
Authoring Property Sets and Quantity Sets
Property sets refer to extensible data definitions in the IFC specification, where custom setting may be defined on particular objects. To make use of properties, some familiarity with the IFC specification is necessary -- for example, properties attached to a wall are defined for IfcWall (within the IfcSharedBldgElements schema in Section 6). Users of application software must also have understanding of how their software maps vendor-specific definitions into IFC.
Various IFC-compatible software applications may allow use of custom property sets defined in IFC files. Custom property sets may be defined by selecting a Schema and clicking Insert / User Data / Property Set, and then selecting the Property Set and clicking Insert / User Data / Property for each property to be defined. Properties may be edited via clicking Edit / Properties. To use resulting property sets in supporting applications, use File / Export and select ".ifc" as the format to generate an IFC file containing templates for properties. This file may then be loaded into software applications supporting custom IFC properties.
As defined in the IFC specification, there are seven basic types of properties:
- Single Value - a value of a particular data type with optional unit; this is the most commonly used and most widely supported type of property.
- Bounded Value - similar to Single Value but also including a Minimum and Maximum range, which may be useful for defining ranged values such as operating electrical current.
- Enumerated Value - a value which must be set to one of several predefined names.
- List Value - a list of values of a particular data type.
- Table Value - a table of values, where each column defines a particular data type. This may be used to define available product configurations or graphs of engineering data (e.g. efficiency curves for air conditioning at various temperature differentials, etc.)
- Reference Value - a predefined data structure such as a Time Series, which may be used for capturing real time or historical data such as energy usage.
- Complex Value - a combination of any of the above properties into a group. For the widest support of software applications, Single Value is recommended.
Authoring Model Views
Model View Definitions indicate the subset of data structures, attributes, and permitted values (or graphs of values) supported within a particular model view.
Fundamental to creating model views is defining (or using) Concept Templates. A Concept Template indicates a graph of object types that may be referenced at particular data structures. To Create a Concept Template, select a parent template in the tree view (if any), and click Insert > Model View > Concept Template.
To indicate the root data definition for which the template applies, switch to the Template tab and click the + button to select the definition. To add or remove attribute rules or entity rules, select the nodes in the Template tab tree and click + or - buttons. Alternatively, definitions may be added by double-clicking on attributes in the diagram. To link an entity rule to another template, click the arrow button -- this will then pull in rules indicated at the referenced template.
To define constraints on values, switch to the Operations tab. To add or remove constraints, click + or - buttons. Constraints may support various operations (equal, comparison, inclusion). Logic may be nested using Move In or Move Out buttons, where parent nodes may support AND, OR, or XOR behavior.
Note that defining a template by itself does not impose any requirements for a model view; a model view must specifically reference a template at one or more entities.
To define a Model View, click Insert > Model View > View. Optionally, define Exchange Requirements within a Model View. Exchange requirements essentially allow more specific subsets of information to be defined where what is required or optional may be made more granular. The scope of what model views and exchanges may encompass is entirely up to the usage. They may be very general, such as "Coordination" model view with "Early Design", or they may be very specific, such as "Electrical" model view with "Load Letter for Utility" as an Exchange Requirement. Ultimately, an Exchange Requirement describes a set of information that would be demanded for a particular use, and could be referenced within a contract.
Once a Model View is defined and Templates are defined, then entities may be referenced within the model view. To link an entity to a model view, select the Model View in the tree, click Insert > Model View Definition > Entity Usage, and select the corresponding entity. Within this entity usage, specific data requirements may be defined, including attributes, properties, quantities, and mappings. To add requirements for attributes, click Insert > Model View Definition > Attribute Usage and select the corresponding Concept Template. Other commands for properties, quantities, and mappings accomplish the same as Attribute Usage, but provide shortcuts for automatically populating specific templates.
The Mapping Usage command may be used to describe how data definitions (e.g. IFC) may be mapped to other schemas or tabular formats (e.g. a COBie spreadsheet). With such information defined, documentation produced will show such mappings in a formatted table, along with examples formatted according to the fields indicated.
If the template supports parameters to customize it, such parameters may be edited within the grid. For example, a template indicating required ports on a particular type of object may support entries for each port, indication of the system type, and flow direction. Similar may be done for properties, materials, geometry, or any other repetitive construct.
Upon editing parameters, rows may be inserted or removed. The ordering of rows impacts presentation in documentation, and possibly in software applications that generate user interfaces based on the rows, but does not impact validation logic. For a file to conform to the specified parameters, all rows must validate (treated as AND logic).
The Change Template button (the arrow) allows transforming the concept to use a different template.
The Concept Inheritance drop-down button (the colored circle) allows inheriting, overriding, or suppressing the concept -- for example, extruded geometry defined at IfcFlowFitting would be inherited at IfcPipeSegment, while B-Rep geometry defined at IfcBeam would be suppressed at IfcBeamStandardCase.
Use the Requirements tab to indicate whether the particular concept is required or optional on the entity for a particular exchange.
Schemas may be edited while defining graphical layouts within an EXPRESS-G diagram or simply as definitions without defining diagram placement. While the resulting data definitions may be represented as XML Schema Definition (XSD), C#, or Java, the originating format is based on a neutral representation that aligns with EXPRESS (ISO 10303-11) and EXPRESS-G graphical notation. Full familiarity with IFC is recommended for creating definitions consistent with IFC design patterns.
To add definitions within a diagram, select a schema (creating if necessary) within sections 5-8, set the View mode to Diagram, and under the Diagram menu, click Move tool, then click anywhere within the diagram to establish a placement point (shown as red plus), then click Insert / Schema definition, and choose an item from within. A block will be constructed at the insertion point.
The following items may be inserted.
- Primitive: a reference to a built-in data type, which may be BOOLEAN, LOGICAL, INTEGER, REAL, NUMBER, STRING, or BINARY.
- Enumeration: a data type limited to one of multiple values identified by unique name. Each value may be inserted underneath the Enumeration in the tree view.
- Defined: a reference to another data type (such as a primitive) with additional constraints defined (e.g. length, collection, value constraints). For example, IfcLabel is defined as a STRING limited to 255 characters, whereas IfcText has no such restriction. A Defined definition is similar to a "struct" in C# of one element and a "typedef" in C++.
- Select: similar to Defined but supports one of multiple definitions (commonly Entities). A Select is also similar in concept to the "interface" definition in C#, C++, and Java.
- Entity: a data type containing attributes, where each attribute may be defined as a single value or collection of entities or any of the above types. Entities support multiple inheritance from other entities, however IFC only uses single inheritance.
- Reference: a reference to a data type from another schema, which may be any of the above types.
- Comment: a freeform comment placed within the diagram for annotation purposes.
Blocks may be moved when the diagram is set to Place mode by clicking and dragging within the border of the block; new pages within the diagram may be created by dragging to the right or down. Blocks may be resized by clicking along the border of the selected object and dragging.
Entity attributes, Select items, Defined items, and Subtypes may be defined when the diagram is set to Link mode by clicking and dragging from a parent definition onto a child definition. To indicate a subtype relationship between two entities (as opposed to an attribute), click and drag from the edge of the entity. Alternatively, attributes may be inserted from the menu, where the diagram will be automatically updated to include references to any dependencies.
Select items and subtypes may be organized into trees for better organization by selecting the outer item (supertype entity or select), and checking Diagram / Format Tree (unchecking to revert). Trees may be repositioned along one axis by clicking and dragging.
Definitions may be split across pages using page references by selecting the target definition and checking Diagram / Format Page Link (unchecking to revert).
Definitions may be formatted to align with others, match size, or distribute placement by selecting multiple items when the diagram is set to Move mode. Multiple items may be selected by either clicking and dragging within the background to form a selection box including all intersecting items, or by holding down the Control key while clicking items with the mouse. The last item selected is considered the "primary selection", appearing different from others, and is used as the target item when using formatting comments.