# 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:**
```xml
```
**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:**
```xml
```
### 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:**
```xml
```
**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:**
```xml
```
### 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:**
```xml
```
## 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:**
```xml
```
**Transformation sequence:**
1. Line is created at origin with points along X-axis
2. Translated by (500, 300)
3. 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:**
```xml
```
***
## 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
```xml
```
**Transformation sequence:**
1. **Group level:**
* Translate by (30, -40)
* Rotate coordinate system by π/8
2. **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
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
```xml
```
**Result:** Two identical columns positioned symmetrically at X = 250.
***
### Parent Transformations Affect All Children
```xml
```
***
## 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:**
1. **Bearing on pier cap** - Use pier cap's station as bearing's AlignX
2. **Column under pier cap** - Use pier cap's station as column's AlignX
3. **Objects referenced to a common point** - Override attachment to align with parent object
**Example 1: Bearing on Pier Cap**
```xml
```
**Example 2: Column Under Pier Cap**
```xml
```
**For more details:** See `AI-Bridge-Alignment-Guide.md`
***
### Alignment Examples
#### Example 1: Deck Following Alignment
```xml
```
**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)
```xml
```
**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)
```xml
```
**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.
```xml
```
**What this example demonstrates:**
1. **Basic Geometry:**
* Circular column section using Repeat
* Rectangular cap section
* Lines creating vertical columns and transverse cap
2. **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
3. **Hierarchy:**
* All elements grouped under common Group
* Group's alignment transformation applies to all children
* Column positions defined relative to group origin
4. **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
```xml
```
### Pattern 2: Conditional Geometry with Guards
```xml
```
### Pattern 3: Composite Assemblies
```xml
```
### Pattern 4: Variable Cross-Sections
```xml
```
### Pattern 5: Complex Curved Geometry
```xml
```
## Best Practices
### 1. Use Descriptive Object Names
```xml
```
### 2. Parameterize Dimensions
```xml
```
### 3. Group Related Geometry
```xml
```
### 4. Optimize Segment Counts
```xml
```
### 5. Use Concise Format When Appropriate
```xml
```
### 6. Control Rendering with Drawing Flags
```xml
```
## Common Pitfalls to Avoid
1. **Insufficient Points:** Surfaces need minimum 3 points, Text3D needs minimum 3 points
```xml
```
2. **Mismatched Cross-Sections:** For Line3D/Volume3D, ensure consistent point counts
```xml
```
3. **Zero-Length Geometry:** Ensure points are not coincident
```xml
```
4. **Missing Cross-Sections:** Line3D objects require at least one Surface3D child
```xml
```
5. **Incorrect Point Order:** Points should be ordered counter-clockwise for proper face orientation
```xml
```
6. **Excessive Segments:** Too many segments can impact performance
```xml
```
## 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 | 0 | 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 | 0 | 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:
1. **Point** objects (XML type `T="Point"`) define positions and can create curves/arcs
2. **Surface** objects (XML type `T="Surface"`) create 2D faces from Point children
3. **Line** objects (XML type `T="Line"`) extrude surfaces along paths
4. **Volume** objects (XML type `T="Volume"`) create complex 3D volumes with full control over rendering
5. **Circle** objects (XML type `T="Circle"`) generate circular/elliptical patterns
6. **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.