ifcopenshell
¶
Welcome to IfcOpenShell! IfcOpenShell provides a way to read and write IFCs.
IfcOpenShell can open IFC files, read entities (such as walls, buildings,
properties, systems, etc), edit attributes, write out .ifc
files and more.
This module provides primitive functions to interact with IFC, including:
For most users, you can open and read IFC models, see docs for
open()
. This returns anfile
object representing the IFC model. You can then query the model to filter elements.For developers, you can query the schema itself, see docs for
schema_by_name()
. This returns a schema object which you can use to analyse the definitions of IFC classes and data types.
You may also be interested in:
For model authoring and editing operations, see
ifcopenshell.api
.For extracting information from models, see
ifcopenshell.util
.For processing geometry, see
ifcopenshell.geom
.
For more details, consult https://docs.ifcopenshell.org/
Example:
import ifcopenshell
print(ifcopenshell.version) # v0.7.0-1b1fd1e6
model = ifcopenshell.open("/path/to/model.ifc")
walls = model.by_type("IfcWall")
for wall in walls:
print(wall.Name)
Subpackages¶
Submodules¶
Package Contents¶
- exception ifcopenshell.Error¶
Bases:
Exception
Error used when a generic problem occurs
Initialize self. See help(type(self)) for accurate signature.
- exception ifcopenshell.SchemaError¶
Bases:
Error
Error used when an IFC schema related problem occurs
Initialize self. See help(type(self)) for accurate signature.
- class ifcopenshell.entity_instance(e, file=None)¶
Represents an entity (wall, slab, property, etc) of an IFC model
An IFC model consists of entities. Examples of entities include walls, slabs, doors and so on. Entities can also be non-physical things, like properties, systems, construction tasks, colours, geometry, and more.
Entities are defined through an IFC Class. There are hundreds of IFC Classes defined as part of the ISO standard by the buildingSMART International organisation. The IFC Class defines the attributes of an entity, as well as the data types and whether or not an attribute is mandatory or optional.
IfcOpenShell’s API dynamically implements the IFC schema. You will not find documentation about available IFC Classes, or what attributes they have. Please consult the buildingSMART official documentation or start reading Introduction to IFC.
In addition to the Python methods you see documented here, an instantiated entity_instance will have attributes defined by its IFC class. For example, an entity instance which is an IfcWall class will have a
Name
attribute, and an IfcColourRgb will have aRed
attribute. Please consult the buildingSMART official documentation.Example:
model = ifcopenshell.open(file_path) walls = model.by_type("IfcWall") wall = walls[0] print(wall) # #38=IFCWALL('2MEinnTPbCMwLOgceaQZFu',$,$,'My Wall',$,#52,#47,$,$); print(wall.is_a()) # IfcWall # Note: the `Name` attribute is dynamic, based on the IFC class. print(wall.Name) # My Wall # Attributes are ordered and may also be accessed via index. print(wall[3]) # My Wall print(wall.__class__) # <class 'ifcopenshell.entity_instance'>
- property file¶
- wrapped_data: ifcopenshell.ifcopenshell_wrapper.entity_instance¶
- attribute_name(attr_idx: int) str ¶
Return the name of a positional attribute of the element
- Parameters:
attr_idx (int) – The index of the attribute
- Return type:
string
- attribute_type(attr: int) str ¶
Return the data type of a positional attribute of the element
- Parameters:
attr (int) – The index of the attribute
- Return type:
string
- compare(other, op, reverse=False)¶
Compares with another instance.
For simple types the declaration name is not taken into account:
>>> f = ifcopenshell.file() >>> f.createIfcInteger(0) < f.createIfcPositiveInteger(1) True
For entity types the declaration name is taken into account:
>>> f.createIfcWall('a') < f.createIfcWall('b') True
>>> f.createIfcWallStandardCase('a') < f.createIfcWall('b') False
Comparing simple types with different underlying types throws an exception:
>>> f.createIfcInteger(0) < f.createIfcLabel('x') Traceback (most recent call last): File "<stdin>", line 1, in <module> File "entity_instance.py", line 371, in compare return op(a, b) TypeError: '<' not supported between instances of 'int' and 'str'
- Args:
other (_type_): Right hand side (or lhs when reverse = True) op (_type_): The comparison operator (likely from the operator module) reverse (bool, optional): When true swaps lhs and rhs. Defaults to False.
- Returns:
bool: The comparison predicate applied to self and other
- get_info(include_identifier=True, recursive=False, return_type=dict, ignore=(), scalar_only=False) dict ¶
Return a dictionary of the entity_instance’s properties (Python and IFC) and their values.
- Parameters:
include_identifier (bool) – Whether or not to include the STEP numerical identifier
recursive (bool) – Whether or not to convert referenced IFC elements into dictionaries too. All attributes also apply recursively
return_type (dict|list|other) – The return data type to be casted into
ignore (set|list) – A list of attribute names to ignore
scalar_only (bool) – Filters out all values that are IFC instances
- Returns:
A dictionary of properties and their corresponding values
- Return type:
dict
Example:
ifc_file = ifcopenshell.open(file_path) products = ifc_file.by_type("IfcProduct") obj_info = products[0].get_info() print(obj_info.keys()) >>> dict_keys(['Description', 'Name', 'BuildingAddress', 'LongName', 'GlobalId', 'ObjectPlacement', 'OwnerHistory', 'ObjectType', >>> ...'ElevationOfTerrain', 'CompositionType', 'id', 'Representation', 'type', 'ElevationOfRefHeight'])
- get_info_2(include_identifier=True, recursive=False, return_type=dict, ignore=())¶
More perfomant version of .get_info() but with limited arguments values.
Method has exactly the same signature as .get_info() but it doesn’t support getting information non-recursively.
- Currently supported arguments values:
include_identifier: True
recursive: True (will fail with default False value from .get_info())
return_type: dict
ignore: () (empty tuple)
- id() int ¶
Return the STEP numerical identifier
- Return type:
int
- is_a() str ¶
- is_a(ifc_class: str) bool
- is_a(with_schema: bool) str
Return the IFC class name of an instance, or checks if an instance belongs to a class.
The check will also return true if a parent class name is provided.
- Parameters:
args (Union[str, bool]) – If specified, is a case insensitive IFC class name to check or if specified as a boolean then will define whether returned IFC class name should include schema name (e.g. “IFC4.IfcWall” if True and “IfcWall” if False). If omitted will act as False.
- Returns:
Either the name of the class, or a boolean if it passes the check
- Return type:
Union[str, bool]
Example:
f = ifcopenshell.file() f.create_entity('IfcPerson') f.is_a() >>> 'IfcPerson' f.is_a('IfcPerson') >>> True
- is_entity() bool ¶
Tests whether the instance is an entity type as opposed to a simple data type.
- Returns:
bool: True if the instance is an entity
- to_string(valid_spf=True) str ¶
Returns a string representation of the current entity instance. Equal to str(self) when valid_spf=False. When valid_spf is True returns a representation of the string that conforms to valid Step Physical File notation. The difference being entity names in upper case and string attribute values with unicode values encoded per the specific control directives.
- static unwrap_value(v)¶
- static walk(f: Callable[[Any], bool], g: Callable[[Any], Any], value: Any) Any ¶
Applies a transformation to value based on a given condition.
If value is a nested structure (e.g., a list or a tuple) will apply transformation to it’s elements.
- Parameters:
f (Callable) – A callable that takes a single argument and returns a boolean value. It represents the condition.
g (Callable) – A callable that takes a single argument and returns a transformed value. It represents the transformation.
value (Any) – Any object, the input value to be processed
- Returns:
Transformed value
- Return type:
Any
Example:
# Define condition and transformation functions condition = lambda v: v == old transform = lambda v: new # Usage example attribute_value = element.RelatedElements print(old in attribute_value, new in attribute_value) # True, False result = element.walk(condition, transform, element.RelatedElements) print(old in attribute_value, new in attribute_value) # False, True
- static wrap_value(v, file)¶
- class ifcopenshell.sqlite(filepath)¶
Bases:
ifcopenshell.file.file
Base class for containing IFC files.
Class has instance methods for filtering by element Id, Type, etc. Instantiated objects can be subscripted by Id or Guid
Example:
model = ifcopenshell.open(file_path) products = model.by_type("IfcProduct") print(products[0].id(), products[0].GlobalId) # 122 2XQ$n5SLP5MBLyL442paFx print(products[0] == model[122] == model["2XQ$n5SLP5MBLyL442paFx"]) # True
Create a new blank IFC model
This IFC model does not have any entities in it yet. See the
create_entity
function for how to create new entities. All data is stored in memory. If you wish to write the IFC model to disk, see thewrite
function.- Parameters:
f – The underlying IfcOpenShell file object to be wrapped. This is an internal implementation detail and should generally be left as None by users.
schema (string) – Which IFC schema to use, chosen from “IFC2X3”, “IFC4”, or “IFC4X3”. These refer to the ISO approved versions of IFC. Defaults to “IFC4” if not specified, which is currently recommended for all new projects.
schema_version (tuple[int, int, int, int]) – If you want to specify an exact version of IFC that may not be an ISO approved version, use this argument instead of
schema
. IFC versions on technical.buildingsmart.org are described using 4 integers representing the major, minor, addendum, and corrigendum number. For example, (4, 0, 2, 1) refers to IFC4 ADD2 TC1, which is the official version approved by ISO when people refer to “IFC4”. Generally you should not use this argument unless you are testing non-ISO IFC releases.
Example:
# Create a new IFC4 model, create a wall, then save it to an IFC-SPF file. model = ifcopenshell.file() model.create_entity("IfcWall") model.write("/path/to/model.ifc") # Create a new IFC4X3 model model = ifcopenshell.file(schema="IFC4X3") # A poweruser testing out a particular version of IFC4X3 model = ifcopenshell.file(schema_version=(4, 3, 0, 1))
- by_id(id)¶
Return an IFC entity instance filtered by IFC ID.
- Parameters:
id (int) – STEP numerical identifier
- Raises:
RuntimeError – If id is not found.
- Returns:
An ifcopenshell.entity_instance
- Return type:
- by_type(type, include_subtypes=True)¶
Return IFC objects filtered by IFC Type and wrapped with the entity_instance class.
If an IFC type class has subclasses, all entities of those subclasses are also returned.
- Parameters:
type (string) – The case insensitive type of IFC class to return.
include_subtypes (bool) – Whether or not to return subtypes of the IFC class
- Raises:
RuntimeError – If type is not found in IFC schema.
- Returns:
A list of ifcopenshell.entity_instance objects
- Return type:
- clear_cache()¶
- create_entity(type, *args, **kawrgs)¶
Create a new IFC entity in the file.
- Parameters:
type (string) – Case insensitive name of the IFC class
args – The positional arguments of the IFC class
kwargs – The keyword arguments of the IFC class
- Returns:
An entity instance
- Return type:
Example:
f = ifcopenshell.file() f.create_entity("IfcPerson") # >>> #1=IfcPerson($,$,$,$,$,$,$,$) f.create_entity("IfcPerson", "Foobar") # >>> #2=IfcPerson('Foobar',$,$,$,$,$,$,$) f.create_entity("IfcPerson", Identification="Foobar") # >>> #3=IfcPerson('Foobar',$,$,$,$,$,$,$)
- get_geometry(ids: list[int]) dict[str, dict] ¶
- get_inverse(inst, allow_duplicate=False, with_attribute_indices=False)¶
Return a list of entities that reference this entity
- Parameters:
inst (ifcopenshell.entity_instance) – The entity instance to get inverse relationships
allow_duplicate – Returns a list when True, set when False
with_attribute_indices – Returns pairs of <i, idx> where i[idx] is inst or contains inst. Requires allow_duplicate=True
- Returns:
A list of ifcopenshell.entity_instance objects
- Return type:
- is_entity_list(attribute)¶
- preprocess_schema()¶
- traverse(inst, max_levels=None, breadth_first=False)¶
Get a list of all referenced instances for a particular instance including itself
- Parameters:
inst (ifcopenshell.entity_instance) – The entity instance to get all sub instances
max_levels (bool) – How far deep to recursively fetch sub instances. None or -1 means infinite.
breadth_first – Whether to use breadth-first search, the default is depth-first.
- Returns:
A list of ifcopenshell.entity_instance objects
- Return type:
- class ifcopenshell.sqlite_entity(id, ifc_class, file=None)¶
Bases:
ifcopenshell.entity_instance.entity_instance
Represents an entity (wall, slab, property, etc) of an IFC model
An IFC model consists of entities. Examples of entities include walls, slabs, doors and so on. Entities can also be non-physical things, like properties, systems, construction tasks, colours, geometry, and more.
Entities are defined through an IFC Class. There are hundreds of IFC Classes defined as part of the ISO standard by the buildingSMART International organisation. The IFC Class defines the attributes of an entity, as well as the data types and whether or not an attribute is mandatory or optional.
IfcOpenShell’s API dynamically implements the IFC schema. You will not find documentation about available IFC Classes, or what attributes they have. Please consult the buildingSMART official documentation or start reading Introduction to IFC.
In addition to the Python methods you see documented here, an instantiated entity_instance will have attributes defined by its IFC class. For example, an entity instance which is an IfcWall class will have a
Name
attribute, and an IfcColourRgb will have aRed
attribute. Please consult the buildingSMART official documentation.Example:
model = ifcopenshell.open(file_path) walls = model.by_type("IfcWall") wall = walls[0] print(wall) # #38=IFCWALL('2MEinnTPbCMwLOgceaQZFu',$,$,'My Wall',$,#52,#47,$,$); print(wall.is_a()) # IfcWall # Note: the `Name` attribute is dynamic, based on the IFC class. print(wall.Name) # My Wall # Attributes are ordered and may also be accessed via index. print(wall[3]) # My Wall print(wall.__class__) # <class 'ifcopenshell.entity_instance'>
- get_info(include_identifier=True, recursive=False, return_type=dict, ignore=(), scalar_only=False)¶
Return a dictionary of the entity_instance’s properties (Python and IFC) and their values.
- Parameters:
include_identifier (bool) – Whether or not to include the STEP numerical identifier
recursive (bool) – Whether or not to convert referenced IFC elements into dictionaries too. All attributes also apply recursively
return_type (dict|list|other) – The return data type to be casted into
ignore (set|list) – A list of attribute names to ignore
scalar_only (bool) – Filters out all values that are IFC instances
- Returns:
A dictionary of properties and their corresponding values
- Return type:
dict
Example:
ifc_file = ifcopenshell.open(file_path) products = ifc_file.by_type("IfcProduct") obj_info = products[0].get_info() print(obj_info.keys()) >>> dict_keys(['Description', 'Name', 'BuildingAddress', 'LongName', 'GlobalId', 'ObjectPlacement', 'OwnerHistory', 'ObjectType', >>> ...'ElevationOfTerrain', 'CompositionType', 'id', 'Representation', 'type', 'ElevationOfRefHeight'])
- id()¶
Return the STEP numerical identifier
- Return type:
int
- unserialise_value(value)¶
- ifcopenshell.create_entity(type, schema='IFC4', *args, **kwargs)¶
Creates a new IFC entity that does not belong to an IFC file object
Note that it is more common to create entities within a existing file object. See
ifcopenshell.file.create_entity()
.- Parameters:
type (string) – Case insensitive name of the IFC class
schema (string) – The IFC schema identifier
args – The positional arguments of the IFC class
kwargs – The keyword arguments of the IFC class
- Returns:
An entity instance
- Return type:
Example:
person = ifcopenshell.create_entity("IfcPerson") # #0=IfcPerson($,$,$,$,$,$,$,$) model = ifcopenshell.file() model.add(person) # #1=IfcPerson($,$,$,$,$,$,$,$)
- ifcopenshell.guess_format(path: pathlib.Path) str | None ¶
Guesses the IFC format using file extension
IFCs may be serialised as different formats. The most common is a
.ifc
file, which is plaintext and stores data using the STEP Physical File format. IFC can also be stored as a Zipfile, XML, JSON, or SQL.This will return the canonical form of the format. For example, if a path has the extension of .xml or .ifcxml (case insensitive), it will return .ifcXML.
Users generally won’t call this function. The
open()
function uses this internally to guess the file format.- Returns:
Either .ifc, .ifcZIP, .ifcXML, .ifcJSON, .ifcSQLite, or None.
- ifcopenshell.open(path: os.PathLike | str, format: str | None = None, should_stream: bool = False) file.file ¶
Loads an IFC dataset from a filepath
You can specify a file format. If no format is given, it is guessed from its extension. Currently supported specified format: .ifc | .ifcZIP | .ifcXML.
You can then filter by element ID, class, etc, and subscript by id or guid.
Example:
model = ifcopenshell.open("/path/to/model.ifc") model = ifcopenshell.open("/path/to/model.ifcXML") model = ifcopenshell.open("/path/to/model.any_extension", ".ifc") products = model.by_type("IfcProduct") print(products[0].id(), products[0].GlobalId) # 122 2XQ$n5SLP5MBLyL442paFx print(products[0] == model[122] == model["2XQ$n5SLP5MBLyL442paFx"]) # True
- ifcopenshell.register_schema(schema)¶
Registers a custom IFC schema
- Parameters:
schema (ifcopenshell.express.schema_class.SchemaClass) – A schema object
Example:
schema = ifcopenshell.express.parse("/path/to/ifc-custom.exp") ifcopenshell.register_schema(schema) ifcopenshell.file(schema="IFC_CUSTOM")
- ifcopenshell.register_schema_attributes(schema: ifcopenshell.ifcopenshell_wrapper.schema_definition) None ¶
- ifcopenshell.schema_by_name(schema: str | None = None, schema_version: tuple[int, Ellipsis] | None = None) ifcopenshell_wrapper.schema_definition ¶
Returns an object allowing you to query the IFC schema itself
- Parameters:
schema (string, optional) – Which IFC schema to use, chosen from “IFC2X3”, “IFC4”, or “IFC4X3”. These refer to the ISO approved versions of IFC.
schema_version (tuple[int, ...], optional) – If you want to specify an exact version of IFC that may not be an ISO approved version, use this argument instead of
schema
. IFC versions on technical.buildingsmart.org are described using 4 integers representing the major, minor, addendum, and corrigendum number. For example, (4, 0, 2, 1) refers to IFC4 ADD2 TC1, which is the official version approved by ISO when people refer to “IFC4”. Generally you should not use this argument unless you are testing non-ISO IFC releases.
- Returns:
Schema definition object.
- Return type:
ifocpenshell_wrapper.schema_definition
- ifcopenshell.NO_HEADER¶
- ifcopenshell.READ_ERROR¶
- ifcopenshell.UNSUPPORTED_SCHEMA¶
- ifcopenshell.get_log¶
- ifcopenshell.platform_architecture = '32bit'¶
- ifcopenshell.platform_system¶
- ifcopenshell.python_distribution¶
- ifcopenshell.python_version_tuple¶
- ifcopenshell.version¶