IModel abstract#

Comprehensive model management interface for creating, querying, and manipulating structured data instances with support for persistence, relationships, and schema validation.

The IModel interface provides a complete framework for managing structured data models with the following core capabilities:

Instance Management:

• Create, save, and delete instances with transactional support
• Batch operations for efficient bulk processing
• Instance tagging and categorization for organized retrieval
• Cross-model instance copying with dependency handling

Query & Retrieval:

• Flexible instance querying by type, ID ranges, and tags
• Paginated access for handling large datasets efficiently
• Hierarchical type queries including subtypes
• Reference tracking and dependency analysis

Persistence & Storage:

• Database-backed and in-memory storage options
• Automatic metadata management for performance optimization
• Export capabilities to multiple formats (ISO 10303-21, JSON, proprietary binary)
• Transactional integrity with atomic batch operations

Advanced Manipulation:

• Deep attribute access via path-based navigation
• JSON-based instance creation and manipulation
• ID resolution and consistency management
• Aggregate attribute manipulation (lists, sets, arrays)
• Complex hierarchy copying with composed dependencies

Constructors#

IModel()#

Properties#

createdAt no setter#

get creation time stamp

//int getTimeStamp();
int get createdAt;

hashCode no setter inherited#

The hash code for this object.

A hash code is a single integer which represents the state of the object that affects operator == comparisons.

All objects have hash codes. The default hash code implemented by Object represents only the identity of the object, the same way as the default operator == implementation only considers objects equal if they are identical (see identityHashCode).

If operator == is overridden to use the object state instead, the hash code must also be changed to represent that state, otherwise the object cannot be used in hash based data structures like the default Set and Map implementations.

Hash codes must be the same for objects that are equal to each other according to operator ==. The hash code of an object should only change if the object changes in a way that affects equality. There are no further requirements for the hash codes. They need not be consistent between executions of the same program and there are no distribution guarantees.

Objects that are not equal are allowed to have the same hash code. It is even technically allowed that all instances have the same hash code, but if clashes happen too often, it may reduce the efficiency of hash-based data structures like HashSet or HashMap.

If a subclass overrides hashCode, it should override the operator == operator as well to maintain consistency.

Inherited from Object.

external int get hashCode;

id no setter#

Gets the unique identifier of this model.

//String getId();
String get id;

isIfc extension no setter#

Returns true if the model is a IFC model, false otherwise.

Available on IModel, provided by the IModelExtension extension

bool get isIfc => isIfcSchema(schemaEnum);

isReference no setter#

Returns true if this is a reference model (read-only)

bool get isReference;

name no setter#

Gets the human-readable name of this model.

// String getName();
String get name;

projectId no setter#

Gets the project ID that this model belongs to.

//String getProjectId();
String get projectId;

runtimeType no setter inherited#

A representation of the runtime type of the object.

Inherited from Object.

external Type get runtimeType;

schema no setter#

Gets the schema definition used by this model.

//ISchema getSchema();
ISchema get schema;

schemaEnum no setter#

Gets the schema enumeration value for this model.

SupportedSchema get schemaEnum;

Methods#

addInstanceRef() extension#

add instance reference and clean up the old reference. and return the old referenced instance

Available on IModel, provided by the IModelExtension extension

IInstance addInstanceRef(IInstance instance, IInstance ref,
    {String? attName, int? attIndex, bool addInverse = false}) {
  if (instance.isNull || ref.isNull) {
    return createNullInstance();
  }

  final prevRef = instance.getInstance(attIndex: attIndex, attName: attName);
  IInstance prev = createNullInstance();
  if (!prevRef.isNull && prevRef.isInstanceReference) {
    prev = getInstance(prevRef.instanceHandle);
  }
  if (!prev.isNull) {
    prev.removeInverse(instance.instanceId);
  }
  instance.addInstanceRef(ref,
      attName: attName, attIndex: attIndex, addInverse: addInverse);
  return prev;
}

axis2Placement3dFromMatrix() extension#

Creates an Axis2Placement3D from a transformation matrix.

Extracts the location, axis, and reference direction from the matrix columns:

• Location: column 3 (translation component)
• Axis: column 2 (Z-axis direction)
• Reference direction: column 0 (X-axis direction)

Available on IModel, provided by the IModelExtension extension

IInstance axis2Placement3dFromMatrix(Matrix4 mat) {
  final location = mat.getColumn(3);
  final ref = mat.getColumn(0);
  final axis = mat.getColumn(2);
  return createAxis2Placement3D(
    [location[0], location[1], location[2]],
    [axis[0], axis[1], axis[2]],
    [ref[0], ref[1], ref[2]],
  );
}

canDelete()#

Checks if an instance can be safely deleted from the model.

This method performs a dependency analysis to determine if the instance can be deleted without causing referential integrity issues. It checks if any other instances in the model reference the specified instance.

Returns false if the instance is referenced by other instances, indicating that deletion would break relationships and cause database integrity problems.

Returns true otherwise

bool canDelete(IInstance instance);

clear()#

Clears all instances from the model. This completely empties the model database.

This method performs a complete wipe of all instances and associated data from the model, effectively resetting it to an empty state.

Returns true if the clear operation was successful, false otherwise.

bool clear();

copyInstance()#

Copies an instance from another model into this model.

This method creates a copy of the specified instance from the fromModel and adds it to the current model. If fromModel is null, the copy is performed within the same model.

The copy operation performs the following transformations:

• Nullifies references: All entity reference attributes in the copied instance are set to null to avoid cross-model reference issues
• Removes inverse relations: Any inverse relationship attributes are cleared to maintain referential integrity
• Resolves IDs: The copied instance receives a new consistent instance ID that fits within this model's ID allocation scheme
• if instance is a IfcRoot instance (ifc model), it is assigned a new IfcGloballyUniqueId

This method is ideal for copying simple instances without complex dependency hierarchies. For copying instances with composed dependencies, use copyInstanceWithComposedDependency instead.

Parameters:

• fromModel: The source model containing the instance to copy. If null, the copy is performed within the current model.
• instance: The instance to copy from the source model.

Returns the copied IInstance in the current model, or null instance copy fails

Example usage:

// Copy a point from another model
final otherModel = getOtherModel();
final pt = otherModel.getInstancesByType(toTypeId('cartesian_point')).first;

final copiedPt = copyInstance(otherModel, pt);
if (!copiedPt.isNull) {
  print('copiedPt copied successfully with new ID: ${copiedPt.instanceId}');
} else {
  print('Failed to copy pt');
}

See also:

• copyInstanceWithComposedDependency: For copying with dependency hierarchies
• resolveIndex: To ensure ID consistency after manual instance manipulation
• IInstance.duplicate: Alternative instance-level duplication method
• For ifc model, IIfcModel.copyChildrenWithComposedDependency : For copying from one hierarchy to another.

IInstance copyInstance(IModel fromModel, IInstance instance);

copyInstanceWithComposedDependency()#

Copies an instance along with its composed dependency hierarchy from another model.

This method performs a deep copy of the specified instance from the fromModel, including all its composed child instances and non-reference type dependencies. Unlike copyInstance, this method preserves the complete composition hierarchy by recursively copying dependent instances that are composed within the main instance.

The copy operation handles different attribute types differently:

• Reference types: Attributes marked as reference types (via isReferenceType) are not copied and remain as null references in the copied instance
• Non-reference types: Composed child instances and non-reference attributes are recursively copied to maintain the complete dependency hierarchy
• Inverses: Inverses are cleared

Parameters:

• fromModel: The source model containing the instance and its dependencies to copy. Must not be null for cross-model copying.
• instance: The root instance to copy from the source model, along with its composed dependency hierarchy.

Returns a list of IInstance objects where:

• The first element is the copy of the root instance

Returns an empty list if failed.

Example usage:

// Copy a wall with all its composed properties and geometry
final otherModel = getOtherModel();
final wallToCopy = otherModel.getInstancesByType(toTypeId('IfcWall')).first;

final copied = copyInstanceWithComposedDependency(otherModel, wallToCopy);
if (copied.isNotEmpty) {
  final copiedWall = copied[0];
  print('New wall ID: ${copiedWall.instanceId}');
  // Composition hierarchy is preserved, reference types are nullified
} else {
  print('Failed to copy wall with dependencies');
}

⚠️ Important Considerations:

• Reference type attributes will be nullified in the copied hierarchy
• All copied instances receive new consistent IDs in the target model

See also:

• copyInstance: For copying single instances without dependencies
• isReferenceType: To check which types are treated as references
• resolveIndices: To ensure ID consistency after complex copy operations
• For ifc model, IIfcModel.copyChildrenWithComposedDependency : For copying from one hierarchy to another.

List<IInstance> copyInstanceWithComposedDependency(
    IModel fromModel, IInstance instance);

createAxis2Placement2D() extension#

Creates an Axis2Placement2D from location and reference direction.

The location parameter must contain 2 coordinates. The ref parameter is optional but must contain 2 coordinates if provided. Returns a null instance if any coordinate list has an invalid length.

Available on IModel, provided by the IModelExtension extension

IInstance createAxis2Placement2D(List<double> location, [List<double>? ref]) {
  if (location.length != 2) {
    return createNullInstance();
  }
  final placement = createInstance(
      typeName: isIfc ? kIfcAxis2Placement2d : kAxis2Placement2d)
    ..setAttribute(createCartesianPoint(location), attName: 'location');
  ref ??= [1.0, 0];
  if (ref.length != 2) {
    return createNullInstance();
  }
  final refDir = createDirection(ref);
  placement.setAttribute(refDir,
      attName: isIfc ? 'refdirection' : 'ref_direction');
  return placement;
}

createAxis2Placement3D() extension#

Creates an Axis2Placement3D from location, axis, and reference direction.

The location parameter must contain 3 coordinates. The axis and ref parameters are optional but must contain 3 coordinates if provided. Returns a null instance if any coordinate list has an invalid length.

Available on IModel, provided by the IModelExtension extension

IInstance createAxis2Placement3D(List<double> location,
    [List<double>? axis, List<double>? ref]) {
  if (location.length != 3) {
    return createNullInstance();
  }
  final placement = createInstance(
      typeName: isIfc ? kIfcAxis2Placement3d : kAxis2Placement3d)
    ..setAttribute(createCartesianPoint(location), attName: 'location');
  axis ??= [0, 0, 1.0];
  if (axis.length != 3) {
    return createNullInstance();
  }
  placement.setAttribute(createDirection(axis), attName: 'axis');
  ref ??= [1.0, 0, 0];
  if (ref.length != 3) {
    return createNullInstance();
  }
  placement.setAttribute(createDirection(ref),
      attName: isIfc ? 'RefDirection' : 'ref_direction');
  return placement;
}

createCartesianPoint() extension#

Creates a Cartesian point from coordinates.

The coordinates list must contain either 2 or 3 values for 2D or 3D points respectively. Returns a null instance if the coordinate list length is invalid.

Available on IModel, provided by the IModelExtension extension

IInstance createCartesianPoint(List<double> coords) {
  final length = coords.length;
  if (length != 2 && length != 3) {
    return createNullInstance();
  }
  final inst =
      createInstance(typeName: isIfc ? kIfcCartesianPoint : kCartesianPoint)
        ..setAttribute(coords, attName: 'coordinates');
  return inst;
}

createDirection() extension#

Creates a direction vector from direction ratios.

The direction ratios list must contain either 2 or 3 values for 2D or 3D directions respectively. Returns a null instance if the ratios list length is invalid.

Available on IModel, provided by the IModelExtension extension

IInstance createDirection(List<double> coords) {
  final length = coords.length;
  if (length != 2 && length != 3) {
    return createNullInstance();
  }
  return createInstance(typeName: isIfc ? kIfcDirection : kDirection)
    ..setAttribute(coords,
        attName: isIfc ? 'DirectionRatios' : 'direction_ratios');
}

createEnum() inherited#

Creates an EXPRESS enumeration instance.

typeId: Hash-based type identifier of the enumeration typeName: EXPRESS type name of the enumeration value: Integer value to initialize the enumeration stringValue: String representation value to initialize the enumeration

Returns null enum if typeId or typeName does not correspond to a valid EXPRESS enumeration type.

Inherited from IObjectFactory.

PIEnum createEnum(
    {int? typeId, String? typeName, int? value, String? stringValue});

createHeader() extension#

Creates the header instance from PIModelHeader structure. The header instance captures all information in the header section of the Part 21 CSV file: HEADER; header information. ENDSEC; The header instance has three instance attributes:

1. file_description
2. file_name
3. file_schema

Available on IModel, provided by the IModelExtension extension

IInstance createHeader(PIModelHeader header) {
  final fileDescription =
      createInstance(typeName: 'file_description', setId: false)
        ..setAttribute(header.description, attName: 'description')
        ..setAttribute(
            header.implementation_level.isEmpty
                ? kImplementationLevel
                : header.implementation_level,
            attName: 'implementation_level');
  final fileName = createInstance(typeName: 'file_name', setId: false)
    ..setAttribute(header.name, attName: 'name')
    ..setAttribute(PIModelHeader.getTimeStamp(), attName: 'time_stamp')
    ..setAttribute(header.author.isEmpty ? [kAuthor] : header.author,
        attName: 'author')
    ..setAttribute(header.organization, attName: 'organization')
    ..setAttribute(
        header.preprocessor_version.isEmpty
            ? kProcessorVersion
            : header.preprocessor_version,
        attName: 'preprocessor_version')
    ..setAttribute(header.originating_system, attName: 'originating_system')
    ..setAttribute(header.authorization, attName: 'authorization');
  final schemas = [header.schema_identifier.toUpperCase()];
  final fileSchema = createInstance(typeName: 'file_schema', setId: false)
    ..setAttribute(schemas, attIndex: 0);
  final headerInst = createInstance(typeName: 'file_header', setId: false)
    ..setAttribute(fileDescription, attIndex: 0)
    ..setAttribute(fileName, attIndex: 1)
    ..setAttribute(fileSchema, attIndex: 2);
  headerInst.setAttribute(header.schemaEnum.index, attName: 'schema_enum');
  return headerInst;
}

createInstance() inherited#

Creates an ENTITY instance of the specified type.

typeName: EXPRESS entity type name to create typeId: Hash-based type identifier to create setId: If true, automatically assigns a new instance identifier. Set to false for header instances or when manual ID assignment is needed.

Returns a new IInstance of the requested type.

Inherited from IObjectFactory.

IInstance createInstance({String? typeName, int? typeId, bool setId = true});

createInstanceReference() inherited#

Creates an instance reference from an instance handle.

instHandle: The InstanceHandle containing reference information

Returns a lightweight reference instance pointing to the specified target.

Inherited from IObjectFactory.

IInstance createInstanceReference(InstanceHandle instHandle);

createNullInstance() inherited#

Creates a null instance representing an unset or missing value.

Returns a special IInstance that represents a null value.

Inherited from IObjectFactory.

IInstance createNullInstance();

createSelect() inherited#

Creates an EXPRESS SELECT instance.

typeId: Hash-based type identifier of the SELECT type typeName: EXPRESS type name of the SELECT type selectedType: Optional initial selected type identifier

Returns a configured ISelect instance ready for use.

Inherited from IObjectFactory.

ISelect createSelect(
    {int? typeId,
    String? typeName,
    int? selectedType,
    String? selectedTypeName});

deleteInstance()#

Removes an instance from the model and database.

This method permanently deletes the instance specified by instance handle from both the database storage. For memory-only models, the instance is removed from the in-memory collection. For database-backed models, the instance is permanently deleted from storage.

It is strongly recommended to call canDelete before using this method to ensure the instance can be safely removed without causing referential integrity issues. If an instance is referenced by other instances, deletion may orphan those references and cause database consistency problems.

Returns true if the instance was successfully deleted, or false otherwise.

bool deleteInstance(IInstance instance);

exportModel()#

Exports the model to the specified file path in the given format.

This method serializes the entire model and writes it to the specified filePath in the requested format. The export includes all instances, relationships defined in the primary schema of the model.

Supported formats:

• ExportFormat.csv: ISO 10303-21 standard (STEP Physical File format) for model exchange with other IFC/STEP-compliant applications. This is the industry standard format for data exchange.

• ExportFormat.json: Experimental JSON encoding suitable for web-based applications and REST APIs.

• ExportFormat.pib: PIComposer proprietary binary format for backup and internal model exchange within the PIComposer application ecosystem. Provides optimal performance and complete semantic preservation but is not compatible with external applications.

Parameters:

• filePath: The complete path and filename where the model should be exported. The directory must exist and be writable.
• format: The export format to use. See ExportFormat enum for options.

Returns true if the export was successful, or false otherwise Example usage:

// Export to ISO 10303-21 standard format for external exchange
final success1 = exportModel('/projects/buildingA.ifc', ExportFormat.csv);
if (success1) {
  print('Model exported to ISO 10303-21 format successfully');
  // File can now be shared with Revit, ArchiCAD, etc.
} else {
  print('ISO 10303-21 export failed');
}

// Export to JSON for web application consumption
final success2 = exportModel('/projects/buildingA.json', ExportFormat.json);
if (success2) {
  print('Model exported to JSON format successfully');
  // File can be loaded by web applications or used for debugging
} else {
  print('JSON export failed');
}

// Export to PIComposer binary for backup
final success3 = exportModel('/backups/buildingA.pib', ExportFormat.pib);
if (success3) {
  print('Model backed up to PIComposer binary format');
  // File can be quickly reloaded in PIComposer with full fidelity
} else {
  print('PIB export failed');
}

bool exportModel(String filePath, ExportFormat format);

getAttributeByPath()#

Gets an attribute value using a path specification.

This method retrieves values from deep within complex instance hierarchies by specifying a navigation path to the target attribute. It returns both the value and its fundamental type, providing complete type information for proper handling of the retrieved data.

The path can traverse through multiple levels of:

• Instance attributes (by name)
• Select type selections (using the selected type name)
• Aggregate elements (using integer indices for LIST, SET, ARRAY)

Together with setAttributeByPath and getAttributeContainer, this method provides a comprehensive way to inspect and manipulate complex instance structures without manual traversal.

Parameters:

• path: An InstancePath object specifying the navigation path to the target attribute. The path consists of a starting instance handle and a list of path components (strings for attributes, integers for aggregates).

Returns a tuple (FundamentalType, dynamic) where:

• FundamentalType: The fundamental type of the retrieved value, which determines how the value should be interpreted and handled
• dynamic: The actual value at the specified path, whose type corresponds to the fundamental type

Returns (FundamentalType.UNKNOWN, null) if:

• The path is invalid or cannot be resolved
• The target attribute does not exist
• Any intermediate object in the path is null or invalid
• The path index is out of bounds for aggregate attributes

Example usage:

// Get a nested attribute with type information
final path = InstancePath(
  wallHandle,
  ['ObjectPlacement', 'RelativePlacement', 'IfcAxis2Placement3D', 'Location']
);

final (type, value) = getAttributeByPath(path);

if (type != FundamentalType.UNKNOWN) {
  print('Found value of type: $type');
  if (type == FundamentalType.ENTITY) {
    final location = value as IInstance;
    print('Location instance: ${location.typeName}');
  }
} else {
  print('Path not found or invalid');
}

(FundamentalType, dynamic) getAttributeByPath(InstancePath path);

getAttributeByPathAsDynamic()#

Gets an attribute value using a path specification as a dynamic value.

This method retrieves values from deep within complex instance hierarchies by specifying a navigation path to the target attribute. It returns only the value without the fundamental type information, making it simpler to use when type information is not required.

This is a convenience wrapper around getAttributeByPath that discards the type information for simpler use cases.

Parameters:

• path: An InstancePath object specifying the navigation path to the target attribute. The path consists of a starting instance handle and a list of path components (strings for attributes, integers for aggregates).

Returns the value at the specified path as a dynamic value, or null if:

• The path is invalid or cannot be resolved
• The target attribute does not exist
• Any intermediate object in the path is null or invalid
• The path index is out of bounds for aggregate attributes

Example usage:

// Simple value retrieval when type is known
final path = InstancePath(
  wallHandle,
  ['Name'] // Known to be a string
);

final name = getAttributeByPathAsDynamic(path) as Option<String>?;
if (name != null) {
  print('Wall name: $name.getOrElse(() => '')');
}

dynamic getAttributeByPathAsDynamic(InstancePath path);

getHeader()#

Gets the header instance containing model metadata.

This method retrieves the header instance that contains essential metadata about the model, including file description, naming information, and schema details. The header follows the ISO 10303-21 (STEP) file structure and is typically created during model initialization.

The header instance contains three main attributes:

1. file_description - Implementation level and description
2. file_name - Name, timestamp, author, organization, and system information
3. file_schema - Schema identifiers and version information

See IModelExtension.createHeader for details on how the header structure is created and the specific information captured in each attribute.

Returns the header IInstance if it exists, or null instance.

IInstance getHeader();

getHeaderClearTextRepresentation()#

Gets the string representation of the header instance in the specified format.

This method serializes the model header information into a human-readable string format suitable for display, export, or debugging. The header contains essential metadata about the model including file description, naming information, and schema details.

Supported formats:

• ExportFormat.csv: Generates the HEADER section of an ISO 10303-21 (STEP) Part 21 file. This includes the standardized header structure with FILE_DESCRIPTION, FILE_NAME, and FILE_SCHEMA sections in the exact format required by the ISO standard.

• ExportFormat.json: Generates a JSON representation of the header information suitable for web applications, APIs, or debugging. Provides a structured hierarchical view of the header data.

Together with IInstance.getClearTextRepresentation, this method enables users to implement custom export logic by combining the header content with individual instance representations to create complete model exports.

Parameters:

• type: The export format to use. Only ExportFormat.csv and ExportFormat.json are supported for header representation.

Returns a string containing the header representation in the requested format. Returns an empty string if:

• The header instance is missing or invalid

String getHeaderClearTextRepresentation(ExportFormat type);

getInfo()#

Gets generic information about the model as a ModelInfo object.

ModelInfo getInfo();

getInstance()#

Gets an instance from the database by its persistent handle.

This method retrieves the instance corresponding to the specified instance handle from the database or in-memory storage.

For database-backed models, this may involve a database query to load the instance data. For memory-only models, this retrieves the instance from the in-memory collection.

If the handle is invalid, or refers to a non-existent instance, null instance is returned. You should always check IInstance.isNull on the returned object before using it.

IInstance getInstance(InstanceHandle instance);

getInstances()#

Gets all instance handles in the model.

This method retrieves handles for every instance currently in the model. The returned list can be used to access, process, or iterate over all instances in the model.

⚠️ Performance Warning: This method should not be used for large models as it may cause significant memory usage and performance degradation. For models containing more than a few thousand instances, use the paginated API getInstancesPaginated instead.

Returns an empty list if the model contains no instances or if the model is not properly initialized.

List<InstanceHandle> getInstances();

getInstancesByFilter()#

Gets instances filtered by ID lists and/or ID ranges for a specific type.

This method retrieves instances of the specified type that match either the explicit ids list or fall within the specified range intervals.

Parameters:

• ids: A list of specific instance IDs to retrieve. Empty list means no ID filtering.
• range: A list of IdRange objects defining inclusive ID ranges to retrieve. Empty list means no range filtering.
• type: The type ID of instances to retrieve. Use toTypeId() to convert type names.

Returns a list of IInstance objects that match the filter criteria. Returns an empty list if no instances match the filters or if the type has no instances.

List<IInstance> getInstancesByFilter(
    List<int> ids, List<IdRange> range, int type);

getInstancesByHandle()#

Gets instances from the database by their persistent handles.

List<IInstance> getInstancesByHandle(List<InstanceHandle> handles);

getInstancesByTag()#

Gets all instances with the given tag.

This method retrieves all instances that have been tagged with the specified tag string using the tagInstance method. Each instance can have only one tag at a time - setting a new tag replaces any existing tag.

Tags are not case-sensitive. The search will match tags regardless of capitalization. The method returns actual IInstance objects rather than handles, making it convenient for immediate processing of tagged instances.

Parameters:

• tag: The tag string to search for. Tag matching is case-insensitive.

Returns a list of IInstance objects that have been tagged with the specified tag (case-insensitive match). Returns an empty list if no instances have the tag.

List<IInstance> getInstancesByTag(String tag);

getInstancesByType()#

Gets all instances of a given type.

This method retrieves all instances that match the specified typeId. When includeSubType is true, it also includes instances of all subtypes that inherit from the specified type, providing a hierarchical query capability.

The returned instances are ordered according to the same sorting as getInstancesPaginated: first by typeId, then by instanceId.

Parameters:

• typeId: The type identifier to filter instances by. Use toTypeId() to convert a type name to its corresponding ID.
• includeSubType: When true, includes instances of all subtypes that inherit from the specified type. When false, returns only exact matches.

Returns a list of instance handles matching the type criteria. Returns an empty list if no instances of the specified type (and subtypes, if enabled) exist in the model.

⚠️ Performance Note: For types with many instances or deep inheritance hierarchies, this method may be expensive. Consider using paginated approaches for very large result sets by using InstanceHandle(typeId, 0) as startingHandle to call getInstancesByTypePaginated.

List<IInstance> getInstancesByType(
    {int? typeId, String? typeName, bool includeSubType = false});

getInstancesByTypePaginated()#

Gets all instances of a given type.

This method retrieves all instances that match the specified typeId. When includeSubType is true, it also includes instances of all subtypes that inherit from the specified type, providing a hierarchical query capability.

The returned instances are ordered according to the same sorting as getInstancesPaginated: first by typeId, then by instanceId.

Parameters:

• typeId: The type identifier to filter instances by. Use toTypeId() to convert a type name to its corresponding ID.
• includeSubType: When true, includes instances of all subtypes that inherit from the specified type. When false, returns only exact matches.
• pageSize: The number of return value per page, the maximum size is 2000.

Returns a list of instance handles matching the type criteria. Returns an empty list if no instances of the specified type (and subtypes, if enabled) exist in the model.

⚠️ Performance Note: For types with many instances or deep inheritance hierarchies, this method may be expensive. Consider using paginated approaches for very large result sets by using InstanceHandle(typeId, 0) as startingHandle to call getInstancesByTypePaginated.

List<IInstance> getInstancesByTypePaginated(
    InstanceHandle startHandle, int pageSize,
    {int? typeId, String? typeName, bool includeSubType = false});

getInstancesPaginated()#

Gets instances paginated for efficient handling of large models.

This method retrieves instances in manageable chunks (pages) to avoid memory overload and performance issues when working with large models. It is the recommended alternative to getInstances for models containing more than a few thousand instances.

The paging order is determined by the InstanceHandle's comparison operator, which sorts instances first by typeId and then by instanceId. This ensures consistent ordering across pagination requests.

Parameters:

• startingHandle: The handle to start pagination from. Use InstanceHandle.nullHandle() for the first page. For subsequent pages, use the last handle from the current page.
• pageSize: The number of instances to retrieve per page. Defaults to 2000, the maximum page size. Adjust based on available memory and performance requirements.

Returns a list of instance handles for the current page, sorted by typeId then instanceId. Returns an empty list when no more instances are available (end of model reached).

Example usage:

// Paginate through all instances sorted by typeId then instanceId
InstanceHandle currentHandle = InstanceHandle.nullHandle();
int totalProcessed = 0;
do {
  final pageHandles = getInstancesPaginated(currentHandle, pageSize: 250);
  if (pageHandles.isEmpty) break;
  for (final handle in pageHandles) {
    final instance = getInstance(handle);
    // do something with instance
    processInstance(instance);
    totalProcessed++;
  }
  currentHandle = pageHandles.last;
} while (true);

List<IInstance> getInstancesPaginated(InstanceHandle startingHandle,
    {int pageSize = 2000});

getInstanceTypes()#

Gets a list of all instance types that appear at least once in the model.

• sorted: When true, returns the type names in alphabetical order.

List<String> getInstanceTypes({bool sorted = false});

getLocation()#

Gets the database location/path of this model.

String getLocation();

getModelLengthUnit()#

Gets the length unit instance defined in this model's IfcUnitAssignment.

This method retrieves the length unit instance that represents the base measurement unit for all geometric data in the model. The length unit is typically defined in the model's IfcUnitAssignment and is essential for ensuring consistent interpretation of dimensional values throughout the model.

The returned instance is usually of type IfcSIUnit (e.g., METER, MILLIMETER) or IfcConversionBasedUnit for custom unit definitions.

Returns the length unit IInstance if found in the model's unit assignment. Returns null instance if error See also:

• hasSameLengthUnit: Compares length units between models

IInstance getModelLengthUnit();

getOneInstanceOfType()#

get one instance of a given type.

IInstance getOneInstanceOfType({int? typeId, String? typeName});

getReferencingInstances()#

Gets all instances that reference the specified instance.

This method performs an inverse relationship query to find all instances in the model that contain references to the specified inst.

The method is useful for:

• Dependency analysis before deleting instances
• Understanding how an instance is used throughout the model
• Identifying relationships that might be affected by instance modifications
• Debugging reference integrity issues

Parameters:

• inst: The target instance to find references for.

Returns a list of InstanceHandle objects representing all instances that reference the specified inst.

List<InstanceHandle> getReferencingInstances(IInstance inst);

getTypeCount()#

Gets the approximate count of instances of the given type.

This method returns an approximate count of instances for the specified typeId. The count is based on metadata that tracks type distributions and is optimized for performance rather than absolute accuracy. For absolutely accurate counts, use getInstancesByType.length, but note this has significant performance implications for types with many instances.

Parameters:

• typeId: The type identifier to count instances for. Use toTypeId() to convert type names to IDs.
• includeSubType: When true, includes instances of all subtypes that inherit from the specified type. When false, counts only exact matches.

Returns an approximate count of instances for the specified type. Returns 0 if the type has no instances, the type doesn't exist, or the metadata hasn't been initialized.

int getTypeCount(int typeId, {bool includeSubType = false});

hasSameLengthUnit()#

Checks if another model uses the same length unit as this model.

This method compares the length unit definition of this model with another model to determine if they use compatible measurement units. This is essential when merging models, exchanging data, or performing cross-model geometric operations to ensure dimensional consistency.

The comparison is based on the actual unit definition and conversion factors, not just unit names, ensuring accurate compatibility checking even for different unit representations that measure the same quantity.

Parameters:

• model: The other model to compare against. Must be a valid, initialized model.

Returns true if both models use the same length unit definition (equivalent measurement units) See also:

• getModelLengthUnit: Retrieves this model's length unit instance

bool hasSameLengthUnit(IModel model);

incrementTypeCount()#

Increments the type count for a specific type.

This method manually increases the metadata counter for the specified typeId. It is automatically called internally by saveInstance and saveInstances when new instances are persisted to the database, ensuring type counts are maintained for approximate counting via getTypeCount.

⚠️ Manual Use Warning: This method should generally not be called manually unless you are implementing custom instance creation logic that bypasses the standard saveInstance mechanism. Improper use can lead to inaccurate type counts and metadata inconsistencies.

Parameters:

• typeId: The type identifier to increment. Use toTypeId() to convert type names to IDs.

Returns the new count after incrementing

int incrementTypeCount(int typeId);

initialize()#

Initializes the model with the given parameters. Currently not in use.

FutureOr<void> initialize(dynamic parameter);

instanceFromJson() inherited#

Creates an instance declaratively from JSON data.

This method provides a convenient way to create IFC instances using a JSON-like structure that mirrors the object composition hierarchy. It handles the complete instantiation process including object creation, attribute setting, and relationship establishment.

The JSON structure uses special keys and conventions:

• '@type': Specifies the IFC type name for the instance (required for root objects)
• Nested objects: Represent composed child instances or complex attributes
• Arrays: Represent aggregate attributes (LIST, SET, ARRAY)
• Select types: Use the selected type name as key with object as value

Parameters:

• json: A JSON-like map representing the instance structure and attributes. The map must contain at least an '@type' key for the root object.

Returns the created IInstance, or null instance if:

• The '@type' key is missing or invalid
• The JSON structure is malformed or inconsistent
• Attribute values are incompatible with the target types

Example usage:

// Create a simple Cartesian point
final point = instanceFromJson({
  '@type': 'IfcCartesianPoint',
  'Coordinates': [1.0, 2.0, 3.0]
});

// Create property sets with complex values
final pset = instanceFromJson({
  '@type': 'IfcPropertySet',
  'Name': 'Pset_WallCommon',
  'HasProperties': [
    {
      '@type': 'IfcPropertySingleValue',
      'Name': 'Reference',
      'NominalValue': {
        'IfcSimpleValue' : {
          'IfcIdentifier': 'EXTERIOR_WALL_001'
         }
      }
    },
    {
      '@type': 'IfcPropertySingleValue',
      'Name': 'LoadBearing',
      'NominalValue': {
        'IfcSimpleValue' : {
            'IfcBoolean': true
         }
      }
    }
  ]
});

Inherited from IObjectFactory.

IInstance instanceFromJson(Map<String, dynamic> json);

isReferenceType()#

Checks if a type is a reference type (should not be composed in instance attributes).

In IFC, reference types include:

• IfcOwnerHistory, IfcPerson, IfcOrganization, IfcPersonAndOrganization
• IfcApplication, IfcProject, IfcShapeRepresentation, IfcUnitAssignment
• IfcGeometricRepresentationContext, IfcGeometricRepresentationSubContext
• IfcLocalPlacement, IfcGridPlacement, IfcTask, IfcWorkCalendar
• IfcGrid, IfcGridAxis, IfcStyledItem, IfcWorkPlan
• All subtypes of: IfcProduct, IfcObjectPlacement, IfcRelationship, IfcPresentationLayerAssignment, IfcGroup

bool isReferenceType(int typeId);

nextInstanceId() inherited#

Gets the next available instance identifier.

incrementId: If true, advances the internal ID counter after retrieval. If false, returns the next ID without changing the counter.

Returns the next available instance identifier that will be assigned.

Inherited from IObjectFactory.

int nextInstanceId([bool incrementId = false]);

noSuchMethod() inherited#

Invoked when a nonexistent method or property is accessed.

A dynamic member invocation can attempt to call a member which doesn't exist on the receiving object. Example:

dynamic object = 1;
object.add(42); // Statically allowed, run-time error

This invalid code will invoke the noSuchMethod method of the integer 1 with an Invocation representing the .add(42) call and arguments (which then throws).

Classes can override noSuchMethod to provide custom behavior for such invalid dynamic invocations.

A class with a non-default noSuchMethod invocation can also omit implementations for members of its interface. Example:

class MockList<T> implements List<T> {
  noSuchMethod(Invocation invocation) {
    log(invocation);
    super.noSuchMethod(invocation); // Will throw.
  }
}
void main() {
  MockList().add(42);
}

This code has no compile-time warnings or errors even though the MockList class has no concrete implementation of any of the List interface methods. Calls to List methods are forwarded to noSuchMethod, so this code will log an invocation similar to Invocation.method(#add, [42]) and then throw.

If a value is returned from noSuchMethod, it becomes the result of the original invocation. If the value is not of a type that can be returned by the original invocation, a type error occurs at the invocation.

The default behavior is to throw a NoSuchMethodError.

Inherited from Object.

@pragma("vm:entry-point")
@pragma("wasm:entry-point")
external dynamic noSuchMethod(Invocation invocation);

resolveIndex()#

Makes the instance's ID consistent with other instance IDs in the model.

This method ensures that the specified instance has an ID that is unique and consistent with the model's ID allocation scheme. The operation cascades recursively through the entire composition structure of the instance, including:

• All composed child instances
• All composites

This is typically used when:

• manually copying instances between models
• instance create from IInstance.duplicate resolve id consistency
• Repairing models with ID conflicts or inconsistencies

The method performs a deep resolution, ensuring that all components of the instance hierarchy have consistent IDs that won't conflict with existing instances in the model.

Parameters:

• instance: The instance to resolve. Must be a valid instance handle.

Returns true if the ID resolution was successful for the entire hierarchy, otherwise false.

bool resolveIndex(IInstance instance);

resolveIndices()#

Makes instance IDs in the list consistent with other instance IDs in the model.

This method ensures that all instances in the provided instances list have unique IDs that are consistent with the model's ID allocation scheme. The operation processes each instance and its entire composition hierarchy, similar to resolveIndex, but handles multiple instances in a single call.

Parameters:

• instances: The list of instances to resolve.

Returns true if all instances and their hierarchies were successfully resolved, or false otherwise.

bool resolveIndices(List<IInstance> instances);

resolveIndicesWithIds()#

Resolves instance IDs while mapping them using the provided ID map.

This method provides precise control over ID resolution by allowing explicit mapping of original IDs to new IDs using the provided ids mapping dictionary. For any instance ID not explicitly mapped in the ids dictionary, the method will automatically assign a new consistent ID to maintain model integrity.

The operation performs the following:

1. Reassigns instance IDs according to the provided mapping for specified IDs
2. Automatically generates consistent IDs for any unmapped instances
3. Updates all internal references within the instance hierarchies
4. Ensures consistency across the entire composition structure
5. Validates that new IDs don't conflict with existing instances in the model

Parameters:

• instances: The list of instances to resolve. These instances will have their IDs remapped according to the provided mapping or auto-assigned.
• ids: A mapping dictionary where keys are original IDs and values are the new target IDs. Instances with IDs not in this map will receive automatically generated consistent IDs.

Returns true if all instances were successfully remapped and all references updated consistently, or false otherwise.

bool resolveIndicesWithIds(List<IInstance> instances, Map<int, int> ids);

saveHeader()#

Saves the header instance to the database.

void saveHeader();

saveInstance()#

Saves an instance to the database.

This method persists the specified instance to the underlying database storage. If this is a memory-only model, the method does nothing and returns true (as memory models don't require persistence).

The optional tag parameter allows you to associate a custom tag with the instance for later retrieval using getInstancesByTag. Tags are useful for categorizing instances or marking them for specific processing.

Returns true if the instance was successfully saved (or if this is a memory model), or false if:

• The instance handle is invalid
• The database operation fails

Example usage:

final wallInstance = createInstance(typeName: 'IfcWall');
wallInstance.setString('Exterior Wall', attName: 'Name');

// Save without tag
final success1 = saveInstance(wallInstance);
if (success1) {
  print('Wall instance saved successfully');
}

// Save with tag for easy retrieval
final success2 = saveInstance(wallInstance, tag: 'exterior_walls');
if (success2) {
  print('Wall instance saved and tagged');
}

// Later retrieve by tag
final exteriorWalls = getInstancesByTag('exterior_walls');
print('Found ${exteriorWalls.length} exterior walls');

bool saveInstance(
  IInstance instance, {
  String? tag,
});

saveInstances()#

Saves multiple instances to the database in a batch operation.

This method persists a list of instances to the underlying database storage in a single transaction, which is significantly more efficient than saving instances individually. If this is a memory-only model, the method does nothing and returns true (as memory models don't require persistence).

The batch operation is atomic - either all instances are saved successfully or none are saved if an error occurs during the transaction.

Returns true if all instances were saved successfully (or if this is a memory model), or false if:

• The entire batch operation fails
• The database transaction cannot be completed

Example usage:

// Create multiple instances
final wall1 = createInstance(typeName: 'IfcWall')..setString('Wall 1', attName: 'Name');
final wall2 = createInstance(typeName: 'IfcWall')..setString('Wall 2', attName: 'Name');
final wall3 = createInstance(typeName: 'IfcWall')..setString('Wall 3', attName: 'Name');

final instancesToSave = [wall1, wall2, wall3];

// Save in batch for better performance
final success = saveInstances(instancesToSave);

if (success) {
  print('All ${instancesToSave.length} instances saved successfully in batch');
} else {
  print('Batch save operation failed - no instances were saved');
  // All instances remain unchanged and need to be handled individually
}

bool saveInstances(List<IInstance> instances);

saveMetaData()#

Saves metadata to the database.

This method persists model metadata to the database, including:

• Entity types present in the model
• Instance counts for each entity type
• Schema version information
• Model statistics and usage metrics

Metadata is used for efficient querying, reporting, and model analysis. It enables quick access to model composition without scanning all instances.

This method is called automatically in several scenarios:

• During saveInstances operations to keep metadata synchronized
• During database shutdown (Project.Uninitialize) to ensure final persistence

If this is a memory-only model, the method does nothing and returns true (as memory models don't require persistence).

Returns true if the metadata was successfully saved (or if this is a memory model), or else false.

While called automatically, you may want to call this method explicitly:

• After bulk operations that bypass normal save mechanisms
• Before generating reports that rely on accurate type counts
• When manually modifying instance counts or model composition

bool saveMetaData();

setAttributeByPath()#

Sets an attribute value using a path specification.

This method allows precise modification of nested attributes within complex instance hierarchies by specifying a path to the target attribute. The path can traverse through multiple levels of object composition, aggregate elements, select type selections and across instance boundaries.

The path follows the same structure as IInstance.setAttributeByPath, allowing you to navigate through:

• Instance attributes (by name)
• Select type selections (using the selected type name)
• Aggregate elements (using integer indices for LIST, SET, ARRAY)

Together with getAttributeByPath and getAttributeContainer, this method provides a powerful way to manipulate complex instance structures without needing to manually traverse and extract intermediate objects.

Parameters:

• path: An InstancePath object specifying the navigation path to the target attribute. The path consists of a starting instance handle and a list of path components (strings for attributes, integers for aggregates).
• value: The value to set. The type must be compatible with the target attribute's fundamental type. For instance attributes, this can be an IInstance, ISelect, or primitive value. For aggregate elements, it must match the aggregate's element type.

Returns true if the attribute was successfully set, or false if:

• The path is invalid or cannot be resolved
• The target attribute does not exist
• The value type is incompatible with the target attribute
• The path traverses through null or invalid intermediate instance

Example usage:

// Set a nested attribute in a complex hierarchy
final attPath = ['RelativePlacement', 'IfcAxis2Placement2D', 'RefDirection'];
final handle = getInstancesByType(toTypeId('IfcLocalPlacement')).first;
final path = InstancePath(handle, attPath);

final refDir = instanceFromJson({
  '@type': 'IfcDirection',
  'DirectionRatios': [1.0, 0.0]
});

final success = setAttributeByPath(path, refDir);
if (success) {
  print('Reference direction set successfully');
} else {
  print('Failed to set reference direction');
}

bool setAttributeByPath(InstancePath path, dynamic value);

setAttributeByPathWithJson()#

Sets an attribute value using both path specification and JSON data.

This method combines the functionality of setAttributeByPath and JSON-based instance creation to provide a powerful way to set complex nested attributes using a declarative JSON structure. It navigates to the target attribute using the specified path and sets its value using the provided json data.

The method handles the complete process:

1. Navigates through the instance hierarchy using the provided path
2. Creates appropriate values from the JSON data (including nested instances)
3. Sets the target attribute to the created value(s)

This is particularly useful for setting complex attributes that require creating nested object hierarchies or select type values.

Parameters:

• path: An InstancePath object specifying the navigation path to the target attribute where the JSON value should be set.
• json: A JSON-like map representing the value to set. The structure follows the same conventions as instanceFromJson, including support for: - '@type' key for entity instances
  • Nested objects for complex attributes
  • Arrays for aggregate values
  • Select type specifications

Returns true if the attribute was successfully set using the JSON data, or false if:

• The path is invalid or cannot be resolved
• The JSON structure is malformed or incompatible with the target attribute
• The target attribute cannot accept the created value type
• Any intermediate object in the path is null or invalid

Example usage:

// Set a complex placement attribute using JSON
final placementPath = InstancePath(wallHandle, ['ObjectPlacement', 'RelativePlacement',
   'IfcAxis2Placement3D', 'Location']);
final success = setAttributeByPathWithJson(placementPath, {
      '@type': 'IfcCartesianPoint',
      'Coordinates': [10.0, 5.0, 3.0]
});

if (success) {
  print('Complex placement hierarchy created and set successfully');
} else {
  print('Failed to set placement from JSON');
}

See also:

• setAttributeByPath: Sets attribute using direct value assignment
• instanceFromJson: Creates complete instances from JSON data
• getAttributeByPath: Retrieves values using path specification

bool setAttributeByPathWithJson(InstancePath path, Map<String, dynamic> json);

setInstanceRef() extension#

Available on IModel, provided by the IModelExtension extension

IInstance setInstanceRef(IInstance instance, IInstance ref,
    {String? attName, int? attIndex, bool addInverse = false}) {
  if (instance.isNull || ref.isNull) {
    return createNullInstance();
  }

  final prevRef = instance.getInstance(attIndex: attIndex, attName: attName);
  IInstance prev = createNullInstance();
  if (!prevRef.isNull && prevRef.isInstanceReference) {
    prev = getInstance(prevRef.instanceHandle);
  }
  if (!prev.isNull) {
    prev.removeInverse(instance.instanceId);
  }
  instance.setInstanceRef(ref,
      attName: attName, attIndex: attIndex, addInverse: addInverse);
  return prev;
}

setNextInstanceId() inherited#

Sets the next instance identifier to use.

nextId: The next instance identifier value to set.

Use with caution: Setting this value affects all subsequent instance creations and may cause identifier conflicts if not managed carefully.

Inherited from IObjectFactory.

void setNextInstanceId(int nextId);

tagInstance()#

Tags an instance with the specified tag string.

This method assigns a tag to the specified instance. Each instance can have only one tag at a time - calling this method with a new tag will replace any existing tag on the instance.

Tags are not case-sensitive. The tag string will be stored and matched in a case-insensitive manner. However, the exact case used when setting the tag may be preserved for display purposes.

To remove a tag from an instance, use an empty string ('') as the tag parameter.

Parameters:

• instance: The instance to be tagged
• tag: The tag string to assign. Use '' to remove existing tags.

Returns true if the tag was successfully assigned, or false otherwise.

bool tagInstance(IInstance instance, String tag);

toString() inherited#

A string representation of this object.

Some classes have a default textual representation, often paired with a static parse function (like int.parse). These classes will provide the textual representation as their string representation.

Other classes have no meaningful textual representation that a program will care about. Such classes will typically override toString to provide useful information when inspecting the object, mainly for debugging or logging.

Inherited from Object.

external String toString();

uninitialize()#

Uninitializes the model, releasing resources. Currently not in use.

FutureOr<void> uninitialize();

updateModelInfo()#

update model info. ModelInfo is derived from model header, the mutable values are: name and tag.

bool updateModelInfo(String name, String tag);

Operators#

operator ==() inherited#

The equality operator.

The default behavior for all Objects is to return true if and only if this object and other are the same object.

Override this method to specify a different equality relation on a class. The overriding method must still be an equivalence relation. That is, it must be:

• Total: It must return a boolean for all arguments. It should never throw.

• Reflexive: For all objects o, o == o must be true.

• Symmetric: For all objects o1 and o2, o1 == o2 and o2 == o1 must either both be true, or both be false.

• Transitive: For all objects o1, o2, and o3, if o1 == o2 and o2 == o3 are true, then o1 == o3 must be true.

The method should also be consistent over time, so whether two objects are equal should only change if at least one of the objects was modified.

If a subclass overrides the equality operator, it should override the hashCode method as well to maintain consistency.

Inherited from Object.

external bool operator ==(Object other);