C and C++
openbim-ifc-capi is a versioned C ABI over the IFC core, usable from C, C++, or anything with a C FFI. It ships as a CMake package, openbim_ifc, with pkg-config files on Linux and macOS, rather than through a registry.
Task-sized recipes are in the C cookbook, and every declaration of the header is in the C API reference.
The binding exposes the record model over STEP -- parse, read and edit attributes, and write -- plus lenient reads, the file header, validation, ifcXML, the reachability lint and read-only domain views (see Beyond the record model).
Install via CMake
Link the imported target:
find_package(openbim_ifc 0.1 CONFIG REQUIRED)
target_link_libraries(app PRIVATE openbim_ifc::openbim_ifc)openbim_ifc::openbim_ifc is the shared library. Set OPENBIM_IFC_LINKAGE to STATIC before find_package for the static one, or link openbim_ifc::openbim_ifc_shared or openbim_ifc::openbim_ifc_static by name. The static target brings the system libraries Rust's standard library needs. On Windows the package requires MSVC.
There are three ways to get the package:
Prebuilt archive. Every
openbim-ifc-capi-v*GitHub release attachesopenbim-ifc-capi-v<version>-<target>.tar.gz(.zipon Windows) for Linux, macOS and Windows, each on x86_64 and aarch64, with aSHA256SUMSfile. Each holds the header, both libraries, the CMake config and, on Linux and macOS, the pkg-config files. Unpack it anywhere and pass that directory asCMAKE_PREFIX_PATH.Install from a checkout. This needs Rust, which CMake drives:
bashcmake -S crates/openbim-ifc-capi -B build cmake --build build cmake --install build --prefix /opt/openbim-ifcBuild inside your project.
add_subdirectory(<checkout>/crates/openbim-ifc-capi)builds the library with cargo as part of your build and defines the same targets.OPENBIM_IFC_CARGO_FEATURESenables crate features such asrusty_alloc.
The shared library records only its file name (an ELF SONAME, and the Mach-O install name @rpath/libopenbim_ifc_capi.dylib), so it can move with your application. CMake sets the runtime path in your build tree. An installed application sets its own: INSTALL_RPATH on Linux and macOS, the DLL next to the executable on Windows.
The header is crates/openbim-ifc-capi/include/openbim_ifc.h, and the package installs it as include/openbim_ifc.h. It is generated by cbindgen, and the gate fails when the committed copy is stale. Without CMake, cargo build -p openbim-ifc-capi --release leaves both libraries in target/release/; static linking on Linux then also needs -lpthread -ldl -lm.
The gate builds a CMake consumer that runs the C smoke test against the source tree, the installed package and an unpacked archive, shared and static, on Linux; CI repeats it on macOS and Windows.
Install via pkg-config
For Make, Meson, autotools or a plain compiler call, cmake --install and the Linux and macOS release archives also lay out two pkg-config files in lib/pkgconfig/:
| Module | Links | Extra flags |
|---|---|---|
openbim_ifc | the shared library, -lopenbim_ifc_capi | -- |
openbim_ifc-static | the static archive, by path | the system libraries Rust's standard library needs |
They are two modules, not one with Libs.private, because lib/ holds both libraries under one name: -lopenbim_ifc_capi would pick the shared one even under pkg-config --static. The static module lists the same system libraries as the CMake target openbim_ifc::openbim_ifc_static (-lgcc_s -lutil -lrt -lpthread -lm -ldl on Linux, -lc -lm on macOS). Both files take their paths from their own location (${pcfiledir}), so an archive works wherever it is unpacked, and carry the crate version.
Point pkg-config at the tree:
export PKG_CONFIG_PATH=/opt/openbim-ifc/lib/pkgconfig
pkg-config --modversion openbim_ifcWith Make:
CFLAGS += $(shell pkg-config --cflags openbim_ifc)
LDLIBS += $(shell pkg-config --libs openbim_ifc)
# Static instead:
# LDLIBS += $(shell pkg-config --libs openbim_ifc-static)With Meson:
openbim_ifc = dependency('openbim_ifc', version: '>=0.1')
# or dependency('openbim_ifc-static')
executable('app', 'app.c', dependencies: openbim_ifc)pkg-config sets no runtime path. A program linked against the shared library finds it through the system's library path, LD_LIBRARY_PATH / DYLD_LIBRARY_PATH, or an rpath you add. On macOS the install name is @rpath/libopenbim_ifc_capi.dylib, so a program needs an rpath there, for example -Wl,-rpath,$(pkg-config --variable=libdir openbim_ifc).
Windows (MSVC) is CMake-only: the install tree and the .zip archive carry no pkg-config files.
The same check script builds the smoke test, as C11 and C++17, from nothing but pkg-config --cflags --libs for both modules, against the installed tree and the unpacked archive, on Linux in the gate and on macOS in CI. With the tree moved away, the shared builds must fail to start and the static ones must still run.
Read an entity
OpenbimIfcModel model = 0;
if (openbim_ifc_v0_1_model_parse(data, len, &model, NULL, 0) != OPENBIM_IFC_STATUS_OK) {
return 1;
}
/* Every call that returns a buffer: ask for the size, then fetch. */
size_t need = 0;
openbim_ifc_v0_1_entity_type(model, 1, NULL, 0, &need);
uint8_t *type = (uint8_t *)malloc(need);
openbim_ifc_v0_1_entity_type(model, 1, type, need, &need);
printf("#1 is %s\n", (const char *)type); /* #1 is IFCWALL */
free(type);
openbim_ifc_v0_1_model_destroy(model);The protocol is documented in the crate's README:
- every export is versioned (
openbim_ifc_v0_1_*); - models are opaque integer handles;
- no Rust allocation crosses the ABI, so every variable-size output is a caller-owned buffer, sized by a first call with
NULL, 0; - every failure is an
OpenbimIfcStatus, never a crash.
Attributes by name
/* Read and write #1's Name by name: the slot comes from the release the
* header declares, so the same call works for IFC2X3, IFC4 and IFC4X3. */
OpenbimIfcValueNode value[4];
uint8_t text[64];
size_t value_nodes = 0, text_len = 0;
const char name[] = "Name";
if (openbim_ifc_v0_1_entity_attribute_by_name(model, 1, (const uint8_t *)name,
strlen(name), value, 4, &value_nodes,
text, sizeof text,
&text_len) != OPENBIM_IFC_STATUS_OK) {
return 1;
}
printf("Name: %.*s\n", (int)value[0].str_len, (const char *)text + value[0].str_offset);
/* The new value is a one-value tape: TEXT at offset 0 of `renamed`. */
const char renamed[] = "Renamed";
OpenbimIfcValueNode edit;
memset(&edit, 0, sizeof edit);
edit.kind = OPENBIM_IFC_KIND_TEXT;
edit.str_len = strlen(renamed);
OpenbimIfcStatus status = openbim_ifc_v0_1_entity_set_attribute_by_name(
model, 1, (const uint8_t *)name, strlen(name), &edit, 1,
(const uint8_t *)renamed, strlen(renamed));openbim_ifc_v0_1_entity_attribute_by_name and openbim_ifc_v0_1_entity_set_attribute_by_name take the name as UTF-8 bytes and resolve it against the release the file's header declares: IfcTask.Status is slot 6 of an IFC2X3 file and slot 7 of an IFC4 one. openbim_ifc_v0_1_entity_attribute_names returns a tape LIST of AttributeInfo records, one per explicit attribute in slot order, inherited first: name (TEXT), index (INTEGER), type name (TEXT), optional, aggregate and derived (BOOL), declared by (TEXT). Names match case-insensitively and come back in the schema's spelling. An INVERSE name (#462) reads through openbim_ifc_v0_1_entity_attribute_by_name as well, following the declared release's FOR clause: a LIST of REFs in ascending id order for a SET or BAG (SET [0:1] included: zero or one element), a REF or NULL for a single-valued inverse, where two referrers are OPENBIM_IFC_STATUS_INVALID_MODEL. A write to one is OPENBIM_IFC_STATUS_INVERSE_ATTRIBUTE (inverse-attribute). openbim_ifc_v0_1_entity_inverse_attribute_names lists the declarations as InverseAttributeInfo records (name, entity, for attribute, aggregate, lower, upper or NULL for ?, declared by); openbim_ifc_v0_1_entity_inverse_references lists every referrer as an InverseReference record (REF id, INTEGER attribute index), and openbim_ifc_v0_1_entity_total_inverses counts the distinct referrers. A name that is neither is OPENBIM_IFC_STATUS_UNKNOWN_ATTRIBUTE (unknown-attribute). A derived slot reads as stored (OPENBIM_IFC_KIND_DERIVED) and refuses a write (OPENBIM_IFC_STATUS_DERIVED_ATTRIBUTE, derived-attribute). An entity type the declared release does not have is OPENBIM_IFC_STATUS_UNSUPPORTED_SCHEMA. The positional openbim_ifc_v0_1_entity_attribute and _entity_set_attribute are unchanged.
openbim_ifc_v0_1_entity_set_attribute_by_name_plain (#342) takes the same one-value tape, read as plain host values coerced against the attribute's declared type: a TEXT becomes a label (written bare) or the enumeration item it names in any case; an INTEGER an INTEGER, or a REAL where one is declared; a REAL a REAL; a BOOL a BOOLEAN or LOGICAL; a REF a reference, once the entity exists (OPENBIM_IFC_STATUS_MISSING_REFERENCE) and is of an accepted type; a LIST an aggregate, element by element; NULL $. In a SELECT, the one member that takes the value is written as its typed parameter. An OPENBIM_IFC_KIND_EXACT node (12, valid only here) is followed by one value written exactly as given, as are DERIVED, UNKNOWN, BINARY, ENUM and TYPED nodes. A value that does not fit is OPENBIM_IFC_STATUS_TYPE_MISMATCH (32, type-mismatch), one several SELECT members take OPENBIM_IFC_STATUS_AMBIGUOUS_VALUE (33, ambiguous-value; the message names them).
/* A plain TEXT for an enumeration attribute: coerced against the declared
* type (IfcWallTypeEnum) and written .STANDARD.; a label would be written
* as text, a SELECT member as its typed parameter. */
const char attribute[] = "PredefinedType";
const char item[] = "standard";
OpenbimIfcValueNode value;
memset(&value, 0, sizeof value);
value.kind = OPENBIM_IFC_KIND_TEXT;
value.str_len = strlen(item);
OpenbimIfcStatus status = openbim_ifc_v0_1_entity_set_attribute_by_name_plain(
model, 1, (const uint8_t *)attribute, strlen(attribute), &value, 1,
(const uint8_t *)item, strlen(item));Beyond the record model
/* A damaged export: skip what cannot be read; each skip is a diagnostic. */
OpenbimIfcModel model = 0;
if (openbim_ifc_v0_1_model_parse_with_options(data, len, OPENBIM_IFC_PARSE_LENIENT,
&model, NULL, 0) != OPENBIM_IFC_STATUS_OK) {
return 1;
}
/* Validation: the counts land in a summary even on a size query; the
* findings come as a value tape, fetched like any other. */
OpenbimIfcValidationSummary summary;
memset(&summary, 0, sizeof summary);
size_t nodes_needed = 0, strings_needed = 0;
openbim_ifc_v0_1_model_validate(model, 0, &summary, NULL, 0, &nodes_needed,
NULL, 0, &strings_needed);
printf("%zu errors, conformant: %u\n", summary.errors, (unsigned)summary.conformant);
openbim_ifc_v0_1_model_destroy(model);- Lenient reads.
openbim_ifc_v0_1_model_parse_with_options,_open_with_optionsand_open_mapped_with_optionstakeOPENBIM_IFC_PARSE_*flag bits (OPENBIM_IFC_PARSE_LENIENTis the preset); an unknown bit isINVALID_VALUE. Recoveries are listed byopenbim_ifc_v0_1_model_diagnostic. - Header.
openbim_ifc_v0_1_model_headerreturns a value tape: aLISTof the ten header fields in STEP order;_model_set_headertakes the same shape back. - Validation.
openbim_ifc_v0_1_model_validatefills anOpenbimIfcValidationSummaryand a tape of findings, each aLISTof severity, rule, entity (REForNULL), attribute index, attribute name, path and message. A size query runs the validation, so pass buffers you expect to fit and retry onBUFFER_TOO_SMALL. - Validation with EXPRESS rules.
openbim_ifc_v0_1_model_validate_express(model, express, express_len, max_findings, &summary, ...)evaluates every WHERE, type and global rule of the declared release fromexpress, the UTF-8 text of that release's.expfile, which you supply: the schemas are CC BY-ND, so none is bundled. It fills anOpenbimIfcExpressValidationSummary(the counts ofOpenbimIfcValidationSummaryplusindeterminate, the rules that evaluated to UNKNOWN) and the same findings tape, whose severities addindeterminate. The text is parsed on every call, so a size query parses and validates. Text that declares another schema than the model's, or disagrees with the release's tables, isEXPRESS_MISMATCH(36), codeexpress-mismatch; text that does not parse isINVALID_EXPRESS(37), codeinvalid-express; text that is not UTF-8 isINVALID_ARGUMENT. Thev0_1summary record and_model_validateare unchanged. This export makes the ABI version 0.1.22. - ifcXML.
openbim_ifc_v0_1_model_write_ifcxmland_model_parse_ifcxmltake a profile name:NULL, 0for this library's lossless layout,IFC4orIFC4X3_ADD2for that release's XSD layout. - ifcZIP.
openbim_ifc_v0_1_model_parseand_model_openread an ifcZIP archive, recognized by its ZIP signature: its one STEP or ifcXML model (either layout), within a decompression budget.openbim_ifc_v0_1_model_write_ifcziptakes the inner format (NULL, 0orstep, orifcxml) and a profile as for ifcXML. An archive is refused withPARSEwhen it holds no.ifcor.ifcXMLentry at its root or several,UNSUPPORTEDfor an encrypted entry or a compression other than Stored and Deflate, andBUDGET_EXCEEDEDfor an entry that would inflate past 4 GiB or 200 times its compressed size. - Reachability.
openbim_ifc_v0_1_model_unreachable_productsreturns a tape of products no viewer will draw, each with a stable reason.
Domain views
OpenbimIfcModel model = 0;
if (openbim_ifc_v0_1_model_parse(data, len, &model, NULL, 0) != OPENBIM_IFC_STATUS_OK) {
return 1;
}
/* The property sets of wall #3, inherited ones included: a LIST of
* PropertySet records, each a LIST of its fields (see the table below). */
size_t sets = 0, nodes_needed = 0, strings_needed = 0;
openbim_ifc_v0_1_model_property_sets(model, 3, &sets, NULL, 0, &nodes_needed, NULL, 0,
&strings_needed);
OpenbimIfcValueNode *nodes =
(OpenbimIfcValueNode *)malloc(nodes_needed * sizeof(OpenbimIfcValueNode));
uint8_t *strings = (uint8_t *)malloc(strings_needed);
openbim_ifc_v0_1_model_property_sets(model, 3, &sets, nodes, nodes_needed, &nodes_needed,
strings, strings_needed, &strings_needed);
/* nodes[4] is the first set's name, nodes[6] its source ("type"). */
printf("%zu set(s); first: %.*s\n", sets, (int)nodes[4].str_len,
(const char *)strings + nodes[4].str_offset);
free(nodes);
free(strings);
openbim_ifc_v0_1_model_destroy(model);The domain views of the Rust facade cross as value tapes. Each record is a LIST of its fields in the order below; a nested record is a nested LIST, an id a REF, an absent field NULL, a count an INTEGER, a resolved parameter (a thickness, a map offset) a REAL, and an IFC value its own tagged node, typed wrapper included (TYPED IFCLENGTHMEASURE over REAL 0.2). As for validation, a size query runs the read.
| Export | Tape |
|---|---|
openbim_ifc_v0_1_model_property_sets(model, object, &count, ...) | LIST of PropertySet, the object's own then its type's |
openbim_ifc_v0_1_model_property_sets_many(model, ids, id_count, &count, ...) | LIST of ObjectPropertySets, one per id in order; null ids with count 0: every object definition. One pass through one property index (#358): linear where a loop of the call above is quadratic |
openbim_ifc_v0_1_model_resolve_unit(model, measure, len, unit, ...) | one ResolvedUnit; unit 0 is the project default |
openbim_ifc_v0_1_model_spatial_tree(model, ...) | one SpatialTree |
openbim_ifc_v0_1_model_classifications(model, object, &count, ...) | LIST of Classification |
openbim_ifc_v0_1_model_material(model, object, ...) | one MaterialAssignment, or NULL when there is none |
openbim_ifc_v0_1_model_systems(model, ...) | one Systems |
openbim_ifc_v0_1_model_cost(model, ...) | one Cost |
openbim_ifc_v0_1_model_georeferencing(model, &count, ...) | LIST of MapConversion |
Domain record tapes
| Record | Fields, in tape order |
|---|---|
PropertySet | id, global id, name, type name, source (occurrence/type), source id, properties (LIST of Property) |
Property | id, name, type name, kind, value type, unit, value (tagged), enumeration, bounds, table, usage, discrimination, quality, members (LIST of Property) |
PropertyEnumeration | id, name, values (LIST of tagged values) |
PropertyBounds | lower, upper, set point (tagged values, NULL when unstated) |
PropertyTable | rows (LIST of [defining, defined]), expression, defining unit, defined unit, interpolation |
ObjectPropertySets | object, sets (LIST of PropertySet, empty when refused), refusal ([code, message] or NULL: what _model_property_sets returns for the object) |
ResolvedUnit | unit, from project (BOOL), dimensions (seven INTEGERs), scale, offset |
SpatialTree | release, roots, nodes (LIST of SpatialNode), orphans, dangling (LIST of [relation, target]), anomalies (LIST of [kind, relation, subject, kept]) |
SpatialNode | id, global id, name, type name, kind, parent, children, elements, referenced |
Classification | relationship, global id, source, type object, target, kind, identification, name, location, notation, parents, system ([id, name, source, edition]) |
MaterialAssignment | relationship, global id, source, type object, target, type name, kind, set, name, materials, layers, profiles, constituents, usage |
MaterialRef | id, name, category |
MaterialLayer | id, material, thickness, is ventilated (tagged), name, category, priority |
MaterialProfile | id, material, profile, name, category, priority |
MaterialConstituent | id, material, name, category, fraction |
MaterialUsage | layer set direction, direction sense, offset from reference line, reference extent, cardinal point, end set, cardinal end point |
Systems | systems (LIST of System), anomalies (LIST of [kind, subject, other, message]) |
System | id, global id, type name, name, long name, predefined type, members, serviced buildings, serviced facilities |
Cost | schedules, items, anomalies (LIST of [item, kept, rejected, relation]) |
CostSchedule | id, global id, name, identification, status, predefined type, items |
CostItem | id, global id, name, identification, description, predefined type, parent, children, values, quantities, objects |
CostValue | id, name, description, category, condition, applied value (tagged), operator, unit basis ([id, value, unit]), components (LIST of CostValue) |
MapConversion | operation, kind, source, source kind, target CRS, eastings, northings, orthogonal height, x axis, scale, factors, project unit, map unit, map unit declared, linear (three columns), translation |
ProjectedCrs | id, name, description, geodetic datum, vertical datum, map projection, map zone, well-known text |
LengthUnit | name, metres per unit |
Refusals keep the codes every host shares, with new statuses INVALID_MODEL (19), MISSING_REFERENCE (21), BUDGET_EXCEEDED (22), UNSUPPORTED (23) and WRONG_ENTITY_TYPE (24); a release a view does not read is UNSUPPORTED_SCHEMA. These exports make the ABI version 0.1.2; no v0_1 symbol changed.
Writing property sets
/* Wall #3 inherits IsExternal from its type: writing it on the wall
* creates an occurrence override; the type's shared set is unchanged.
* The value is a one-value tape: IFCBOOLEAN(.F.). */
const char *wrapper = "IFCBOOLEAN";
OpenbimIfcValueNode value[2];
memset(value, 0, sizeof value);
value[0].kind = OPENBIM_IFC_KIND_TYPED;
value[0].str_len = strlen(wrapper);
value[1].kind = OPENBIM_IFC_KIND_BOOL;
value[1].int_value = 0;
uint64_t property = 0;
OpenbimIfcStatus status = openbim_ifc_v0_1_model_set_property(
model, 3, (const uint8_t *)"Pset_WallCommon", 15, (const uint8_t *)"IsExternal", 10,
value, 2, (const uint8_t *)wrapper, strlen(wrapper), NULL, 0, &property);openbim_ifc_v0_1_model_set_properties writes and removes property and quantity values as one checked transaction: every edit, in order, or, when any is refused, none, and the model is unchanged. The batch is one tape, a LIST of edits, each a LIST:
| Edit | Fields, in tape order |
|---|---|
| write | ENUM SET, object (REF or INTEGER), set name (TEXT), property name (TEXT), value (the Property value field, typed), set type (TEXT IfcPropertySet/IfcElementQuantity, or NULL; may be left off) |
| removal | ENUM REMOVE, object, set name, property name |
A batch is never run as a size query: the caller passes one uint64_t per edit, which gets the id of the entity holding the property afterwards (0 when the batch leaves none), and a buffer shorter than the edit count is BUFFER_TOO_SMALL before anything is written. openbim_ifc_v0_1_model_set_property (a one-value tape) and openbim_ifc_v0_1_model_remove_property are the one-edit forms.
A missing set is created with its relationship, the object's owner history and a name-based GlobalId; a removal that empties a set removes it. A value the occurrence inherits from its type is overridden on the occurrence and never changed on the type's shared set (pass the type object to change that), and a set or property shared with other objects is copied before it changes. As for the views, the edit refuses rather than writes when a value is not admissible: invalid-value when the declared release (IFC2X3, IFC4 or IFC4X3) has no such IfcValue member, the payload does not fit it, a quantity's measure is another, or a stated unit fixes another measure; template-violation (TEMPLATE_VIOLATION, 25) when the release's PSD/QTO catalog entry for a Pset_/Qto_ set (data type, enumeration, form, quantity kind, a property it does not declare) or the property's own enumeration refuses it; missing-property (MISSING_PROPERTY, 26) for a removal of a property the object does not state (one it only inherits included); unsupported for a bounded, table, reference or complex value; and wrong-entity-type for a set type that disagrees with the set. These exports make the ABI version 0.1.3; no v0_1 symbol changed. The library carries the PSD/QTO catalog; a build without the core's property-catalog feature refuses a write to a Pset_/Qto_ set with FEATURE_DISABLED. Status 27, OPENBIM_IFC_STATUS_CATALOG_NOT_LOADED (catalog-not-loaded), is the refusal of the npm build, which loads the catalog at runtime; this library embeds it, so it never returns 27. Adding it makes the ABI version 0.1.4.
Not bound yet: checked multi-edit transactions over arbitrary entities (Transaction, Applied, Conflict), deferred until a host asks for them. Use the Rust crates for those.
GlobalIds, types and openings
openbim_ifc_v0_1_model_by_guid finds an entity by GlobalId through an index built on the first lookup and kept until the model changes; a GlobalId several entities carry is INVALID_MODEL, the last error naming them all, and openbim_ifc_v0_1_model_duplicate_global_ids lists every one. openbim_ifc_v0_1_entity_type_object and openbim_ifc_v0_1_entity_occurrences read IfcRelDefinesByType in every release; openbim_ifc_v0_1_entity_openings, openbim_ifc_v0_1_entity_fillings and openbim_ifc_v0_1_entity_voided_element read IfcRelVoidsElement and IfcRelFillsElement. An optional answer is written to out_id, or is NO_VALUE. openbim_ifc_v0_1_new_guid draws a random version-4 GlobalId and openbim_ifc_v0_1_name_based_guid derives a reproducible version-8 one; neither needs a model. These exports make the ABI version 0.1.10; no v0_1 symbol changed. The cookbook has a recipe.
Selectors and values by path
openbim_ifc_v0_1_model_select and openbim_ifc_v0_1_model_select_from fill the caller's buffer with the ids a selector selects, in ascending order. openbim_ifc_v0_1_entity_get_value reads a value by path as a tape (a property set as a LIST of name and value pairs) and openbim_ifc_v0_1_entity_set_value writes one from a tape of plain values as a single checked transaction. A selector that does not parse is INVALID_SELECTOR; openbim_ifc_v0_1_last_error_span then gives the byte range it refuses. These exports make the ABI version 0.1.14; no v0_1 symbol changed. The cookbook has a recipe.
Tables
openbim_ifc_v0_1_model_export_table writes the entities a selector selects as a table into a byte buffer, in OPENBIM_IFC_TABLE_CSV, _TSV or _XLSX, keyed by OPENBIM_IFC_TABLE_KEY_GLOBAL_ID (or _AUTO) or _ID, one column per value path of a columns array. openbim_ifc_v0_1_model_import_table applies a table back by its key as one checked transaction and answers with a TableImport record tape: applied (BOOL), changes (LIST of TableChange: row, column, key, path, entity, target entity, target, before, after) and refusals (LIST of TableRefusal: row, column, code, message, span). Any refusal means nothing was written, as does OPENBIM_IFC_TABLE_DRY_RUN; a size query or a short buffer plans the import and writes nothing. The cookbook has a recipe.
Geometry
Geometry crosses at three levels (ADR 0021): placements, the exact neutral representation and meshes.
/* Level 1, in every build: each product's placement and Body as a tape of
* ProductPlacement records; null ids with count 0 select every product. */
OpenbimIfcValueNode nodes[128];
uint8_t strings[1024];
size_t products = 0, node_count = 0, string_len = 0;
openbim_ifc_v0_1_model_product_placements(model, NULL, 0, &products, nodes, 128,
&node_count, strings, sizeof strings, &string_len);
/* nodes[5] is the first record's transform: a LIST of 16 REALs, a
* column-major 4x4 in metres; its translation is nodes[18..20]. */
printf("%zu product(s); first at %g %g %g\n", products, nodes[18].real_value,
nodes[19].real_value, nodes[20].real_value);
/* Level 3, in a library built with the `mesh` feature: compile once into
* a set, then copy each product's arrays out. */
OpenbimIfcMeshes meshes = 0;
if (openbim_ifc_v0_1_model_product_meshes(model, NULL, 0, &meshes) == OPENBIM_IFC_STATUS_OK) {
size_t need = 0;
openbim_ifc_v0_1_meshes_positions(meshes, 0, NULL, 0, &need);
float *positions = (float *)malloc(need * sizeof(float)); /* x y z, metres */
openbim_ifc_v0_1_meshes_positions(meshes, 0, positions, need, &need);
openbim_ifc_v0_1_meshes_indices(meshes, 0, NULL, 0, &need);
uint32_t *indices = (uint32_t *)malloc(need * sizeof(uint32_t)); /* 3 per triangle */
openbim_ifc_v0_1_meshes_indices(meshes, 0, indices, need, &need);
printf("%zu triangle(s)\n", need / 3);
free(positions);
free(indices);
openbim_ifc_v0_1_meshes_destroy(meshes);
}openbim_ifc_v0_1_model_product_placements is in every build: for the id_count products in ids, or, with ids null and id_count 0, for every product with a shape, a tape of ProductPlacement records -- id, global id, type name, transform (a LIST of 16 REALs, a column-major 4x4 in metres, or NULL), representation (a SelectedRepresentation: id, identifier, representation type, context, context type, context identifier, target view; NULL for an axis-only product) and refusal (a GeometryRefusal: code, entity, message; or NULL). A product that cannot be placed is a record with a refusal coded unsupported, invalid-model, missing-reference or budget-exceeded, not a failed call.
Meshes link a geometry kernel, so they are the cargo feature mesh, which the release archives leave out (FEATURE_DISABLED); build with cargo build --release -p openbim-ifc-capi --features mesh or CMake with -DOPENBIM_IFC_CARGO_FEATURES=mesh. Compiling is the expensive step, and every buffer is sized by a first call, so openbim_ifc_v0_1_model_product_meshes compiles once into a mesh set, an opaque non-zero OpenbimIfcMeshes handle that owns its data and outlives the model. openbim_ifc_v0_1_meshes_records returns its ProductMesh records (id, global id, type name, transform, vertex count, triangle count, refusal, colour, colour refusal; the colour, #449, is a SurfaceColour record of red, green, blue, transparency, source item, layer, material or materialSet, source entity, surface style and, last, source materials (a LIST of REF: for materialSet the materials of the set that colour the item, ascending, else empty; #603), read from the Body item's style, else its presentation layer's, else its material's, and a colour refusal of code ambiguous never refuses the mesh; these two fields make the ABI version 0.1.11; source materials, 0.1.24); openbim_ifc_v0_1_meshes_positions copies mesh index's float positions (x, y, z per vertex, metres, relative to its transform) and openbim_ifc_v0_1_meshes_indices its uint32_t indices (three per triangle), each after the usual size query; an index past the set is OUT_OF_RANGE. openbim_ifc_v0_1_meshes_destroy frees the set. A product with no Body has no vertices and no refusal. These exports make the ABI version 0.1.7; no v0_1 symbol changed.
Curves have no triangles, so the curves of a curve representation -- an Axis, a FootPrint, an annotation's curves -- come as polylines (#458), from the same mesh feature. openbim_ifc_v0_1_model_product_curves(model, ids, id_count, representation, representation_len, out_curves) compiles them once into an OpenbimIfcCurves set, read and freed as a mesh set is. representation is UTF-8: Plan (the best drawing curves: Plan, then Annotation, FootPrint and Axis, preferring one in a PLAN_VIEW context), or one RepresentationIdentifier, Axis, FootPrint, Annotation, Body, Surface or Reference; another name is INVALID_VALUE. openbim_ifc_v0_1_curves_records returns a ProductCurves record per product (id, global id, type name, transform, vertex count, polylines, refusal, skipped), each polyline a ProductPolyline record (curve, first vertex, vertex count, closed, chord bound, chord requested: the certified bound in metres on how far the exact curve lies from the polyline, 0 for a polyline the file authored, and the one-millimetre budget); openbim_ifc_v0_1_curves_positions copies a product's float positions, every polyline's vertices in turn, relative to its transform; and openbim_ifc_v0_1_curves_destroy frees the set. Trimmed, composite, offset and intrinsic curves compile (#506); a curve the reference compiler has no certified polyline for (an implicit curve, an offset of an offset) is a record refused unsupported, naming the product. A representation that also holds text or a fill area (a dimension and its value) gives its curves; each IfcTextLiteral, IfcTextLiteralWithExtent and IfcAnnotationFillArea of it is listed by entity id in skipped (a LIST of REFs), not drawn and not a refusal (#512). openbim_ifc_v0_1_model_product_meshes_for meshes a named representation instead of the Body, such as Surface, its curves left out; every ProductMesh record now ends with its closure, solid, surface (an area, no volume) or unknown. These exports make the ABI version 0.1.17; no v0_1 symbol changed.
The exact neutral representation (#367) is each product's Body as Axiolid's geometry graph, serialised in Axiolid's versioned wire format 1.0 (Axiolid ADR 0085) for a host's own kernel. It links the lowering, so it is the cargo feature graph, which the release archives leave out (FEATURE_DISABLED); build with --features graph (or mesh,graph), or CMake with -DOPENBIM_IFC_CARGO_FEATURES=graph:
/* Level 2, in a library built with the `graph` feature: lower and encode
* once into a set, then copy each product's wire payload out. */
OpenbimIfcGraphs graphs = 0;
size_t products = 0;
if (openbim_ifc_v0_1_model_product_geometry(model, NULL, 0, OPENBIM_IFC_GEOMETRY_JSON,
&graphs) == OPENBIM_IFC_STATUS_OK) {
OpenbimIfcValueNode nodes[128];
uint8_t strings[1024];
size_t node_count = 0, string_len = 0, need = 0;
/* ProductGeometry records: id, global id, type, transform, encoding,
* payload size, refusal. */
openbim_ifc_v0_1_graphs_records(graphs, &products, nodes, 128, &node_count, strings,
sizeof strings, &string_len);
openbim_ifc_v0_1_graphs_payload(graphs, 0, NULL, 0, &need);
char *json = (char *)malloc(need + 1);
openbim_ifc_v0_1_graphs_payload(graphs, 0, (uint8_t *)json, need, &need);
json[need] = '\0'; /* {"format":"axiolid-geometry-graph","version":"1.0",...} */
printf("%zu graph(s); %.52s...\n", products, json);
free(json);
openbim_ifc_v0_1_graphs_destroy(graphs);
}openbim_ifc_v0_1_model_product_geometry(model, ids, id_count, encoding, &graphs) lowers and encodes once into a graph set, an opaque non-zero OpenbimIfcGraphs handle that owns its data and outlives the model; encoding is OPENBIM_IFC_GEOMETRY_JSON (0, UTF-8 text without a trailing NUL) or OPENBIM_IFC_GEOMETRY_CBOR (1, RFC 8949), and any other value is INVALID_ARGUMENT. openbim_ifc_v0_1_graphs_records returns its ProductGeometry records (id, global id, type name, transform, encoding, payload size, refusal); openbim_ifc_v0_1_graphs_payload copies graph index's payload, {"format":"axiolid-geometry-graph","version":"1.0", "graph":{"nodes":[...],"roots":[...]}}, after the usual size query; an index past the set is OUT_OF_RANGE, and a product with no Body or a refused one has an empty payload. openbim_ifc_v0_1_graphs_destroy frees the set. The graph is in world coordinates, metres, with the record's transform already applied. These exports make the ABI version 0.1.9; no v0_1 symbol changed. Its version is the lowest the content needs: 1.0 unless a station carries a seam-snapping window (#423), then 1.1, or a run's sections do (#429, a sectioned solid or surface along such an offset), then 1.2, or an offset run continues to a basis end the kernel measures (#433, an IfcOffsetCurveByDistances along such an offset), then 1.3, or a polygonal bounded half-space clips (#515, an IfcPolygonalBoundedHalfSpace bounded along its Position's Z), then 1.4 (axiolid/kernel#297, #301, #303, #321). A reader on axiolid-model 0.3.8 or older reads a 1.0 payload and refuses 1.1; one on 0.3.10 or older refuses 1.2, one on 0.3.11 or older 1.3, one on 0.3.13 or older 1.4, one on 0.3.17 or older 1.5. A major version of the wire format would be a breaking change of the ABI (ADR 0021).
Creating entities
/* Create an IfcBuildingElementProxy named "Proxy": the attributes are a
* LIST of (TEXT name, value) pairs, checked against the release the
* header declares; the GlobalId is generated. */
static const char names[] = "NameProxy";
OpenbimIfcValueNode attributes[4];
memset(attributes, 0, sizeof attributes);
attributes[0].kind = OPENBIM_IFC_KIND_LIST;
attributes[0].child_count = 1;
attributes[1].kind = OPENBIM_IFC_KIND_LIST;
attributes[1].child_count = 2;
attributes[2].kind = OPENBIM_IFC_KIND_TEXT; /* "Name" */
attributes[2].str_len = 4;
attributes[3].kind = OPENBIM_IFC_KIND_TEXT; /* "Proxy" */
attributes[3].str_offset = 4;
attributes[3].str_len = 5;
const char type[] = "IfcBuildingElementProxy";
uint64_t proxy = 0;
OpenbimIfcStatus status = openbim_ifc_v0_1_model_create_entity(
model, (const uint8_t *)type, strlen(type), attributes, 4, (const uint8_t *)names,
strlen(names), &proxy);openbim_ifc_v0_1_model_author creates and edits entities as one checked transaction against the release the header declares: every operation, in order, or, when any is refused, none, and the model is unchanged. An operation names the entity an earlier operation of the same batch produced by OPENBIM_IFC_HANDLE_BASE plus its position, anywhere an id goes, attribute values included, and the result holds per operation the id its entity received. openbim_ifc_v0_1_model_create_entity and openbim_ifc_v0_1_entity_remove_with_relationships are the one-operation forms. A model built from nothing needs a header naming its release first (openbim_ifc_v0_1_model_set_header).
| Operation | What it writes |
|---|---|
CREATE | one entity by type and named attributes |
EDIT | named attributes of entity; the whole entity is checked again |
REMOVE | removes entity and takes it out of every relationship; a relationship left without an end goes too |
PROJECT | the model's one Ifc_project |
SPATIAL | a spatial element of type and its Ifc_rel_aggregates under parent |
PRODUCT | a product, its Ifc_rel_contained_in_spatial_structure in container and its Ifc_rel_defines_by_type by type_object |
TYPE_OBJECT | a type object (Ifc_wall_type, ...) |
ASSIGN_TYPE, CONTAIN, AGGREGATE | one relationship; an object already related is refused unless replace (see Assigning types) |
PLACEMENT | an Ifc_local_placement over an Ifc_axis2Placement3D at location, relative to relative_to; axis and ref_direction both or neither |
OWNER_HISTORY | an Ifc_owner_history with its person, organization and application |
Every record is built by attribute name through ifc-author against the declared release, and refused with the shared codes: a type the release does not declare (unsupported-schema) or an abstract one (wrong-entity-type); an unknown name (unknown-attribute); a value of the wrong type or form, or an aggregate outside its declared bounds (invalid-value); a required attribute left unset (missing-attribute); a derived one set (derived-attribute); a reference to an entity that does not exist (missing-reference) or of a type the attribute does not accept (wrong-entity-type). An object is contained, aggregated and typed once and a model holds one IfcProject (invalid-model); a removal an entity other than a relationship still needs is still-referenced.
An IfcRoot created without a GlobalId gets a fresh one. OwnerHistory is never invented: a builder writes the one it is given on every record it creates, and IFC2X3, which requires it, refuses a record without (missing-attribute). The batch is one value tape: a LIST of operations, each a LIST of an ENUM naming it, then alternating field names (TEXT, snake case) and values. Ids are REFs, points and directions a LIST of three REALs, attributes a LIST of LIST(TEXT name, value) pairs; a NULL value is an absent field. One id per operation comes back (0 for a removal), and an id buffer shorter than the batch is BUFFER_TOO_SMALL before anything is written.
Assigning types
The type assignment propagates the type to each object when asked (#480); every option is off by default, and the operation then writes only the IfcRelDefinesByType.
| Option | What it does |
|---|---|
map_representations (BOOL) | maps each of the type's RepresentationMaps onto the object: an IfcShapeRepresentation in the map's context with its RepresentationIdentifier, RepresentationType MappedRepresentation and one IfcMappedItem, added to the object's IfcProductDefinitionShape (created when it has none) |
mapping_target | the IfcCartesianTransformationOperator every mapped item uses; by default a fresh identity operator (3D, or 2D for a 2D MappingOrigin) per object, so the geometry sits at the object's placement |
material_usage (BOOL) | derives the object's material usage from the type's set: an IfcMaterialLayerSetUsage (DirectionSense POSITIVE, OffsetFromReferenceLine 0) for a layer set, an IfcMaterialProfileSetUsage (no CardinalPoint) for a profile set, one per object in its own IfcRelAssociatesMaterial; any other material applies through the type |
layer_set_direction | the layer direction, "AXIS1" to "AXIS3" (TEXT); by default the one the IFC documentation fixes for the class: AXIS2 for IfcWall, AXIS3 for IfcSlab and IfcPlate |
predefined_type | "ignore" (default) leaves PredefinedType; "validate" refuses an object whose own value is set, not NOTDEFINED, and differs from the one the type provides (for USERDEFINED, ObjectType against the type's ElementType); "sync" unsets the object's (and its USERDEFINED ObjectType) where the type provides one, as IFC asks |
replace (BOOL) | unassigns the previous type instead of refusing: the object leaves its IfcRelDefinesByType (removed when left relating nothing), and the representations mapped from the previous type's maps and the usage derived from its set are removed with what only they use |
A type provides a PredefinedType when its own is set and not NOTDEFINED; nothing is synchronised where the object or the type has no such attribute in the declared release (IFC2X3 IfcWall, IfcDoorStyle). The containment and aggregation take replace too: the object leaves its previous container or whole, whose relationship goes when it is left relating nothing.
Refused, with the model unchanged: a representation that clashes with one the object has (same identifier, or unnamed in the same context) or a product definition shape another product shares, a contradicting PredefinedType, and an object that already has a material (invalid-model); a map whose representation is not an IfcShapeRepresentation, a type with several material associations or a usage instead of a set, and a layer set usage for a class with no documented direction when none is given (unsupported).
/* Door 1 (#100) typed again by D-90 (#111) with replace: what the old
* assignment mapped is taken back, the type's representation map is
* mapped afresh, and PredefinedType is left to the type. Wall B (#40)
* moves into the building (#13). One batch: both, or neither. */
static Builder b;
memset(&b, 0, sizeof b);
b_list(&b, 2);
b_op(&b, "ASSIGN_TYPE", 5);
b_text(&b, "type_object");
b_ref(&b, 111);
b_text(&b, "objects");
b_list(&b, 1);
b_ref(&b, 100);
b_text(&b, "map_representations"); /* also: material_usage, mapping_target */
b_bool(&b, 1);
b_text(&b, "predefined_type"); /* "ignore" (default), "validate" or "sync" */
b_text(&b, "sync");
b_text(&b, "replace");
b_bool(&b, 1);
b_op(&b, "CONTAIN", 3);
b_text(&b, "structure");
b_ref(&b, 13);
b_text(&b, "elements");
b_list(&b, 1);
b_ref(&b, 40);
b_text(&b, "replace");
b_bool(&b, 1);
uint64_t ids[2];
size_t count = 0;
if (openbim_ifc_v0_1_model_author(model, b.nodes, b.count, (const uint8_t *)b.strings, b.len, ids,
2, &count) != OPENBIM_IFC_STATUS_OK) {
print_error(model); /* without replace: INVALID_MODEL, both are related already */
return 1;
}Shape representations
The batch tape (openbim_ifc_v0_1_model_author) carries five operations: SHAPE_REPRESENTATION (context, items, optional identifier and representation_type), ASSIGN_REPRESENTATION (representation, to), UNASSIGN_REPRESENTATION (representation, from), COPY_REPRESENTATION and REMOVE_REPRESENTATION (representation).
SHAPE_REPRESENTATION assembles an IfcShapeRepresentation of existing items (built in the same batch with CREATE) in a geometric representation context or sub-context. Its representation_type is checked against the items by the release's IfcShapeRepresentationTypes (CorrectItemsForType): a mismatch, items no listed type admits, a topological item other than a vertex point, edge curve or face surface, and a missing identifier are InvalidValue; a label the release does not list is written as given. Without a type the most specific one admitting every item is inferred (SweptSolid, AdvancedSweptSolid, Brep, Clipping, CSG, Tessellation, Curve2D, Curve3D, MappedRepresentation, ...; IFC2X3 lists fewer). The identifier defaults to the context's ContextIdentifier; IFC4 and IFC4X3 require one.
A shape representation belongs to exactly one product definition shape, representation map or shape aspect (IfcShapeModel.WR11). Assigning adds it to a product's IfcProductDefinitionShape (created when missing; one several products share is refused) or wraps it in a new IfcRepresentationMap of a type, at the origin; one already used is InvalidModel. Unassigning takes it off again (an emptied product shape, or the type's map with its origin, goes) and leaves it for the batch to assign elsewhere or remove. A copy copies every item, profile, point, direction and placement it reaches and the styled items of the copied items, and shares the context, styles, colours and the type map a mapped item maps; it joins the layers of the original. Removal takes it off what uses it and removes it with its items down to what nothing else uses, by the cascade rules below; a type map an occurrence still maps is StillReferenced.
openbim_ifc_v0_1_model_remove_representation(model, id, flags, ...) is the one-operation removal; it answers the RemovalReport tape of openbim_ifc_v0_1_model_remove_product, and OPENBIM_IFC_REMOVE_DRY_RUN is its one flag.
Removing products and purging
openbim_ifc_v0_1_model_remove_product(model, id, flags, ...) removes a product, or a type object, with everything it solely owns, as one checked transaction, and answers a RemovalReport tape: removed (LIST of RemovedEntity: id, type name), kept (LIST of KeptEntity: id, type name, reason, users), detached, rebased (LISTs of REF) and applied (BOOL). OPENBIM_IFC_REMOVE_DRY_RUN only reports. The buffer protocol never applies a removal it cannot report: a size query or a short buffer plans it, answers BUFFER_TOO_SMALL with the sizes and leaves the model unchanged.
The cascade decides "solely owned" by counting references within the same transaction: an entity reached from a removed one goes when nothing that stays needs it, a relationship that only loses a list member or a presentation layer assignment not counting. It removes the product's ObjectPlacement, its representation down to the items no one else uses, the property and quantity sets only it is defined by with their properties, its material usage (not the material definitions), its openings (each with the same cascade), its ports, and every relationship left without an end. It keeps, and reports with a reason, what other entities still use (shared, with the users: a property set another wall uses, a door type's representation maps, a style or point used elsewhere), objects of their own (related-object: the type, the container, the fillings of a removed opening) and definitions it never deletes (definition: material definitions, classification references, units, contexts, the owner history).
It is STILL_REFERENCED while other placements that stay are relative to the product's placement; OPENBIM_IFC_REMOVE_REBASE_PLACEMENTS re-bases them onto the removed placement's parent instead, composing the transforms so nothing moves. A type object that still types objects is STILL_REFERENCED unless OPENBIM_IFC_REMOVE_UNTYPE_OCCURRENCES.
openbim_ifc_v0_1_model_purge(model, classes, class_lengths, class_count, flags, ...) with no classes removes every resource entity no IfcRoot reaches, nor annotates something reached; with classes, the unreferenced entities of those classes. IfcRoots and the owner history with its actors stay unless asked (OPENBIM_IFC_PURGE_INCLUDE_ROOTS, OPENBIM_IFC_PURGE_INCLUDE_OWNER_HISTORY); OPENBIM_IFC_PURGE_DRY_RUN reports without removing. The cookbook has a recipe.
openbim_ifc_v0_1_entity_remove is deprecated: it leaves references dangling. It keeps working for the life of the v0_1 ABI; use openbim_ifc_v0_1_entity_remove_with_relationships for one entity or openbim_ifc_v0_1_model_remove_product for a product.
Copying products and appending
openbim_ifc_v0_1_model_copy_product copies a product, or a type object, with what it solely owns, as one checked transaction, and returns a CopyReport: copy (REF), copied and reused (LISTs of CopiedEntity: original, copy, type name), joined, skipped and regenerated (LISTs of REF), applied (BOOL). OPENBIM_IFC_COPY_DRY_RUN only reports, and a size query plans the copy without applying it.
What the copy owns is what openbim_ifc_v0_1_model_remove_product would remove with the product, by the same reference count, and the copy copies it: the product (with a new GlobalId), its ObjectPlacement (relative to the same parent, moved by a non-null offset of three doubles in the parent's frame, or replaced by a non-zero placement), its representation (items and profiles copied; the context, styles and a type's representation maps shared), the property and quantity sets only it is defined by with their properties, its material usage (not the material definitions), its ports, and its openings and the doors and windows filling them, placed relative to the copied placements. A type object copies its own representation maps and property sets. What the removal would keep is shared: the copy joins the original's type assignment, the shared property sets, its classification, document and library references, groups and presentation layers, its spatial container and the whole it is a part of. OPENBIM_IFC_COPY_NO_OPENINGS, _NO_FILLINGS, _NO_CONTAINER and _NO_AGGREGATE leave openings, fillings, the container or the whole out. Relationships that would bind another object to the copy (a connection, a space boundary, the parts of a whole, a type's occurrences) are not carried and are listed in skipped. Entities a UNIQUE rule binds (an IfcPropertyEnumeration, an IfcApplication) are always shared.
openbim_ifc_v0_1_model_append(target, source, ids, id_count, global_ids, flags, ...) copies entities of another model into this one with what belongs to them: what they reference (a product's placement chain, representation and owner history), their property sets, type, material and classification with their relationships, their openings, fillings and ports, and what attaches to their geometry (styled items, layers). A relationship to an object that is not copied (the source's spatial container) is skipped; relate the copies afterwards. Units, contexts, the owner history, materials and styles equal to one this model holds (same type, same values all the way down) are reused instead of copied (OPENBIM_IFC_APPEND_NO_REUSE_UNITS, _CONTEXTS, _OWNER_HISTORY, _MATERIALS and _STYLES turn a kind off). GlobalIds are kept (OPENBIM_IFC_GLOBAL_IDS_KEEP, refused when this model holds one), merged (OPENBIM_IFC_GLOBAL_IDS_MERGE: an IfcRoot this model holds by GlobalId and type is that entity, and its relationships are joined), or regenerated (OPENBIM_IFC_GLOBAL_IDS_REGENERATE, or _REGENERATE_COLLIDING for those this model holds). Between releases each attribute moves by name; a type, attribute or enumeration constant the target release lacks is refused with unsupported-schema, never dropped. Models whose length or plane angle units differ are refused with unsupported: convert one with openbim_ifc_v0_1_model_convert_length_unit first. The cookbook has a recipe.
In a batch, the copy_product and copy_entity operations do the same (the copy is the operation's produced entity), and a low-level deep copy follows an entity's references by an explicit policy: classes always copied, classes always shared, and whether other IfcRoots and definitions are copied (by default shared). These exports make the ABI version 0.1.21.
Units and the model's length unit
A unit is named as UTF-8 text: an SI unit with its prefix written before it (METRE, MILLIMETRE, MILLI METRE, SQUARE_MILLIMETRE; METER spellings accepted), or a named conversion-based unit of IFC4 Table 673 with exact factors (inch, foot, yard, mile, square foot, gallon US, pound, degree ...) or US survey foot (#469).
openbim_ifc_v0_1_convert_unit(value, from, from_len, to, to_len, &out_value) converts one value and needs no model; openbim_ifc_v0_1_model_convert_unit_value(model, value, from, to, &out_value) converts between two unit entities of the model. openbim_ifc_v0_1_format_length writes a length as NUL-terminated text: OPENBIM_IFC_LENGTH_FORMAT_DECIMAL in a display unit, OPENBIM_IFC_LENGTH_FORMAT_FEET_INCHES (5' - 6 1/2", rounded to 1/places of an inch) or OPENBIM_IFC_LENGTH_FORMAT_INCHES. Units of different dimensions are TYPE_MISMATCH; a monetary, context-dependent or offset unit (degree Fahrenheit, IfcConversionBasedUnitWithOffset, not applied until #110 is settled) is UNSUPPORTED.
openbim_ifc_v0_1_model_convert_length_unit(model, target, target_len, flags, ...) converts the model's length unit and rescales every length, area and volume value the release declares as one, as one checked transaction, and answers a LengthUnitReport tape: from and to (TEXT), the length factor (REAL), the area and volume factors (REAL, NULL when that unit does not follow), the new length, area and volume unit ids, converted (LIST of ConvertedValues: entity type, attribute, kind, entities, values), kept (LIST of KeptValues: entity type, attribute, reason, values), entities changed, values converted, created and removed (LISTs of REF) and applied (BOOL). OPENBIM_IFC_LENGTH_UNIT_KEEP_AREA_AND_VOLUME leaves the area and volume units and their values; OPENBIM_IFC_LENGTH_UNIT_KEEP_REPLACED_UNITS keeps the replaced unit entities; OPENBIM_IFC_LENGTH_UNIT_DRY_RUN only reports. A size query or a short buffer plans the conversion, answers BUFFER_TOO_SMALL and leaves the model unchanged; the plan lists the ids the commit creates, so the applied report has the planned size. Values the conversion cannot carry (a parameter on a curve whose parameter space IFC leaves undefined, a p-curve off a plane, polynomial coefficients) refuse the whole call with UNSUPPORTED, each named in the last error message. These exports make the ABI version 0.1.19. The cookbook has a recipe.
Undo and redo
History is off until openbim_ifc_v0_1_model_set_history_limit(model, limit) gives it a bound on undo entries (0 turns it off and drops what is held); then every mutating export is one entry, author for its whole batch. openbim_ifc_v0_1_model_history(model, &state) fills an OpenbimIfcHistoryState (limit, undo, redo), and openbim_ifc_v0_1_model_clear_history drops the entries. openbim_ifc_v0_1_model_undo restores the model to the state before the last entry, entities under their ids and at their file positions, the header included; _model_redo reverses an undo. Both answer with a HistoryChange tape: created, removed and modified (LISTs of REF) and header (BOOL). A size query or a short buffer peeks the step and answers BUFFER_TOO_SMALL without applying it. With nothing to step through, or while history is off, the status is HISTORY_EMPTY (38), code history-empty; after a change made outside the history it is HISTORY_STALE (39), code history-stale, and the model is unchanged. Undoing a creation frees its id again. These exports make the ABI version 0.1.23.
API
The C API reference lists every type, constant, function and status code of openbim_ifc.h, generated from the header; the C cookbook has task-sized examples.