openbim_ifc

An empty model.

Parse a STEP (.ifc) file from its bytes.

An ifcZIP archive (.ifczip) is recognized by its ZIP signature and its one model entry read, STEP or ifcXML in either layout, within a decompression budget: an archive with no model or several raises parse, an encrypted entry or a compression other than Stored and Deflate unsupported, and one that inflates past the budget budget-exceeded.

options relaxes the strict read, e.g. ParseOptions.lenient() skips damaged records; each one skipped is listed by diagnostics().

Parse an ifcXML document.

Without xsd_profile it reads this library's lossless layout; with "IFC4" or "IFC4X3_ADD2" it reads the buildingSMART XSD layout of that release.

Read a STEP (.ifc) file, or an ifcZIP archive as parse() reads one, from disk.

Cheaper than IfcModel.parse(Path(path).read_bytes()): the file is read once, straight into the model, with the GIL released.

mapped=True memory-maps the file instead of reading it: nothing is copied, and the pages belong to the OS page cache. The model keeps decoding from the file while it is alive, so the file must not be modified or truncated until the model is gone -- a truncated file can terminate the interpreter (SIGBUS), and a rewritten one makes reads fail or return other content. Use it only for files that stay put, such as a read-only export.

options is as for parse().

Raises openbim_ifc.IfcError with code == "io" when the file cannot be read.

Serialize as STEP bytes.

Serialize as ifcXML bytes, in the layout parse_ifcxml reads.

An XSD-layout write needs the header to declare the profile's schema and refuses with write what the layout cannot carry.

Serialize as ifcZIP bytes: one Deflate entry holding STEP (model.ifc), or, with inner="ifcxml", ifcXML (model.ifcXML) in the layout xsd_profile names, as for write_ifcxml(). parse() and open() read it back.

Raises invalid-value for another inner, or an xsd_profile with STEP inside.

The STEP file header: description, name, time stamp, author, ...

Replace the STEP file header, e.g. with dataclasses.replace.

Validate against the schema the header declares.

Findings are sorted by severity, rule, entity and slot. max_findings caps the report (default 10,000) and sets truncated when reached.

Validate with the EXPRESS rules of the declared release.

express is the text of that release's .exp file, which the caller supplies: the schemas are CC BY-ND and not bundled. Every WHERE, type and global rule is evaluated, and INVERSE cardinality is checked; indeterminate counts the rules that evaluated to UNKNOWN. The text is parsed on every call. Raises express-mismatch for text that declares another schema than the model's or disagrees with the release's tables, and invalid-express for text that does not parse. max_findings is as for validate().

Products no viewer will draw, with a stable reason, in id order.

The property sets, quantity sets and predefined property sets of object id: its own first, then those its type object holds, an occurrence property overriding an inherited one of the same name.

Values keep their declared IFC type, e.g. Typed("IFCLENGTHMEASURE", Real(0.2)). Resolved against the release the header declares (IFC2X3, IFC4 or IFC4X3).

property_sets() of each of ids, in that order, or, with None, of every object definition (IfcObjectDefinition and its subtypes) in file order, in one pass.

The file's property relationships are validated once for the whole call rather than once per object, so resolving every object is linear in the model. Each ObjectPropertySets holds exactly what property_sets() returns for its object, or, in refusal, the code and message it raises; only a refusal of the whole model (unsupported-schema) raises. No index outlives the call, so a call after an edit sees the edit.

The effective unit of a measure_type value ("IFCAREAMEASURE"): unit when given (a property's stated unit), otherwise the project default, resolved exactly to SI.

Write and remove property and quantity values as one checked transaction: every edit, in order, or none.

A refused batch raises openbim_ifc.IfcError and leaves the model unchanged. A write's value is the read side's Property.value. A value an occurrence inherits from its type is overridden on the occurrence, never changed on the shared type set; pass the type object's id to change that. Values are checked against the declared release (IFC2X3, IFC4 or IFC4X3) and, for a Pset_/Qto_ set, its PSD/QTO catalog template.

Write one value (set_properties() with one edit); returns the id of the entity holding it.

Remove one property from object's own set (set_properties() with one edit).

The spatial containment tree: every container with its parent, sub-containers and contained elements.

The classifications of object id: its own, then its type's.

The material association of object id, its own or its type's, or None.

Each product's world placement (a column-major 4x4 in metres) and the Body representation a viewer draws, for ids or every product with a shape. A product that cannot be placed carries a typed refusal; the call raises only unsupported-schema or feature-disabled.

Each product's Body as Axiolid's neutral geometry graph, exact, for ids or every product with a shape, in Axiolid's versioned wire format: {"format": "axiolid-geometry-graph", "version": "1.0", "graph": {"nodes": [...], "roots": [...]}} (the lowest version the content needs, "1.0" to "1.4"), in world coordinates, metres. encoding "json" gives the payload as a str, "cbor" as bytes; any other raises ValueError. A product that cannot be lowered carries a typed refusal; the call raises only unsupported-schema or feature-disabled.

Each product's Body as triangles from the reference backend, for ids or every product with a shape; a product that cannot be meshed carries a typed refusal. representation meshes another one instead (#458): "Surface", or any name product_curves() takes; its curves are left to that call, and closure says "solid" or "surface". Only a Body mesh carries a colour. Needs a wheel built with the mesh feature; the published wheel raises feature-disabled.

Each product's curves as polylines from the reference backend (#458), for ids or every product with a shape. representation is "Plan" (the best drawing curves: Plan, Annotation, FootPrint, then Axis, preferring a PLAN_VIEW context), or "Axis", "FootPrint", "Annotation", "Body" or "Surface"; another name raises invalid-value. A product whose curves cannot be compiled carries a typed refusal: a curve the reference compiler has no certified polyline for (an implicit curve, an offset of an offset) is unsupported; trimmed, composite, offset and intrinsic curves compile (#506). Text literals and annotation fill areas beside the curves (a dimension's value) are listed in skipped, not refused (#512). Needs a wheel built with the mesh feature.

Every system with its members and served structures, and the memberships the reader could not honour.

Every cost schedule and cost item; values as authored, typed.

Every coordinate operation resolved with the project length unit; empty when the model has none. IFC2X3 is read from its ePSet_MapConversion and ePSet_ProjectedCRS property sets.

The first FILE_SCHEMA token, e.g. "IFC4", or None.

Non-fatal problems found while reading.

Every entity id, in file order.

Ids of every entity of exactly type_name (case-insensitive).

Ids of type_name or any subtype, per the file's schema.

The ids selector query selects, ascending (#464).

"IfcWall, Pset_WallCommon.IsExternal=TRUE + IfcSlab": class facets (subtypes included) add entities, ! removes them, attribute, property and type=, material=, classification=, location= and group= facets filter; , chains facets and + unites lists. With base, facets select from those entities alone. The grammar and its differences from IfcOpenShell's selector are documented in the guide.

Raises invalid-selector (with span, the byte range in the UTF-8 query) for a query that does not parse or names a class or attribute the file's release does not declare.

select_ids() as Entity views.

The value path reads from entity (#464): "Name", "type.Name", "Pset_WallCommon.FireRating", "materials.Name", "storey.Name", "occurrences.count".

Plain Python values as Entity attributes read them: a reference is an Entity, $ is None, several values a tuple, and a property set a read-only mapping of its properties.

Write value at path of entity (#464), as one checked transaction: an attribute ("Name", "type.Name") coerced as set_attribute_by_name_plain() coerces it, or a property ("Pset_WallCommon.FireRating") from a typed value, or a plain one when the property already states its type. A refused write changes nothing; a path naming no single value raises invalid-value.

The entities selector query selects as a table (#474): format "csv", "tsv" or "xlsx", the key column first ("GlobalId", or "id" with key="id"), then one column per value path of columns ("Name", "type.Name", "Pset_WallCommon.FireRating"), each cell the value the path reads as text and NULL as null.

Raises invalid-selector for a query or path that does not parse, invalid-value for an unknown format or key, and wrong-entity-type for an entity without a GlobalId in a table keyed by it.

Apply a table (bytes, or str for CSV and TSV) back to the model by its key column (#474), as one checked transaction: every other cell is written by its header's value path, typed by the attribute's declared type or the property's stated one, and a cell that reads what the model holds changes nothing, so an exported table imported unchanged is a no-op.

The answer lists every change and every refusal by row and column; any refusal means nothing was written, as does dry_run. Raises only for a call that cannot start: an unknown format or key, bytes that are no table of the format.

The id of the entity whose GlobalId is global_id, or None. The first lookup indexes every GlobalId once; later ones reuse it until the model changes. Raises invalid-value for text that is not a GlobalId and invalid-model when several entities carry it. by_guid() returns the Entity.

Every GlobalId several entities carry, with its holders; empty for a conformant file.

The type object of occurrence id (IfcRelDefinesByType), or None. Raises wrong-entity-type for a non-IfcObject and invalid-model when the file states two types.

Every object type object id types, in file order.

Every opening voiding element id (IfcRelVoidsElement).

Every element filling opening id (IfcRelFillsElement).

The element opening id voids, or None.

The upper-case type name of entity id.

Every attribute of entity id, in declaration order.

Attribute index of entity id; Null past the end.

Set attribute index of entity id; returns the old value.

Every explicit attribute of entity id in slot order, inherited first, as the release the header declares defines them. INVERSE attributes hold no slot and are listed by inverse_attribute_names().

Attribute name of entity id, matched case-insensitively ("Name") and resolved against the declared release; Null when the record stops before its slot.

An INVERSE name ("IsDefinedBy", #462) reads the entities referencing id through the release's FOR clause: a List of Ref for a SET or BAG -- SET [0:1] included, so ContainedInStructure is a list of zero or one -- in ascending id order; a Ref or Null for a single-valued inverse (VoidsElements), which two referrers refuse with invalid-model.

Every INVERSE attribute of entity id, inherited ones first, with its FOR clause and bounds, as the declared release defines them.

Every reference to entity id: the referencing entity and the attribute index holding the reference, in ascending order, one per entity and attribute. IfcOpenShell's file.get_inverse(entity, allow_duplicate=True, with_attribute_indices=True).

How many distinct entities reference entity id, through any attribute. IfcOpenShell's file.get_total_inverses.

Set attribute name of entity id; returns the old value. A derived attribute raises derived-attribute, an INVERSE one inverse-attribute, an unknown name unknown-attribute, and a refused write changes nothing.

Set attribute name of entity id from a plain Python value, coerced against the attribute's declared type in the declared release; returns the old tagged value. wall.Name = "x" calls this.

A str becomes a label (written bare, 'x') or the enumeration item it names in any case (.STANDARD.); an int an INTEGER or a REAL as declared; a float a REAL; a bool a BOOLEAN or LOGICAL; a list or tuple an aggregate, element by element; an openbim_ifc.Entity a reference, checked to exist and to be of an accepted type; None $. In a SELECT the one member that takes the value is written as its typed parameter (IFCDESCRIPTIVEMEASURE('by layer')). A tagged value (Text, Enum, Typed, ...) is written exactly as given.

Raises type-mismatch for a value that does not fit, ambiguous-value when several SELECT members would take it (the message names them; pass a Typed value instead), and otherwise as set_attribute_by_name(). A refused write changes nothing.

Append an entity; returns its new id.

Remove entity id, leaving references to it dangling.

Deprecated since version 0.9: A file with dangling references parses and is wrong. Use remove_with_relationships() for one entity, or remove_product() for a product with what it solely owns. It keeps working, with a DeprecationWarning.

Apply authoring operations as one checked transaction against the release the header declares: every operation, in order, or none.

A refused batch raises openbim_ifc.IfcError and leaves the model unchanged. An operation names the entity an earlier one produced by openbim_ifc.handle(); result.ids holds, per operation, the id the produced entity received.

Create one entity of type_name from named attributes, checked against the declared release (author() with one AuthorOp.create()); returns its id.

Remove entity id with the relationships that reference it, leaving nothing dangling (author() with one AuthorOp.remove()). Raises still-referenced while an entity other than a relationship needs it.

Keep at most limit undo entries; 0 (the default) turns history off and drops what is held. While it is on, every method that changes the model is one entry (author() is one entry for its whole batch).

The history bound and how many entries each direction holds.

Restore the model to the state before the last change: entities under their ids and at their file positions, the header included. Undoing a creation frees its id again.

Raises history-empty with nothing to undo (also while history is off) and history-stale when the model changed outside the history; the model is unchanged then.

Reverse the last undo(). Raises history-empty with nothing to redo and history-stale as undo() does.

Drop every undo and redo entry, keeping the limit.

Remove product (or type object) id with everything it solely owns -- its placement, representation, own property and quantity sets, material usage, openings and ports, and the relationships left without an end -- as one checked transaction. Shared data stays: a property set another object uses, a type's representation maps, a style used elsewhere. The report says what went and what stayed, and why; with dry_run nothing changes.

Raises still-referenced while other placements are relative to its placement (rebase_placements re-bases them, composing the transforms so nothing moves) or while a type object types objects (untype_occurrences unassigns the type), wrong-entity-type for an entity that is neither an IfcProduct nor an IfcTypeObject, and unsupported for a placement that cannot be re-based.

Remove unreferenced entities as one checked transaction; with dry_run, only report.

Without classes: every resource entity no IfcRoot reaches (nor annotates something reached, as a styled item does). With classes (subtypes included, any case): the entities of those classes nothing references; an IfcRoot among them only with include_roots. The owner history with its actors stays unless include_owner_history. Raises unsupported-schema for a class the release does not declare.

Remove shape representation id with what only it uses, as one checked transaction: it is taken off its product definition shape (which goes when left empty), representation map or shape aspects, then removed with its items down to what nothing else uses. Shared items, profiles, points and styles stay, and the report says why; with dry_run nothing changes.

Raises still-referenced for a representation map an IfcMappedItem still maps, and wrong-entity-type for an entity that is not an IfcShapeModel.

Copy product (or type object) id with everything it solely owns, as one checked transaction (#479): what remove_product() would remove with it is copied, what it would keep is shared.

Copied, each with a new GlobalId: its placement (relative to the same parent; moved by offset, in the parent's frame, or replaced by placement), its representation (items and profiles copied, the context, styles and type geometry shared), its own property and quantity sets, its material usage, its ports and, with openings and fillings, its openings and the doors and windows filling them. Shared, the copy joining the relationship: its type, shared property sets, material definitions, classification and, with container and aggregate, its spatial container and its whole. The report maps every original to its copy; with dry_run nothing changes.

Raises wrong-entity-type for neither an IfcProduct nor an IfcTypeObject, invalid-value for both offset and placement, and unsupported for an offset onto a placement that is not a local placement with a Cartesian location, or a moved copy whose openings or fillings are not placed relative to it.

Copy entities ids of source into this model with what belongs to them, as one checked transaction (#479): what they reference, their property sets, type, material and classification, their openings, fillings and ports, and what attaches to their geometry. Units, contexts, the owner history, materials and styles equal to this model's are reused, for the kinds reuse names. Relationships to objects not copied (a spatial container) are skipped and reported; relate the copies afterwards.

global_ids: keep (a GlobalId this model holds is refused), merge (an IfcRoot this model holds by GlobalId and type is reused, its relationships joined), regenerate or regenerate-colliding.

Raises unsupported when the models' length or plane angle units differ (convert one with convert_length_unit() first), unsupported-schema for an entity this model's release cannot hold (a type or attribute it lacks, a constant it does not know), invalid-value for a kept GlobalId this model holds. With dry_run nothing changes.

Convert value from unit entity from_unit to unit entity to_unit of this model (an IfcSIUnit, IfcConversionBasedUnit or IfcDerivedUnit), exactly: prefixes convert by a power of ten, conversion-based units through their factor, derived units by their exponents.

Raises type-mismatch for units of different dimensions, unsupported for a monetary or context-dependent unit or one with an offset (#110), and missing-entity for an id the model lacks.

Convert the model's length unit to target (an SI METRE with any prefix, such as "MILLIMETRE", or "inch", "foot", "yard", "mile", "US survey foot"), rescaling every length, area and volume value -- geometry, placements, quantities and property values -- as one checked transaction.

Which values are lengths is read from the release's measure types; values with a unit of their own keep it, and curve parameters that are angles, knots or multiples stay. With area_and_volume the area and volume units become the square and cube of the new length unit; with dry_run nothing changes and the report says what would.

Raises unsupported naming every value the conversion cannot carry (a p-curve off a plane, a polynomial curve, a parameter on an undefined parameter space), invalid-value for a target that is not a length unit, invalid-model when the project length unit cannot be resolved and unsupported-schema for a release other than IFC2X3, IFC4 or IFC4X3. A refusal leaves the model unchanged.

Every (from, to) pair where to does not exist.

A view of entity id; IfcModel.by_id() checks it exists.

The entity's #id.

The model the entity belongs to.

The upper-case type name, e.g. "IFCWALL".

Whether the entity is a type_name or a subtype of it, per the file's schema; case-insensitive. A name the schema lacks is False.

Attribute name as a plain value; entity.Name with the precise type. Raises openbim_ifc.IfcError as IfcModel.attribute_by_name() does.

Attribute name as the exact tagged value, e.g. Typed("IFCLABEL", Text("W1")) or Derived().

Write attribute name (entity.Name = value); returns the old tagged value. A plain value is coerced against the declared type (openbim_ifc.IfcModel.set_attribute_by_name_plain()); a tagged one is written as given. A refused write changes nothing.

Every explicit attribute, in slot order, as IfcModel.attribute_names() lists them.

Every INVERSE attribute, as IfcModel.inverse_attribute_names() lists them.

Every entity referencing this one, with the attribute index holding the reference: IfcModel.inverse_references() as (Entity, index) pairs.

How many distinct entities reference this one: IfcModel.total_inverses().

The exact records IfcModel.property_sets() returns.

Property sets and predefined property sets by name, each a read-only mapping of property name to PropertyValue.

The object's own values and those its type object holds, an occurrence value overriding an inherited one, as IfcModel.property_sets() resolves them; quantity sets are in qtos. A snapshot: read it again after a write. Write with set_property().

Quantity sets (IfcElementQuantity) by name, as psets.

Write one property or quantity value: IfcModel.set_property() on this entity. value is exact, e.g. Typed("IFCLABEL", Text("F60")). Returns the id of the entity holding it.

Remove one property from the entity's own set: IfcModel.remove_property().

One entity of type_name from named attributes; an IfcRoot without a GlobalId gets one.

Replace named attributes; the whole entity is checked again.

Remove an entity with the relationships that reference it.

The model's one IfcProject.

A spatial element aggregated under parent (IfcRelAggregates).

A product, contained in container (IfcRelContainedInSpatialStructure) and typed by type_object (IfcRelDefinesByType).

A type object (IfcWallType, ...).

IfcRelDefinesByType; an object already typed is refused unless replace.

When the type already has an IfcRelDefinesByType the objects join its RelatedObjects and the produced id is that relationship's; owner_history applies only to a relationship that is created (#534).

With map_representations the type's RepresentationMaps are mapped onto each object (IfcMappedItem through mapping_target or an identity operator); with material_usage a layer or profile set usage is derived from the type's set (layer_set_direction "AXIS1".."AXIS3" overrides the class default); predefined_type is "ignore" (default), "validate" or "sync". replace unassigns the previous type and removes what it propagated (#480).

IfcRelContainedInSpatialStructure; an element already contained is refused unless replace, which moves it out of its previous container.

IfcRelAggregates; a part already aggregated is refused unless replace, which moves it out of its previous whole.

An IfcLocalPlacement; axis and ref_direction both or neither.

An IfcOwnerHistory with its person, organization and application, through ifc-author.

An IfcShapeRepresentation of items in context, unassigned. representation_type is checked against the items by the release's CorrectItemsForType rule, or inferred (the most specific type admitting them all); identifier defaults to the context's ContextIdentifier.

Assign a shape representation to a product (its IfcProductDefinitionShape, created when missing) or to a type (as a new IfcRepresentationMap). A representation already used is refused.

Take a shape representation off a product or type; it stays, unassigned, for the batch to assign elsewhere or remove.

A copy of a shape representation with copies of its items, sharing its context, styles and mapped type geometry.

Remove a shape representation with what only it uses.

Copy a product or type with what it solely owns (see IfcModel.copy_product()); produces the copy.

Deep-copy an entity and what it references: classes in copy are copied, classes in share (and entities a UNIQUE clause binds) shared; other IfcRoot entities are shared unless copy_roots, definitions (materials, units, contexts, the owner history) unless copy_definitions; any other resource is copied. Produces the copy.

Any malformed record fails the read.

Skip malformed records and accept reals without a point.

An edit removing property name from object's own set.