Ctrlk
For the complete documentation index, see llms.txt. This page is also available as Markdown.

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 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:

4. Unit Formatting

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

Key Properties

Property
Type
Description
Default

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

Property
Type
Description
Default

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

Property
Type
Description
Default

N

Text

Table identifier

Optional

Guard

Expression

Conditional rendering

-

Structure

Tables contain:

  • DocRow objects (rows)

  • Each row contains DocCell objects (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

Property
Type
Description
Default

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

Property
Type
Description
Default

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

Property
Type
Description
Default

Width

Number

Drawing width (pixels)

800

Height

Number

Drawing height (pixels)

600

Child Elements

Contains a <P> element with:

  • N="CADD": Parameter name

  • V: Reference to section/geometry object

  • T: 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

Property
Type
Description
Default

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

Property
Type
Description
Default

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

Property
Type
Description
Default

Guard

Expression

Conditional rendering

-

Content Format

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

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

Property
Type
Description
Default

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)

Formats value with units based on the project unit system.

Parameters:

  • value: Number to format

  • 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.

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:

  1. Input Data (geometry, materials, loads)

  2. Analysis Results (forces, stresses, displacements)

  3. Design Checks (code compliance verification)

  4. 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 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.

PreviousCADD Drawing GuideNextFEA Guide

Last updated