Joist Girder Weight Tool

Automatically estimates and updates weight parameters for joist girder elements in Revit structural models.

Overview

The Joist Girder Weight tool provides automated weight estimation for steel joist girders using moment-based structural engineering calculations. It calculates weight per linear foot based on the number of joists, point loads, span length, and girder depth, then writes the result to the element's Wt parameter.

Source: src/Tools/Structural/JoistGirderWeight/Features/JoistGirderWeightCalculator.cs:9-74

The tool operates in two modes:

Manual - User-initiated command via ribbon button
Automatic - Triggered on view activation when auto-update is enabled

Features

Weight Calculation

The calculator uses moment-based weight estimation derived from structural engineering principles:

Panel Spacing Calculation - Girder length divided by number of joists
Maximum Moment Calculation - Based on total reaction and span, with adjustments for even/odd panel counts
Section Modulus Estimation - Uses engineering constants for chord and web member sizing
Weight Aggregation - Combines top chord, bottom chord, and web weights

Source: src/Tools/Structural/JoistGirderWeight/Features/JoistGirderWeightCalculator.cs:20-74

Engineering Constants

The calculation employs the following constants:

Constant	Value	Description
Allowable Stress	50.0 ksi	Design stress limit
Section Modulus Factor	0.28356	Geometric section factor
Depth Efficiency Factor	0.95	Effective depth ratio
Top Chord Factor	1.06	Top chord sizing multiplier
Bottom Chord Factor	1.13	Bottom chord sizing multiplier
Web Member Factor	0.7	Web element sizing multiplier
Connection Factor	0.6	Joint efficiency factor

Source: src/Tools/Structural/JoistGirderWeight/Features/JoistGirderWeightCalculator.cs:51-58

Multi-Parameter Support

The estimator supports:

fixed aliases for joist count/length/depth inputs, and
settings-driven regex matching for load parameter names.

Default load regex pattern:

^(?:Panel Point Load|(?:Dead|Live) Load(?: - User Defined)?)$

This matches: Panel Point Load, Dead Load, Dead Load - User Defined, Live Load, Live Load - User Defined.

When multiple parameters match:

one populated Point Load / Panel Point Load / Total Load value is treated as authoritative
otherwise, one Dead Load plus one Live Load are summed
multiple populated parameters within the same classifier group are rejected as ambiguous

Instance parameters take priority over type parameters for same-named params to avoid double-counting.

Point load values are normalized to kips before calculation:

Force-typed parameters (SpecTypeId.Force) are converted from internal units to UnitTypeId.Kips
Unitless numeric parameters are treated as kips
Text parameters are parsed as kips and may include units like 10 kips, 10000 lb, or 45 kN

Input Group	Supported Resolution
Number of Joists	Fixed aliases: `Number of Joists`, `SpaceNum`, `Number of Equal Spaces`
Point Load	Regex pattern list from `Tools.JoistGirderWeight.LoadParameterPatterns`
Length	Fixed aliases: `Cut Length`, `Length`
Depth	Fixed alias: `Depth`
Output	`Wt` (required, writable)

Parameters are resolved in priority order; instance parameters are preferred over type parameters.

Source: src/Tools/Structural/JoistGirderWeight/Features/JoistGirderWeightEstimator.cs Source: src/Tools/Structural/JoistGirderWeight/Features/JoistGirderLoadParser.cs

Element Filtering

The tool targets structural framing elements using settings-driven regex family matching.

Default family regex:

^(?:(?:[BV]?G)|Vulcraft) Joist Girder$

This matches:

G Joist Girder
BG Joist Girder
VG Joist Girder
Vulcraft Joist Girder

Source: src/Tools/Structural/JoistGirderWeight/Features/JoistGirderWeightEstimator.cs Source: src/Tools/Structural/JoistGirderWeight/Settings/JoistGirderWeightSettings.cs

Auto-Update on View Activation

When enabled, the tool automatically updates joist girder weights whenever a view is activated. This is controlled by the AutoUpdateEnabled setting.

Source: src/Tools/Structural/JoistGirderWeight/Hooks/JoistGirderViewActivatedTask.cs:19-44

Architecture

Component Structure

JoistGirderWeight/
├── Features/
│   ├── JoistGirderWeightCalculator.cs    # Pure calculation logic (no Revit dependencies)
│   ├── JoistGirderWeightEstimator.cs     # Revit integration and parameter handling
│   └── UpdateJoistGirderWeightsCommand.cs # Ribbon command implementation
├── Hooks/
│   └── JoistGirderViewActivatedTask.cs   # Auto-update on view change
├── Settings/
│   └── JoistGirderWeightSettings.cs      # Configuration model
├── Assets/
│   └── joist_girder_icon.png             # Ribbon button icon
├── JoistGirderWeightToolModule.cs        # DI and module registration
└── manifest.yml                          # Tool manifest

Key Classes

JoistGirderWeightCalculator

Pure static calculation class with no Revit dependencies, enabling unit testing without Revit runtime.

public static class JoistGirderWeightCalculator
{
    public static double EstimateWeight(
        double numberOfJoists, 
        double pointLoad, 
        double lengthFeet, 
        double depthFeet);
    
    public static bool ValidateInputs(
        double numberOfJoists, 
        double pointLoad, 
        double lengthFeet, 
        double depthFeet);
}

Source: src/Tools/Structural/JoistGirderWeight/Features/JoistGirderWeightCalculator.cs:9-92

JoistGirderWeightEstimator

Orchestrates the update process:

Collects joist girder elements from the document
Validates parameters and computes weights (outside transaction)
Applies updates within a single transaction
Reports success/failure counts

Source: src/Tools/Structural/JoistGirderWeight/Features/JoistGirderWeightEstimator.cs:13-111

UpdateJoistGirderWeightsCommand

The ribbon command entry point. Displays an alert with the update count upon completion.

Source: src/Tools/Structural/JoistGirderWeight/Features/UpdateJoistGirderWeightsCommand.cs:15-42

Error Handling

The tool follows the no-fallback, no-silent-failure principle:

Pre-validation: All elements are validated before the transaction starts
Partial updates: If some elements fail validation, valid ones are updated and a warning is logged
Complete failure: If no elements can be updated, an InvalidOperationException is thrown with a sample error

Source: src/Tools/Structural/JoistGirderWeight/Features/JoistGirderWeightEstimator.cs:84-97

Settings

Configuration Schema

# tools.json or per-user settings
Tools:
  JoistGirderWeight:
    AutoUpdateEnabled: true
    FamilyNamePattern: "^(?:(?:[BV]?G)|Vulcraft) Joist Girder$"
    DeadLoadPattern: "(?:^DL$|Dead\\s*Load)"
    LiveLoadPattern: "(?:^LL$|Live\\s*Load)"
    TotalLoadPattern: "(?:Point\\s*Load|Total\\s*Load)"

Source: src/Tools/Structural/JoistGirderWeight/Settings/JoistGirderWeightSettings.cs

Settings Properties

Property	Type	Default	Description
`AutoUpdateEnabled`	`bool`	`true`	Whether to auto-update weights on view activation
`FamilyNamePattern`	`string`	See above	Regex pattern for joist girder family/type matching
`DeadLoadPattern`	`string`	See above	Regex pattern for dead load parameters
`LiveLoadPattern`	`string`	See above	Regex pattern for live load parameters
`TotalLoadPattern`	`string`	See above	Regex pattern for total/point load parameters

Warning System

When a warning is active:

HasWarning is set to true
AutoUpdateEnabled is forced to false
The UpdateJoistGirderWeights command is disabled in the ribbon

Source: src/Tools/Structural/JoistGirderWeight/JoistGirderWeightToolModule.cs:49-68

Manifest

id: DBTools.Structural.JoistGirderWeight
assembly: DBTools
moduleType: DBTools.Structural.JoistGirderWeight.JoistGirderWeightToolModule
order: 0
tool:
  settings:
    configSection: Tools.JoistGirderWeight
  settingsPacks:
    - key: structural.joist_girder_weight
      title: "Joist Girder Weights"
      warnings:
        - id: core.structural.joist_girder
          title: "Joist Girder Weights Disabled"
          message: "Joist girder weight updates are disabled due to a warning..."
          disableTools:
            - DBTools.UpdateJoistGirderWeights
  ribbonTools:
    - internalName: DBTools.UpdateJoistGirderWeights
      commandType: DBTools.Structural.JoistGirderWeight.UpdateJoistGirderWeightsCommand
      availabilityType: DBTools.App.Tools.Availability.DbtDocumentAvailability
      runProfile: InlineUi
      displayText: "Update Joist\nGirder Weights"
      iconBaseKey: joist_girder
      tooltip: "Update joist girder weights"
      controlKind: PushButton
      order: 30

Source: src/Tools/Structural/JoistGirderWeight/manifest.yml:1-27

Ribbon Configuration

Property	Value
Display Text	"Update Joist\nGirder Weights"
Icon Key	`joist_girder`
Availability	Document-dependent
Run Profile	`InlineUi`
Order	30

Input Validation

Required Constraints

Parameter	Constraint	Rationale
Number of Joists	> 1	At least 2 joists required to create panel points
Point Load	>= 0	Negative loads are physically invalid
Length	> 0	Zero/negative span is invalid
Depth	> 0	Zero/negative depth is invalid

Source: src/Tools/Structural/JoistGirderWeight/Features/JoistGirderWeightCalculator.cs:84-91

Validation Methods

// Throws ArgumentOutOfRangeException for invalid inputs
double weight = JoistGirderWeightCalculator.EstimateWeight(n, load, length, depth);

// Returns bool for pre-validation
bool isValid = JoistGirderWeightCalculator.ValidateInputs(n, load, length, depth);

Testing

The calculator has comprehensive unit test coverage (56 tests) covering:

Valid input scenarios
Scaling behavior (load, length, depth relationships)
Invalid input handling
Edge cases (overflow, underflow, fractional values)
Input validation
Determinism/consistency

Source: src/Tools/Structural/JoistGirderWeight/Tests/JoistGirderWeightCalculatorTests.cs

Running Tests

# Build tests
bash build.sh BuildTests

# Run calculator tests (headless, no Revit required)
dotnet test testing/DBTools.BuildArtifacts.Tests \
  --filter "FullyQualifiedName~JoistGirderWeightCalculator"

Usage Notes

Family Requirements

For the tool to work correctly, joist girder families must:

Belong to the Structural Framing category
Have "joist girder" in the family name or type name
Include at least one parameter from each input group
Have a writable Wt parameter (Double storage type)

Known Limitations

Estimation only: Results are engineering estimates, not certified designs
Single formula: Uses one calculation method regardless of manufacturer specifications
No SJI validation: Does not validate against Steel Joist Institute load tables

Table of Contents