OpenBrIM's document generation system enables creation of professional engineering calculation reports, design check documents, and technical documentation. The system uses XML-based document objects that integrate seamlessly with the parametric engine (ParamML), allowing dynamic content generation based on analysis results and design parameters.
This guide explains the document generation objects, patterns, and best practices for AI agents who will create comprehensive engineering documentation.
Key Capabilities:
Dynamic Content: Variables and expressions evaluated from parametric model
Conditional Rendering: Guards control content visibility based on design conditions
Rich Formatting: Tables, sections, text, equations, and visualizations
CAD Integration: Embed section drawings and 3D visualizations
Design Code Integration: Reference code check calculations and results
Unit-Aware Output: Automatic unit conversion and formatting
1. Document Object Hierarchy
Documents are structured as trees of objects:
Root document defines title and metadata
Sections organize content hierarchically
Content objects (tables, text, CAD, etc.) populate sections
All objects follow OpenBrIM object model (<O> elements with N, T attributes)
2. Variable Embedding
Embed parametric expressions in document content using pipe delimiters:
Syntax: |expression|
Example:
The expression is evaluated and the result is inserted into the document.
3. Conditional Content
Use Guard attributes to conditionally include/exclude document objects:
Syntax: Guard="expression"
Example:
The withunits() function formats values with proper units:
Syntax: withunits(value, unitSystemParam, unitType, precision)
Parameters:
value: Numeric value to format
unitSystemParam: Unit system reference (e.g., 'DR_PropU1', 'DR_StressU')
unitType: Type of unit ('Length', 'Force', 'Stress', 'Area', etc.)
precision: Decimal places
Example:
Result: 24.00 in (depending on unit system)
Core Document Objects
1. Document (Root Object)
The root document object defines the overall report structure.
Object Type: Document Prefix: DOC
Property
Type
Description
Default
2. DocSection (Document Section)
Hierarchical sections organize content into logical groups.
Object Type: DocSection Prefix: SEC
Property
Type
Description
Default
Sections can contain subsections to create hierarchy:
Simple Section:
Conditional Section:
Nested Sections:
3. DocTable (Document Table)
Tables display tabular data with rows and cells.
Object Type: DocTable Prefix: TABLE
Property
Type
Description
Default
Tables contain:
Each row contains DocCell objects (cells)
Two-Column Table with Header:
Three-Column Table (Description, Parameter, Value):
4. DocRow (Table Row)
Represents a single row in a document table.
Object Type: DocRow
Property
Type
Description
Default
Conditional Row:
5. DocCell (Table Cell)
Represents a single cell within a table row.
Object Type: DocCell
Property
Type
Description
Default
Common Style Properties
Cell content can include:
Embedded variables: |expression|
HTML formatting: <sub>, <sup>, <b>, <i>
Line breaks: Standard text wrapping
Header Cell:
Data Cell with Variable:
Cell with Subscript/Superscript:
Multi-line Cell:
6. DocCADD (CAD Drawing/Visualization)
Embeds CAD drawings, section visualizations, or 3D geometry in the document.
Object Type: DocCADD Prefix: CADD
Property
Type
Description
Default
Contains a <P> element with:
V: Reference to section/geometry object
T: Type of visualization ("Section", "3D", etc.)
Section Drawing:
3D Visualization:
With Section Context:
7. DocDesignCode (Design Code Check Reference)
References design code check calculations and results.
Object Type: DocDesignCode
Property
Type
Description
Default
Reference to design check object
Simple Code Check:
Conditional Code Check:
Multiple Code Checks:
Code Check with Context:
8. DocRef (Document Reference)
References another document object or table from elsewhere in the model.
Object Type: DocRef
Property
Type
Description
Default
Reference to document object
Reuse tables defined elsewhere
Reference results from other sections
Include shared content across multiple documents
Reference Table:
Reference Multiple Tables:
Conditional Reference:
9. DocText (Free-Form Text)
Inserts formatted text content, including markdown.
Object Type: DocText
Property
Type
Description
Default
Text is defined within a <![CDATA[...]]> section to preserve formatting and special characters.
Markdown Support:
Start with --md to enable markdown processing
Supports standard markdown syntax
Simple Text:
Markdown Text:
Text with Context Label:
Complete Example in Context:
10. DocSectionAnalysis (Section Analysis Diagram)
Generates interaction diagrams and section analysis visualizations.
Object Type: DocSectionAnalysis
Property
Type
Description
Default
Type of analysis (0=PM, 1=MM, etc.)
Section orientation (degrees)
Compression reduction factor φ
Tension reduction factor φ
0: P-M interaction diagram (axial-moment)
1: M-M interaction diagram (biaxial moment)
Additional types depend on section analysis module
P-M Interaction Diagram:
With Section Context:
Variable Embedding and Expressions
1. Basic Variable Reference
Syntax: |variableName|
Example:
2. Function Calls
Syntax: |functionName(arg1, arg2, ...)|
Examples:
Round Values:
Unit Conversion:
Nested Functions:
3. Object Property Access
Syntax: |objectName.propertyName|
Example:
4. Mathematical Expressions
Expressions are evaluated before display:
5. Common Functions
withunits(value, unitSystem, unitType, precision)
Formats value with units based on the project unit system.
Parameters:
unitSystem: Unit system reference ('DR_PropU1', 'DR_StressU', etc.)
unitType: 'Length', 'Force', 'Stress', 'Area', 'Moment', etc.
precision: Decimal places
Examples:
round(value, decimals?)
Rounds a number to specified decimal places.
Examples:
Guard Expressions
Guards control conditional rendering of document content based on design parameters.
Comparison Operators
.GE. : Greater than or equal
.LE. : Less than or equal
Note: Use .EQ. instead of == for guards in document context.
Simple Condition:
Multiple Conditions (OR):
Multiple Conditions (AND):
Null Check:
Numeric Comparison:
Document Structure Patterns
1. Two-Direction Design Report
Common pattern for pier footings, columns, and biaxial elements:
2. Load Case Results Pattern
Standard pattern for showing unfactored, service, and strength results:
3. Conditional Design Sections
Sections that appear only when specific design options are enabled:
4. Properties Table Pattern
Standard two-column table for properties:
5. Material Properties Table Pattern
Three-column table with description, symbol, and value:
Complete Document Examples
Example 1: Simple Beam Design Report
1. Consistent Table Styling
Use consistent cell styles throughout documents:
Header Cells:
Data Cells:
Left-aligned Text Cells:
Always use withunits() for dimensional quantities:
3. Precision Control
Use appropriate precision for different quantities:
Lengths: 2 decimal places
Stresses: 3 decimal places
Forces: 1-2 decimal places
Dimensionless ratios: 3 decimal places
4. Section Organization
Use hierarchical sections for logical organization:
Input Data (geometry, materials, loads)
Analysis Results (forces, stresses, displacements)
Design Checks (code compliance verification)
Summary (design ratios, pass/fail status)
Place guards at appropriate levels:
Section level: Hide entire design sections (e.g., optional torsion design)
Row level: Hide individual table rows (e.g., optional parameters)
Cell level: Rarely needed, usually guard at row or section level
6. CAD Drawing Placement
Place CAD drawings before related tables:
7. DocText for Context
Use DocText to provide context between design checks:
8. Subscripts and Superscripts
Use HTML tags for mathematical notation:
9. Error Handling in Expressions
Use conditional expressions to handle null values:
10. Reusable Content with DocRef
Define tables once and reference multiple times:
Advanced Patterns
1. Dynamic Table Generation
Generate table rows based on lists:
2. Multi-Level Conditional Content
Nested guards for complex logic:
3. Combined Results Tables
Single table showing multiple limit states:
4. Summary Pass/Fail Table
Design check summary with status indicators:
Common Pitfalls and Solutions
1. Missing Variable Delimiters
Wrong:
Correct:
2. Incorrect Guard Syntax
Wrong:
Correct:
3. Forgetting CDATA for DocText
Wrong:
Correct:
4. Inconsistent Cell Heights
Problem: Rows with different cell heights look unprofessional.
Solution: Use consistent height in all cells:
5. Null Value Handling
Wrong:
Correct:
6. Object Reference Syntax
Wrong:
Correct:
The OpenBrIM document generation system provides comprehensive tools for creating professional engineering reports:
Core Objects:
Document: Root object defining report structure
DocSection: Hierarchical organization of content
DocTable: Tabular data with rows and cells
DocCADD: Embedded CAD drawings and visualizations
DocDesignCode: Design code check references
DocRef: Content reuse via references
DocText: Free-form text and markdown
DocSectionAnalysis: Interaction diagrams and section analysis
Key Features:
Variable Embedding: |expression| syntax for dynamic content
Unit Formatting: withunits() for unit-aware display
Conditional Rendering: Guard attributes for adaptive documents
Rich Formatting: HTML/CSS styling in cells, subscripts, superscripts
Parametric Integration: Full access to ParamML expressions
Best Practices:
Use consistent table styling throughout documents
Always format dimensional quantities with withunits()
Place guards at appropriate hierarchical levels
Organize content logically (Input → Analysis → Design → Summary)
Use DocText to provide context between technical sections
Handle null values gracefully in expressions
Reuse common content with DocRef
By following this guide, AI agents can create comprehensive, professional engineering documentation that integrates seamlessly with OpenBrIM's parametric modeling and analysis capabilities.