3D Visualization Guide

Overview

This guide explains how to define 3D visualization structures in OpenBrIM using XML, building on top of the parametric engine. The 3D visualization system enables you to create geometric primitives (points, lines, surfaces, volumes) that are automatically rendered in 3D space.

Prerequisites: Read AI-Parametric-Engine-Guide.md first to understand the core parametric concepts (Objects, Parameters, Expressions, Repeat, etc.).

Core 3D Primitive Types

Type Names: The XML type names for 3D primitives are:

Point - 3D point (TypeScript class: Point3D)
Surface - 2D surface (TypeScript class: Surface3D)
Line - Linear extrusion (TypeScript class: Line3D)
Volume - 3D volume (TypeScript class: Volume3D)
Circle - Circular pattern (TypeScript class: Circle/ShapeCircle)
Text3D - 3D text label (TypeScript class: Text3D)

Note: The TypeScript class names include "3D" suffix, but the XML type names (used in T= attribute) do NOT include "3D" for most types, except Text3D.

What you'll learn:

Basic geometry creation (Line, Surface, Volume)
Geometric transformations (Translation, Rotation)
Transformation hierarchy and coordinate systems
Alignment-based positioning
Complete examples combining all concepts

1. Basic Geometry Generation

Line with Section

A Line creates linear 3D geometry by extruding a cross-section along a path.

Components:

Section - Defines the cross-section shape
Line - Path with 2 or more points (use PolyLine="1" for 3+ points)

Example:

<O N="MyComponent" T="Project">
    <!-- Define section parameters -->
    <P N="width" V="30" />
    <P N="depth" V="60" />
    
    <!-- Define rectangular section -->
    <O N="RectSection" T="Section">
        <O T="Shape">
            <O T="Point" X="-width/2" Y="-depth/2" />
            <O T="Point" X="width/2" Y="-depth/2" />
            <O T="Point" X="width/2" Y="depth/2" />
            <O T="Point" X="-width/2" Y="depth/2" />
        </O>
    </O>
    
    <!-- Create polyline with 3 points -->
    <O T="Line" Section="@RectSection|Section" PolyLine="1">
        <O T="Point" X="0" Y="0" Z="0" />
        <O T="Point" X="1200" Y="0" Z="0" />
        <O T="Point" X="1200" Y="600" Z="0" />
    </O>
</O>

Result: A beam with rectangular cross-section (30×60) following an L-shaped path.

2. Surface

2D surfaces defined by a set of Point children. Surfaces can be filled, have borders, include cutouts, and have thickness for extrusion into 3D.

Sub-Shape Positioning: Surfaces can contain sub-shapes (like Circle objects for cutouts) that have their own local coordinate system relative to the parent surface. Use the X, Y, and Z parameters to position sub-shapes within the parent's local coordinate space:

Sub-shapes inherit a local reference point at (0,0,0) of the parent surface
Use X, Y, Z parameters on the sub-shape to offset it from this reference point
The IsCutout parameter determines whether the sub-shape adds or subtracts from the parent

Key Parameters:

IsCutout: Boolean - if true, this surface cuts out from parent (default: false)
Thickness: Extrude the surface in Z direction (default: 0)
LocalZOffset: Offset in local Z before transformation (default: 0)
DrawBorder: Boolean - draw the perimeter border (default: false)
SegmentsAlong: Mesh density along extrusion (default: 10)
SegmentsAround: Mesh density around perimeter (default: 1)
OnExtrudedSurface: Array specifying which surfaces this appears on

XML Examples:

<!-- Simple rectangle surface -->
<O N="Rectangle" T="Surface">
  <O T="Point" X="0" Y="0" Z="0"/>
  <O T="Point" X="100" Y="0" Z="0"/>
  <O T="Point" X="100" Y="50" Z="0"/>
  <O T="Point" X="0" Y="50" Z="0"/>
</O>

<!-- Parametric surface with thickness -->
<O N="Plate" T="Surface" Thickness="2" DrawBorder="1">
  <P N="Width" V="100" Role="Input"/>
  <P N="Height" V="50" Role="Input"/>
  
  <O T="Point" X="0" Y="0" Z="0"/>
  <O T="Point" X="Width" Y="0" Z="0"/>
  <O T="Point" X="Width" Y="Height" Z="0"/>
  <O T="Point" X="0" Y="Height" Z="0"/>
</O>

<!-- Surface with circular cutout (Method 1: Using sub-Surface) -->
<O N="PlateWithHole" T="Surface">
  <O T="Surface">
    <O T="Point" X="0" Y="0" Z="0"/>
    <O T="Point" X="100" Y="0" Z="0"/>
    <O T="Point" X="100" Y="100" Z="0"/>
    <O T="Point" X="0" Y="100" Z="0"/>
  </O>
  <!-- Cutout circle positioned at center using X, Y in parent's local coordinates -->
  <O T="Circle" Radius="20" Segments="36" IsCutout="1" X="50" Y="50"/>
</O>

<!-- Surface with circular cutout (Method 2: Points directly in main surface) -->
<O N="PlateWithHole2" T="Surface">
  <O T="Point" X="0" Y="0" Z="0"/>
  <O T="Point" X="100" Y="0" Z="0"/>
  <O T="Point" X="100" Y="100" Z="0"/>
  <O T="Point" X="0" Y="100" Z="0"/>
  <!-- Cutout circle positioned at center -->
  <O T="Circle" Radius="20" Segments="36" IsCutout="1" X="50" Y="50"/>
</O>

<!-- Surface with rounded corners -->
<O N="RoundedRect" T="Surface" DrawBorder="1">
  <P N="CR" V="10" D="Corner radius"/>
  <O T="Point" X="0" Y="100" Z="0" R="CR"/>
  <O T="Point" X="100" Y="100" Z="0" R="CR"/>
  <O T="Point" X="100" Y="0" Z="0" R="CR"/>
  <O T="Point" X="0" Y="0" Z="0" R="CR"/>
</O>

<!-- Surface with chamfered corners (straight cuts) -->
<O N="ChamferedRect" T="Surface" DrawBorder="1">
  <P N="CC" V="10" D="Chamfer distance"/>
  <O T="Point" X="0" Y="100" Z="0" C="CC"/>
  <O T="Point" X="100" Y="100" Z="0" C="CC"/>
  <O T="Point" X="100" Y="0" Z="0" C="CC"/>
  <O T="Point" X="0" Y="0" Z="0" C="CC"/>
</O>

3. Volume

A Volume creates 3D solid geometry by lofting between surfaces.

Requirements:

At least 2 surfaces
Surface points must be in same order
All points coplanar within each surface

Rendering Parameters:

DrawBorder: Draw edges of extruded surfaces (default: true)
DrawFaceA: Draw start face (default: true)
DrawFaceB: Draw end face (default: true)
DrawFaceABorder: Draw border of start face (default: true)
DrawFaceBBorder: Draw border of end face (default: true)
SegmentsAlong: Mesh segments along extrusion direction (default: 10)
SegmentsAround: Mesh segments around perimeter (default: 1)
Thickness: Extrusion thickness (default: 0)
PolyLine: Treat as polyline instead of closed volume (default: false)

Transformation Parameters:

StartOffsetX, StartOffsetY, StartOffsetZ: Offset at start
EndOffsetX, EndOffsetY, EndOffsetZ: Offset at end
StartSkewX, StartSkewY: Skew angles at start
EndSkewX, EndSkewY: Skew angles at end
ReverseDir: Reverse extrusion direction (default: false)

Note: The BetaAngle parameter (rotation around extrusion axis) is only available for Line3D objects, not Volume3D.

XML Examples:

<!-- Simple box volume -->
<O N="Box" T="Volume" DrawBorder="1">
  <P N="Width" V="10"/>
  <P N="Height" V="10"/>
  <P N="Length" V="20"/>
  
  <!-- Start surface -->
  <O T="Surface">
    <O T="Point" X="0" Y="0" Z="0"/>
    <O T="Point" X="0" Y="Width" Z="0"/>
    <O T="Point" X="0" Y="Width" Z="Height"/>
    <O T="Point" X="0" Y="0" Z="Height"/>
  </O>
  
  <!-- End surface -->
  <O T="Surface">
    <O T="Point" X="Length" Y="0" Z="0"/>
    <O T="Point" X="Length" Y="Width" Z="0"/>
    <O T="Point" X="Length" Y="Width" Z="Height"/>
    <O T="Point" X="Length" Y="0" Z="Height"/>
  </O>
</O>

<!-- Tapered volume with offsets -->
<O N="TaperedBeam" T="Volume">
  <P N="Length" V="100"/>
  <P N="StartDepth" V="24"/>
  <P N="EndDepth" V="36"/>
  
  <O T="Surface">
    <O T="Point" X="0" Y="-6" Z="0"/>
    <O T="Point" X="0" Y="6" Z="0"/>
    <O T="Point" X="0" Y="6" Z="StartDepth"/>
    <O T="Point" X="0" Y="-6" Z="StartDepth"/>
  </O>
  
  <O T="Surface">
    <O T="Point" X="Length" Y="-6" Z="0"/>
    <O T="Point" X="Length" Y="6" Z="0"/>
    <O T="Point" X="Length" Y="6" Z="EndDepth"/>
    <O T="Point" X="Length" Y="-6" Z="EndDepth"/>
  </O>
</O>

<!-- Volume with offset transformation -->
<O N="OffsetColumn" T="Volume">
  <P N="Height" V="100"/>
  <P N="OffsetAmount" V="10"/>
  
  <!-- Square base -->
  <O T="Surface">
    <O T="Point" X="0" Y="-5" Z="0"/>
    <O T="Point" X="0" Y="5" Z="0"/>
    <O T="Point" X="0" Y="5" Z="10"/>
    <O T="Point" X="0" Y="-5" Z="10"/>
  </O>
  
  <!-- Offset top (using EndOffsetY) -->
  <O T="Surface" EndOffsetY="OffsetAmount">
    <O T="Point" X="Height" Y="-5" Z="0"/>
    <O T="Point" X="Height" Y="5" Z="0"/>
    <O T="Point" X="Height" Y="5" Z="10"/>
    <O T="Point" X="Height" Y="-5" Z="10"/>
  </O>
</O>

Important: Point order must match between surfaces for correct lofting.

4. Circle (ShapeCircle)

Generates circular or elliptical point patterns. Often used as cross-sections for pipes, columns, or standalone circular surfaces.

Parameters:

Radius: Primary radius (X-axis) (default: 0.1)
Radius2: Secondary radius (Y-axis) for ellipses (default: same as Radius)
Segments: Number of points/segments (default: 36)
StartAngle: Starting angle in radians (default: 0)
EndAngle: Ending angle in radians (default: 2π for full circle)

XML Examples:

<!-- Full circle -->
<O T="Circle" Radius="10" Segments="36"/>

<!-- Half circle (arc) -->
<O T="Circle" Radius="10" Segments="18" StartAngle="0" EndAngle="3.14159"/>

<!-- Ellipse -->
<O T="Circle" Radius="15" Radius2="10" Segments="48"/>

<!-- Quarter circle -->
<O T="Circle" Radius="5" StartAngle="0" EndAngle="1.5708" Segments="12"/>

<!-- Circular surface with border -->
<O N="Disk" T="Surface" DrawBorder="1">
  <O T="Circle" Radius="20" Segments="48"/>
</O>

<!-- Circular pipe -->
<O N="Pipe" T="Line">
  <P N="Length" V="100"/>
  <P N="OuterRadius" V="5"/>
  <P N="InnerRadius" V="4"/>
  
  <O T="Point" X="0" Y="0" Z="0"/>
  <O T="Point" X="Length" Y="0" Z="0"/>
  
  <!-- Hollow circular cross-section -->
  <O T="Surface">
    <!-- Outer circle -->
    <O T="Circle" Radius="OuterRadius" Segments="32"/>
  </O>
  <O T="Surface" IsCutout="1">
    <!-- Inner circle (cutout) -->
    <O T="Circle" Radius="InnerRadius" Segments="32"/>
  </O>
</O>

5. Text3D

Renders 3D text labels in space. Useful for annotations, labels, and dimension text.

Parameters:

Label: The text string to display
FontSize: Size of the font (default: 0 = auto-size)
TextAlign: Alignment (0=center, 1=left, 2=right) (default: 0)
Document: Reference to a document object for dynamic text

Positioning:

Requires minimum 3 Point children to define the text plane
First two points define the baseline and width
Third point defines the plane orientation

XML Examples:

<!-- Simple centered text -->
<O N="Label" T="Text3D" Label="BEAM A" FontSize="2">
  <O T="Point" X="0" Y="0" Z="0"/>
  <O T="Point" X="50" Y="0" Z="0"/>
  <O T="Point" X="0" Y="0" Z="10"/>
</O>

<!-- Left-aligned parametric text -->
<O N="MemberLabel" T="Text3D" FontSize="1.5" TextAlign="1">
  <P N="MemberName" V="Column-1" T="Text"/>
  <P N="Label" V="MemberName"/>
  
  <O T="Point" X="0" Y="0" Z="100"/>
  <O T="Point" X="20" Y="0" Z="100"/>
  <O T="Point" X="0" Y="5" Z="100"/>
</O>

<!-- Auto-sized text fitting width -->
<O N="AutoLabel" T="Text3D" Label="FOUNDATION" FontSize="0">
  <O T="Point" X="0" Y="0" Z="0"/>
  <O T="Point" X="100" Y="0" Z="0"/>
  <O T="Point" X="0" Y="10" Z="0"/>
</O>

2. Geometric Transformations

Objects can be translated and rotated in 3D space using transformation attributes.

Translation and Rotation (Most Common)

The most common geometric operation combines translation (X, Y) and rotation (RZ).

Transformation Attributes:

X, Y, Z - Translation along axes
RX, RY, RZ - Rotation about axes (in radians)
AX, AY, AZ - Rotation origin point

Example - Translated and Rotated Beam:

<O N="AngledBeam" T="Project">
    <P N="beam_length" V="1000" />
    <P N="beam_width" V="200" />
    <P N="beam_height" V="400" />
    
    <!-- Section definition -->
    <O N="BeamSection" T="Section">
        <O T="Shape">
            <O T="Point" X="-beam_width/2" Y="-beam_height/2" />
            <O T="Point" X="beam_width/2" Y="-beam_height/2" />
            <O T="Point" X="beam_width/2" Y="beam_height/2" />
            <O T="Point" X="-beam_width/2" Y="beam_height/2" />
        </O>
    </O>
    
    <!-- Beam translated to (500, 300) and rotated 45° -->
    <O T="Line" Section="@BeamSection|Section" X="500" Y="300" RZ="pi/4">
        <O T="Point" X="0" Y="0" Z="0" />
        <O T="Point" X="beam_length" Y="0" Z="0" />
    </O>
</O>

Transformation sequence:

Line is created at origin with points along X-axis
Translated by (500, 300)
Rotated 45° (π/4) about Z-axis

Result: A beam starting at (500, 300) oriented at 45° from horizontal.

Rotation with Custom Origin

By default, rotation occurs about the object's origin. Use AX, AY, AZ to specify a different rotation center.

Example:

<!-- Rotate about point (100, 100) instead of origin -->
<O T="Volume" X="200" Y="150" RZ="pi/6" AX="100" AY="100">
    <!-- Geometry rotates about (100, 100) -->
</O>

3. Transformation Hierarchy

Key principle: Each object's transformations are applied in its parent's transformed coordinate system.

Transformations are cumulative - child transformations occur in the already-transformed coordinate system of the parent.

Example: Nested Transformations

<O T="Group" X="30" Y="-40" RZ="pi/8">
    <O T="Line" X="60" Y="40" RZ="pi/3">
        <O N="pt1" T="Point" X="10" Y="-50" Z="0"/>
        <O N="pt2" T="Point" X="10" Y="50" Z="0"/>
    </O>
</O>

Transformation sequence:

Group level:
- Translate by (30, -40)
- Rotate coordinate system by π/8
Line level (in Group's rotated coordinate system):
- Translate by (60, 40) in rotated frame
- Rotate coordinate system another π/3
- Total rotation from global: π/8 + π/3
Point level (in Line's doubly-rotated coordinate system):
- pt1 at (10, -50) in final coordinate system
- pt2 at (10, 50) in final coordinate system

Key insight: The Line's translation (60, 40) occurs along the Group's rotated axes, not global axes.

Practical Example: Symmetric Structure

<O N="SymmetricColumns" T="Project">
    <P N="column_height" V="300" />
    <P N="column_width" V="40" />
    <P N="spacing" V="500" />
    
    <!-- Column section -->
    <O N="ColSection" T="Section">
        <O T="Shape">
            <O T="Point" X="-column_width/2" Y="-column_width/2" />
            <O T="Point" X="column_width/2" Y="-column_width/2" />
            <O T="Point" X="column_width/2" Y="column_width/2" />
            <O T="Point" X="-column_width/2" Y="column_width/2" />
        </O>
    </O>
    
    <!-- Left column -->
    <O T="Line" Section="@ColSection|Section" X="-spacing/2" Y="0">
        <O T="Point" X="0" Y="0" Z="0" />
        <O T="Point" X="0" Y="0" Z="column_height" />
    </O>
    
    <!-- Right column -->
    <O T="Line" Section="@ColSection|Section" X="spacing/2" Y="0">
        <O T="Point" X="0" Y="0" Z="0" />
        <O T="Point" X="0" Y="0" Z="column_height" />
    </O>
</O>

Result: Two identical columns positioned symmetrically at X = 250.

Parent Transformations Affect All Children

<O T="Group" X="100" Y="50" RZ="pi/4">
    <!-- All children are in rotated coordinate system -->
    
    <O T="Point" X="10" Y="0" Z="0"/>
    <!-- Actual global position: 
         1. Start at (10, 0) in rotated frame
         2. Rotated frame is at (100, 50) rotated π/4
         3. Final position calculated in global coordinates -->
    
    <O T="Line" X="20" Y="10">
        <!-- This line is translated (20, 10) in the rotated frame -->
    </O>
</O>

4. Alignment-Based Positioning

Alignments define 3D curves for positioning objects along roadways. Objects can follow alignment geometry in various ways.

What Are AlignH, AlignV, AlignT?

These three parameters control how an object attaches to an alignment:

AlignH (Horizontal Alignment) Controls how the object follows the horizontal curve (plan view)

AlignV (Vertical Alignment) Controls how the object follows the vertical profile (elevation curve)

AlignT (Transverse/Superelevation) Controls how the object follows the cross-slope/banking of the road

Alignment Modes

(1) None

Object is moved to correct station and offset
Does NOT rotate to match alignment
Does NOT bend/warp to follow curvature
Useful for translation only, preserving original orientation

(2) Orient

Object is translated and rotated to match alignment direction (tangent)
Follows alignment horizontally/vertically depending on AlignH or AlignV
No bending occurs - object remains rigid
Most commonly used for objects that must face direction of travel

(3) Warp

Object is translated, rotated, and warped to follow curvature
Continuously follows 3D shape of alignment
Perfect for continuous elements that must bend with alignment

(4) Ignore

Object does not use alignment for that axis
Alignment curvature, rotation, elevation, or superelevation completely ignored
Used when object position/rotation is independent of alignment
Allows manual coordinate specification using global coordinates

When to Use Which Mode

AlignH (Horizontal) Usage:

Mode

Use When

Examples

Ignore

No relationship to horizontal alignment, using global XY or manual calculations

Manually positioned elements

None

Placed on alignment but not rotated with curve

Roadside furniture, fixed-orientation objects

Orient

Should face road direction but remain rigid

Piers, foundations, supports

Warp

Must bend to match curved horizontal alignment

Slabs, girders, road surfaces, barriers

AlignV (Vertical) Usage:

Mode

Use When

Examples

Ignore

Using global elevation, not following road grade

Column bottom elevations, foundations

None

Apply vertical elevation at single reference point (no rotation/deformation)

Pier cap top elevation

Orient

Must rotate to match vertical slope but not deform

Pedestals, bearing seats

Warp

Must follow vertical curvature (crest/sag)

Deck surfaces, barriers, girders

AlignT (Transverse) Usage:

Mode

Use When

Examples

Ignore

Does not care about superelevation

Columns, piles, foundations

None

Superelevation should not affect rotation

Decorative geometry, steel I-girders

Orient

Should rotate with cross-slope as rigid body

U-girders, tub girders

Warp

Needs to warp across width due to superelevation

Deck slabs, road surfaces

Simple Rule of Thumb

Goal

Use

Just place object, don't rotate

None

Rotate with road direction

Orient

Bend/warp to fully follow alignment

Warp

Ignore alignment completely

Ignore

Alignment Reference Parameters

AlignX, AlignY, AlignZ Override where the object enters/attaches to the alignment, separate from the object's actual geometry coordinates (X, Y, Z).

Key distinction:

X, Y, Z - Actual geometry coordinates (always required)
AlignX, AlignY, AlignZ - Override alignment attachment point

Use case: When you want an object to attach to alignment based on another object's position.

Common scenarios:

Bearing on pier cap - Use pier cap's station as bearing's AlignX
Column under pier cap - Use pier cap's station as column's AlignX
Objects referenced to a common point - Override attachment to align with parent object

Example 1: Bearing on Pier Cap

<!-- Pier cap at station 900" (75 ft) -->
<O N="PierCap" T="Line" Alignment="@MainAlignment|Alignment" AlignH="Orient" AlignV="Ignore" AlignX="900" X="900" Y="0">
    <!-- Cap geometry -->
</O>

<!-- Bearing placed on pier cap -->
<O N="Bearing" T="Volume" Alignment="@MainAlignment|Alignment" AlignH="Orient" AlignV="Ignore" AlignX="900" X="912" Y="0">   
   <!-- Use pier cap's station for AlignX -->
   <!-- Bearing geometry offset 1 ft from reference -->
   <!-- Bearing geometry -->
</O>

Example 2: Column Under Pier Cap

<!-- Pier cap at station 900" -->
<O N="PierCap" T="Line" Alignment="@MainAlignment|Alignment" AlignX="900" X="900" Y="0" Z="0" />

<!-- Column under pier cap -->
<O N="Column" T="Line" Alignment="@MainAlignment|Alignment" AlignX="900" X="900" Y="-90" Z="-360">
    <!-- Attach at pier cap station -->
    <!-- Column offset 7.5 ft transversely -->
    <!-- Column 30 ft below cap -->         
    <O T="Point" X="0" Y="0" Z="0" />
    <O T="Point" X="0" Y="0" Z="360" />  <!-- 30 ft tall -->
</O>

For more details: See AI-Bridge-Alignment-Guide.md

Alignment Examples

Example 1: Deck Following Alignment

<O N="ConcreteDeck" T="Line" Alignment="@DeckAlignment|Alignment" AlignH="Warp" AlignV="Warp" AlignT="Warp" Section="@DeckSection|Section">
    <O T="Point" X="0" Y="0" Z="0" />        <!-- Start station -->
    <O T="Point" X="1800" Y="0" Z="0" />     <!-- End station (150 ft span) -->
</O>

Behavior:

Deck warps horizontally with horizontal curves
Deck warps vertically with vertical curves
Deck rotates with superelevation/cross-slope
Follows alignment completely in 3D

Example 2: Pier (Rigid, Oriented)

<O N="Pier" T="Volume" Alignment="@DeckAlignment|Alignment" AlignH="Orient" AlignV="Ignore" AlignT="Ignore" AlignX="900" X="900" Y="0" Z="0">
    <!-- Pier rotates to face road direction but doesn't warp -->
    <!-- Elevation is fixed (Ignore), not following vertical profile -->
    <!-- No superelevation rotation (Ignore) -->
</O>

Behavior:

Positioned at station 900" (75 ft), centerline offset
Rotates to face alignment direction (tangent)
Does not follow vertical profile (fixed elevation)
Does not rotate with superelevation

Example 3: Column Foundation (Fixed)

<O N="Foundation" T="Volume" Alignment="@DeckAlignment|Alignment" AlignH="Orient" AlignV="Ignore" AlignT="Ignore" AlignX="900" X="900" Y="0">
    <!-- Foundation placed at station but not rotated or following alignment -->
</O>

Behavior:

Positioned at station 900" (75 ft)
Rotate with horizontal alignment, but do not bend
Uses global elevation (not following vertical profile)
No superelevation effects

5. Complete Example: Bridge Pier with Columns

This example combines all concepts: basic geometry, transformations, hierarchy, and alignment.

<O N="BridgePier" T="Project">
    <!-- Parameters (all in inches) - typical highway bridge pier -->
    <P N="pier_station" V="900" />        <!-- 75 ft along alignment -->
    <P N="column_spacing" V="180" />      <!-- 15 ft spacing -->
    <P N="column_diameter" V="48" />      <!-- 4 ft diameter -->
    <P N="column_height" V="360" />       <!-- 30 ft tall -->
    <P N="cap_width" V="240" />           <!-- 20 ft wide -->
    <P N="cap_depth" V="60" />            <!-- 5 ft deep -->
    <P N="cap_height" V="36" />           <!-- 3 ft tall -->
    
    <!-- Column section (circular) -->
    <O N="ColumnSection" T="Section">
        <O T="Circle" Radius="column_diameter/2" />
    </O>
    
    <!-- Cap section (rectangular) -->
    <O N="CapSection" T="Section">
        <O T="Shape">
            <O T="Point" X="-cap_width/2" Y="-cap_depth/2" />
            <O T="Point" X="cap_width/2" Y="-cap_depth/2" />
            <O T="Point" X="cap_width/2" Y="cap_depth/2" />
            <O T="Point" X="-cap_width/2" Y="cap_depth/2" />
        </O>
    </O>
    
    <!-- Group positioned and oriented on alignment -->
    <O T="Group" Alignment="@MainAlignment|Alignment" AlignH="Orient" AlignV="Ignore" AlignT="Ignore" AlignX="pier_station" X="pier_station" Y="0">
        <!-- Left column -->
        <O T="Line" Section="@ColumnSection|Section" X="0" Y="-column_spacing/2" Z="0">
            <O T="Point" X="0" Y="0" Z="0" />
            <O T="Point" X="0" Y="0" Z="column_height" />
        </O>
        
        <!-- Right column -->
        <O T="Line" Section="@ColumnSection|Section" X="0" Y="column_spacing/2" Z="0">
            <O T="Point" X="0" Y="0" Z="0" />
            <O T="Point" X="0" Y="0" Z="column_height" />
        </O>
        
        <!-- Pier cap (elevated to top of columns) -->
        <O T="Line" Section="@CapSection|Section" X="0" Y="0" Z="column_height">
            <O T="Point" X="0" Y="-column_spacing/2 - column_diameter/2" Z="0" />
            <O T="Point" X="0" Y="column_spacing/2 + column_diameter/2" Z="0" />
        </O>
        
    </O>
</O>

What this example demonstrates:

Basic Geometry:
- Circular column section using Repeat
- Rectangular cap section
- Lines creating vertical columns and transverse cap
Transformations:
- Columns positioned using Y translation (±column_spacing/2 = ±7.5 ft)
- Cap elevated using Z translation (column_height = 30 ft)
- All X, Y, Z explicitly defined for geometry
Hierarchy:
- All elements grouped under common Group
- Group's alignment transformation applies to all children
- Column positions defined relative to group origin
Alignment:
- Group positioned at station 900" (75 ft) using AlignX
- AlignH="Orient" - pier faces road direction
- AlignV="Ignore" - fixed elevation (not following grade)
- AlignT="Ignore" - no superelevation rotation
- Children inherit alignment context from group
- X, Y, Z define actual geometry coordinates

Result: A typical highway bridge pier with two circular columns (4 ft diameter, 30 ft tall, spaced 15 ft apart) and rectangular cap (20 ft × 5 ft × 3 ft), positioned on the alignment at station 75 ft, oriented to face the road direction.

Practical Patterns

Pattern 1: Array of Elements Using Repeat

<!-- Array of columns -->
<O N="Columns" T="Group">
  <P N="NumColumns" V="5" Role="Input"/>
  <P N="Spacing" V="20" Role="Input"/>
  <P N="Height" V="100" Role="Input"/>
  
  <O T="Repeat" N="ColumnArray" S="0" E="NumColumns - 1" I="1" CTRL="i" i="0">
    <O N="Column" T="Line">
      <!-- Path -->
      <O T="Point" X="i*Spacing" Y="0" Z="0"/>
      <O T="Point" X="i*Spacing" Y="0" Z="Height"/>

      <!-- Circular cross-section -->
      <O T="Surface">
        <O T="Circle" Radius="2" Segments="24"/>
      </O>
    </O>
  </O>
</O>

Pattern 2: Conditional Geometry with Guards

<!-- Optional stiffener plates -->
<O N="Girder" T="Line">
  <P N="RequireStiffeners" V="1" Role="Input"/>
  <P N="StiffenerSpacing" V="10"/>
  
  <!-- Main girder geometry -->
  <O T="Point" X="0" Y="0" Z="0"/>
  <O T="Point" X="100" Y="0" Z="0"/>
  
  <O T="Surface">
    <!-- I-beam cross-section here -->
  </O>
  
  <!-- Conditional stiffeners -->
  <O T="Repeat" N="Stiffeners" S="1" E="9" I="1" CTRL="i" i="1" Guard="RequireStiffeners == 1">
    <O T="Surface" Thickness="0.5">
      <O T="Point" X="i*StiffenerSpacing" Y="-6" Z="0"/>
      <O T="Point" X="i*StiffenerSpacing" Y="6" Z="0"/>
      <O T="Point" X="i*StiffenerSpacing" Y="6" Z="24"/>
      <O T="Point" X="i*StiffenerSpacing" Y="-6" Z="24"/>
    </O>
  </O>
</O>

Pattern 3: Composite Assemblies

<!-- Steel connection assembly -->
<O N="Connection" T="Group">
  <P N="BeamDepth" V="24"/>
  <P N="PlateThickness" V="0.75"/>
  
  <!-- End plate -->
  <O N="EndPlate" T="Surface" Thickness="PlateThickness">
    <O T="Point" X="0" Y="-8" Z="0"/>
    <O T="Point" X="0" Y="8" Z="0"/>
    <O T="Point" X="0" Y="8" Z="BeamDepth"/>
    <O T="Point" X="0" Y="-8" Z="BeamDepth"/>
  </O>
  
  <!-- Bolts (represented as small cylinders) -->
  <O T="Repeat" N="Bolts" S="0" E="3" I="1" CTRL="i" i="0">
    <O N="Bolt" T="Line">
      <O T="Point" X="-PlateThickness" Y="0" Z="4+i*5"/>
      <O T="Point" X="2" Y="0" Z="4+i*5"/>

      <O T="Surface">
        <O T="Circle" Radius="0.5" Segments="12"/>
      </O>
    </O>
  </O>
</O>

Pattern 4: Variable Cross-Sections

<!-- Tapered beam with varying depth -->
<O N="TaperedGirder" T="Line">
  <P N="Length" V="120"/>
  <P N="StartDepth" V="36"/>
  <P N="MidDepth" V="48"/>
  <P N="EndDepth" V="36"/>
  
  <!-- Path with multiple segments -->
  <O T="Point" X="0" Y="0" Z="0"/>
  <O T="Point" X="Length/2" Y="0" Z="0"/>
  <O T="Point" X="Length" Y="0" Z="0"/>
  
  <!-- Start section (defined in X-Y plane) -->
  <O T="Surface">
    <O T="Point" Y="-6" X="0"/>
    <O T="Point" Y="6" X="0"/>
    <O T="Point" Y="6" X="StartDepth"/>
    <O T="Point" Y="-6" X="StartDepth"/>
  </O>
  
  <!-- Mid section (deeper, defined in X-Y plane) -->
  <O T="Surface">
    <O T="Point" Y="-6" X="0"/>
    <O T="Point" Y="6" X="0"/>
    <O T="Point" Y="6" X="MidDepth"/>
    <O T="Point" Y="-6" X="MidDepth"/>
  </O>
  
  <!-- End section (defined in X-Y plane) -->
  <O T="Surface">
    <O T="Point" Y="-6" X="0"/>
    <O T="Point" Y="6" X="0"/>
    <O T="Point" Y="6" X="EndDepth"/>
    <O T="Point" Y="-6" X="EndDepth"/>
  </O>
</O>

Pattern 5: Complex Curved Geometry

<!-- Curved bridge girder -->
<O N="CurvedGirder" T="Line">
  <P N="ArcRadius" V="200"/>
  <P N="ArcAngle" V="0.7854"/> <!-- 45 degrees -->
  <P N="Depth" V="48"/>
  
  <!-- Curved path using R parameter -->
  <O T="Point" X="0" Y="0" Z="0"/>
  <O T="Point" X="ArcRadius*sin(ArcAngle/2)" Y="ArcRadius*(1-cos(ArcAngle/2))" Z="0" R="ArcRadius" Segments="20"/>
  <O T="Point" X="ArcRadius*sin(ArcAngle)" Y="ArcRadius*(1-cos(ArcAngle))" Z="0"/>
  
  <!-- I-beam cross-section (defined in X-Y plane) -->
  <O T="Surface">
    <!-- Define I-beam points here (example simplified section) -->
    <O T="Point" Y="-6" X="0"/>
    <O T="Point" Y="6" X="0"/>
    <O T="Point" Y="6" X="Depth"/>
    <O T="Point" Y="-6" X="Depth"/>
  </O>
</O>

Best Practices

1. Use Descriptive Object Names

<!-- Good -->
<O N="ExteriorColumn" T="Line">

<!-- Avoid -->
<O N="C1" T="Line">

2. Parameterize Dimensions

<!-- Good: Easy to modify -->
<O N="Beam" T="Line">
  <P N="Length" V="100" Role="Input"/>
  <P N="Width" V="12" Role="Input"/>
  <P N="Depth" V="24" Role="Input"/>
  <!-- Use parameters in geometry -->
</O>

<!-- Avoid: Hard-coded values -->
<O N="Beam" T="Line">
  <O T="Point" X="0" Y="0" Z="0"/>
  <O T="Point" X="100" Y="0" Z="0"/>
  <!-- ... -->
</O>

<O N="StructuralFrame" T="Group">
  <O N="Columns" T="Group">
    <!-- Column objects -->
  </O>
  
  <O N="Beams" T="Group">
    <!-- Beam objects -->
  </O>
  
  <O N="Bracing" T="Group">
    <!-- Bracing objects -->
  </O>
</O>

4. Optimize Segment Counts

<!-- For display quality, use appropriate segment counts -->
<O T="Circle" Radius="10" Segments="36"/>  <!-- Good for large circles -->
<O T="Circle" Radius="1" Segments="12"/>   <!-- Sufficient for small circles -->
<O T="Circle" Radius="0.5" Segments="8"/>  <!-- Adequate for very small circles -->

5. Use Concise Format When Appropriate

<!-- Concise: When no metadata needed -->
<O T="Point" X="10" Y="5" Z="0"/>

<!-- Verbose: When you need units, descriptions, or roles -->
<O T="Point">
  <P N="X" V="10" UT="Length" D="X position" Role="Input"/>
  <P N="Y" V="5" UT="Length" D="Y position" Role="Input"/>
  <P N="Z" V="0" UT="Length" D="Z position" Role="Input"/>
</O>

6. Control Rendering with Drawing Flags

<!-- Hide end faces for joined elements -->
<O N="BeamSegment" T="Volume" DrawFaceA="0" DrawFaceB="0">
  <!-- geometry -->
</O>

<!-- Show borders for clarity -->
<O N="Plate" T="Surface" DrawBorder="1" Thickness="1">
  <!-- geometry -->
</O>

Common Pitfalls to Avoid

Insufficient Points: Surfaces need minimum 3 points, Text3D needs minimum 3 points

<!-- WRONG: Only 2 points -->
<O T="Surface">
  <O T="Point" X="0" Y="0" Z="0"/>
  <O T="Point" X="10" Y="0" Z="0"/>
</O>

<!-- CORRECT: At least 3 points -->
<O T="Surface">
  <O T="Point" X="0" Y="0" Z="0"/>
  <O T="Point" X="10" Y="0" Z="0"/>
  <O T="Point" X="5" Y="10" Z="0"/>
</O>

Mismatched Cross-Sections: For Line3D/Volume3D, ensure consistent point counts

<!-- PROBLEMATIC: Different point counts can cause issues -->
<O T="Volume">
  <O T="Surface">
    <!-- 4 points -->
  </O>
  <O T="Surface">
    <!-- 5 points - may not interpolate smoothly -->
  </O>
</O>

Zero-Length Geometry: Ensure points are not coincident

<!-- WRONG: Start and end are the same -->
<O T="Line">
  <O T="Point" X="0" Y="0" Z="0"/>
  <O T="Point" X="0" Y="0" Z="0"/> <!-- Same as start! -->
  <O T="Surface">
    <O T="Circle" Radius="5"/>
  </O>
</O>

<!-- CORRECT: Points are different -->
<O T="Line">
  <O T="Point" X="0" Y="0" Z="0"/>
  <O T="Point" X="100" Y="0" Z="0"/>
  <O T="Surface">
    <O T="Circle" Radius="5"/>
  </O>
</O>

Missing Cross-Sections: Line3D objects require at least one Surface3D child

<!-- WRONG: No cross-section -->
<O T="Line">
  <O T="Point" X="0" Y="0" Z="0"/>
  <O T="Point" X="100" Y="0" Z="0"/>
</O>

<!-- CORRECT: Has cross-section -->
<O T="Line">
  <O T="Point" X="0" Y="0" Z="0"/>
  <O T="Point" X="100" Y="0" Z="0"/>
  <O T="Surface">
    <O T="Circle" Radius="5"/>
  </O>
</O>

Incorrect Point Order: Points should be ordered counter-clockwise for proper face orientation

<!-- Ensure points follow counter-clockwise order when viewed from outside -->
<O T="Surface">
  <O T="Point" X="0" Y="0" Z="0"/>
  <O T="Point" X="10" Y="0" Z="0"/>
  <O T="Point" X="10" Y="10" Z="0"/>
  <O T="Point" X="0" Y="10" Z="0"/>
</O>

Excessive Segments: Too many segments can impact performance

<!-- AVOID: Unnecessarily high segment count -->
<O T="Circle" Radius="1" Segments="360"/>

<!-- BETTER: Appropriate for the size -->
<O T="Circle" Radius="1" Segments="24"/>

Coordinate System

OpenBrIM uses a right-handed coordinate system:

X-axis: Typically corresponds to longitudinal direction (along the structure)
Y-axis: Typically corresponds to transverse direction (across the structure)
Z-axis: Typically corresponds to vertical direction (up)

For Line and Volume objects:

The extrusion path is defined by Point children along the X-axis
Cross-sections are defined in the local X-Y plane (where Z=0 for the cross-section points)
The cross-section is extruded along the path from start to end point

Quick Reference Table

XML Type

Purpose

Minimum Children

Key Parameters

Point

3D position

X, Y, Z, R, C, Arc, Segments

Surface

2D surface/face

3 Point

Thickness, IsCutout, DrawBorder

Line

Linear extrusion

2 Point, 1 Surface

BetaAngle (+ inherits from Volume)

Volume

3D volume

2 Surface

DrawFaceA/B, SegmentsAlong/Around, Offsets

Circle

Circular pattern

Radius, Radius2, Segments, StartAngle, EndAngle

Text3D

3D text label

3 Point

Label, FontSize, TextAlign

Key Takeaways

Basic Geometry

Line requires Section + 2+ Points
Volume requires 2+ Surfaces with matching point order
Section defines cross-section for Line objects

Transformations

X, Y, Z - Translation
RX, RY, RZ - Rotation (radians)
Most common: X, Y, RZ together

Hierarchy

Transformations are cumulative
Children transform in parent's coordinate system
Use Groups to organize related geometry

Alignment

None - Position only, no rotation
Orient - Position and rotate, no warping
Warp - Position, rotate, and bend with curvature
Ignore - Use global coordinates
AlignX/Y/Z - Reference point for positioning

Summary

The OpenBrIM 3D visualization system provides a powerful XML-based approach to defining 3D geometry:

Point objects (XML type T="Point") define positions and can create curves/arcs
Surface objects (XML type T="Surface") create 2D faces from Point children
Line objects (XML type T="Line") extrude surfaces along paths
Volume objects (XML type T="Volume") create complex 3D volumes with full control over rendering
Circle objects (XML type T="Circle") generate circular/elliptical patterns
Text3D objects (XML type T="Text3D") add 3D text annotations

Combined with the parametric engine's capabilities (expressions, variables, Repeat, conditional Guards), you can create sophisticated, reusable, and flexible 3D structural models. Always remember to:

Use descriptive names
Parameterize dimensions for flexibility
Ensure correct point counts and ordering
Optimize segment counts for performance
Control rendering with appropriate flags
Group related geometry logically

For more information on the underlying parametric system, refer to the AI-Parametric-Engine-Guide.md document.

PreviousParametric Engine Guide NextBridge Alignment Guide

Last updated 24 days ago

Good night

hashtagOverview

hashtagCore 3D Primitive Types

hashtag1. Basic Geometry Generation

hashtagLine with Section

hashtag2. Surface

hashtag3. Volume

hashtag4. Circle (ShapeCircle)

hashtag5. Text3D

hashtag2. Geometric Transformations

hashtagTranslation and Rotation (Most Common)

hashtagRotation with Custom Origin

hashtag3. Transformation Hierarchy

hashtagExample: Nested Transformations

hashtagPractical Example: Symmetric Structure

hashtagParent Transformations Affect All Children

hashtag4. Alignment-Based Positioning

hashtagWhat Are AlignH, AlignV, AlignT?

hashtagAlignment Modes

hashtag(1) None

hashtag(2) Orient

hashtag(3) Warp

hashtag(4) Ignore

hashtagWhen to Use Which Mode

hashtagAlignH (Horizontal) Usage:

hashtagAlignV (Vertical) Usage:

hashtagAlignT (Transverse) Usage:

hashtagSimple Rule of Thumb

hashtagAlignment Reference Parameters

hashtagAlignment Examples

hashtagExample 1: Deck Following Alignment

hashtagExample 2: Pier (Rigid, Oriented)

hashtagExample 3: Column Foundation (Fixed)

hashtag5. Complete Example: Bridge Pier with Columns

hashtagPractical Patterns

hashtagPattern 1: Array of Elements Using Repeat

hashtagPattern 2: Conditional Geometry with Guards

hashtagPattern 3: Composite Assemblies

hashtagPattern 4: Variable Cross-Sections

hashtagPattern 5: Complex Curved Geometry

hashtagBest Practices

hashtag1. Use Descriptive Object Names

hashtag2. Parameterize Dimensions

hashtag3. Group Related Geometry

hashtag4. Optimize Segment Counts

hashtag5. Use Concise Format When Appropriate

hashtag6. Control Rendering with Drawing Flags

hashtagCommon Pitfalls to Avoid

hashtagCoordinate System

hashtagQuick Reference Table

hashtagKey Takeaways

hashtagBasic Geometry

hashtagTransformations

hashtagHierarchy

hashtagAlignment

hashtagSummary

Overview

Core 3D Primitive Types

1. Basic Geometry Generation

Line with Section

2. Surface

3. Volume

4. Circle (ShapeCircle)

5. Text3D

2. Geometric Transformations

Translation and Rotation (Most Common)

Rotation with Custom Origin

3. Transformation Hierarchy

Example: Nested Transformations

Practical Example: Symmetric Structure

Parent Transformations Affect All Children

4. Alignment-Based Positioning

What Are AlignH, AlignV, AlignT?

Alignment Modes

(1) None

(2) Orient

(3) Warp

(4) Ignore

When to Use Which Mode

AlignH (Horizontal) Usage:

AlignV (Vertical) Usage:

AlignT (Transverse) Usage:

Simple Rule of Thumb

Alignment Reference Parameters

Alignment Examples

Example 1: Deck Following Alignment

Example 2: Pier (Rigid, Oriented)

Example 3: Column Foundation (Fixed)

5. Complete Example: Bridge Pier with Columns

Practical Patterns

Pattern 1: Array of Elements Using Repeat

Pattern 2: Conditional Geometry with Guards

Pattern 3: Composite Assemblies

Pattern 4: Variable Cross-Sections

Pattern 5: Complex Curved Geometry

Best Practices

1. Use Descriptive Object Names

2. Parameterize Dimensions

3. Group Related Geometry

4. Optimize Segment Counts

5. Use Concise Format When Appropriate

6. Control Rendering with Drawing Flags

Common Pitfalls to Avoid

Coordinate System

Quick Reference Table

Key Takeaways

Basic Geometry

Transformations

Hierarchy

Alignment

Summary