Tool for building a better world.

Introduction

.1. PIComposer Store: Store Management API

.1.1. Introduction

The Store Management API provides a comprehensive interface for managing projects and their metadata within the Blockly-based development environment. This API enables developers to perform essential CRUD (Create, Read, Update, Delete) operations on projects, manage project information, handle backups, and interact with template systems. The API is exposed through Blockly blocks that generate corresponding Dart code, allowing visual programming while maintaining type safety and proper data management patterns.

The store acts as a centralized repository for all project-related data, supporting operations such as project creation, retrieval, deletion, and metadata management. Each project contains both its core data and associated metadata (project info), which includes identifiers, descriptive information, creator details, and timestamps. The API also provides functionality for backup restoration and template management, making it suitable for applications requiring robust project lifecycle management.

.1.2. Usage Notes and Best Practices

Project Lifecycle Management

  1. Project Creation: Use store_create_project to create new projects with descriptive names and descriptions. The returned PIProject object contains the loaded project database.

  2. Project Retrieval: store_get_project automatically loads the project database upon retrieval, eliminating the need for separate initialization calls.

  3. Project Deletion: Both single-project (store_delete_project) and bulk deletion (store_delete_projects) operations are available. Use caution with bulk deletion as it’s irreversible.

Project Information vs. Project Data

  • Project Information (ProjectInfo): Contains metadata about projects accessible via store_get_project_info and store_get_project_infos.

  • Project Data (PIProject): Contains the actual project content and database, accessed via store_get_project.

  • These are separate entities; modifying project info does not affect project data and vice versa.

Type Safety Considerations

  • The store_project_info_setter block enforces type matching between input values and field types. Ensure string values for string fields and numeric values for numeric fields.

  • Store blocks use strict type checking (setCheck() methods) to prevent runtime errors.

Null Store Handling

  • Use store_create_null_store for initialization or when a store reference is required but no actual store exists.

  • Check store validity with store_is_null before performing operations to avoid null reference errors.

  • The store_get_store function typically returns the active store for the current execution context.

Template System Integration

  • The template manager (store_get_template_manager) provides access to project templates, enabling template-based project creation and management.

  • Template operations are separate from project operations and may require additional permissions or context.

Backup and Restoration

  • Backup restoration requires both project ID and backup ID, indicating a robust backup management system.

  • The restore function returns a boolean success indicator; implement appropriate error handling based on this return value.

  • Backup operations typically create immutable copies, while restoration creates new project instances from backup data.

Performance Considerations

  • store_get_project_infos returns all project metadata at once; for large project collections, consider implementing pagination or filtering at the application level.

  • Project count retrieval (store_get_project_count) is a lightweight operation suitable for UI updates and conditional logic.

  • Database loading occurs automatically with store_get_project, which may have performance implications for large projects.

Error Handling Patterns

  • Most functions return null or empty values for non-existent entities rather than throwing exceptions.

  • Check return values before using project objects to handle "not found" scenarios gracefully.

  • Implement try-catch blocks around store operations in the generated Dart code for production applications.

This API provides a comprehensive foundation for building applications with complex project management requirements, supporting everything from simple project tracking to advanced template-based workflows and backup systems.

.1.3. Block Reference

Section Block Generated Function Description

Project Operations

store delete project

deleteProject(projectId)

delete the project with the given id, returns true if success. Delete is not allow if a project has any backup.

Project Operations

store delete projects

deleteProjects()

delete projects in data store. Return the deleted count. Any project with backup will not be deleted.

Project Operations

store create project

createProjectExt(name, description)

Creates a new project with the specified name and description, returning the created project object.

Project Operations

store get project

getProject(projectId)

Retrieves a project from the store by its ID, automatically loading its database. Returns null if the project doesn’t exist.

Project Information

store get project info

getProjectInfo(projectId)

Retrieves metadata information about a specific project.

Project Information

store get project infos

getProjectInfos()

Gets metadata information for all projects in the store as an array.

Project Information

store project info getter

Dynamic field access

  • id

  • name

  • description

  • …​

Accesses specific fields from a project info object using dropdown selection.

Store Management

store create null store

nullStore()

Creates a null or empty store instance, typically used for initialization, testing, or as a default value.

Store Management

store is null

isNull (property)

Checks whether a store instance is null or uninitialized.

Store Management

store get store

getStore()

Retrieves the main or default store instance for the current context.

Template Management

store get template manager

getTemplateManager()

Gets the template manager associated with the store for template-related operations.

Backup Management

store restore project from backup

restoreProjectFromBackup(projectId, backupId)

Restores a project from a backup using both the project ID and backup ID. Returns boolean indicating success.

Utility Functions

store get project count

getProjectCount()

Returns the total number of projects currently stored.

.2. Template Management API Documentation

.2.1. Introduction

The Template Management API provides a comprehensive system for creating, managing, and instantiating templates within the Blockly-based development environment. This API enables developers to work with reusable template components across different schema standards (AP203, AP210, AP214, AP242, CIS2, IFC4x3) and template types, including entity templates, procedural templates, transform templates, and various specialized template categories.

Templates serve as reusable blueprints for creating instances in models, supporting a wide range of applications from simple entity definitions to complex procedural models and transformations. The API provides full lifecycle management including template creation, storage, retrieval, filtering, and file-based import/export operations. Each template is associated with a TemplateInstanceHandle that provides access to template metadata and properties.

.2.2. Usage Notes and Best Practices

Template Types and Schemas

  • Supported Template Types: The system supports 11 template types including user-defined enums, spatial templates, property/quantity sets, entity templates, procedural entities/models, transform templates, and timer/generic procedures.

  • Schema Standards: Templates can be associated with industry standards including AP203, AP210, AP214, AP242, CIS2, and IFC4x3 schemas.

  • Type Conversion: Note that getTemplatesByType() and getTemplatesByTag() automatically call .toTypeId() on the input values, requiring proper type ID formatting.

Template Lifecycle Management

  1. Creation: Templates can be created either from scratch using createTemplate() with a type specification, or from existing instances using createTemplateTransform().

  2. Storage: Use saveTemplate() to persist templates to the database. Each template receives a unique TemplateInstanceHandle.

  3. Retrieval: Templates can be retrieved individually by handle or filtered by various criteria (type, tag, schema).

  4. Deletion: Templates are deleted by their handle using deleteTemplate().

Template Instantiation

  • Instantiation Process: Use instantiate() on a template instance to create actual instances within a model.

  • Result Access: After instantiation, use getInstantiatedRootInstance() and getInstantiatedItems() to access the created instances.

  • Model Requirements: Instantiation requires a valid model context (PIModel, PIIfcModel, or PISTPModel).

File-Based Operations

  • Export: saveTemplatesToFile() allows exporting template collections to external files for backup or sharing.

  • Import/Export: Two import methods are available - loadTemplatesFromFile() (returns array) and importTemplatesFromFile() (imports into system).

  • File Format: The file operations imply a structured template serialization format, though the specific format is not detailed in the API.

Procedure Templates

  • Procedure Functions: Specialized templates (procedural entities, model procedures, transform functions) have associated procedure functions.

  • Function Retrieval: getProcedureForTemplate dynamically calls the appropriate procedure function based on template type.

  • Null Handling: Returns null if the template doesn’t exist, requiring null-checking in calling code.

Filtering and Searching

  • Combined Filters: Use getTemplatesByTagSchema() for precise filtering by both tag and schema.

  • Schema-Based: getTemplatesBySchema() retrieves all templates for a specific industry standard.

  • Type-Based: getTemplatesByType() filters by template type category.

  • Performance: For large template collections, consider using specific filters rather than retrieving all templates.

Error Handling and Validation

  • Input Validation: Most functions check for valid input lengths before generating code, returning empty strings for invalid inputs.

  • Type Safety: The blocks enforce type checking through setCheck() methods on inputs.

  • Null Returns: Functions that retrieve data return empty results rather than throwing exceptions for missing entities.

Template Instance Handles

  • Handle Properties: Access template metadata through .instanceId, .typeId, and .schema properties on TemplateInstanceHandle objects.

  • Handle Lifetime: Template handles remain valid as long as the template exists in the system.

  • Handle Usage: Use handles for all template operations except initial creation.

Integration with Store API

  • Template Manager Retrieval: Templates are managed through a PITemplateManager, which is typically retrieved via store_get_template_manager from the Store API.

  • System Integration: Templates are stored within the project/store system, ensuring persistence across sessions.

This API provides a robust foundation for template-driven development, enabling reusable component creation across multiple industry standards and application domains.

.2.3. Block Reference

Section Block Generated Function Description

Template Access

template templateinstancehandle access

Dynamic property access

  • instanceId

  • typeId

  • schema

Access template instance handle properties including instance ID, type ID, and schema information.

Template Handle

template templatehandle from json

TemplateInstanceHandle.fromJson()

Create a template handle from json(.@type, .instanceid, .schema).

Template Handle

template templatehandle from template

blocklyHandle

get template handle from template.

Template Creation

template create template of type

createTemplate(templateType)

Create a new template of the specified type using the template manager.

Template Creation

template create entity template

createTemplateTransform(model, instance)

Create an entity template from an existing instance within a model.

Template Persistence

template save template

saveTemplate(template)

Save a template to the database using the template manager.

Template Persistence

template delete template

deleteTemplate(templateHandle)

Delete a template from the database using its handle.

Template Retrieval

template get template

getTemplate(templateHandle)

Retrieve a template from the database using its handle.

Template Filtering

template get templates by tag schema

getTemplatesByTagSchema(tag, schema)

Retrieve templates filtered by both tag and schema type.

Template Filtering

template get templates by schema

getTemplatesBySchema(schema)

Retrieve templates filtered by schema type only.

Template Filtering

template get templates by type schema

getTemplatesByTypeSchema(type.toTypeId(), schema)

Retrieve templates filtered by type and schema.

Template Filtering

template get templates by type

getTemplatesByType(type.toTypeId())

Retrieve templates filtered by type only.

Template Filtering

template get templates by tag

getTemplatesByTag(tag.toTypeId())

Retrieve templates filtered by tag only.

Template Listing

template get template handles

getTemplateHandles()

List all template handles available in the system.

Template Listing

template get all templates

getTemplates()

List all template objects available in the system.

Procedure Management

template get procedure for template

Dynamic procedure function call

Get the procedure function for a template by ID, returns the template procedure function.

Template Instantiation

template instance template instantiate

instantiate(model)

Instantiate an instance template and save it in the specified model.

Instantiation Results

template get instance template instantiated root

getInstantiatedRootInstance()

Get the root instance created when instantiating a template.

Instantiation Results

template get instance template instantiated items

getInstantiatedItems()

Get all instantiated instances for a template (first item is root if present).

File Operations

template save templates to file

saveTemplatesToFile(templates, filepath)

Save a collection of templates to an external file.

File Operations

template load templates from file

loadTemplatesFromFile(filepath)

Load templates from an external file (returns array).

File Operations

template import templates from file

importTemplatesFromFile(filepath)

Import templates from an external file into the system.

1. Schema Management API Documentation

1.1. Introduction

The Schema Management API provides access to industry-standard schema definitions and their structural metadata within the Blockly-based development environment. This API enables developers to work with standardized schema systems including AP203, AP210, AP214, AP238, AP242, CIS2, and IFC4x3, which are commonly used in CAD, engineering, and building information modeling (BIM) applications.

The API focuses on schema introspection and descriptor retrieval, allowing programs to dynamically query entity definitions, attribute structures, enumerated types, select types, and defined types. Each schema provides a rich type system with descriptors that expose metadata about entities, their attributes, inheritance hierarchies, and type characteristics. This enables type-safe operations, validation, and dynamic entity creation based on schema definitions.

2. Usage Notes and Best Practices

2.1. Schema Standards Support

  • Supported Schemas: The system supports major industry standards including STEP AP203, AP210, AP214, AP238, AP242, CIS2, and IFC4x3.

  • Schema Enumeration: Use SupportedSchema enum values (e.g., SupportedSchema.ap203, SupportedSchema.ifc4x3) to reference specific schemas.

  • Schema Objects: Each schema (PISchema) provides access to its complete type system and descriptor hierarchy.

2.2. Type ID Conversion

  • String to TypeId: Most descriptor retrieval functions automatically convert string type names to TypeId using .toTypeId() method.

  • Exception: getComplexEntityDescriptor() accepts a List<String> directly without .toTypeId() conversion.

  • Type Safety: TypeId conversion ensures type-safe operations and prevents runtime errors from invalid type names.

2.3. Descriptor Hierarchy

  • EntityDescriptor: Describes entities with attributes, inheritance, and structural metadata.

  • SelectDescriptor: Describes SELECT types that can be one of several possible types.

  • EnumDescriptor: Describes enumerated types with predefined value sets.

  • TypeDescriptor: Describes defined (typedef) types.

  • AttributeDescriptor: Describes individual attributes within entity descriptors.

2.4. Property Access Patterns

  • Dynamic Property Access: Accessor blocks use dropdowns to select from available properties for each descriptor type.

  • Property Types: Return types vary by property (strings, numbers, booleans, arrays, or specialized types like FundamentalType).

  • Null Output: Accessor blocks have null output type, requiring type inference based on property selection.

2.5. Complex Entity Descriptors

  • Type Lists: getComplexEntityDescriptor() accepts a List<String> of type names to create combined descriptors.

  • Use Cases: Useful for queries that need to match multiple entity types or create flexible type constraints.

  • AND/OR Logic: The "complex" descriptor likely combines types using logical operations (AND/OR) for flexible matching.

2.6. Attribute Descriptor Access

  • Two-Step Process: getAttributeDescriptor() first calls getAttributeIndex() to locate the attribute by name, then retrieves the descriptor.

  • Attribute Indexing: This pattern suggests attributes are indexed internally for performance optimization.

  • Error Handling: Invalid attribute names are handled at the getAttributeIndex() stage.

2.7. Select Type System

  • Selectable Types: SELECT types define sets of allowable types for an attribute.

  • Fundamental Type Resolution: Use getSelectableFundamentalType() to determine the underlying fundamental type for selectable items.

  • Type Flexibility: SELECT types provide polymorphism within strongly-typed schemas.

2.8. Schema Introspection Workflow

  1. Get Schema: Start with getSchemaByEnum() to obtain the desired schema instance.

  2. Retrieve Descriptors: Use appropriate get*Descriptor() methods for the needed type information.

  3. Access Properties: Use accessor blocks to query specific descriptor properties.

  4. Handle Results: Process descriptor data for validation, UI generation, or dynamic entity creation.

2.9. Performance Characteristics

  • Descriptor Caching: Descriptors are automatically cached upon first access, ensuring subsequent retrievals are efficient.

  • Optimized Storage: Schema data uses efficient binary storage with fast lookup capabilities.

  • Memory Efficiency: The system minimizes memory footprint while providing fast access through shared descriptor instances.

  • Type ID Optimization: Internal integer Type IDs enable rapid descriptor resolution compared to string-based lookups.

  • Indexed Attributes: Attributes are indexed within entity descriptors for efficient access by name.

2.10. Error Handling

  • Invalid Type Names: Functions return appropriate null or error values for non-existent type names.

  • Missing Attributes: getAttributeIndex() handles missing attribute names gracefully.

  • Schema Availability: Ensure requested schemas are available in the runtime environment.

2.11. Integration with Other APIs

  • Template System: Schema descriptors work with the Template API for type-safe template creation.

  • Entity Creation: Use descriptor information to create properly typed entities in models.

  • Validation: Leverage schema metadata for runtime validation of entity structures and attributes.

  • Code Generation: Descriptor metadata supports automated code generation and documentation.

3. Implementation Advantages

The schema system is designed for high-performance access to standardized schema definitions:

  • Binary Efficiency: Schema definitions are stored in optimized binary format for minimal memory usage and fast loading

  • Intelligent Caching: All descriptor types are cached upon first retrieval with automatic memory management

  • Optimized Lookups: Internal indexing and integer-based Type IDs ensure rapid descriptor resolution

  • Scalable Architecture: Efficiently handles large schemas with thousands of entity definitions

  • Consistent Performance: Caching ensures predictable performance across repeated operations

This API provides comprehensive schema introspection capabilities, enabling dynamic, type-safe operations across multiple industry standards. The descriptor system exposes rich metadata that supports validation, code generation, and intelligent entity manipulation within engineering and BIM applications while maintaining optimal performance through intelligent caching and efficient data structures.

3.1. Block Reference

Section Block Image Generated Function Description

Schema Access

Schema Get Schema Block

getSchemaByEnum(schemaEnum)

Get the schema object as specified by SupportedSchema enum.

Entity Descriptors

Get Entity Descriptor Block

getEntityDescriptor(type)

Get entity descriptor of a given type in schema.

Entity Descriptors

Get Complex Entity Descriptor Block

getComplexEntityDescriptor(types)

Get complex entity descriptor for a list of type names.

Select Descriptors

Get Select Descriptor Block

getSelectDescriptor(type)

Get select descriptor for a specific type.

Enum Descriptors

Get Enum Descriptor Block

getEnumDescriptor(type)

Get enum descriptor for a specific enumerated type.

Type Descriptors

Get Type Descriptor Block

getTypeDescriptor(type)

Get defined type descriptor for a specific type.

Entity Descriptor Properties

Entity Descriptor Accessor Block

Dynamic property access

  • type

  • typeId

  • baseType

  • …​

Access properties from an EntityDescriptor object.

Attribute Descriptor Access

Get Attribute Descriptor Block

getAttributeDescriptor(getAttributeIndex(attributeName))

Get an AttributeDescriptor by name from an EntityDescriptor.

Select Descriptor Properties

Select Descriptor Accessor Block

Dynamic property access

  • type

  • typeId

  • referenceType

  • …​

Access properties from a SelectDescriptor object.

Select Type Resolution

Selectable Fundamental Type Block

getSelectableFundamentalType(typeId)

Get the fundamental type for a selectable type ID from a SelectDescriptor.

Type Descriptor Properties

Type Descriptor Accessor Block

Dynamic property access

  • type

  • typeId

  • baseType

  • …​

Access properties from a TypeDescriptor object.

Enum Descriptor Properties

Enum Descriptor Accessor Block

Dynamic property access

  • type

  • typeId

  • baseType

  • …​

Access properties from an EnumDescriptor object.

Attribute Descriptor Properties

Attribute Descriptor Accessor Block

Dynamic property access

  • attributeName

  • attributeTypeId

  • baseType

  • …​

Access properties from an AttributeDescriptor object.

Project API Block Reference

4. Introduction

The Project API provides comprehensive functionality for managing PI (Product Information) projects within the Blockly visual programming environment. This API enables users to create, manipulate, and maintain engineering data projects containing multiple models with different schemas (AP203, AP210, AP214, AP242, CIS2, IFC4X3).

Key capabilities include: * Project Management: Create, activate, close, and update project metadata * Model Operations: Add, remove, import, and query models within projects * Schema Support: Handle multiple industry-standard schemas for different engineering domains * Backup System: Create, retrieve, and manage project backups with version control * Memory Models: Create transient in-memory models for temporary operations * Reference Models: Import files as reference models for external data integration

The API is designed to work with the PI Platform’s data model system, providing a visual interface for complex data management operations typically performed programmatically.

5. Usage Notes

5.1. Project Lifecycle Management

  • Always activate projects before performing operations using activateProject()

  • Close projects properly after operations using closeProject() to ensure data integrity

  • Check project state with isActivated() before critical operations

  • Validate project references with isNull to avoid null pointer exceptions

5.2. Model Operations Best Practices

  • Schema Selection: Choose appropriate schema for your data type:

    • AP203/AP214/AP242: Mechanical CAD data

    • AP210: Electronic assembly data

    • AP238: NC machining data

    • CIS2: Construction industry data

    • IFC4X3: Building information modeling

  • Tagging Strategy: Use consistent tagging for model organization

  • ID Management: Model IDs should be unique and persistent

  • Import Considerations: Reference models are read-only; regular imports create editable copies

5.3. Backup System Guidelines

  • Regular Backups: Use createBackup() before major changes

  • Descriptive Names: Provide meaningful descriptions for backup identification

  • Cleanup Policy: Implement purgeOldBackups() to manage disk space

  • Backup Verification: Always check backup success with returned BackupInfo

5.4. Memory Model Usage

  • Temporary Operations: Use memory models for calculations or transformations

  • No Persistence: Memory models are not saved automatically

  • Performance: Memory operations are faster but limited by available RAM

  • Cleanup: Memory models are garbage collected when no longer referenced

5.5. Error Handling

  • Null Checks: Always verify objects are not null before method calls

  • Validation: Check input parameters meet requirements (non-empty strings, valid IDs)

  • Exception Handling: Wrap operations in try-catch blocks for production code

  • State Verification: Confirm project is activated before model operations

5.6. Performance Considerations

  • Batch Operations: Use bulk methods when processing multiple models

  • Selective Loading: Activate only necessary projects

  • Memory Management: Clean up memory models when no longer needed

  • Backup Strategy: Balance backup frequency with storage constraints

This API provides a comprehensive visual interface for PI project management, enabling both novice and expert users to perform complex data operations through intuitive Blockly blocks.

6. API Reference Table

Section Block Image Generated Function Description

Model Creation

Create Model Block

createModelEx(SupportedSchema.schema, name, description, tag)

Creates new model in project with schema and metadata

Model Import

Import Model Block

importModel(filePath, modelId, asReference)

Imports model file into project with options

Model by ID

Get Model by ID Block

getModel(modelId)

Retrieves a specific model by ID

All Model Infos

All Model Infos Block

modelInfos()

Returns a list of all model information

Models by Tag

Models by Tag Block

getModelInfosByTag(tag)

Returns model information filtered by tag

Models by Schema

Models by Schema Block

getModelsBySchema(SupportedSchema.schema)

Returns models filtered by schema

Schema in Project

Schema in Project Block

getModelSchemas()

Returns all model schema enum

Model Count

Model Count Block

getModelCount()

Returns total number of models

Model Deletion

Delete Model Block

deleteModel(modelId)

Delete a model by ID from project

Bulk Deletion

Bulk Delete Block

deleteModels()

Deletes ALL models from project

Project Activation

Activate Project Block

activateProject()

Activates and loads project

Project Closure

Close Project Block

closeProject()

Closes and deactivates project

Status Check

Status Check Block

isActivated()

Checks if project is activated

Null Check

Null Check Block

isNull

Checks if project object is null

Null Project

Null Project Block

PIProject.nullProject()

Creates empty/null project object

Project Update

Update Project Block

updateProject(name, description)

Updates project name and description

Project Info

Project Info Block

getInfo()

Returns project metadata

Memory Model

Memory Model Block

PIProject.createMemoryModel(id, SupportedSchema.schema)

Creates transient in-memory model

Memory Reference

Memory Reference Block

PIProject.createMemoryReferenceModel(filePath)

Creates transient reference from STEP

Backup Creation

Create Backup Block

createBackup(description)

Creates backup of project

Backup Info

Backup Info Block

getBackupInfo(backupId)

Returns backup info for ID

All Backups

All Backups Block

getBackupInfos()

Returns array of all backups

Backup Delete

Delete Backup Block

deleteBackup(backupId)

Deletes specific backup

Backup Cleanup

Purge Backups Block

purgeOldBackups(backupCount)

Purges old backups, keeps recent

7. Model API Overview

The Model API provides a comprehensive set of tools for creating, managing, querying, and manipulating model data within the Blockly visual programming environment. This API enables developers to work with structured data models, instances, and their relationships through an intuitive graphical interface.

7.1. Key Features

  • Instance Management: Create, read, update, and delete model instances

  • Type System: Support for different instance types including references, selects, and enums

  • Query Capabilities: Advanced filtering by type, tags, and relationships

  • Pagination: Efficient handling of large datasets through paginated queries

  • Model Operations: Export, import, copying, and comparison between models

  • Metadata Management: Comprehensive model information and property access

7.2. Architecture Principles

The Model API follows these design principles:

  1. Type Safety: All blocks enforce type checking through Blockly’s type system

  2. Consistency: Similar operations follow consistent patterns across the API

  3. Error Resilience: Functions return appropriate defaults or boolean indicators for error conditions

  4. Performance: Paginated queries and batch operations for handling large datasets

7.3. Core Concepts

7.3.1. Model

A container for instances and metadata. Models can be: * PIModel: Standard model type * PIIfcModel: IFC-specific model type * PISTPModel: STP-specific model type

7.3.2. Instance

An object within a model, representing a specific entity with: * Type: The class or category of the instance * Handle: Unique identifier within the model * Properties: Attributes and values specific to the instance type

7.3.3. Instance Handle

A reference to an instance within a model, used for retrieval and referencing without loading the full instance data.

7.3.4. Reference Types

Special types that can compose their attribute instances, enabling hierarchical data structures.

7.4. Usage Notes

7.4.1. Creating Instances

Instances can be created in several ways:

  • By Type Name: Create a basic instance of a specific type

  • From Dictionary: Create and populate an instance using key-value pairs

  • As Reference: Create an instance reference from an existing handle

  • Special Types: Create select or enum instances with type-specific configurations

// Example: Creating different types of instances
var wallInstance = model.createInstance(typeName: 'IfcWall');
var enumInstance = model.createEnum(typeName: 'IfcDoorTypeOperationEnum', stringValue: 'SINGLE_SWING_LEFT');
var selectInstance = model.createSelect(typeName: 'IfcPropertySetDefinitionSelect');

7.4.2. Instance Lifecycle Management

  1. Creation: Instances are created using factory methods

  2. Population: Values are set through property assignments or dictionary initialization

  3. Saving: Instances are persisted to the model using saveInstance()

  4. Retrieval: Instances are fetched by handle, type, or tag

  5. Deletion: Instances are removed using deleteInstance() after checking dependencies

7.4.3. Working with Tags

Tags provide a flexible way to categorize and retrieve instances:

// Tag an instance during creation
model.saveInstance(wallInstance, tag: 'exterior_walls');

// Tag an existing instance
model.tagInstance(wallInstance, 'load_bearing');

// Retrieve instances by tag
var exteriorWalls = model.getInstancesByTag('exterior_walls');

7.4.4. Query Patterns

Basic Queries

  • All Instances: model.getInstances()

  • By Handle: model.getInstance(handle)

  • By Type: model.getInstancesByType(typeName: 'IfcWall')

Advanced Queries

  • With Subtypes: Include derived types in type-based queries

  • Paginated: Retrieve instances in pages for large datasets

  • With Conditions: Filter by multiple criteria using chained operations

Performance Considerations

For large models: * Use paginated queries instead of loading all instances at once * Consider using detachAll: true for read-only operations to improve performance * Use type-specific queries when possible instead of retrieving all instances

Example: Efficient Query Pattern
// Instead of loading all instances
// var allInstances = model.getInstances(); // ❌ Inefficient for large models

// Use paginated queries
var firstPage = model.getInstancesPaginated(null, pageSize: 50);
// Process page by page...

// Or use type-specific queries
var walls = model.getInstancesByType(typeName: 'IfcWall', includeSubType: true);

7.4.5. Model Operations

Export and Import

Models can be exported in multiple formats: * CSV: Comma-separated values for spreadsheet compatibility * JSON: JavaScript Object Notation for web applications * PIB: Proprietary binary format for optimal performance

Copying Between Models

  • Simple Copy: Copy a single instance between models

  • With Dependencies: Copy an instance along with its composed dependencies

  • ID Resolution: Automatically resolve ID conflicts during copying

Example: Export Workflow
// Export model to different formats
var success1 = model.exportModel('/path/to/model.csv', 0);  // CSV
var success2 = model.exportModel('/path/to/model.json', 1); // JSON
var success3 = model.exportModel('/path/to/model.pib', 2);  // PIB

7.4.6. Error Handling

Most operations return boolean indicators or null values for error conditions:

  • Success/Failure: Boolean return values indicate operation success

  • Null Checks: Use .isNull to check for null models or instances

  • Dependency Checks: Use canDelete() before removing instances

// Safe deletion pattern
if (model.canDelete(instance)) {
    var success = model.deleteInstance(instance);
    if (!success) {
        // Handle deletion failure
    }
} else {
    // Handle dependency constraints
}

7.4.7. Best Practices

  1. Always Check Dependencies: Use canDelete() before deleting instances

  2. Use Pagination for Large Models: Avoid loading entire models into memory

  3. Leverage Tags for Organization: Use tags for logical grouping and retrieval

  4. Validate Type Names: Ensure type names exist in the model schema

  5. Handle Null Returns Gracefully: Always check for null instances after retrieval

  6. Use detachAll for Read-Only Access: Improves performance for queries that don’t need write access

7.4.8. Common Patterns

Batch Operations
// Create multiple instances
var instances = [];
for (var i = 0; i < 10; i++) {
    var instance = model.createInstance(typeName: 'IfcWall');
    instances.add(instance);
}
model.saveInstances(instances);
Type-Safe Retrieval
// Get instances with type checking
var walls = model.getInstancesByType(typeName: 'IfcWall');
for (var wall in walls) {
    // Type-safe operations on wall instances
    if (!wall.isNull) {
        // Process wall
    }
}
Model Comparison
// Check model compatibility
if (model1.hasSameLengthUnit(model2)) {
    // Safe to copy instances between models
    var copied = model2.copyInstance(instance, model1);
}

7.5. API Organization

The Model API is organized into logical categories:

7.6. Performance Considerations

Utility Functions:: Helper operations and checks

  • Memory Usage: Large models should use paginated queries

  • detachAll Parameter: Use detachAll: true for read-only operations to reduce memory overhead

  • Batch Operations: Use saveInstances() for multiple saves instead of individual calls

  • Caching: Consider caching frequently accessed instances or metadata

7.7. Security Notes

  • Input Validation: All user inputs should be validated before passing to model operations

  • Path Security: Validate file paths in export operations

  • Access Control: Implement appropriate access controls at the application level

7.8. Migration and Compatibility

When working with different model types or versions: 1. Check schema compatibility using model.getInfo() 2. Use model.hasSameLengthUnit() before copying between models 3. Handle type name changes or deprecations in your application logic

7.9. Troubleshooting

Common issues and solutions:

  • Null Returns: Check if the model or instance exists before operations

  • Type Errors: Verify type names exist in the model using model.getInstanceTypes()

  • Performance Issues: Implement pagination and use detachAll: true for queries

  • Export Failures: Verify file paths and permissions

7.10. Further Reading

  • See the complete Block Functions Reference for detailed API documentation

  • Consult the Dart API documentation for specific method signatures

  • Review example projects for implementation patterns

Section Block Image Generated Function Description

Model Management

Add Instance Block

saveInstance(instance, tag: tag)

save instance to model data base with optional tag. Returns true if success.

Model Management

Add Instances Block

saveInstances(instances)

save a collection of instances to model. Returns true if success.

Instance Creation

Create Instance Block

createInstance(typeName: typeName, detachAll: detachAll)

create an instance of the given type in model. If detachAll is true, instance is created in detached mode.

Instance Creation

Create Instance Reference Block

createReferenceInstance(instanceHandle)

create an instance reference from instance handle.

Instance Creation

Create Select Block

createSelect(typeName: selectType, selectedTypeName: name, detachAll: detachAll)

create ISelect of given type and optional set the selected value type.

Instance Creation

Create Enum Block

createEnum(typeName: enumType, stringValue: enumValue)

create PIEnum of given type and optional set its value.

Instance Creation

Create Instance with Dictionary Block

createInstanceFromDictionary(dictionary, detachAll: detachAll)

create an instance in model and fill the value using a dictionary. Instance type is given by the special key @type, returns the create IInstance.

Instance Deletion

Delete Instance Block

deleteInstance(instance)

delete an instance from model. Returns true if success.

Instance Deletion

Can Delete Instance Block

canDelete(instance)

can the instance be safely deleted?. Returns a bool value.

Instance Query

List Instances Block

getInstances()

list all instances (InstanceHandle) in the model. Use paginated api if returning List<IInstance> is desirable.

Instance Query

List Instances with Tag Block

getInstancesByTag(tag, detachAll: detachAll)

list instances (IInstance) with a given tag in model.

Instance Query

Get Instance Block

getInstance(instanceHandle, detachAll: detachAll)

get instance with InstanceHandle in model. The return instance isNull == true if not found.

Instance Query

Get Instances with Handles Block

getInstancesByHandle(handles, detachAll: detachAll)

get instances corresponding to a list of instance handles. Returns List<IInstance>.

Instance Query

List Instances by Type Block

getInstancesByType(typeName: typeName, selectedTypeName: type, detachAll: detachAll)

list instances by type, optionally, search all subtype in a model. Return List<IInstance>.

Instance Query

get one instance by type Block

getOneInstanceOfType(typeName: typeName, detachAll: detachAll)

get one instance of a type.

Instance Query

Type Count Block

getTypeCount(typeName, includeSubType: includeSub)

approximate instance type count in model. Returns integer count.

Instance Query

Get Referencing Instances Block

getReferencingInstances(instance)

get instances that reference the given instance in the model. Returns a list instance handes.

Instance Query

Get Instances Paginated Block

getInstancesPaginated(startHandle, pageSize: pageSize, detachAll: detachAll)

get instance from model paginated, with starting page instance handle, page size. If detachAll is true, instances are in safe mode.

Instance Query

Get Instances by Type Paginated Block

getInstancesByTypePaginated(startHandle, pageSize, includeSubType: yes-no, detachAll: detachAll)

get instance from model paginated, with starting page instance handle, page size. If detachAll is true, instances are in safe mode.

Model Metadata

Get Model Info Block

getInfo()

get model meta info from model. Returns a ModelInfo object.

Model Metadata

List Instance Types Block

getInstanceTypes()

list all instance type names that appears in model. Returns a List<String>.

Model Metadata

Get Header Block

getHeader()

get the model header instance which contains the header section information.

Model Metadata

Get Header Clear Text Representation Block

getHeaderClearTextRepresentation(ExportFormat)

get clear text representation of header instance. Returns the clear text string.

Model Metadata

Get Read Only Properties Block

  • id

  • name

  • createdAt

  • schema

  • …​

get model’s readonly property, including: id, name, createdAt, schema…​

Model Operations

Tag Instance Block

tagInstance(instance, tag)

tag instance in model. Return true if success.

Model Operations

Update Model Block

updateModelInfo(name, tag)

update model meta data. Returns true if success.

Model Operations

Resolve Index Block

resolveIndex(instance)

resolve instanceId of the instance to make sure it does not collide with existing ids, return the update instance.

Model Operations

Clear Instances Block

clear()

clear all instance in model. Return true if success.

Model Operations

Save Meta Data Block

saveMetaData()

save model meta data. Return true if success.

Model Operations

Resolve Instances Indices with ID Map Block

resolveIndicesWithIds(instances, idMap)

harmonize instance ids for the given instances using the id maps, and use the next model instance id when needed. Return true if success.

Model Operations

Resolve Instances Indices Block

resolveIndices(instances)

harmonize instance ids for the instances use the next model instance id. Returns true if success.

Model Operations

Copy Instance with Composed Dependency Block

copyInstanceWithComposedDependancy(instance, fromModel)

copy instance from one model to another and composed dependency when appropriate, updates are saved. Returns a list of updated instance.

Model Operations

Copy Instance Block

copyInstance(instance, fromModel)

copy instance from one model to another, if copying within model, set toModel PIModel.nullModel. Returns the copied instance.

Model Operations

Export Model Block

exportModel(filePath, format)

export model to the given location and format. Returns true if success.

Model Factory

Factory Null Model Block

PIModel.nullModel()

create a null model.

Model Factory

Is Null Model Block

isNull

is model null?

Model Comparison

Has Same Length Unit Block

hasSameLengthUnit(otherModel)

does the two models have the same length unit?

Model Comparison

Get Length Unit Block

getModelLengthUnit()

get model’s length unit instance.

Model Comparison

Is Reference Type Block

isReferenceType(typeName)

is the given type(name) a reference type. A reference type are those that could compose its attribute instance.

IFC Model Extension API Documentation

8. Introduction

The IFC Model Extension API provides a comprehensive set of operations for manipulating IFC (Industry Foundation Classes) models within a Blockly-based visual programming environment. This API enables users to perform advanced BIM (Building Information Modeling) operations including spatial structure management, property set manipulation, geometric operations, and model transformation tasks.

8.1. Key Features

  • Spatial Structure Management: Navigate and modify IFC spatial hierarchies (sites, buildings, stories, spaces)

  • Property Operations: Create, modify, and query property sets (PSets) and quantity sets (QSets)

  • Geometric Manipulation: Handle shape representations, placements, and geometric contexts

  • Relationship Management: Manage complex IFC relationships and dependencies

  • Material & Layer Management: Associate materials with elements and manage layer assignments

  • Model Transformation: Copy, convert, and transform model elements between contexts

8.2. API Philosophy

The API follows a consistent pattern where: . All operations require a model instance as primary context . Optional parameters follow Dart’s named parameter convention . Operations return new instances with detachAll option for isolation . Error conditions return empty strings or default values rather than throwing exceptions

9. Usage Notes

9.1. Model Context Requirement

All API operations require a valid model instance as their primary context. The model instance must be obtained from an existing project or created through the appropriate project management functions.

// Correct usage - model context is required
var children = model.getSpatialChildren(parent);

// Incorrect usage - will generate empty code
var children = getSpatialChildren(parent);

9.2. Parameter Validation

The API performs basic validation on required parameters. If essential parameters are missing or empty, the generated code will return an empty string, which typically results in no operation being performed in the target environment.

// If 'parent' or 'model' are empty, returns ''
var children = model.getSpatialChildren(parent);

// If 'instance' is empty, returns ''
var shapes = model.getShapes(instance);

9.3. Optional Parameters

Most API functions support optional parameters using Dart’s named parameter syntax. The most common optional parameter is detachAll, which controls whether returned instances are detached from the original model context.

// Without optional parameter
var project = model.getIfcProject();

// With optional parameter
var detachedProject = model.getIfcProject(detachAll: true);

9.4. DetachAll Parameter

The detachAll parameter is a boolean flag that determines whether returned instances are: * false (default): Returned instances maintain references to the original model * true: Returned instances are fully detached, allowing independent modification

Use detachAll: true when you need to modify instances independently of the original model or when passing instances between different model contexts.

9.5. String Type Parameters

Certain functions require string type parameters that are automatically converted to Dart string literals using the getDartString() utility function.

// The TYPE parameter is automatically converted to a Dart string
var pset = model.createPSetOfType("IfcPropertySingleValue");

// Equivalent to: model.createPSetOfType("IfcPropertySingleValue")

9.6. Error Handling

The API uses defensive programming patterns: * Missing required parameters result in empty code generation * Invalid operations return empty strings or default values * No runtime exceptions are thrown by the generated code

Always validate that generated code is not empty before using results in subsequent operations. Empty results indicate missing or invalid inputs.

9.7. Performance Considerations

  • Batch Operations: When possible, use batch operations like copyChildrenWithComposedDependency instead of individual operations

  • Detached Instances: Creating detached instances (detachAll: true) has higher memory overhead

  • Hierarchy Navigation: Use specialized hierarchy functions rather than manual traversal

9.8. Common Patterns

9.8.1. Adding Elements to Collections

// Add a property set to a product
model.addPSet(product, pset);

// Add a child to a parent spatial element
model.addChild(parent, child);

// Add a shape to a layer
model.addToLayer(shape, layer);

9.8.2. Clearing Collections

// Clear all property sets from an instance
model.clearPSets(instance);

// Clear all shapes from an instance
model.clearShapes(instance);

// Clear all materials from a product
model.clearMaterials(product);

9.8.3. Querying with Conditions

// Get relations with specific type and include subtypes
var relations = model.getInstanceRelations(
  product,
  relType: "IfcRelContainedInSpatialStructure",
  bIncludeSub: true
);

// Get shapes with detached instances
var shapes = model.getShapes(instance, detachAll: true);

10. Compatibility Notes

  • IFC Schema Support: The API supports multiple IFC schemas (IFC2x3, IFC4, IFC4x3)

  • Blockly Version: Requires Blockly version 8.0.0 or higher

  • Dart Compatibility: Generated code targets Dart 2.17+ with null safety

11. Examples

11.1. Basic Spatial Navigation

// Get the project
var project = model.getIfcProject();

// Get spatial children of project (typically sites)
var sites = model.getSpatialChildren(project);

// For each site, get building children
foreach (var site in sites) {
  var buildings = model.getSpatialChildren(site);
}

11.2. Property Set Management

// Create a new property set from template
var psetTemplate = getPsetTemplate("CustomProperties");
var newPset = model.createPSetFromTemplate(psetTemplate);

// Add property set to a product
model.addPSet(product, newPset);

// Later, retrieve property sets
var psets = model.getPSets(product);

11.3. Shape Operations

// Get existing shapes
var shapes = model.getShapes(product);

// Add a new shape representation
var newShape = createBoxShape();
model.addShape(newShape, product);

// Convert to mapped representation for reuse
model.convertShapeToMappedRepresentation(newShape, product);

12. Troubleshooting

12.1. Common Issues

  1. Empty Code Generation: Check that all required block inputs are connected

  2. Incorrect Results: Verify that model instances are from the same context

  3. Performance Issues: Consider using detachAll: false when possible

  4. Missing Dependencies: Ensure all referenced instances exist in the model

12.2. Debug Tips

  • Use intermediate variables to inspect results

  • Verify that all block connections are secure

  • Check console for warnings about missing inputs

  • Test with simple cases before complex operations

13. See Also

  • API Function Reference for complete function list

  • Blockly Documentation for general visual programming guidance

  • IFC Specification for underlying data model details

Section Block Image Generated Function Description

Spatial Structure

Get Spatial Children Block

getSpatialChildren(parent, detachAll: detachAll)

Retrieves all spatial structure children of a parent element

Spatial Structure

Get Spatial Parent Block

getSpatialParent(child, detachAll: detachAll)

Gets the spatial parent element of a child element

Placement Hierarchy

Get Placement Children Block

getPlacementChildren(parent, detachAll: detachAll)

Retrieves placement children under a parent element

Placement Hierarchy

Get Placement Hierarchy Block

getPlacementHierarchy(instance, detachAll: detachAll)

Gets the complete placement hierarchy for an instance

Placement Hierarchy

Get Instance Placement Block

getInstancePlacement(instance, detachAll: detachAll)

Retrieves the placement transformation for an instance

Placement Hierarchy

Get Absolute Placement Block

getAbsolutePlacement(instance)

Calculates the absolute placement transformation for an instance

Type Information

Get Instance Type Product Block

getTypeProduct(instance, detachAll: detachAll)

Gets the type product associated with an instance

Type Information

Remove Type Product From Instance Block

deleteTypeProduct(instance)

Removes type product association from an instance

Type Information

Add Type Product Block

addTypeProduct(product, typeProduct)

Associates a type product with a product instance

Property Sets

Get Instance PSet Block

getPSets(instance, detachAll: detachAll)

Retrieves property sets associated with an instance

Property Sets

Clear PSet From Instance Block

clearPSets(instance)

Clears all property sets from an instance

Property Sets

Remove PSet From Instance Block

removePSet(instance, psetInstance)

Removes a specific property set from an instance

Property Sets

Add PSet Block

addPSet(product, pset)

Adds a property set to a product instance

Property Sets

Create PSet From Template Block

createPSetFromTemplate(template, detachAll: detachAll)

Creates a property set from a template

Property Sets

Create QSet From Template Block

createQSetFromTemplate(template, detachAll: detachAll)

Creates a quantity set from a template

Property Sets

Create PSet Of Type Block

createPSetOfType(type, detachAll: detachAll)

Creates a property set of specified type

Property Sets

Create QSet Of Type Block

createQSetOfType(type, detachAll: detachAll)

Creates a quantity set of specified type

Shape Management

Get Instance Shapes Block

getShapes(instance, detachAll: detachAll)

Retrieves shape representations for an instance

Shape Management

Clear Instance Shapes Block

clearShapes(instance)

Clears all shape representations from an instance

Shape Management

Remove Shape From Instance Block

removeShape(instance, shapeInstance)

Removes a specific shape from an instance

Shape Management

Add Shape To Product Block

addShape(shape, product)

Adds a shape representation to a product

Shape Management

Derive Mapped Shape From Shape Block

deriveMappedShapeFromShape(shape, scale)

Creates a mapped shape representation from an existing shape

Shape Management

Convert Shape To Mapped Representation Block

convertShapeToMappedRepresentation(shape, product)

Converts a shape to mapped representation format

Child Management

Add Child To Parent Block

addChild(parent, child)

Adds a child element to a parent element

Child Management

Delete Child Block

deleteChild(parent, child)

Removes a child element from a parent

Child Management

Get All Children Types Block

getAllChildrenTypes(parent)

Gets all child element types under a parent

Project Management

Create IFC Project Block

createIfcProject(detachAll: detachAll)

Creates a new IFC project in the model

Project Management

Get IFC Project Block

getIfcProject(detachAll: detachAll)

Retrieves the IFC project from the model

Project Management

Get Project RelDeclares Block

getProjectRelDeclares(detachAll: detachAll)

Gets the project’s RelDeclares relationship

Project Management

Get Project Declare References Block

getProjectRelDeclaresReferences(detachAll: detachAll)

Gets project declare references

Instance Operations

Clear Relations Block

clearRelations(product)

Clears all relations from a product

Instance Operations

Get Relations Block

getInstanceRelations(product, relType: type, bIncludeSub: includeSub, detachAll: detachAll)

Gets relations of specified type for a product

Representation Items

Add RepItem To Shape Block

addRepItemToShape(shape, item, styleItem)

Adds a representation item to a shape with optional styling

Representation Items

Add Shape As Item To Shape Block

addShapeAsMappedItemToShape(shape, item, styleItem)

Adds a shape as a mapped item to another shape

Layer Management

Get Layer For Shape Block

getLayers(shape, detachAll: detachAll)

Gets layers associated with a shape

Layer Management

Add Shape To Layer Block

addToLayer(shape, layer)

Associates a shape with a layer

Layer Management

Remove Shape From Layer Block

removeLayer(shape, layer)

Removes a shape from a layer

Layer Management

Clear Layers From Shape Block

clearLayers(shape)

Clears all layer associations from a shape

Layer Management

Get Shapes In Layer Block

getShapesInLayer(layer, detachAll: detachAll)

Gets all shapes in a specific layer

Material Management

Get Materials Associated To Product Block

getMaterials(product, detachAll: detachAll)

Gets materials associated with a product

Material Management

Associate Material To Product Block

addMaterial(product, material)

Associates a material with a product

Material Management

Remove Material From Product Block

removeMaterial(product, material)

Removes a material association from a product

Material Management

Clear Materials From Product Block

clearMaterials(product)

Clears all material associations from a product

Styling

Create Styled Item With Color Block

createStyledItem(color, detachAll: detachAll)

Creates a styled item with color information

Context & Units

Get 3D Geometric Context Block

getBody3dGeometricContext(detachAll: detachAll)

Gets the 3D geometric context from the model

Context & Units

Create Unit Assignment Block

createModelUnits(detachAll: detachAll)

Creates model unit assignments

Context & Units

Get Matching Geo Context Block

getMatchingContext(context, detachAll: detachAll)

Finds a matching geometric context

Copy Operations

Copy Children With Composed Dependency Block

copyChildrenWithComposedDependency(fromModel, fromParent, toParent, children, includeRelTypes: relationTypes)

Copies children with composed dependency relationships

Copy Operations

Copy Children Of Types Composed Dependency Block

copyChildrenOfTypesWithComposedDependency(fromModel, fromParent, toParent, type, includeRelTypes: relationTypes)

Copies children of specific types with composed dependency

STEP Model Extension API Documentation

14. Introduction

The STEP Model Extension API provides specialized operations for working with STEP (Standard for the Exchange of Product model data, ISO 10303) models within a Blockly-based visual programming environment. This API enables users to create, query, and manipulate complex STEP data structures including complex instances, contexts, and product definitions essential for CAD data exchange.

14.1. What is STEP?

STEP (ISO 10303) is an international standard for representing and exchanging product manufacturing information. Unlike IFC which is focused on building information, STEP is widely used in mechanical CAD, automotive, aerospace, and manufacturing industries for exchanging 3D product data.

14.2. Key Features

  • Complex Instance Management: Create and query complex STEP instances with multiple part types

  • Context Creation: Establish necessary contexts for valid STEP files

  • Type Hierarchy Support: Automatic inclusion of subtype relationships (e.g., SI_UNIT → NAMED_UNIT)

  • Instance Querying: Find instances by ID, part type, or complex structure

  • Detached Instance Support: Work with isolated instances for transformation and analysis

14.3. Key STEP Concepts

  • Complex Instance: A STEP entity composed of multiple part types, e.g., #41=(LENGTH_UNIT()NAMED_UNIT(*)SI_UNIT(.MILLI.,.METRE.))

  • Simple Instance: A basic STEP entity with a single type, e.g., #156=VERTEX_POINT('',#155)

  • Part Type: The individual components of a complex instance (LENGTH_UNIT, NAMED_UNIT, SI_UNIT)

  • Context: Required contextual information for STEP entities (application, geometric, product contexts)

15. Usage Notes

15.1. Model Context Requirement

All API operations require a valid STEP model instance as their primary context. The model must be created as a STEP model or converted from an existing model.

// Correct - model is STEP model
var instances = stepModel.getComplexInstances();

// Incorrect - will generate empty code if model is not STEP
var instances = nonStepModel.getComplexInstances();

15.2. Complex Instance Creation

Complex instances are created from an array of root types only. The API automatically includes necessary subtypes based on STEP type hierarchies.

// User provides root types only
var types = ["LENGTH_UNIT", "SI_UNIT"];

// API automatically includes NAMED_UNIT (subtype of SI_UNIT)
var complexInstance = model.createComplexInstance(typeNames: types);

// Result: (LENGTH_UNIT()NAMED_UNIT(*)SI_UNIT(.MILLI.,.METRE.))

15.3. Type Hierarchy Automation

The API automatically manages type inheritance relationships:

  • SI_UNIT → Includes NAMED_UNIT automatically

  • Other type hierarchies are handled similarly

  • Users only specify the top-level types needed

Do not include subtypes in your type array. The system will add them automatically based on STEP type hierarchies.

15.4. Part Name Queries

When querying for complex instances by part type, specify the exact part type name:

// Find all complex instances containing LENGTH_UNIT
var lengthUnits = model.getComplexInstancesWithPart(partName: "LENGTH_UNIT");

// Find specific instance by ID containing SI_UNIT
var instance = model.getComplexInstanceWithIdPart(41, partName: "SI_UNIT");

15.5. Context Creation Order

STEP contexts have dependencies that should be created in order:

  1. Application Context (APPLICATION_CONTEXT)

  2. Geometric Representation Context (GEOMETRIC_REPRESENTATION_CONTEXT)

  3. Product Context (PRODUCT_CONTEXT)

  4. Product Definition Context (PRODUCT_DEFINITION_CONTEXT)

// Create contexts in proper order
var appContext = model.createAppContext();
var geomContext = model.createGeometryContext(3, 0.0);
var productContext = model.createProductContext(appContext);
var productDefContext = model.createProductDefinitionContext(appContext, stage: "design");

15.6. DetachAll Parameter

The detachAll parameter controls instance isolation:

  • false (default): Instance maintains model references

  • true: Instance is fully detached for independent modification

// With references to original model
var attached = model.getComplexInstances();

// Fully independent copy
var detached = model.getComplexInstances(detachAll: true);

15.7. String Parameter Handling

String parameters for part names are automatically converted to Dart string literals:

// Block input "LENGTH_UNIT" becomes "LENGTH_UNIT" in Dart
var instances = model.getComplexInstancesWithPart(partName: "LENGTH_UNIT");

15.8. Error Handling

The API uses defensive patterns:

  • Missing required inputs → Empty code generation

  • Non-existent instances → isNull = true returned instances

  • Invalid operations → Empty results

// Returns isNull=true if instance #999 doesn't exist
var instance = model.getComplexInstanceWithIdPart(999, partName: "LENGTH_UNIT");
if (instance.isNull) {
  // Handle missing instance
}

15.9. Performance Considerations

  • Complex Instance Creation: Creating complex instances with many part types has higher overhead

  • Instance Queries: Querying by part type is optimized for STEP structure

  • Detached Instances: Use detachAll: false when possible for better performance

16. Common Patterns

16.1. Creating Measurement Units

// Create millimeter unit complex instance
var mmUnit = model.createComplexInstance(typeNames: ["LENGTH_UNIT", "SI_UNIT"]);

// Result in STEP: #41=(LENGTH_UNIT()NAMED_UNIT(*)SI_UNIT(.MILLI.,.METRE.))

16.2. Querying Complex Structures

// Find all unit definitions
var allUnits = model.getComplexInstances();

// Find specific unit type
var lengthUnits = model.getComplexInstancesWithPart(partName: "LENGTH_UNIT");

// Get specific instance by ID
var unit41 = model.getComplexInstanceWithIdPart(41, partName: "SI_UNIT");

16.3. Setting Up STEP Contexts

// Complete context setup for mechanical design
var appContext = model.createAppContext();
var geomContext = model.createGeometryContext(3, 0.0);  // 3D, exact
var productContext = model.createProductContext(appContext);
var designContext = model.createProductDefinitionContext(
  appContext,
  stage: "design"
);

17. Compatibility Notes

  • STEP Versions: Supports ISO 10303 (STEP) AP203, AP214, AP242

  • CAD Compatibility: Generates data compatible with major CAD systems

  • Blockly Version: Requires Blockly 8.0.0+

  • Dart Compatibility: Targets Dart 2.17+ with null safety

18. Examples

18.1. Basic Complex Instance Workflow

// Create complex instance
var types = ["LENGTH_UNIT", "SI_UNIT"];
var complexInstance = model.createComplexInstance(typeNames: types);

// Get its type name
var typeName = model.getComplexInstanceTypeName(types);
// Returns: "LENGTH_UNIT_AND_NAMED_UNIT_AND_SI_UNIT"

// Later find similar instances
var similar = model.getComplexInstancesWithPart(partName: "LENGTH_UNIT");

18.2. Context Management

// Create necessary contexts for product data
var contexts = [];

// Application context
contexts.add(model.createAppContext());

// 3D geometric context (exact measurements)
contexts.add(model.createGeometryContext(3, 0.0));

// Product context using application context
var appContext = contexts[0];
contexts.add(model.createProductContext(appContext));

// Design stage product definition
contexts.add(model.createProductDefinitionContext(
  appContext,
  stage: "design"
));

19. Troubleshooting

19.1. Common Issues

  1. Empty Results: Verify model is a STEP (PISTPModel) instance

  2. Missing Subtypes: Check that you’re providing root types only (not subtypes)

  3. Invalid Part Names: Ensure part names match exact STEP type names

  4. Context Errors: Create contexts in proper dependency order

19.2. Debug Tips

  • Use simple test cases with known STEP structures first

  • Verify all required inputs are connected in blocks

  • Check that part type names are spelled correctly

  • Test context creation in the recommended order

20. See Also

  • API Function Reference for complete function list

  • ISO 10303 (STEP) specification for underlying data model

  • CAD system documentation for STEP import/export requirements

  • IFC Model Extension API for building information modeling

Section Block Image Generated Function Description

Complex Instance Creation

Create Complex Instance Block

createComplexInstance(typeNames: types, detachAll: detachAll)

Create complex instance like (LENGTH_UNIT()NAMED_UNIT(*)SI_UNIT(.MILLI.,.METRE.)) with the given type names [LENGTH_UNIT,SI_UNIT] in model.

Complex Instance Management

Get Complex Type Name Block

getComplexInstanceTypeName(types)

Generate complex type name from array of part types. For ['LENGTH_UNIT','SI_UNIT'] returns combined type name LENGTH_UNIT_AND_NAMED_UNIT_AND_SI_UNIT.

Complex Instance Management

Get Complex Instances Block

getComplexInstances(detachAll: detachAll)

Get all complex instances in the stp model. Returns a list of IInstance.

Complex Instance Management

Get Complex Instances With Part Block

getComplexInstancesWithPart(partName: part, detachAll: detachAll)

Get complex instances containing specific part type (e.g., 'LENGTH_UNIT'). Returns list of matching IInstance objects.

Complex Instance Management

Get Complex Instances With ID Part Block

getComplexInstanceWithIdPart(id, partName: part, detachAll: detachAll)

Get specific complex instance by ID that contains given part type (e.g., instance containing 'LENGTH_UNIT'). Returns IInstance (isNull=true if not found).

Context Creation

Create App Context Block

createAppContext(detachAll: detachAll)

Create default STEP application context (APPLICATION_CONTEXT). Returns the context instance.

Context Creation

Create Geometry Context Block

createGeometryContext(dimension, uncertainty, detachAll: detachAll)

Create GEOMETRIC_REPRESENTATION_CONTEXT for STEP model. Dimension: coordinate space dimension (3 for 3D). Uncertainty: 0.0 for exact values. Returns context instance.

Context Creation

Create Product Context Block

createProductContext(appContext, detachAll: detachAll)

Create PRODUCT_CONTEXT using given APPLICATION_CONTEXT instance. Returns product context instance.

Context Creation

Create Product Definition Context Block

createProductDefinitionContext(appContext, stage: stage, detachAll: detachAll)

Create PRODUCT_DEFINITION_CONTEXT. Stage examples: 'design', 'manufacturing', 'inspection'. Default: 'design'. Returns context instance.

Reference Model API Documentation

21. Introduction

Reference Models in PicoComposer are imported models where the imported content is treated as a reference portion that cannot be deleted. This architectural pattern enables powerful workflows where users can:

  • Import baseline content from CSV or JSON files

  • Add new instances to extend the model

  • Update existing reference instances

  • Load and unload reference content at runtime for memory management

  • Maintain the original reference file while working with a modifiable copy

Reference Models are subtypes of IIfcModel and ISTPModel, inheriting all their functionality while adding reference-specific capabilities.

22. Key Concepts

22.1. Reference vs. Added vs. Updated Instances

  • Reference Instances: Original content imported from reference files (CSV/JSON)

  • Added Instances: New instances created after import, not present in reference files

  • Updated Instances: Reference instances that have been modified

22.2. ID vs. Handle Access Pattern

One of the most important architectural decisions in the Reference Model API is the distinction between ID-based and Handle-based access:

Table 1. ID vs. Handle Access Pattern
ID-Based Access Handle-Based Access

Data Structure

Integer value only

Struct containing (id, typeid)

Used For

Reference portion operations

Outside/database operations

When to Use

- Checking instance status - Undoing updates - Reference-specific queries

- Database lookups - Type-based operations - Integration with IModel/IIfcModel/ISTPModel APIs

Example Operations

isReferenceInstance(id) undoUpdate(id) isUpdatedInstance(id)

model.deleteInstance(handle) getTypeFromHandle(handle) filterByType(handles, typeid)

Conversion

Use instance_extract_id_from_handle() block

Use instance_create_handle() block

Rule of Thumb: "Inside the reference part, use ID. Outside the reference part, use Handle."

22.3. Load/Unload Architecture

Reference content can be loaded and unloaded at runtime:

  • Loaded State: Reference content is in memory, available for queries and operations

  • Unloaded State: Reference content is persisted to disk, freeing memory while maintaining instance metadata

  • Dynamic Management: Applications can load/unload based on memory constraints or workflow requirements

23. API Overview

23.1. Instance Retrieval Functions

The API provides three primary functions for getting instance collections:

  • getReferenceInstances() - Returns handles for all reference instances

  • getAddedInstances() - Returns handles for newly added instances

  • getUpdatedInstances() - Returns handles for updated reference instances

All three functions return handles for consistency with the broader model API ecosystem.

23.2. Status Checking Functions

These functions use ID-based access to check instance status:

  • isReferenceInstance(id) - Checks if an instance is part of the reference content

  • isAddedInstance(id) - Checks if an instance was added after import

  • isUpdatedInstance(id) - Checks if a reference instance has been updated

23.3. Operations Functions

  • undoUpdate(id) - Reverts changes to a reference instance (ID-based)

  • loadReferenceModel() - Loads reference content into memory

  • unloadReferenceModel() - Unloads reference content from memory

  • isReferenceLoaded - Property indicating if reference content is loaded

24. Usage Examples

24.1. Basic Workflow

Table 1: Reference Model Block FunctionsManage memory with load/unload
Section Block Image Generated Function Description

Reference Model Instances

Get Reference Instances Block

getReferenceInstances()

get all reference instance handles in a reference model.

Reference Model Instances

Get Added Instances Block

getAddedInstances()

get all newly added instance handles in a reference model.

Reference Model Instances

Get Updated Instances Block

getUpdatedInstances()

get all updated instance handles in a reference model.

Instance Status Checks

Is Reference Instance Block

isReferenceInstance(id)

is the given instance a reference instance in a reference model. Returns true if instance is a imported reference instance.

Instance Status Checks

Is Added Instance Block

isAddedInstance(id)

is the given instance a newly added instance in a reference model. Return true if instance is not part of imported reference file.

Instance Status Checks

Is Updated Instance Block

isUpdatedInstance(id)

has instance been updated?. Return true if instance is part of the reference file and had been updated.

Reference Model Operations

Undo Update Block

undoUpdate(id)

undo update to a reference instance. Return true if success.

Reference Model Loading

Load Reference Model Block

loadReferenceModel()

load the referenced content of the model. Returns true if success.

Reference Model Loading

Unload Reference Model Block

unloadReferenceModel()

unload the referenced content of the model from memory. Returns true is success.

Reference Model Loading

Is Reference Loaded Block

isReferenceLoaded

is the referenced content of model loaded?

Instance API Guide

25. Introduction

The Instance API provides a comprehensive, type-safe interface for working with object instances in a Blockly-to-Dart visual programming environment. This API enables developers to create, manipulate, and manage complex object hierarchies with rich attribute systems, relationships, and metadata.

At its core, the Instance API revolves around the IInstance interface, which represents individual object instances with properties, attributes, and relationships. The system supports a wide range of data types—from simple booleans and numbers to complex enumerations, nested instances, and multi-dimensional arrays—all while maintaining strict type safety through Blockly’s visual type system.

The API is particularly well-suited for:

  • Data modeling applications where objects have complex relationships

  • Configuration management systems with hierarchical structures

  • CAD/BIM applications requiring rich object properties

  • Any system needing strong typing with visual programming

Key design principles include:

  • Type safety: Every operation validates input and output types

  • Relationship integrity: Automatic management of references and inverses

  • Performance efficiency: Batch operations and lazy evaluation where possible

  • Developer experience: Consistent patterns across all operations

26. Core Concepts

26.1. Instance Types

IInstance

The primary object representation. Every instance has a unique ID, type information, and can contain multiple attributes.

InstanceHandle

A lightweight reference to an instance containing instanceId and typeId. Used for relationships without full object loading.

PIEnum

Type-safe enumeration values with both string and integer representations.

ISelect

Selection objects that can choose between different instance types.

26.2. Attribute System

The attribute system supports three categories of data:

Basic Types

Simple data types including BOOL, INT32, UINT32, INT64, FLOAT, REAL, STRING, BINARY, and LOGICAL.

Complex Types

Structured types including ENUM, INSTANCE, and SELECT.

Aggregate Types

Collections including 1D arrays (BOOLS, INT32S, etc.), 2D arrays (INT32S2, REALS2, etc.), and 3D arrays (REALS3, INSTANCES3).

26.3. Relationship Models

Composites

Parent-child hierarchical relationships where child instances are owned by parents.

Inverses

Bidirectional references that automatically maintain relationship integrity.

References

One-way pointers to other instances without ownership.

27. Quick Start Guide

27.1. Creating Your First Instance

// 1. Create a null instance as a starting point
create null instance

// 2. Create an attribute on the instance
create [instance] attribute with name: "properties" for instance: [myInstance]

// 3. Set some basic properties
set attribute with name: "name" to value: "Example Object" for instance: [myInstance]
set attribute with name: "width" to value: 100 for instance: [myInstance]
set attribute with name: "height" to value: 200 for instance: [myInstance]

// 4. Create an enum attribute
create [enum] attribute with name: "status" for instance: [myInstance]
set enum: [status] value to: "ACTIVE"

27.2. Working with Relationships

// 1. Create parent and child instances
create [instance] attribute with name: "parentObject"
create [instance] attribute with name: "childComponent"

// 2. Set up the parent-child relationship
add instance: [childComponent] as composite to instance: [parentObject]

// 3. Create a reference to another instance
add instance reference: [externalObject] add inverse? true
  to aggregate attribute with name: "dependencies"
  for instance: [parentObject]

27.3. Batch Operations

// 1. Create configuration data
set instance: [configInstance] attributes by dictionary: {
  "name": "Main Configuration",
  "version": 2.1,
  "enabled": true
}

// 2. Update multiple attributes by path
set attribute with path: ["components", "0", "settings"]
  to value: {"x": 100, "y": 200, "z": 300}
  for instance: [mainObject]

28. Best Practices

28.1. Type Safety

Always use the appropriate type-specific getters:

// GOOD: Type-specific getter
get [bool] attribute with name: "enabled" from instance: [config]

// AVOID: Generic getter when type is known
get attribute with path: ["enabled"] for instance: [config]

28.2. Error Handling

Check operation results and null states:

// Check if operation succeeded
set attribute with name: "criticalSetting"
  to value: importantValue
  for instance: [mainObject]
// Returns Boolean success indicator

// Check for null before using
is instance: [result] null?
if not [isNull] {
  // Safe to use result
}

28.3. Performance Optimization

Use appropriate patterns for different scenarios:

  • For deep attribute access: Use path-based operations instead of nested getters

  • For batch updates: Use dictionary loading instead of individual sets

  • For read-heavy operations: Cache results when possible

  • For temporary instances: Use detach() to release resources

28.4. Memory Management

// Release instances when done
detach instance from parent buffer: [temporaryInstance] detachAll? false

// Clean up relationships
clear composites from instance: [parent]
clear references for instance: [instance] include internal reference? false

29. Common Patterns

29.1. Configuration Object Pattern

// Create configuration instance
create [instance] attribute with name: "appConfig"

// Set configuration values
set attribute with name: "appName" to value: "My Application" for instance: [appConfig]
set attribute with name: "version" to value: "1.0.0" for instance: [appConfig]
set attribute with name: "debugMode" to value: false for instance: [appConfig]

// Create nested settings
create [instance] attribute with name: "uiSettings" for instance: [appConfig]
set attribute with name: "theme" to value: "dark" for instance: [uiSettings]
set attribute with name: "language" to value: "en-US" for instance: [uiSettings]

29.2. Component Hierarchy Pattern

// Create assembly structure
create [instance] attribute with name: "assembly"

// Add components
create [instance] attribute with name: "component1"
create [instance] attribute with name: "component2"

// Build hierarchy
add instance: [component1] as composite to instance: [assembly]
add instance: [component2] as composite to instance: [assembly]

// Set component properties
set attribute with name: "position" to value: {"x": 0, "y": 0} for instance: [component1]
set attribute with name: "position" to value: {"x": 100, "y": 0} for instance: [component2]

29.3. Data Validation Pattern

// Validate instance state
validate references for instance: [mainInstance]
validate inverses for instance: [mainInstance]

// Check data integrity
is instance: [result] null?
is attribute with name "requiredField" in instance: [data] null?

// Clean up stale references
clear references for instance: [instance]
  include internal reference? true
  excluding ids: [validIds]

30. Troubleshooting

30.1. Common Issues and Solutions

Attribute not found

Verify attribute names match exactly, including case. Use get attribute type with name: to check existence.

Null returns

Always check with is null instance or is null attribute blocks before using results.

Performance issues

Use detach() for temporary instances, prefer batch operations, and validate that references aren’t creating circular dependencies.

Relationship errors

Run validateReferences() and validateInverses() periodically to clean stale relationships.

30.2. Debugging Techniques

// 1. Inspect instance properties
get: [instanceId] from instance: [target]
get: [typeName] from instance: [target]

// 2. Check dirty state
is instance: [target] dirty?

// 3. Get all attributes
get: [attributeNames] from instance: [target]

// 4. Export for inspection
get clear text representation of type [json] for instance: [target]

31. Advanced Features

31.1. Custom Type Creation

// Create complex type definition
create complex instance for attribute of name: "customType"
  with parts: [
    {"name": "id", "type": "INT32"},
    {"name": "data", "type": "STRING"},
    {"name": "metadata", "type": "INSTANCE"}
  ]
  for instance: [typeRegistry]

31.2. Dynamic Attribute Management

// Work with unknown attribute structures
get attribute with path as dynamic with path: ["dynamic", "path"] for instance: [data]

// Handle optional attributes
nullify attribute with path: ["optional", "attribute"] for instance: [instance]

31.3. Version Control Integration

// Track changes
get version id from instance: [document]
increment version id for instance: [document]

// Mark as modified
set dirty flag true for instance: [document]

32. Conclusion

The Instance API provides a powerful, type-safe foundation for building complex object hierarchies in visual programming environments. By understanding the core concepts of instances, attributes, and relationships, developers can create robust applications with rich data models while maintaining the accessibility of block-based programming.

Remember to:

  1. Always use type-specific operations when types are known

  2. Validate relationships periodically

  3. Clean up unused instances with detach()

  4. Use batch operations for performance-critical sections

  5. Leverage the comprehensive property system for debugging and inspection

With these patterns and practices, you can build maintainable, efficient applications using the Instance API’s full capabilities.

Section Block Image Generated Function Description

Attribute Creation

Create Instance Attribute Block

  • createSelect(attName: name, selectedType: type)

  • createInstance(attName: name, type: type)

  • createEnum(attName: name, value: value)

create select, instance, enum for the attribute of the given name. Optionally set the selected type, instance subtype or enum value.

Complex Attribute

Create Complex Attribute Instance Block

createComplexInstance(attName: name, parts: parts)

create a complex attribute instance with the given parts.

Enum Operations

Set Enum Value Block

strValue = value

set enum’s value

Enum Operations

Get Enum Value Block

strValue

get enum string value

Enum Operations

Get Enum Integer Value Block

value

get enum integer value

Attribute Information

Get Attribute Type Block

getAttributeType(attName: name)

get instance attribute type, empty string if attribute with name does not exist.

Attribute Information

Get Attribute Fundamental Type Block

getAttributeFundamentalType(attName: name)

get instance attribute fundamental type. Return Fundamental.UNKNOWN if attribute with name does not exist.

Attribute Operations

Set Attribute Value Block

setAttribute(attName: name, value)

set attribute of name to the given value, returns true if success.

Aggregate Operations

Update Item in Aggregate Attribute Block

updateAttribute(index, value, attName: name)

update an element for a list attribute of an instance, return true if success.

Attribute Information

Is Null Attribute Block

isNullAttribute(attName: name)

does instance attribute with the given name have null value?

Attribute Operations

Get Attribute Value Block

  • .getBool(attName: name)

  • .getInt(attName: name)

  • .getString(attName: name)

  • …​

get instance attribute value by name. To check null return value, use the isNull utility block.

Bulk Operations

Load Attributes by Dictionary Block

setAttributesByJson(dictionary)

use dictionary to set instance’s attributes. Returns true if success.

Composite Management

Get Components Block

getComposites()

get all composite instances for instance.

Composite Management

Get Composite by ID Block

getComposite(id)

get composite by instance id, return instance is null if not exists

Composite Management

Get Composite by Type Block

getCompositesByType(type, includeSubType)

get composite instances by type. Return a list of IInstances.

Composite Management

Add Composite Block

addComposite(instance)

add instance to instance as composite. Return true if success.

Composite Management

Set Composites Block

setComposites(instances)

set instance’s composite with a list of instances. Return true if success.

Composite Management

Remove Composite Block

removeComposite(id)

remove composite from instance by instance id. Returns true if success.

Composite Management

Remove Composite of Type Block

removeCompositeOfType(type: type, includeSubType: includeSubType)

remove composite from instance of the given type. Returns the removed count.

Composite Management

Clear Composites Block

clearComposites()

clear instance’s composites. Returns the removed count.

Composite Management

Get decomposition Block

getDecomposition()

get all instances—​attribute instances, composites—​stored in instance. Optionally include references and detach the result.

Inverse Management

Get Inverses Block

getInverses()

get all inverse for instance. Returns list of instance handles.

Inverse Management

Get Inverses by Type Block

getInversesOfType(type, includeSubType: includeSubType)

get all inverse for instance of type. Return list of instance handles

Inverse Management

Get Inverse by ID Block

getInverse(id)

get inverse (InstanceHandle) with the given instance id.

Inverse Management

Clear Inverses Block

clearInverse(exclusion)

clear inverses for the given instance excluding instance on the exclusion list. Returns the removed count.

Inverse Management

Add Inverse Block

addInverse(handle)

add inverse with the given handle. Returns true if success.

Inverse Management

Remove Inverse by ID Block

removeInverse(id)

remove inverse from instance with the given id. Returns true if success.

Inverse Management

Remove Inverses by Type Block

removeInverseOfType(type: type, includeSubType: includeSubType)

remove inverse of given type from instance. Returns the removed count.

Aggregate Operations

Remove Item from Attribute Block

removeAttribute(index, attName: name)

remove an element from a aggregate attribute of an instance. Returns true if success.

Aggregate Operations

Add Item in Aggregate Attribute Block

addAttribute(value, attName: name)

add an value to a list attribute of an instance. Returns true if success.

Aggregate Operations

Add Instance Ref to Aggregate Attribute Block

addInstanceRef(value, attName: name, addInverse: addInverse)

add instance reference to a aggregate attribute of an instance. If add inverse is true, add inverse to referenced instance. Returns true if success.

2D Aggregate Operations

Remove Item from Attribute2 Block

removeAttribute2(row, column, attName: name)

remove an item from a 2d aggregate attribute of an instance. Returns true if success.

2D Aggregate Operations

Update Item in Aggregate Attribute2 Block

updateAttribute2(row, column, value, attName: name)

update an element of a 2d aggregate attribute of an instance. Return true is success.

3D Aggregate Operations

Remove Item from Attribute3 Block

removeAttribute3(row, column, layer, attName: name)

remove an element from a 3d aggregate attribute of an instance. Return true if success.

3D Aggregate Operations

Update Item in Aggregate Attribute3 Block

updateAttribute3(row, column, layer, value, attName: name)

update an element in a 3d list attribute of an instance. Returns true if successful.

Serialization

Get Clear Text Representation Block

getClearTextRepresentation(ExportFormat.values[type])

get the clear text representation for the instance.

Serialization

instance to json object

toJson(setDefaultForOption: bool)

convert instance to json object recursively. If set default for Option value is true, set attribute to a default otherwise set value to null for Option.isNone.

Instance Creation

Create Null Instance Block

PIInstance.nullInstance()

create a null instance.

Instance Information

Is Null Instance Block

isNull

is instance null object?

Serialization

Instance Handle to JSON Block

toJson()

convert instance handle to json (Map<String, dynamic>).

Serialization

Instance Handle from JSON Block

InstanceHandle.fromJson(json)

create instance handle from json (Map<String, dynamic>). Return the handle.

Instance Handle Operations

Instance Handle Access Block

  • instanceId

  • typeId

get the instance handle properties: instanceId, typeId.

Path Operations

Set Attribute Value with Path Block

setAttributeByPath(path, value)

set attribute specified by the path to given value. Return the updated instance (could be different from the calling instance).

Path Operations

Get Attribute Value with Path Block

getAttributeByPath(path)

get instance attribute specified by the path. The return value is a record (FundamentalType, dynamic), where the second slot is the value.

Path Operations

Remove Attribute from Aggregate Value with Path Block

removeAttributeFromAggregateByPath(path)

remove item from aggregate attribute with the given path and return the modified instance.

Path Operations

Clear Attribute Aggregate with Path Block

clearAttributeAggregateByPath(path)

clear aggregate attribute with the given path. Return the updated instance (might be different from the calling instance).

Path Operations

Get Attribute Value with Path as Dynamic Block

getAttributeByPathAsDynamic(path)

get instance attribute specified by the path. The return value is a dynamic value.

Path Operations

Get Attribute Value Fundamental Type Block

getAttributeValueFundamentalType(path)

get attribute fundamental type addressed by the path.

Path Operations

Nullify Attribute Block

nullifyAttributeByPath(path)

nullify an optional attribute pointed to by the given path. No effect if attribute is not optional.

Path Operations

Set Attribute by Path with JSON Block

setAttributeByPathWithJson(path, json)

set structure attribute (IInstance, ISelect or List of these) value with json.

Version Management

Version ID Access Block

versionId

get instance’s version id.

Version Management

Set Version ID Block

versionId = version;

set instance’s version id.

Version Management

Increment Version ID Block

incrementVersionId()

increment instance’s version id. PIComposer calls this automatically when instance is saved.

Reference Management

Get References Block

getReferences(includeInternal)

get instance’s references to other instances. Returns a list of instance handles.

Reference Management

Clear References Block

clearReferences(includeInternal, exclusion)

clear instance references and keep those in the exclusion list. Return a list of removed handles.

State Management

Dirty Get Block

dirty

is instance dirty (modified in memory)?

State Management

Set Dirty Flag Block

setDirty(dirty)

set instance’s dirty flag. It is automatically set by the system when setAttribute is called and succeeded.

Reference Operations

Set Attribute Instance Reference Block

setInstanceRef(value, attName: name, addInverse: addInverse)

set instance reference value for an instance attribute. If add inverse is true. An inverse to instance is added to the referenced instance.

Instance Operations

Duplicate Instance Block

duplicate(reindex)

create a duplicate and returns it.

Instance Operations

Detach Instance Block

detach(detachAll)

detach instance from parent buffer. If detachAll is true, then all instance and select returns from this instance will be detached. Return true if success.

Instance Properties

Get Read Only Properties Access Block

  • instanceId

  • typeId

  • typeName

  • hash

  • …​

get instance read-only property which includes: id, typeId, typeName, hash…​

Validation

Validate References Block

validateReferences()

validate instance references to other instance in model and remove stale references. Returns list of valid references (InstanceHandle).

Validation

Validate Inverses Block

validateInverses()

validate instance inverses linking to other instance and remove stale inverses. Returns list of valid inverses (InstanceHandle).

Aggregate Operations (Missing)

Remove Item from Attribute Block

removeAttribute(index, attName: name)

remove an element from a aggregate attribute of an instance. Returns true if success.

Aggregate Operations (Missing)

Remove Item from Attribute2 Block

removeAttribute2(row, column, attName: name)

remove an item from a 2d aggregate attribute of an instance. Returns true if success.

Aggregate Operations (Missing)

Remove Item from Attribute3 Block

removeAttribute3(row, column, layer, attName: name)

remove an element from a 3d aggregate attribute of an instance. Return true if success.

Aggregate Operations (Missing)

Update Item in Aggregate Attribute Block

updateAttribute(index, value, attName: name)

update an element for a list attribute of an instance, return true if success.

Aggregate Operations (Missing)

Update Item in Aggregate Attribute2 Block

updateAttribute2(row, column, value, attName: name)

update an element of a 2d aggregate attribute of an instance. Return true is success.

Aggregate Operations (Missing)

Update Item in Aggregate Attribute3 Block

updateAttribute3(row, column, layer, value, attName: name)

update an element in a 3d list attribute of an instance. Returns true if successful.

Path Operations (Missing)

Get Attribute Value with Path as Dynamic Block

getAttributeByPathAsDynamic(path)

get instance attribute specified by the path. The return value is a dynamic value.

Path Operations (Missing)

Get Attribute Value Fundamental Type Block

getAttributeValueFundamentalType(path)

get attribute fundamental type addressed by the path.

Path Operations (Missing)

Nullify Attribute Block

nullifyAttributeByPath(path)

nullify an optional attribute pointed to by the given path. No effect if attribute is not optional.

Path Operations (Missing)

Set Attribute by Path with JSON Block

setAttributeByPathWithJson(path, json)

set structure attribute (IInstance, ISelect or List of these) value with json.

SELECT API Reference

33. Introduction

The SELECT API provides a comprehensive interface for working with SELECT objects in the PicoSTEP environment. SELECTs are fundamental components in STEP (Standard for the Exchange of Product model data) that can hold values of multiple possible types, determined at runtime based on the application protocol schema.

33.1. Key Characteristics

  • Type Flexibility: SELECTs can store values of different fundamental types (bool, int32, real, string, etc.) and complex types (instances, enums, other SELECTs)

  • Runtime Type Validation: Type compatibility is validated against the SELECT’s descriptor at execution time

  • Aggregate Support: Supports aggregate types (arrays/lists) for all fundamental types

  • Dynamic Schema Compatibility: Works with any STEP application protocol without static type constraints

34. Block Categories

34.1. Value Management Blocks

34.1.1. select_set_value

Sets the value of a SELECT object.

Inputs: - TOVALUE: The value to set (any type) - SELECT: Target SELECT object

Output: Boolean (true if successful, false if type mismatch)

Dart Equivalent: select.setValue(value)

34.1.2. select_get_value

Retrieves the value from a SELECT object with specified type.

Inputs: - SELECT: Source SELECT object - VALUE_TYPE: Dropdown specifying expected return type

Output: Value of specified type (varies by selection)

Dart Methods: getBool(), getInt(), getReal(), getString(), etc.

34.2. Aggregate Value Operations

34.2.1. select_add_value_item

Adds an element to an aggregate SELECT value.

Inputs: - VALUE: Value to add - SELECT: Target SELECT object

Output: Boolean (true if successful)

Dart Equivalent: select.addValue(value)

34.2.2. select_remove_item_from_value

Removes an element from an aggregate SELECT value by index.

Inputs: - INDEX: Numerical index of element to remove - SELECT: Target SELECT object

Output: Boolean (true if successful)

Dart Equivalent: select.removeValue(index)

34.2.3. select_update_value_item

Updates an element in an aggregate SELECT value.

Inputs: - INDEX: Numerical index of element to update - VALUE: New value - SELECT: Target SELECT object

Output: Boolean (true if successful)

Dart Equivalent: select.updateValue(index, value)

34.3. Type Management

34.3.1. select_set_selected_type

Sets the selected value type for a SELECT object.

Inputs: - SELECTEDTYPE: Type name as string (e.g., "IfcCartesianPoint") - SELECT: Target SELECT object

Output: Boolean (true if type is valid for this SELECT)

Dart Equivalent: select.setSelectedType(typeName: "TypeName")

Note: Type must be compatible with the SELECT’s descriptor. Returns false for invalid types.

34.3.2. select_create_selected_value

Creates a value object for the SELECT’s selected type.

Inputs: - OBJECTTYPE: Dropdown ("SELECT", "INSTANCE", or "ENUM") - SELECT: Source SELECT object

Output: Created object (PIEnum, ISelect, or IInstance)

Dart Methods: createSelect(), createInstance(), createEnum()

34.3.3. select_set_complex_instance_type

Sets a complex instance type using component parts.

Inputs: - SELECTEDTYPE: Array of type parts - SELECT: Target SELECT object

Output: Boolean (true if successful)

Dart Equivalent: select.setSelectedComplexType(parts)

34.4. Instance Reference Operations

34.4.1. select_set_instance_ref

Sets SELECT value to an instance reference.

Inputs: - INSTANCE: Instance reference - ADDINVERSE: Boolean (optional, default false) - SELECT: Target SELECT object

Output: Boolean (true if successful)

Dart Equivalent: select.setInstanceRef(instance, addInverse?)

34.4.2. select_add_instance_ref

Adds instance reference to aggregate instance values.

Inputs: - INSTANCE: Instance reference to add - ADDINVERSE: Boolean (optional, default false) - SELECT: Target SELECT object

Output: Boolean (true if successful)

Dart Equivalent: select.addInstanceRef(instance, addInverse?)

34.5. Special Operations

34.5.1. select_nullify_value

Sets SELECT value to null.

Inputs: - SELECT: Target SELECT object

Output: Boolean (true if successful, always true for nullable SELECTs)

Dart Equivalent: select.nullify()

34.5.2. select_duplicate

Creates a duplicate of a SELECT object.

Inputs: - SELECT: Source SELECT object

Output: Duplicate ISelect object

Dart Equivalent: select.duplicate()

34.5.3. select_detach

Detaches SELECT from parent buffer.

Inputs: - SELECT: Target SELECT object - DETACHALL: Boolean (optional, default false)

Output: Boolean (true if successful)

Dart Equivalent: select.detach(detachAll?)

34.6. Property Access

34.6.1. select_get_read_only_properties_access

Retrieves read-only properties from a SELECT object.

Inputs: - VALUES: Dropdown selecting property to retrieve - SELECT: Source SELECT object

Output: Property value (type varies by property)

Available Properties: - descriptor - Type constraints and metadata - isDetachAll - Detach status - isDetach - Individual detach status - type - Current type - selectedTypeName - Selected type name - selectedBaseType - Base type - selectedFundamentalType - Fundamental type category

Dart Equivalent: Direct property access (e.g., select.descriptor)

35. Usage Notes

35.1. Type Compatibility

  1. Always validate types: Use the SELECT’s descriptor to check acceptable types before setting

  2. Runtime validation: select_set_selected_type returns false for incompatible types

  3. Aggregate consistency: When working with aggregate values, ensure all elements share compatible types

35.2. Best Practices

// Recommended pattern for type-safe operations
set selected_type "IfcCartesianPoint" for select: [SELECT]
if get:descriptor from select: [SELECT] contains "IfcCartesianPoint"
  create SELECT for select: [SELECT]
  set value: [VALUE] for select: [NEW_SELECT]
else
  // Handle type error

35.3. Error Handling

  • Type mismatches: Most operations return boolean indicating success

  • Empty values: Generators return empty string for incomplete blocks

  • Descriptor checks: Use select_get_read_only_properties_access for debugging

35.4. Performance Considerations

  1. Duplicate vs Reference: Use select_duplicate sparingly for memory efficiency

  2. Detach operations: Use detachAll judiciously with nested structures

  3. Instance references: Inverse relationships (addInverse: true) add overhead

35.5. Common Patterns

35.5.1. Type-Safe Value Setting

// 1. Check type compatibility
get:descriptor from select: [MY_SELECT]
// 2. Create appropriate value
create INSTANCE for select: [MY_SELECT]
// 3. Set value
set value: [INSTANCE] for select: [MY_SELECT]

35.5.2. Aggregate Value Management

// Building a list of instances
for each item in [INSTANCE_LIST]
  add instance reference: [ITEM] to select instances values for select: [AGGREGATE_SELECT]
end

35.5.3. Complex Type Configuration

// Setting up a complex SELECT type
set complex instance type with parts: [TYPE_PARTS] for select: [COMPLEX_SELECT]
set selected type: "ComplexType" for select: [COMPLEX_SELECT]
create SELECT for select: [COMPLEX_SELECT]

36. Dart API Integration

The Blockly generators map directly to Dart method calls:

// Blockly: set value: [VAL] for select: [SEL]
// Generated: sel.setValue(val)

// Blockly: get bool from select: [SEL]
// Generated: sel.getBool()

// Blockly: set selected type: "TYPE" for select: [SEL]
// Generated: sel.setSelectedType(typeName: "TYPE")

36.1. Generator Notes

  1. String handling: Type names are automatically formatted with getDartString()

  2. Optional parameters: Default values used when optional inputs are empty

  3. Error prevention: Generators return empty code for incomplete blocks

37. Limitations

  1. Dynamic type constraints: Cannot provide dropdown validation at design time

  2. Schema dependence: Behavior varies by STEP application protocol

  3. Runtime errors: Type mismatches only caught at execution time

38. Examples

// Example 1: Creating and populating a SELECT
create SELECT for select: [ROOT_SELECT]
set selected type: "IfcCartesianPoint" for select: [NEW_SELECT]
set value: [POINT_INSTANCE] for select: [NEW_SELECT]

// Example 2: Working with aggregate values
add value: 42 to select: [INT_SELECT]
add value: 99 to select: [INT_SELECT]
update element with index: 0 to value: 100 for select: [INT_SELECT]

// Example 3: Instance reference management
set value to instance reference: [WALL_INSTANCE] add inverse? true for select: [REL_SELECT]
add instance reference: [DOOR_INSTANCE] add inverse? false to select instances values for select: [AGG_SELECT]

39. See Also

  • instance_blocks.ts - Instance manipulation blocks

  • utility/utility.ts - String formatting utilities

  • STEP Application Protocols - Schema definitions for type constraints

Section Block Image Generated Function Description

Value Management

Set Value Block

setValue(value)

Set SELECT’s stored value. Returns true if successful (type must match selected type).

Value Management

Get Value Block

  • getBool()

  • getInt()

  • getReal()

  • getString()

  • …​

Get SELECT’s stored value. Specify expected value type from dropdown.

Aggregate Operations

Add Value Item Block

addValue(value)

Add element to aggregate SELECT value. Returns true if successful.

Aggregate Operations

Remove Item From Value Block

removeValue(index)

Remove element from aggregate SELECT value. Returns true if successful.

Aggregate Operations

Update Value Item Block

updateValue(index, value)

Update element in aggregate SELECT value. Returns true if successful.

Type Management

Set Selected Type Block

setSelectedType(typeName: typeName)

Set SELECT’s selected value type. Returns true if successful.

Type Management

Create Selected Value Block

  • createSelect()

  • createInstance()

  • createEnum()

Create value for SELECT’s selected type. Returns created object (ENUM, SELECT, or INSTANCE).

Type Management

Set Complex Instance Type Block

setSelectedComplexType(parts)

Set complex instance type as SELECT’s selected type using component parts. Returns true if successful.

Instance Operations

Set Instance Reference Block

setInstanceRef(instance, addInverse?)

Set SELECT value to instance reference. If 'add inverse' is true, adds inverse relationship. Returns true if successful.

Instance Operations

Add Instance Reference Block

addInstanceRef(instance, addInverse?)

Add instance reference to SELECT’s aggregate instance values. Returns true if successful.

Special Operations

Nullify Value Block

nullify()

Set SELECT value to null. Returns true if successful (always true for nullable SELECTs).

Special Operations

Duplicate Select Block

duplicate()

Create duplicate of SELECT. Returns detached duplicate.

Special Operations

Detach Select Block

detach(detachAll?)

Detach SELECT from parent buffer. If detachAll is true, also detaches all contained instances and nested SELECTs. Returns true if successful.

Property Access

Get Read Only Properties Block

  • descriptor

  • isDetachAll

  • isDetach

  • type

  • …​

Get SELECT read-only properties: descriptor, type, selectedTypeName, selectedBaseType, etc.

Dictionary API Reference

40. Overview

The Dictionary API provides a comprehensive set of tools for working with dictionaries (Map<String, dynamic>) in the PicoSTEP environment. Dictionaries are fundamental data structures used throughout the system for configuration, data exchange, and runtime state management.

40.1. Key Features

  • Type-safe operations with runtime validation

  • JSON interoperability - seamless conversion to/from JSON format

  • Nested path support - access deeply nested values using key paths

  • Dual output generation - supports both JSON (static configuration) and Dart (runtime execution) output formats

  • Dynamic typing - values can be of any type (dynamic), providing maximum flexibility

41. Block Categories

41.1. Dictionary Creation

41.1.1. dictionary_create_empty_dictionary

Creates an empty dictionary as Map<String, dynamic>.

Generated Code: <String, dynamic>{}

Tooltip: create an empty dictionary as a Map<String, dynamic>

41.1.2. dictionary_lateral_object

Creates a dictionary literal with key-value pairs using statement-based construction.

Generated Code: { key1: value1, key2: value2 }

Tooltip: Create an empty dictionary literal with key-value pairs

41.1.3. member / dictionary_key_value_pair

Individual key-value pairs used for constructing dictionaries. These blocks have dual behavior depending on context (JSON vs Dart generation).

Generated Code: "key": value

Tooltip: dictionary key and value pair

41.2. Value Access Operations

41.2.1. dictionary_get_value

Retrieves a value by key with optional default value.

Inputs: - KEY: String key to lookup - DICTIONARY: Source dictionary - DEFAULT: Default value if key not found

Generated Code: (getDictionaryValue(dictionary, key) ?? defaultValue)

Tooltip: Get value for the given key. Returns default value if key not found.

41.2.2. dictionary_get_value_by_path

Retrieves a value using a nested key path (e.g., ['user', 'profile', 'name']).

Inputs: - KEYPATH: Array of keys for nested access - DICTIONARY: Source dictionary - DEFAULT: Default value if path not found

Generated Code: (getDictionaryValueByPath(dictionary, keyPath) ?? defaultValue)

Tooltip: Get value using nested key path (e.g., ['user', 'profile', 'name']). Returns default if path not found.

41.3. Value Modification Operations

41.3.1. dictionary_set_value

Sets or updates a value for a key in the dictionary.

Inputs: - KEY: String key - VALUE: Value to set - DICTIONARY: Target dictionary

Generated Code: setDictionaryValue(dictionary, key, value);

Tooltip: set dictionary value.

41.3.2. dictionary_set_value_by_path

Sets a value using a nested key path, creating intermediate dictionaries if needed.

Inputs: - KEYPATH: Array of keys for nested access - VALUE: Value to set - DICTIONARY: Target dictionary

Generated Code: setDictionaryValueByPath(dictionary, keyPath, value);

Tooltip: Set value using nested key path. Creates intermediate dictionaries if needed.

41.3.3. dictionary_remove_entry_from_dictionary

Removes an entry by key and returns the removed value.

Inputs: - KEY: String key to remove - DICTIONARY: Target dictionary

Generated Code: dictionary.remove(key)

Tooltip: Remove entry with specified key from dictionary. Returns the removed value.

41.3.4. dictionary_clear_dictionary

Removes all entries from a dictionary.

Inputs: - DICTIONARY: Dictionary to clear

Generated Code: dictionary = <String,dynamic>{};

Tooltip: Remove all entries from dictionary, leaving it empty.

41.4. Dictionary Inspection

41.4.1. dictionary_is_key_in_dictionary

Checks if a key exists in the dictionary.

Inputs: - KEY: String key to check - DICTIONARY: Dictionary to inspect

Generated Code: isKeyInDictionary(dictionary, key)

Tooltip: Check if key exists in dictionary. Returns true if key is present.

41.4.2. dictionary_get_keys_or_values

Retrieves all keys or all values from the dictionary as a list.

Inputs: - KEYVALUE: Dropdown ("keys" or "values") - DICTIONARY: Source dictionary

Generated Code: getDictionaryKeys(dictionary) / getDictionaryValues(dictionary)

Tooltip: Get all keys or all values from dictionary as a list.

41.4.3. dictionary_size

Gets the number of key-value pairs in the dictionary.

Inputs: - DICTIONARY: Dictionary to measure

Generated Code: dictionarySize(dictionary)

Tooltip: Get number of key-value pairs in dictionary.

41.4.4. dictionary_is_dictionary

Checks if an object is a valid dictionary (Map<String, dynamic>).

Inputs: - INPUT: Object to check

Generated Code: isDictionary(object)

Tooltip: is object a dictionary Map<String, dynamic>?

41.5. Format Conversion

41.5.1. dictionary_string_to_dictionary

Converts a JSON string to a dictionary.

Inputs: - JSONSTRING: JSON-formatted string

Generated Code: toDictionary(jsonString)

Tooltip: convert json string to dictionary

41.5.2. dictionary_dictionary_to_string

Converts a dictionary to a JSON string.

Inputs: - DICTIONARY: Dictionary to convert

Generated Code: toJsonString(dictionary)

Tooltip: Convert dictionary to JSON string format.

41.6. Type Support

41.6.1. dictionary_user_defined_instance_attribute_value_types

Provides type strings for user-defined instance attributes. Used with dictionary construction for custom entity types.

Inputs: - TYPE: Dropdown of supported types

Generated Code: "TYPE_STRING" (e.g., "BOOLEAN", "INTEGER", "ENTITY")

Tooltip: Returns type strings for user-defined instance attributes. Use with dictionary construction for defined user customer entity type.

42. Usage Patterns

42.1. Basic Dictionary Creation

create empty dictionary
// Then add key-value pairs
key: "name" value: "John"
key: "age" value: 30
// Result: { "name": "John", "age": 30 }

42.2. Nested Dictionary Access

get value with path key: ['user', 'profile', 'email']
from dictionary: [USER_DATA]
if not found: "[email protected]"

42.3. JSON Integration

convert json string to dictionary: '{"key": "value"}'
set value with key: "newKey"
to value: "newValue"
in dictionary: [DICTIONARY]
dictionary: [DICTIONARY] to string

43. Technical Notes

43.1. Dual Generator Architecture

The API supports two output formats through separate generator implementations:

  • JSON Generator (jsonGenerator !== null): Produces static JSON configuration

  • Dart Generator (jsonGenerator === null): Produces runtime Dart code

43.2. String Handling Utilities

The system uses several utility functions for consistent string formatting:

  • getDartString(): Ensures proper Dart string literal formatting

  • replaceQuotes(): Converts single quotes to double quotes for JSON compatibility

  • removeParentheses() / removeOuterParentheses(): Cleans expression formatting

43.3. Type Safety

While dictionaries support dynamic types (Map<String, dynamic>), the API provides:

  • Input validation for required parameters

  • Default value support for safe access patterns

  • Type checking via dictionary_is_dictionary

44. Best Practices

44.1. Always Check for Existence

is key: "requiredKey" in dictionary: [MY_DICT]
if true
    get value with key: "requiredKey" from dictionary: [MY_DICT]
else
    // Handle missing key

44.2. Use Default Values

get value with key: "optionalKey"
from dictionary: [MY_DICT]
if not found: "defaultValue"

44.3. Validate JSON Strings

convert json string to dictionary: [JSON_STRING]
is dictionary? [RESULT]
if true
    // Use dictionary
else
    // Handle parse error

44.4. Path-Based Access for Nested Structures

For deeply nested dictionaries, use path-based access instead of multiple get_value calls:

// Instead of chained gets:
get value with key: "user" from dictionary: [DATA]
get value with key: "profile" from dictionary: [RESULT]
get value with key: "email" from dictionary: [PROFILE]

// Use path-based access:
get value with path key: ['user', 'profile', 'email'] from dictionary: [DATA]

45. Error Handling

45.1. Empty/Missing Inputs

Generators return empty strings for incomplete blocks, preventing runtime errors.

45.2. Invalid JSON

toDictionary() handles JSON parse errors gracefully, returning null or empty dictionaries.

45.3. Missing Keys

All get operations support default values to handle missing keys safely.

46. Performance Considerations

  1. Path-based operations are more efficient for deeply nested structures

  2. Batch operations (keys/values retrieval) are optimized

  3. Inline dictionary creation is preferred for static data

  4. Reuse dictionaries when possible instead of creating new ones

47. Integration Examples

47.1. With SELECT API

create SELECT for select: [ROOT_SELECT]
set value: [DICTIONARY] for select: [SELECT]

47.2. With Instance Attributes

set value with key: "attributeType"
to value: [TYPE_FROM_DROPDOWN]
in dictionary: [ATTRIBUTE_DEF]

47.3. Configuration Management

convert json string to dictionary: [CONFIG_JSON]
get value with path key: ['database', 'host'] from dictionary: [CONFIG]

48. See Also

  • SELECT API - For working with SELECT objects

  • Instance API - For entity instance manipulation

  • Utility Functions - String formatting and type conversion helpers

All dictionary operations are implemented as Map<String, dynamic> in Dart, providing maximum flexibility while maintaining type safety for keys.
Section Block Image Generated Function Description

Dictionary Creation

Create Empty Dictionary Block

<String, dynamic>{}

Create an empty dictionary as a Map<String, dynamic>.

Dictionary Creation

Dictionary Literal Block

lateral map {}

Create an empty dictionary literal with key-value pairs.

Dictionary Creation

Key-Value Pair Block

key: value

Dictionary key and value pair.

Dictionary Creation

Key-Value Pair Block

key: instance key words

Key word constant (as key) for dictionary construction.

Value Access

Get Value Block

getDictionaryValue(dictionary, key) ?? defaultValue

Get value for the given key. Returns default value if key not found.

Value Access

Get Value By Path Block

getDictionaryValueByPath(dictionary, keyPath) ?? defaultValue

Get value using nested key path (e.g., ['user', 'profile', 'name']). Returns default if path not found.

Value Modification

Set Value Block

setDictionaryValue(dictionary, key, value);

Set dictionary value.

Value Modification

Set Value By Path Block

setDictionaryValueByPath(dictionary, keyPath, value);

Set value using nested key path. Creates intermediate dictionaries if needed.

Value Modification

Remove Entry Block

dictionary.remove(key)

Remove entry with specified key from dictionary. Returns the removed value.

Value Modification

Clear Dictionary Block

dictionary = <String,dynamic>{};

Remove all entries from dictionary, leaving it empty.

Dictionary Inspection

Get Keys or Values Block

  • getDictionaryKeys(dictionary)

  • getDictionaryValues(dictionary)

Get all keys or all values from dictionary as a list.

Dictionary Inspection

Dictionary Size Block

dictionarySize(dictionary)

Get number of key-value pairs in dictionary.

Dictionary Inspection

Is Dictionary Block

isDictionary(object)

Is object a dictionary Map<String, dynamic>?

Format Conversion

String to Dictionary Block

toDictionary(jsonString)

Convert json string to dictionary.

Format Conversion

Dictionary to String Block

toJsonString(dictionary)

Convert dictionary to JSON string format.

Type Support

Attribute Types Block

  • BOOLEAN

  • INTEGER

  • REAL

  • STRING

  • …​.

Returns FundamentalType string value for user-defined instance attributes. Use with dictionary construction for defined user customer entity type.

File I/O API Reference

49. Overview

The File I/O API provides a comprehensive set of tools for reading, writing, and manipulating STEP model files in the PicoSTEP environment. This API enables programmatic access to file operations, supporting both CSV (Part 21) and JSON formats for model export and data interchange.

49.1. Key Features

  • Stream-based file operations - Efficient buffered I/O with explicit open/close lifecycle

  • Dual format support - Export models in both CSV (ISO 10303-21) and JSON formats

  • Model-aware operations - Specialized functions for STEP model headers, instances, and reference data

  • Error-safe design - All operations return boolean success indicators

  • Path validation - Automatic folder existence checking for file operations

50. Core Concepts

50.1. PIFileStream

The central object for all file operations. Represents a buffered file stream that must be explicitly opened before use and closed after operations are complete.

50.2. Export Formats

  • CSV (0) - ISO 10303-21 (Part 21) plain text encoding, the standard STEP file format

  • JSON (1) - JavaScript Object Notation, useful for web applications and data interchange

50.3. Operation Lifecycle

create stream → open stream → perform operations → flush/close stream

51. Block Categories

51.1. Stream Management

51.1.1. file_io_create_stream

Creates a new file stream object for output operations.

Generated Code: PIFileStream()

Tooltip: Create an output file stream for write. Returns PIFileStream object.

51.1.2. file_io_open_stream

Opens a file stream to a specific file location.

Inputs: - FILESTREAM: PIFileStream object - FILEPATH: String path to file

Generated Code: stream.open(filepath)

Tooltip: Open the file stream to the given file location. The folder to store the file must exist else open returns false.

51.1.3. file_io_close_stream

Closes an open file stream.

Inputs: - FILESTREAM: PIFileStream object to close

Generated Code: stream.close()

Tooltip: Close the file stream. Returns true if success.

51.1.4. file_io_flush_stream

Flushes buffered data to the file system.

Inputs: - FILESTREAM: PIFileStream object to flush

Generated Code: stream.flush()

Tooltip: Flush the file stream to file system. Return true if success.

51.2. Basic File Operations

51.2.1. file_io_write_string_to_stream

Writes a raw string to an open file stream.

Inputs: - CONTENT: String content to write - FILESTREAM: Target file stream

Generated Code: stream.writeString(content)

Tooltip: Write a string to the stream. Returns true if success.

51.2.2. file_io_sort_csv_file_instances

Sorts instances in a CSV (Part 21) file by instance ID.

Inputs: - INPUTFILE: Path to source CSV file - OUTPUTFILE: Path for sorted output file

Generated Code: PIFileStream.sortInstancesInFile(inputFile, outputFile)

Tooltip: Sort CSV model (part 21) instances in file in ascending order by id. Returns true if success.

51.3. Model Export Operations

51.3.1. file_io_write_header

Exports model header information to file.

Inputs: - HEADER: IInstance containing header data - TYPE: Format (CSV or JSON) - STREAM: Target file stream

Generated Code: stream.writeInstance(header, ExportFormat.values[type])

Tooltip: Output model header instance to the file stream in the selected format. The output will be either the HEADER section of a part21 file (csv) or header object in JSON. Return true if success.

51.3.2. file_io_write_instance

Exports a single model instance to file.

Inputs: - INSTANCE: IInstance to export - TYPE: Format (CSV or JSON) - STREAM: Target file stream

Generated Code: stream.writeInstance(instance, ExportFormat.values[type])

Tooltip: Output the instance to the file stream in the selected format. Return true if success.

51.4. Reference Model Operations

51.4.1. file_io_write_reference_data_section

Exports reference model data section.

Inputs: - MODEL: Reference model (PIModel/PIIfcModel/PISTPModel) - TYPE: Format (CSV or JSON) - STREAM: Target file stream - SKIPUPDATE: Boolean to skip updates

Generated Code: model.writeReferenceDataSectionToStream(stream, skipUpdate, ExportFormat.values[type])

Tooltip: Write reference model’s data section to stream. If 'skip update' is true, outputs original unmodified content. Returns true if successful. This API is only available to IReferenceModel.

51.4.2. file_io_write_reference_model_updated_data

Exports reference model change log.

Inputs: - MODEL: Reference model (PIModel/PIIfcModel/PISTPModel) - TYPE: Format (CSV or JSON) - STREAM: Target file stream

Generated Code: model.writeUpdatedDataSectionToStream(stream, ExportFormat.values[type])

Tooltip: Output reference model updates to file stream. Returns true if success.

52. Usage Patterns

52.1. Basic File Write Pattern

create file stream
open file stream: [STREAM] with file path: "/path/to/file.txt"
write string: "Hello, World!" to stream: [STREAM]
flush file stream: [STREAM]
close file stream: [STREAM]

52.2. Model Export Pattern

create file stream
open file stream: [STREAM] with file path: "/output/model.csv"
write header: [HEADER_INSTANCE] as csv to stream: [STREAM]
write instance: [INSTANCE_1] as csv to stream: [STREAM]
write instance: [INSTANCE_2] as csv to stream: [STREAM]
close file stream: [STREAM]

52.3. CSV File Processing

sort instance in file: "/input/unsorted.csv" save result to file: "/output/sorted.csv"

53. Best Practices

53.1. Always Use Proper Lifecycle Management

// ✅ CORRECT: Explicit open/close
create file stream
open file stream: [STREAM] with file path: "file.txt"
// ... operations ...
close file stream: [STREAM]

// ❌ AVOID: Missing close can cause resource leaks

53.2. Check Folder Existence Before Opening

// The open() method will fail if parent folders don't exist
// Ensure directory structure exists before calling open()

53.3. Use Flush for Critical Data

// After important writes, flush to ensure data is persisted
write string: "Important data" to stream: [STREAM]
flush file stream: [STREAM]
// Data is now safely on disk

53.4. Handle Reference Models Appropriately

// Reference models have special requirements
write reference model: [REF_MODEL] data section as: csv to stream: [STREAM] skip update: false
// Note: Requires IReferenceModel interface

54. Error Handling

54.1. Return Value Checking

All File I/O operations return boolean values indicating success. Always check these returns:

create file stream
set [STREAM] to [RESULT]
open file stream: [STREAM] with file path: "/path/file.txt"
if [RESULT]
    // Success - continue with operations
else
    // Handle error - folder may not exist

54.2. Common Error Conditions

  1. Folder doesn’t exist - open() returns false

  2. File permission issues - Operations return false

  3. Invalid model types - Reference model operations require IReferenceModel

  4. Stream not open - Operations on unopened streams fail

55. Performance Considerations

  1. Buffer management - Use flush() judiciously; frequent flushing reduces performance

  2. Stream reuse - Create stream once and reuse for multiple operations

  3. Batch operations - Group writes before flushing for better performance

  4. Memory usage - Large files may require streaming approach rather than loading entirely

56. Integration Examples

56.1. Exporting Complete Model

create file stream
open file stream: [STREAM] with file path: "model.json"
write header: [MODEL_HEADER] as json to stream: [STREAM]
for each [INSTANCE] in [MODEL_INSTANCES]
    write instance: [INSTANCE] as json to stream: [STREAM]
end
close file stream: [STREAM]

56.2. Data Migration Pipeline

// Convert CSV to JSON format
create file stream
open file stream: [STREAM] with file path: "output.json"
write header: [HEADER] as json to stream: [STREAM]

for each instance in read from: "input.csv"
    write instance: [INSTANCE] as json to stream: [STREAM]
end

close file stream: [STREAM]

56.3. Reference Model Backup

// Backup reference model with original data
create file stream
open file stream: [STREAM] with file path: "backup.csv"
write reference model: [REF_MODEL] data section as: csv to stream: [STREAM] skip update: true
close file stream: [STREAM]

57. Technical Notes

57.1. Format Mapping

  • CSV = ExportFormat.values[0]

  • JSON = ExportFormat.values[1]

The dropdown values map directly to the ExportFormat enum indices.

57.2. File Path Requirements

All file paths must: 1. Use forward slashes (/) or platform-appropriate separators 2. Have existing parent directories 3. Be valid for the operating system

57.3. Stream State Management

PIFileStream objects maintain internal state: 1. Created - Object exists but not connected to file 2. Open - Connected to file, ready for operations 3. Closed - Connection terminated, cannot perform operations

The file_io_write_reference_data_section block requires the model to implement the IReferenceModel interface. Attempting to use this with regular models will fail.

58. See Also

  • SELECT API - For working with SELECT objects in models

  • Instance API - For creating and manipulating model instances

  • Dictionary API - For configuration and data structures used in file operations

Always ensure proper error handling when working with file operations. File system permissions, disk space, and path validity can all cause operations to fail even with correct code logic.

59. Best Practices

  1. Always close streams to prevent resource leaks

  2. Check return values - all operations return success booleans

  3. Use flush() after critical writes to ensure persistence

  4. Verify folder existence before opening files

  5. Reference models require IReferenceModel interface

60. Error Handling

  • open() fails if parent folders don’t exist

  • Operations return false on permission issues

  • Reference model operations fail without IReferenceModel interface

Format mapping: CSV = ExportFormat.values[0], JSON = ExportFormat.values[1] Always implement proper error checking for file system operations.

File I/O API Reference

61. Overview

The File I/O API provides tools for reading, writing, and manipulating STEP model files in PicoSTEP. It supports CSV (Part 21) and JSON formats for model export and data interchange.

62. Core Concepts

PIFileStream: Central object for buffered file operations Export Formats: CSV (0) = ISO 10303-21, JSON (1) = JavaScript Object Notation Lifecycle: create → open → operate → flush/close

63. Block Reference

Section Block Image Generated Function Description

Stream Management

Create Stream Block

PIFileStream() constructor

Create an output file stream for write. Returns PIFileStream object.

Stream Management

Open Stream Block

stream.open(filepath)

Open the file stream to the given file location. The folder must exist.

Stream Management

Close Stream Block

stream.close()

Close the file stream. Returns true if success.

Stream Management

Flush Stream Block

stream.flush()

Flush the file stream to file system. Return true if success.

Basic Operations

Write String Block

stream.writeString(content)

Write a string to the stream. Returns true if success.

Basic Operations

Sort CSV Block

PIFileStream.sortInstancesInFile(inputFile, outputFile)

Sort CSV model (part 21) instances in ascending order by id.

Model Export

Write Header Block

stream.writeInstance(header, ExportFormat.values[type])

Output model header instance as CSV (Part 21 HEADER) or JSON header object.

Model Export

Write Instance Block

stream.writeInstance(instance, ExportFormat.values[type])

Output instance to file stream as CSV Part 21 line or JSON object.

Reference Models

Write Data Section Block

model.writeReferenceDataSectionToStream(stream, skipUpdate, ExportFormat.values[type])

Write reference model’s data section. Skip updates outputs original content. (IReferenceModel only)

Reference Models

Write Updated Data Block

model.writeUpdatedDataSectionToStream(stream, ExportFormat.values[type])

Output reference model updates to file stream.

PicoComposer Utility Blocks API

64. Overview

Utility Blocks provide essential helper functions and operations that complement PicoComposer’s core modeling and instance APIs. These blocks handle common programming tasks, type operations, logging, and utility functions needed in CAD/BIM automation workflows.

All utility blocks use the utility_blocks style category Blocks generate null-safe Dart code compatible with INullableObject interface

65. Block Categories

65.1. Type Operations

Type manipulation and checking blocks for working with PicoComposer’s object system.

65.1.1. Cast Object (utility_object_as)

Casts an object to a specific type using Dart’s as operator.

Inputs: - OBJECT - Object to cast - OBJECTTYPE - Target type (dropdown selection)

Output: Cast object of specified type

Example Dart Output:

someObject as PIStore

This block may throw TypeError if the cast fails. Use with utility_object_is for safe type checking.

65.1.2. Check Object Type (utility_object_is)

Checks if an object is of a specific type using Dart’s is operator.

Inputs: - OBJECT - Object to check - OBJECTTYPE - Type to check against (dropdown)

Output: Boolean (true if type matches)

Example Dart Output:

someObject is PIProject

65.1.3. Check Null Object (utility_is_null_object)

Checks if an object is null using the NullChecker.isNull() method.

Inputs: - OBJECT - Object to check

Output: Boolean (true if object is null)

Example Dart Output:

NullChecker.isNull(someObject)

65.1.4. Dynamic Cast Object (utility_cast_object_type)

Casts an object to a dynamically specified type.

Inputs: - OBJECT - Object to cast - TYPE - Target type as string

Output: Cast object

Example Dart Output:

someObject as "PIStore"

65.1.5. Dynamic Type Check (utility_is_object_type)

Checks if an object is of a dynamically specified type.

Inputs: - OBJECT - Object to check - TYPE - Type to check as string

Output: Boolean (true if type matches)

Example Dart Output:

someObject is "PIStore"

Example Dart Output:

index < FundamentalType.values.length ? FundamentalType.values[index] : FundamentalType.values[0]

If index is out of bounds, returns the first enum value (index 0).

65.2. Function and Method Calling

Blocks for calling functions and object methods.

65.2.1. Call Function (utility_call_function)

Calls a function with optional parameters (void return).

Inputs: - FUNCTIONNAME - Function name as string - PARAMETERS - Optional parameters as string expression

Output: Statement (no return value)

Example Dart Output:

someFunction(param1, param2);

65.2.2. Call Function with Return (utility_call_function_with_return)

Calls a function with optional parameters and returns result.

Inputs: - FUNCTIONNAME - Function name as string - PARAMETERS - Optional parameters as string expression

Output: Function return value

Example Dart Output:

someFunction(param1, param2)

65.2.3. Call Object Method (utility_call_object_method)

Calls a method on an object (void return).

Inputs: - FUNCTIONNAME - Method name as string - OBJECT - Target object - PARAMETERS - Optional parameters as string expression

Output: Statement

Example Dart Output:

someObject.someMethod(param1, param2);

65.2.4. Call Object Method with Return (utility_call_object_method_with_return)

Calls a method on an object and returns result.

Inputs: - FUNCTIONNAME - Method name as string - OBJECT - Target object - PARAMETERS - Optional parameters as string expression

Output: Method return value

Example Dart Output:

someObject.someMethod(param1, param2)

65.3. Object Property Access

65.3.1. Get Object Property (utility_object_get_property)

Retrieves a property value from an object.

Inputs: - PROPERTYNAME - Property name as string - OBJECT - Target object

Output: Property value

Example Dart Output:

someObject.propertyName

65.3.2. Set Object Property (utility_object_set_property)

Sets a property value on an object.

Inputs: - PROPERTYNAME - Property name as string - VALUE - Value to set - OBJECT - Target object

Output: Statement

Example Dart Output:

someObject.propertyName = someValue;

65.3.3. Get Record Item (utility_function_get_record_item)

Retrieves an item from a Dart record.

Inputs: - ITEM - Item number (1-9, dropdown) - RECORD - Record object

Output: Record item value

Example Dart Output:

someRecord.$1

65.3.4. Get Option Value (utility_get_option_value)

Extracts value from Dart Option type with fallback.

Inputs: - OPTION - Option object (PIBool, PIInt, PIString, PIDouble) - ELSEVALUE - Fallback value

Output: Option value or fallback

Example Dart Output:

someOption.getOrElse(() => fallbackValue)

65.4. Logging

65.4.1. Log Message (utility_log_message)

Logs a message to the procedure log file.

Inputs: - MESSAGE - Message string

Output: Statement

Example Dart Output:

piLogger.d("Some message");

65.4.2. Logger with Level (utility_logger)

Logs a message with specified severity level.

Inputs: - MESSAGETYPE - Log level (debug, info, warning, error) - MESSAGE - Message string

Output: Statement

Example Dart Output:

piLogger.e("Error message");

Log files are written to picomposer_procedure.log in the temp directory.

65.5. Time Utilities

65.5.1. Get Timestamp (utility_time_stamp)

Returns current timestamp as number.

Output: Number (timestamp)

Example Dart Output:

timeStamp()

65.5.2. Timestamp to String (utility_time_stamp_to_string)

Converts timestamp number to formatted string.

Inputs: - TIMESTAMP - Timestamp number

Output: String (formatted time)

Example Dart Output:

stringFromTimeStamp(1234567890)

65.6. Math Utilities

65.6.1. Degree to Radian (utility_degree_to_radian)

Converts angle from degrees to radians.

Inputs: - DEGREEINPUT - Angle in degrees

Output: Number (angle in radians)

Example Dart Output:

(someDegrees * Math.pi) / 180.0

65.6.2. String to 32-bit Hash (utility_string_to_32hash)

Computes unsigned 32-bit hash from string.

Inputs: - STRING - Input string

Output: Number (hash value)

Example Dart Output:

toTypeId("some string")

65.6.3. Create GUID (utility_get_guid)

Generates a GUID string.

Output: String (GUID)

Example Dart Output:

getGuid()

65.6.4. Map Key-Value Pair (utility_map_int_int_pair)

Creates a key-value pair for Map<int, int> construction.

Inputs: - KEY - Integer key - VALUE - Integer value

Output: Statement (pair)

Example Dart Output:

1: 100,
2: 200

Use multiple blocks chained together, then collect with a Map constructor block.

65.7. Code Generation

65.7.1. Inline Code Editor (utility_multiline_field_editor)

Inserts inline Dart code as statement.

Inputs: - CODE - Multiline code input field

Output: Statement

Example Dart Output:

// User's code directly inserted
someCustomCode();

65.7.2. Inline Code Editor with Return (utility_multiline_field_editor_with_return)

Inserts inline Dart code with return value.

Inputs: - CODE - Multiline code input field

Output: Code expression result

Example Dart Output:

// User's code directly inserted
someCustomExpression

These blocks execute user-provided Dart code directly. Ensure code is from trusted sources as it runs in the Dart VM sandbox.

65.7.3. Insert Comment (utility_insert_comment)

Adds a comment to generated code.

Inputs: - COMMENT - Comment text

Output: Statement

Example Dart Output:

// Some comment

66. Best Practices

66.1. Type Safety

  • Use utility_object_is before utility_object_as for safe casting

  • Check for null objects before property/method access

  • Use Option types (utility_get_option_value) for nullable values

66.2. Error Handling

  • Wrap risky casts in try-catch blocks (use standard Blockly try-catch)

  • Validate function/method parameters before calling

  • Use logging blocks to trace execution flow

66.3. Performance

  • Cache frequently accessed properties

  • Use string hashing (utility_string_to_32hash) for string comparisons

  • Minimize dynamic type checks in loops

67. Examples

67.1. Safe Type Checking and Casting

[utility_object_is] -> [If] condition
  OBJECT: someObject
  OBJECTTYPE: PIStore

[If] true branch -> [utility_object_as]
  OBJECT: someObject
  OBJECTTYPE: PIStore

[utility_object_as] -> [utility_object_get_property]
  PROPERTYNAME: "storeName"

67.2. Comprehensive Logging

[utility_logger]
  MESSAGETYPE: info
  MESSAGE: "Starting import process"

[utility_time_stamp] -> [utility_log_message]
  MESSAGE: "Started at: [utility_time_stamp_to_string]"

[utility_logger]
  MESSAGETYPE: error
  MESSAGE: "Import failed: [text_join]"

67.3. Enum Iteration

[lists_create_with] -> [For] counter
  items: [utility_create_enum_from_index] for i=0..n

[For] loop -> [utility_get_enum_name]
  ENUM: current item

[utility_get_enum_name] -> [utility_log_message]

68. Supported Types

The following types are supported in type dropdowns:

  • PIStore, PIProject, ProjectInfo

  • PIModel, PIIfcModel, PISTPModel

  • PITemplateManager, PISchema

  • EntityDescriptor, SelectDescriptor, EnumDescriptor

  • TypeDescriptor, AttributeDescriptor

  • PIFileStream, ModelInfo, Dictionary

  • IInstance, PITemplate, InstanceHandle

  • ISelect, PIEnum, List, Matrix4

  • FundamentalType, SupportedSchema, PIAttributeFlag

69. Compatibility

  • Dart Version: 2.12+ (null-safety)

  • Blockly Version: Compatible with Blockly 9+

  • PicoComposer: Requires PicoComposer API 1.0+

  • INullableObject: All generated code respects null-safety

70. Troubleshooting

70.1. Common Errors

  • TypeError on cast: Use utility_object_is to check type first

  • Null reference: Check for null with utility_is_null_object

  • Invalid parameters: Ensure parameter strings are valid Dart expressions

  • Map construction: Use Map constructor block with key-value pairs

70.2. Debugging Tips

  1. Add logging at key points in your workflow

  2. Use comments to document complex logic

  3. Test type checks before risky operations

  4. Check log file for execution errors

71. Glossary

INullableObject

Interface for null-safe objects in PicoComposer system

Option Type

Dart’s functional approach to nullable values

Record

Dart’s lightweight tuple-like structure

GUID

Globally Unique Identifier

Type Cast

Converting an object from one type to another

72. Appendix

72.1. Code Generation Details

All utility blocks generate Dart code that:

  1. Respects null-safety principles

  2. Uses proper Dart syntax and idioms

  3. Includes error prevention checks

  4. Is compatible with PicoComposer’s execution environment

72.2. Migration from Previous Versions

If upgrading from older PicoComposer versions:

  1. Replace manual type checks with utility_object_is

  2. Use utility_get_option_value for Option types

  3. Update logging to use new logger blocks

  4. Review any custom code in multiline editors

Document generated for PicoComposer Utility Blocks API v1.0

Section Block Image Generated Function Description

Type Operations

Check Null Object Block

NullChecker.isNull(object)

Check object nullness. Returns true if target is null.

Type Operations

create typed list

<T>[]

create a empty list of give type.

Type Operations

Dynamic Cast Object Block

object as typeString

Cast an object to the given type using the as operator.

Type Operations

Dynamic Type Check Block

object is typeString

Check object type using the is operator. Returns true if type matches.

Type Operations

Dynamic Type Check Block

object is! typeString

check object is not of given type. Returns true if object is not the given type.

Function Calling

Call Function Block

functionName(parameters)

Call a function with void return. Parameters are optional.

Function Calling

Call Function with Return Block

functionName(parameters)

Call a function with return. Parameters are optional.

Function Calling

Call Object Method Block

object.methodName(parameters)

Call an object method with void return. Parameters are optional.

Function Calling

Call Object Method with Return Block

object.methodName(parameters)

Call an object method with return value. Parameters are optional.

Object Properties

Get Object Property Block

object.propertyName

Get property from object.

Object Properties

Set Object Property Block

object.propertyName = value

Set property for object.

Object Properties

Get Record Item Block

record.$itemNumber

Get ith item from a dart record.

Option Handling

Get Option Value Block

option.getOrElse(() ⇒ elseValue)

Get value from a dart Option object or returns the provided else value.

Logging

Logger Block

piLogger.level(message)

Log debug, info, warning or error message to log file. The logger piLogger is managed by PIComposer dart scripting engine.

Time Utilities

Get Timestamp Block

timeStamp()

Get time stamp as number.

Time Utilities

Timestamp to String Block

stringFromTimeStamp(timestamp)

Get string time stamp from a number.

Math Utilities

Degree to Radian Block

(degrees * Math.pi) / 180.0

Convert angle measure in degree to radian.

Math Utilities

String to Hash Block

toTypeId(string)

Compute an unsigned 32 bit hash from string.

GUID Generation

Create GUID Block

getGuid()

Create guid string.

Map Construction

Map Key-Value Pair Block

key: value

Key and value for Map<int,int> construction.

Code Generation

Inline Code Editor Block

userCode

Inline user input as code.

Code Generation

Inline Code Editor with Return Block

userCode

Inline user input as code with output.

Documentation

Insert Comment Block

//comment

Insert a comment.