Glassvision/IfcOpenShell
1
0
Fork 0
mirror of https://github.com/IfcOpenShell/IfcOpenShell.git synced 2026-08-09 17:31:45 +00:00
Code Issues Packages Projects Releases Wiki Activity

New introduction section in IOS docs

Browse Source
This commit is contained in:
Dion Moult
2023-09-27 18:21:20 +10:00
parent c1bedec354
commit 986ffe66f8
16 changed files with 373 additions and 252 deletions
Download Patch File Download Diff File Expand all files Collapse all files
src/ifcopenshell-python/docs/conf.py
+1 -1
View File
@@ -36,7 +36,7 @@ sys.path.insert(0, os.path.abspath('..'))
# -- Project information -----------------------------------------------------
project = "IfcOpenShell"
copyright = "2020-2022, IfcOpenShell Contributors"
copyright = "2011-2023, IfcOpenShell Contributors"
author = "IfcOpenShell Contributors"
# The full version, including alpha/beta/rc tags
src/ifcopenshell-python/docs/ifcopenshell-python.rst
+2 -1
View File
@@ -2,7 +2,8 @@ IfcOpenShell-Python
===================
IfcOpenShell-Python provides Python bindings to the core IfcOpenShell C++
system, as well as high level analysis and authoring functions.
system, as well as high level analysis and authoring functions. All the
capabilities of the C++ core are available in Python.
.. toctree::
:hidden:
src/ifcopenshell-python/docs/ifcopenshell-python/hello_world.rst
-222
View File
@@ -1,228 +1,6 @@
Hello, world!
=============
What's inside an IFC?
---------------------
An IFC model is a collection of elements (e.g. doors, windows, construction
tasks, materials, etc) with relationships to other elements in a graph-like
database. Together, these elements and their relationships describe the digital
built environment.
.. image:: images/ifc-graph.svg
Each element has a type known as an **IFC Class**. These classes define the
attributes that the element may store. For example, the **IfcWall Class** is
allowed to store a **Name** and **Description** attribute.
This IFC database can be stored in many formats. The most common is the ``.ifc``
format, which stores data in plain text. If you open a ``.ifc`` file in a text
editor, you'll see something like this:
::
#1=IFCPROJECT('3Cbhu4euf1hfgM_SHZbeqM',$,'My Project',$,$,$,$,$,#4);
#2=IFCSIUNIT(*,.LENGTHUNIT.,.MILLI.,.METRE.);
#3=IFCSIUNIT(*,.AREAUNIT.,$,.SQUARE_METRE.);
#4=IFCUNITASSIGNMENT((#2,#3));
#5=IFCCARTESIANPOINT((0.,0.,0.));
In this example there are 5 elements in the graph. The element with the ID of
**#1** has an **IFC Class** of **IfcProject**. This element has 9
comma-separated attributes. IFC defines how many attributes each **IFC Class**
is allowed to have, attribute names, the order of attributes, data type,
optional or mandatory status (i.e. cardinality), and more.
::
IFC Class Quoted string value Null value ID reference
↓ ↓ ↓ ↓
#1=IFCPROJECT('3Cbhu4euf1hfgM_SHZbeqM',$,'My Project',$,$,$,$,$,#4);
↑ ↑
Element ID Comma-separated list of attributes
By selecting elements by their **IFC Class**, and reading their attributes, you
can navigate from one element to another. The relationships between elements are
called **IFC Concepts** and create meaning in our industry. For example, if a
**IfcWall** element has an attribute that references an **IfcBuildingStorey**
element in a particular way, it will mean that the wall is located in the
ground floor of the building.
.. image:: images/ifc-concepts.svg
The official IFC documentation describes hundreds of **IFC Classes**, ranging
from walls, door, to tasks, cost items, parametric materials, and structural
analysis constraints. There are also hundreds of **IFC Concepts**, which may
describe how a wall is in a storey, a construction task might occur one after
another, or how an surface bounds a space for energy analysis.
It takes time to learn the many **IFC Classes** and **IFC Concepts** available.
Once you do, you will be able to richly describe our built environment
digitally. IfcOpenShell can help you navigate these IFC elements, read their
attributes, and explore relationships. Your journey begins here.
.. seealso::
If you are already familiar with IFC and just want to learn how to use
IfcOpenShell, you can jump to the `Core functionality crash course`_.
Begin learning IFC
------------------
IFC has three versions published by ISO: **IFC2X3** from 2007, **IFC4** from
2017, and **IFC4X3** in draft form. Each version improves on the previous
version, and will have different **IFC Classes** with different attributes and
different **IFC Concepts**.
You can access the official documentation here:
- `Official IFC2X3 documentation homepage <https://standards.buildingsmart.org/IFC/RELEASE/IFC2x3/TC1/HTML/>`__
- `Official IFC4 documentation homepage <https://standards.buildingsmart.org/IFC/RELEASE/IFC4/ADD2_TC1/HTML/>`__
- `Official IFC4X3 documentation homepage <http://ifc43-docs.standards.buildingsmart.org/>`__
- `List of all IFC2X3 classes <https://standards.buildingsmart.org/IFC/RELEASE/IFC2x3/TC1/HTML/alphabeticalorder_entities.htm>`__
- `List of all IFC4 classes <https://standards.buildingsmart.org/IFC/RELEASE/IFC4/ADD2_TC1/HTML/link/inheritance-general-usage-all%20entities.htm>`__
- `List of all IFC4X3 classes <https://ifc43-docs.standards.buildingsmart.org/IFC/RELEASE/IFC4x3/HTML/annex-c.html>`__
.. tip::
It is recommended to use IFC4. However, the IFC4X3 documentation is a lot
more friendly to newcomers.
The official ISO documentation is written for a technical audience and may be
overwhelming. This guide will take you slowly through the core concepts, and
leave you with the knowledge you need to discover more.
Before digging into theory, let's explore an existing IFC model. You can
download this sample IFC for this guide.
.. container:: blockbutton
`Download sample IFC <https://www.ifcwiki.org/images/e/e3/AC20-FZK-Haus.ifc>`__
If you open up the model with a text editor, you will see text similar to this:
::
ISO-10303-21;
HEADER;FILE_DESCRIPTION(('ViewDefinition [, QuantityTakeOffAddOnView, SpaceBoundary2ndLevelAddOnView]'),'2;1');
FILE_NAME('AC20-FZK-Haus.ifc','2016-12-21T17:54:06',('Architect'),(''),'','','');
FILE_SCHEMA(('IFC4'));
ENDSEC;
DATA;
#3= IFCORGANIZATION($,'Nicht definiert',$,$,$);
#12= IFCOWNERHISTORY(#7,#11,$,.ADDED.,$,$,$,1482339244);
#13= IFCSIUNIT(*,.LENGTHUNIT.,$,.METRE.);
#14= IFCSIUNIT(*,.AREAUNIT.,$,.SQUARE_METRE.);
...
#62= IFCGEOMETRICREPRESENTATIONCONTEXT($,'Model',3,1.00000000000E-5,#59,#60);
#66= IFCPROJECT('0lY6P5Ur90TAQnnnI6wtnb',#12,'Projekt-FZK-Haus','Projekt FZK-House create by KHH Forschuungszentrum Karlsruhe',$,$,$,(#62,#374),#49);
#77= IFCPROPERTYSINGLEVALUE('GS_TimeStamp',$,IFCTIMESTAMP(9685146),$);
#85= IFCPROPERTYSET('1mnk_H9cG6eU2r9ped0WRu',#12,'GSPset_TimeStamp',$,(#77));
...
#15033= IFCSHAPEREPRESENTATION(#15026,'Axis','Curve2D',(#15031));
#15037= IFCPRODUCTDEFINITIONSHAPE($,$,(#15016,#15024,#15033));
#15042= IFCWALLSTANDARDCASE('2XPyKWY018sA1ygZKgQPtU',#12,'Wand-Int-ERDG-4',$,$,#14983,#15037,'BC6F0F70-6195-495E-A2-FC-239713029DB1',$);
#15046= IFCMATERIAL('Leichtbeton 102890359',$,$);
...
#15231= IFCRELDEFINESBYPROPERTIES('3Q0nMR5elnJFWzAhgkZqe1',#12,$,$,(#15042),#15229);
#15234= IFCWALLTYPE('2AEMyYvIjlsz7LRzqYHy64',#12,'Leichtbeton 102890359 240',$,$,$,(#15244,#15248,#15250,#17288,#17290,#17292,#18637,#18639,#18641,#19015,#19017,#19019,#20770,#20772,#20774),'8A396F22-E52B-6FDB-D1D5-6FDD2247C184',$,.NOTDEFINED.);
#15237= IFCDIRECTION((1.,0.,0.));
#15239= IFCDIRECTION((0.,0.,1.));
... etc
The first thing you should notice is the line that defines that this is an
**IFC4** version. This determines what **IFC Classes** and **IFC Concepts** are
available.
::
FILE_SCHEMA(('IFC4'));
You'll notice certain **IFC Class** keywords jump out at you: things like
**IFCSIUNIT** which defines the length unit of metres, or **IFCPROJECT** which
defines the project, or **IFCPROPERTYSINGLEVALUE** which defines a property of
something, or **IFCWALLSTANDARDCASE** which defines a wall, or **IFCMATERIAL**
which defines a material, and so on.
Let's see how to fetch this data with code. Let's start with loading the model.
Import the IfcOpenShell module, then use the ``open`` function to load the
model into a variable called ``model``. The first piece of information we want
to check is what IFC schema version we are using. We assume the model you are
learning with is IFC4. We'll then fetch all entities that use the **IfcSlab**
class.
.. code-block:: python
import ifcopenshell
model = ifcopenshell.open('/path/to/your/model.ifc')
print(model.schema) # May return IFC2X3, IFC4, or IFC4X3.
print(model.by_type("IfcSlab")) # Will return a list of IFCSLAB entities, like below:
# [
# #34509=IfcSlab('1pPHnf7cXCpPsNEnQf8_6B',#12,'Bodenplatte',$,$,#34464,#34505,'E4D9CD4B-CA43-4735-94-BD-1FD4376BD455',.BASESLAB.),
# #59290=IfcSlab('2RGlQk4xH47RHK93zcTzUL',#12,'Slab-033',$,$,#59253,#59286,'DA0A17AC-B773-47AC-99-C5-D390C73AD5CC',.FLOOR.),
# #59553=IfcSlab('07Enbsqm9C7AQC9iyBwfSD',#12,'Dach-1',$,$,#59508,#59549,'E142B455-80E4-4B96-83-EC-E1589CA998DB',.ROOF.),
# #59753=IfcSlab('2IxUUNUVPB6Ob$eicCfP2N',#12,'Dach-2',$,$,#59716,#59749,'BD6D9414-37DF-40A8-88-40-301A32A9A5B5',.ROOF.)
# ]
.. tip::
Try changing ``model.by_type("IfcSlab")`` to fetch different types of
entities based on their **IFC Class**.
An overview of all IFC classes
------------------------------
There are hundreds of **IFC Classes**. You don't need to know them all, but
we'll help describe the general breakdown so you know where to find the
appropriate class for what you're after.
**IFC Classes** are defined using an **Object Oriented** tree hierarchy. Child
**IFC Classes** inherit the attributes defined by the parent **IFC Class**.
This means that **IFC Classes** with common attributes are grouped together in
the tree.
For example, because all **IfcObject** classes can have a **GlobalId**
attribute, that means that because **IfcWall** is a subtype of **IfcObject**,
it can also have a **GlobalId** attribute.
.. image:: images/ifc-tree.svg
Important IFC concepts
----------------------
There are hundreds of **IFC Concepts** that allow you to describe relationships
between **IFC Classes**. In this guide, we'll focus on the five most common
**IFC Concepts** to get you started.
Concept 1: the project context
------------------------------
Concept 2: spatial decomposition
--------------------------------
Concept 3: object typing
------------------------
Concept 4: attributes and property sets
---------------------------------------
Concept 5: material assignment
------------------------------
Self-learning IFC: how to learn more
------------------------------------
Core functionality crash course
-------------------------------
If you're reading this, we assume you already know IFC and just want to quickly
get started with IfcOpenShell.
src/ifcopenshell-python/docs/ifcopenshell.rst
+13 -13
View File
@@ -1,12 +1,19 @@
IfcOpenShell
============
IfcOpenShell is an open source (LGPL-3.0-or-later) software library for working
with the Industry Foundation Classes (IFC) file format. Extensive geometric
support is implemented for the IFC releases IFC2x3 TC1 and IFC4 Add2 TC1.
Support for parsing is provided for IFC4x1, IFC4x2, and the IFC4x3 release
candidates. Extending with support for arbitrary IFC schemas is possible at
compile-time when using C++ and at run-time when using Python.
IfcOpenShell is an open source (LGPL-3.0-or-later) C++ software library for
working with the Industry Foundation Classes (IFC) file format.
Extensive geometric support is implemented for the IFC releases IFC2x3 TC1 and
IFC4 Add2 TC1. Support for parsing is provided for IFC4x1, IFC4x2, and the
IFC4x3 release candidates. Extending with support for arbitrary IFC schemas is
possible at compile-time when using C++ and at run-time when using Python.
.. seealso::
It is not necessary to be a C++ developer to use IfcOpenShell. Please see
other sections such as :doc:`ifcopenshell-python`, :doc:`ifcconvert`, and
more.
.. toctree::
:hidden:
@@ -17,10 +24,3 @@ compile-time when using C++ and at run-time when using Python.
ifcopenshell/geometry_iterator
ifcopenshell/geometry_settings
ifcopenshell/boolean_process
Indices and tables
------------------
* :ref:`genindex`
* :ref:`modindex`
* :ref:`search`
src/ifcopenshell-python/docs/ifcopenshell/images/intro.png
BIN
View File
Binary file not shown.
Side by Side

After

Width:  |  Height:  |  Size: 132 KiB

src/ifcopenshell-python/docs/index.rst
+5 -15
View File
@@ -1,17 +1,14 @@
Let's learn IfcOpenShell
========================
Let's learn IfcOpenShell!
=========================
IfcOpenShell is a suite of developer libraries and utilities to manipulate OpenBIM data.
.. note::
This documentation is incomplete. Would you like to help write more? `Get in touch! <https://osarch.org/chat/>`__
.. image:: ifcopenshell/images/intro.png
.. toctree::
:hidden:
:maxdepth: 1
:caption: Main:
introduction
ifcopenshell
ifcopenshell-python
ifcconvert
@@ -47,11 +44,4 @@ IfcOpenShell is a suite of developer libraries and utilities to manipulate OpenB
C++ API Reference <https://ifcopenshell.github.io/docs/rst_files/library_root.html>
Python API Reference <autoapi/index>
Indices and tables
==================
* :ref:`genindex`
* :ref:`modindex`
* :ref:`search`
indices
src/ifcopenshell-python/docs/indices.rst
+6
View File
@@ -0,0 +1,6 @@
Indices and tables
==================
* :ref:`genindex`
* :ref:`modindex`
* :ref:`search`
src/ifcopenshell-python/docs/introduction.rst
+89
View File
@@ -0,0 +1,89 @@
Introduction
============
**IfcOpenShell** is an open source software library for software developers and BIM powerusers working with Industry Foundation Classes (`IFC <https://technical.buildingsmart.org/standards/ifc/>`_).
In addition to a C++ and Python API, **IfcOpenShell** comes with an ecosystem of tools, notably including **IfcConvert** (an application to convert IFC models to other formats), the **BlenderBIM Add-on** (an add-on to Blender providing a graphical IFC authoring platform), and many other libraries, CLI apps, and more. Support is also provided for auxiliary standards such as BCF, bSDD, and IDS.
Things you can do
-----------------
**IfcOpenShell** is designed to be a complete BIM authoring platform. Its
capabilities have a similar scope to other BIM libraries, modeling platforms,
costing programs, scheduling software, CAD packages, and simulation software.
It is too numerous to list in full, but an example of what is possible include:
- Viewing models, including spaces, properties, and relationships
- Edit and extract attributes and properties
- Moving objects, and changing their geometry
- Create new objects using library elements
- Manage classification systems, document and library references
- Generating 2D drawings, schedules, and creating sheets
- Investigating and editing structural analysis models
- Connecting and managing distribution systems and ports
- Creating construction schedules, critical path analysis, and generating sequence animations
- Creating cost schedules, using formulas, and deriving quantities from model elements
- Clash detection and managing issues for model coordination
... and much, much more.
What makes IfcOpenShell special?
--------------------------------
IfcOpenShell has a huge amount of unique features and capabilities not found in any other technology.
- IfcOpenShell is the oldest and most mature open source IFC library available. It's developed since 2011 by a community of hundreds of developers and trusted to deliver many AEC technologies that power our industry. IfcOpenShell is also taught in numerous universities and cited in hundreds of academic publications.
- Lots of platforms and package management options are available: Windows, Mac, Mac ARM (M1, M2), Linux, Web Assembly (WASM), Docker, AWS Lambda, Google Colab, and more.
- Develop in C++, Python, or JavaScript via Pyodide.
- All tools can be used either as a developer library, through a command line interface, or using a rich graphical interface. Whether you're deploy headless server tools for your own pipeline, writing your own apps, or an end-user, there's something for you.
- Supports IFC2X3, IFC4, and IFC4.3. Custom schemas (such as experimental or draft schemas) may be loaded at run-time instead of having to recompile.
- Built-in IFC validation is possible from basic syntax validation to more detailed "Where Rule" checks. This is the same validation that powers the official buildingSMART validation engine.
- Read and write IFC-SPF, IFCJSON, IFCXML, IFCHDF5, MySQL, and SQLite.
- High level API for hundreds of tasks. Perform complex authoring like copying objects, cost calculation, or 4D simulation with one line of code. Imagine a complete native IFC authoring and editing platform where every function is available to you as a library.
- Convert parametric geometry into explicit geometry for any CAD system from booleans to complex sweeps. Geometry has been battle-tested over many years to accommodate complex geometric edge cases with an extensive test suite.
- Geometry may be converted into voxels and analysed through voxels to resolve complex non-manifold geometry and precision issues. This analysis may be used from things like head height calculations, formwork analysis, to egress distances.
- Generate and annotate 2D drawings from 3D geometry with ease. Preserve drawing semantics and link model data to and from drawing symbols. Drawings may be richly annotated with text, line styles, hatches, symbols, and more and are used to deliver commercial drawings for projects.
- Clash detection, model comparison, and conversion to over 10 other formats (DAE, GLB, OBJ, SVG, and more). Integrate with technologies like IDS, BCF, and bSDD, and more.
- Extensive documentation, user guides, academic courses, and a vibrant user community to help you begin your journey.
IfcOpenShell utilities
----------------------
IfcOpenShell is a modular ecosystem of tools that work together, where each tool focuses on a particular task.
.. csv-table::
:header: "Name", "Description"
"**IfcOpenShell**", "The core library for C++ developers. The library includes the ability to parse schemas, tessellate and process implicit geometry."
"**IfcOpenShell-Python**", "Python bindings to the core IfcOpenShell C++ system, as well as high level analysis and authoring functions."
"**IfcConvert**", "A command-line application for converting IFC geometry into file formats such as OBJ, DAE, GLB, STP, IGS, XML, SVG, H5, and IFC itself."
"**BlenderBIM Add-on**", "A graphical add-on that lets you analyse, author, and modify IFC with Blender."
"**BCF**", "BIM Collaboration Format (BCF) is a standard to manage and exchange coordination topics between disciplines collaborating on a project by changing XML files or querying an API."
"**BIMServer-Plugin**", "A plugin to the open source BIMServer CDE to allow you to use IfcOpenShell to parse, view, and audit models."
"**BIMTester**", "A utility that allows you to write Gherkin-based tests for models."
"**bSDD**", "A Python library to query the buildingSMART Data Dictionary API to search for standardised classifications and properties."
"**Ifc2CA**", "Converts IFC models to FEM structural analytical models to be used in Code_Aster."
"**Ifc4D**", "A series of utilities for converting to and from various 4D software like MS Project, PowerProject, and Oracle P6."
"**Ifc5D**", "A collection of utilities of manipulating cost-related data to and from formats, reports, and optimisation engines."
"**IfcCityJSON**", "A converter for CityJSON files and IFC. It currently only supports one-way conversion from CityJSON to IFC."
"**IfcClash**", "A CLI utility and library that lets you perform clash detection on one or more IFC models. Clashes are defined in terms of clash sets with filters using the IFC query syntax."
"**IfcCSV**", "View and edit IFC data using spreadsheets or tabular datasets, such as CSV, ODS, XLSX, Pandas DataFrames, and regular Python lists."
"**IfcDiff**", "A CLI utility and library that lets you compare the changes between two IFC models."
"**IfcFM**", "A highly standards-compliant tool (e.g. COBie 2.4, COBie 3.0, AOH-BSEM) to convert FM data in IFC databases to spreadsheets and other machine readable formats, such as ODS, XLSX, CSV, Pandas, XML, and JSON."
"**IfcMax**", "A 3ds Max importer plugin able to import the IFC file format."
"**IfcPatch**", "A CLI utility and library that lets you run and distribute predetermined modifications on an IFC file, known as a patch recipe. Useful in deploying a data pipeline or batch-fixing external models."
"**IfcSverchok**", "A node based visual programming add-on for Blender to interact with IFC and Sverchok."
"**IfcTester**", "Author and read Information Delivery Specification (IDS) files. You can validate IFC models against IDS and generate reports in multiple formats. It works from the command line, as a web app, or as a library."
"**VoxelisationToolkit**", "Converts .ifc geometry into voxels, and lets you perform voxel based geometric analysis."
.. note::
**IfcOpenShell** and all of its libraries are licensed under LGPL-3.0-or-later. Two exceptions to this are the **BlenderBIM Add-on** and **IfcSverchok**, which are both licensed under GPL-3.0-or-later.
.. toctree::
:hidden:
:maxdepth: 1
:caption: Contents:
introduction/introduction_to_bim
introduction/introduction_to_ifc
src/ifcopenshell-python/docs/introduction/images/ifc-concepts.png
BIN
View File
Binary file not shown.
Side by Side

After

Width:  |  Height:  |  Size: 22 KiB

src/ifcopenshell-python/docs/ifcopenshell-python/images/ifc-concepts.svg → src/ifcopenshell-python/docs/introduction/images/ifc-concepts.svg
View File
Side by Side Swipe Overlay

Before

Width:  |  Height:  |  Size: 14 KiB

After

Width:  |  Height:  |  Size: 14 KiB

src/ifcopenshell-python/docs/introduction/images/ifc-graph.png
BIN
View File
Binary file not shown.
Side by Side

After

Width:  |  Height:  |  Size: 28 KiB

src/ifcopenshell-python/docs/ifcopenshell-python/images/ifc-graph.svg → src/ifcopenshell-python/docs/introduction/images/ifc-graph.svg
View File
Side by Side Swipe Overlay

Before

Width:  |  Height:  |  Size: 13 KiB

After

Width:  |  Height:  |  Size: 13 KiB

src/ifcopenshell-python/docs/introduction/images/ifc-tree.png
BIN
View File
Binary file not shown.
Side by Side

After

Width:  |  Height:  |  Size: 50 KiB

src/ifcopenshell-python/docs/ifcopenshell-python/images/ifc-tree.svg → src/ifcopenshell-python/docs/introduction/images/ifc-tree.svg
View File
Side by Side Swipe Overlay

Before

Width:  |  Height:  |  Size: 26 KiB

After

Width:  |  Height:  |  Size: 26 KiB

src/ifcopenshell-python/docs/introduction/introduction_to_bim.rst
+37
View File
@@ -0,0 +1,37 @@
Introduction to BIM
===================
**Building Information Modeling**, or **BIM**, is a way of digitally describing
our built environment to computers. Aspects of our built environment that can be
described are:
- **Products**, like walls, doors, and windows
- **Processes**, like construction or maintenance tasks, and procedures
- **Resources**, like labour, materials, and equipment
- **Controls**, like permits, orders, costs, or calendar availability
- **Actors**, like occupants, clients, architects, and liable parties
- **Groups**, like systems, inventories, or zones
These objects may have lots of data and relationships. Examples of data might be
classification systems, physical materials, associated documents, simulation
results, and construction types. The data may be relevant to multiple
disciplines, such as architecture, engineering, and construction.
.. note::
BIM data is very different from a regular 3D model. In fact, geometry is
optional, and most data is non-geometric. This means that it is not simply a
3D format that you can import or export from and expect meaningful results.
**Industry Foundation Classes**, or **IFC**, is an international standard for
**BIM**. **IFC** is the most well-established open digital language for our
built environment. Most software will be able to describe their **BIM** data
using **IFC**. Most commonly, **IFC** models will be shared as a ``.ifc`` file.
For example, **IFC** will define a wall as an object that can have a name,
construction type, and quantities. **IFC** will also describe that a wall that
be associated with a location, like a building storey, or have an associated
cost item in a schedule.
When you use **IfcOpenShell**, you will be able to view and create **BIM**
objects and relationships using the **IFC** standard.
src/ifcopenshell-python/docs/introduction/introduction_to_ifc.rst
+220
View File
@@ -0,0 +1,220 @@
Introduction to IFC
===================
An IFC model is a collection of elements (e.g. doors, windows, construction
tasks, materials, etc) with relationships to other elements in a graph-like
database. Together, these elements and their relationships describe the digital
built environment.
.. image:: images/ifc-graph.png
Each element has a type known as an **IFC Class**. These classes define the
attributes that the element may store. For example, the **IfcWall Class** is
allowed to store a **Name** and **Description** attribute.
This IFC database can be stored in many formats. The most common is the ``.ifc``
format, which stores data in plain text. If you open a ``.ifc`` file in a text
editor, you'll see something like this:
::
#1=IFCPROJECT('3Cbhu4euf1hfgM_SHZbeqM',$,'My Project',$,$,$,$,$,#4);
#2=IFCSIUNIT(*,.LENGTHUNIT.,.MILLI.,.METRE.);
#3=IFCSIUNIT(*,.AREAUNIT.,$,.SQUARE_METRE.);
#4=IFCUNITASSIGNMENT((#2,#3));
#5=IFCCARTESIANPOINT((0.,0.,0.));
In this example there are 5 elements in the graph. The element with the ID of
**#1** has an **IFC Class** of **IfcProject**. This element has 9
comma-separated attributes. IFC defines how many attributes each **IFC Class**
is allowed to have, attribute names, the order of attributes, data type,
optional or mandatory status (i.e. cardinality), and more.
::
IFC Class Quoted string value Null value ID reference
↓ ↓ ↓ ↓
#1=IFCPROJECT('3Cbhu4euf1hfgM_SHZbeqM',$,'My Project',$,$,$,$,$,#4);
↑ ↑
Element ID Comma-separated list of attributes
By selecting elements by their **IFC Class**, and reading their attributes, you
can navigate from one element to another. The relationships between elements are
called **IFC Concepts** and create meaning in our industry. For example, if a
**IfcWall** element has an attribute that references an **IfcBuildingStorey**
element in a particular way, it will mean that the wall is located in the
ground floor of the building.
.. image:: images/ifc-concepts.png
The official IFC documentation describes hundreds of **IFC Classes**, ranging
from walls, door, to tasks, cost items, parametric materials, and structural
analysis constraints. There are also hundreds of **IFC Concepts**, which may
describe how a wall is in a storey, a construction task might occur one after
another, or how an surface bounds a space for energy analysis.
It takes time to learn the many **IFC Classes** and **IFC Concepts** available.
Once you do, you will be able to richly describe our built environment
digitally. IfcOpenShell can help you navigate these IFC elements, read their
attributes, and explore relationships. Your journey begins here.
.. seealso::
If you are already familiar with IFC and just want to learn how to use
IfcOpenShell, you can jump to the `Core functionality crash course`_.
Begin learning IFC
------------------
IFC has three versions published by ISO: **IFC2X3** from 2007, **IFC4** from
2017, and **IFC4X3** in draft form. Each version improves on the previous
version, and will have different **IFC Classes** with different attributes and
different **IFC Concepts**.
You can access the official documentation here:
- `Official IFC2X3 documentation homepage <https://standards.buildingsmart.org/IFC/RELEASE/IFC2x3/TC1/HTML/>`__
- `Official IFC4 documentation homepage <https://standards.buildingsmart.org/IFC/RELEASE/IFC4/ADD2_TC1/HTML/>`__
- `Official IFC4X3 documentation homepage <http://ifc43-docs.standards.buildingsmart.org/>`__
- `List of all IFC2X3 classes <https://standards.buildingsmart.org/IFC/RELEASE/IFC2x3/TC1/HTML/alphabeticalorder_entities.htm>`__
- `List of all IFC4 classes <https://standards.buildingsmart.org/IFC/RELEASE/IFC4/ADD2_TC1/HTML/link/inheritance-general-usage-all%20entities.htm>`__
- `List of all IFC4X3 classes <https://ifc43-docs.standards.buildingsmart.org/IFC/RELEASE/IFC4x3/HTML/annex-c.html>`__
.. tip::
It is recommended to use IFC4. However, the IFC4X3 documentation is a lot
more friendly to newcomers.
The official ISO documentation is written for a technical audience and may be
overwhelming. This guide will take you slowly through the core concepts, and
leave you with the knowledge you need to discover more.
Before digging into theory, let's explore an existing IFC model. You can
download this sample IFC for this guide.
.. container:: blockbutton
`Download sample IFC <https://www.ifcwiki.org/images/e/e3/AC20-FZK-Haus.ifc>`__
If you open up the model with a text editor, you will see text similar to this:
::
ISO-10303-21;
HEADER;FILE_DESCRIPTION(('ViewDefinition [, QuantityTakeOffAddOnView, SpaceBoundary2ndLevelAddOnView]'),'2;1');
FILE_NAME('AC20-FZK-Haus.ifc','2016-12-21T17:54:06',('Architect'),(''),'','','');
FILE_SCHEMA(('IFC4'));
ENDSEC;
DATA;
#3= IFCORGANIZATION($,'Nicht definiert',$,$,$);
#12= IFCOWNERHISTORY(#7,#11,$,.ADDED.,$,$,$,1482339244);
#13= IFCSIUNIT(*,.LENGTHUNIT.,$,.METRE.);
#14= IFCSIUNIT(*,.AREAUNIT.,$,.SQUARE_METRE.);
...
#62= IFCGEOMETRICREPRESENTATIONCONTEXT($,'Model',3,1.00000000000E-5,#59,#60);
#66= IFCPROJECT('0lY6P5Ur90TAQnnnI6wtnb',#12,'Projekt-FZK-Haus','Projekt FZK-House create by KHH Forschuungszentrum Karlsruhe',$,$,$,(#62,#374),#49);
#77= IFCPROPERTYSINGLEVALUE('GS_TimeStamp',$,IFCTIMESTAMP(9685146),$);
#85= IFCPROPERTYSET('1mnk_H9cG6eU2r9ped0WRu',#12,'GSPset_TimeStamp',$,(#77));
...
#15033= IFCSHAPEREPRESENTATION(#15026,'Axis','Curve2D',(#15031));
#15037= IFCPRODUCTDEFINITIONSHAPE($,$,(#15016,#15024,#15033));
#15042= IFCWALLSTANDARDCASE('2XPyKWY018sA1ygZKgQPtU',#12,'Wand-Int-ERDG-4',$,$,#14983,#15037,'BC6F0F70-6195-495E-A2-FC-239713029DB1',$);
#15046= IFCMATERIAL('Leichtbeton 102890359',$,$);
...
#15231= IFCRELDEFINESBYPROPERTIES('3Q0nMR5elnJFWzAhgkZqe1',#12,$,$,(#15042),#15229);
#15234= IFCWALLTYPE('2AEMyYvIjlsz7LRzqYHy64',#12,'Leichtbeton 102890359 240',$,$,$,(#15244,#15248,#15250,#17288,#17290,#17292,#18637,#18639,#18641,#19015,#19017,#19019,#20770,#20772,#20774),'8A396F22-E52B-6FDB-D1D5-6FDD2247C184',$,.NOTDEFINED.);
#15237= IFCDIRECTION((1.,0.,0.));
#15239= IFCDIRECTION((0.,0.,1.));
... etc
The first thing you should notice is the line that defines that this is an
**IFC4** version. This determines what **IFC Classes** and **IFC Concepts** are
available.
::
FILE_SCHEMA(('IFC4'));
You'll notice certain **IFC Class** keywords jump out at you: things like
**IFCSIUNIT** which defines the length unit of metres, or **IFCPROJECT** which
defines the project, or **IFCPROPERTYSINGLEVALUE** which defines a property of
something, or **IFCWALLSTANDARDCASE** which defines a wall, or **IFCMATERIAL**
which defines a material, and so on.
Let's see how to fetch this data with code. Let's start with loading the model.
Import the IfcOpenShell module, then use the ``open`` function to load the
model into a variable called ``model``. The first piece of information we want
to check is what IFC schema version we are using. We assume the model you are
learning with is IFC4. We'll then fetch all entities that use the **IfcSlab**
class.
.. code-block:: python
import ifcopenshell
model = ifcopenshell.open('/path/to/your/model.ifc')
print(model.schema) # May return IFC2X3, IFC4, or IFC4X3.
print(model.by_type("IfcSlab")) # Will return a list of IFCSLAB entities, like below:
# [
# #34509=IfcSlab('1pPHnf7cXCpPsNEnQf8_6B',#12,'Bodenplatte',$,$,#34464,#34505,'E4D9CD4B-CA43-4735-94-BD-1FD4376BD455',.BASESLAB.),
# #59290=IfcSlab('2RGlQk4xH47RHK93zcTzUL',#12,'Slab-033',$,$,#59253,#59286,'DA0A17AC-B773-47AC-99-C5-D390C73AD5CC',.FLOOR.),
# #59553=IfcSlab('07Enbsqm9C7AQC9iyBwfSD',#12,'Dach-1',$,$,#59508,#59549,'E142B455-80E4-4B96-83-EC-E1589CA998DB',.ROOF.),
# #59753=IfcSlab('2IxUUNUVPB6Ob$eicCfP2N',#12,'Dach-2',$,$,#59716,#59749,'BD6D9414-37DF-40A8-88-40-301A32A9A5B5',.ROOF.)
# ]
.. tip::
Try changing ``model.by_type("IfcSlab")`` to fetch different types of
entities based on their **IFC Class**.
An overview of all IFC classes
------------------------------
There are hundreds of **IFC Classes**. You don't need to know them all, but
we'll help describe the general breakdown so you know where to find the
appropriate class for what you're after.
**IFC Classes** are defined using an **Object Oriented** tree hierarchy. Child
**IFC Classes** inherit the attributes defined by the parent **IFC Class**.
This means that **IFC Classes** with common attributes are grouped together in
the tree.
For example, because all **IfcObject** classes can have a **GlobalId**
attribute, that means that because **IfcWall** is a subtype of **IfcObject**,
it can also have a **GlobalId** attribute.
.. image:: images/ifc-tree.png
Important IFC concepts
----------------------
There are hundreds of **IFC Concepts** that allow you to describe relationships
between **IFC Classes**. In this guide, we'll focus on the five most common
**IFC Concepts** to get you started.
Concept 1: the project context
------------------------------
Concept 2: spatial decomposition
--------------------------------
Concept 3: object typing
------------------------
Concept 4: attributes and property sets
---------------------------------------
Concept 5: material assignment
------------------------------
Self-learning IFC: how to learn more
------------------------------------