Document Generation Guide
Overview
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
Core Concepts
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 withN,Tattributes)
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:
4. Unit Formatting
The withunits() function formats values with proper units:
Syntax: withunits(value, unitSystemParam, unitType, precision)
Parameters:
value: Numeric value to formatunitSystemParam: 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
Key Properties
Title
Text
Document title
Required
N
Text
Document name/identifier
Required
T
Text
Always "Document"
Required
XML Example
2. DocSection (Document Section)
Hierarchical sections organize content into logical groups.
Object Type: DocSection Prefix: SEC
Key Properties
Title
Text
Section heading
Required
Guard
Expression
Conditional rendering
-
Nesting
Sections can contain subsections to create hierarchy:
XML Examples
Simple Section:
Conditional Section:
Nested Sections:
3. DocTable (Document Table)
Tables display tabular data with rows and cells.
Object Type: DocTable Prefix: TABLE
Key Properties
N
Text
Table identifier
Optional
Guard
Expression
Conditional rendering
-
Structure
Tables contain:
DocRowobjects (rows)Each row contains
DocCellobjects (cells)
XML Examples
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
Key Properties
Guard
Expression
Conditional rendering
-
XML Example
Conditional Row:
5. DocCell (Table Cell)
Represents a single cell within a table row.
Object Type: DocCell
Key Properties
Style
CSS
Inline CSS styling
-
colspan
Number
Column span
1
rowspan
Number
Row span
1
Common Style Properties
Content
Cell content can include:
Plain text
Embedded variables:
|expression|HTML formatting:
<sub>,<sup>,<b>,<i>Line breaks: Standard text wrapping
XML Examples
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
Key Properties
Width
Number
Drawing width (pixels)
800
Height
Number
Drawing height (pixels)
600
Child Elements
Contains a <P> element with:
N="CADD": Parameter nameV: Reference to section/geometry objectT: Type of visualization ("Section", "3D", etc.)
XML Examples
Section Drawing:
3D Visualization:
With Section Context:
7. DocDesignCode (Design Code Check Reference)
References design code check calculations and results.
Object Type: DocDesignCode
Key Properties
Obj
String
Reference to design check object
Required
Guard
Expression
Conditional rendering
-
XML Examples
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
Key Properties
Obj
String
Reference to document object
Required
Guard
Expression
Conditional rendering
-
Use Cases
Reuse tables defined elsewhere
Reference results from other sections
Include shared content across multiple documents
XML Examples
Reference Table:
Reference Multiple Tables:
Conditional Reference:
9. DocText (Free-Form Text)
Inserts formatted text content, including markdown.
Object Type: DocText
Key Properties
Guard
Expression
Conditional rendering
-
Content Format
Text is defined within a <![CDATA[...]]> section to preserve formatting and special characters.
Markdown Support:
Start with
--mdto enable markdown processingSupports standard markdown syntax
XML Examples
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
Key Properties
N
Text
Object identifier
Optional
AnalysisType
Number
Type of analysis (0=PM, 1=MM, etc.)
0
Section
String
Section reference
Required
Width
Number
Diagram width (pixels)
800
Height
Number
Diagram height (pixels)
600
AxialForce
Expression
Applied axial force
-
Moment
Expression
Applied moment
-
Orientation
Number
Section orientation (degrees)
0
PhiComp
Number
Compression reduction factor φ
0.75
PhiTens
Number
Tension reduction factor φ
0.9
Ecu
Number
Concrete ultimate strain
0.003
Etu
Number
Steel ultimate strain
0.005
Refinement
Number
Analysis point density
500
Analysis Types
0: P-M interaction diagram (axial-moment)
1: M-M interaction diagram (biaxial moment)
Additional types depend on section analysis module
XML Examples
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)
withunits(value, unitSystem, unitType, precision)Formats value with units based on the project unit system.
Parameters:
value: Number to formatunitSystem: Unit system reference ('DR_PropU1', 'DR_StressU', etc.)unitType: 'Length', 'Force', 'Stress', 'Area', 'Moment', etc.precision: Decimal places
Examples:
round(value, decimals?)
round(value, decimals?)Rounds a number to specified decimal places.
Examples:
Guard Expressions
Guards control conditional rendering of document content based on design parameters.
Syntax
Comparison Operators
.EQ.: Equals.NE.: Not equals.GT.: Greater than.LT.: Less than.GE.: Greater than or equal.LE.: Less than or equal.AND.: Logical AND.OR.: Logical OR
Note: Use .EQ. instead of == for guards in document context.
Examples
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
Example 2: Pier Footing Report (from user example)
Best Practices
1. Consistent Table Styling
Use consistent cell styles throughout documents:
Header Cells:
Data Cells:
Left-aligned Text Cells:
2. Unit Formatting
Always use withunits() for dimensional quantities:
3. Precision Control
Use appropriate precision for different quantities:
Lengths: 2 decimal places
Areas: 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)
5. Guard Usage
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:
Summary
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 contentUnit Formatting:
withunits()for unit-aware displayConditional Rendering:
Guardattributes for adaptive documentsRich 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.
Last updated