Foundation Tags

Overview

The Foundation Tags tool automates the management and positioning of combined foundation tags in Revit structural documentation. It provides two main capabilities: updating parameter values on foundation elements based on pier associations, and moving tags to consistent corner positions on their tagged footings.

Source: src/Tools/Structural/FoundationTags/manifest.yml:1-4

Location: src/Tools/Structural/FoundationTags/

Tool ID: DBTools.Structural.FoundationTags

Ribbon Location: Structural group, split button foundation_tags

Features

Core Functionality

Feature	Description
Update Combined Tags	Updates pier-footing associations and elevation parameters
Move Combined Tags	Moves tags to corner positions on footings
Auto-Update on View	Automatically updates tags when activating floor/ceiling plans
Linked Element Support	Processes tags on footings in linked Revit models
Selection Sets	Creates timestamped selection sets for modified/skipped elements

Source: src/Tools/Structural/FoundationTags/manifest.yml:19-39

Ribbon Commands

Update Combined Foundation Tags

Updates parameter values on piers and footings in the current view:

Pier Processing: Calculates Foundation Pier Top elevation from Top Level + Top Offset
Footing Processing: Associates each footing with its nearest pier (within 2-foot threshold)
Parameter Updates: Sets Associated Pier (type mark) and Associated Pier Elevation on footings

Source: src/Tools/Structural/FoundationTags/Features/CombinedFoundationTagsUpdater.cs:68-267

Command: DBTools.UpdateCombinedFoundationTags
Display Text: "Update Combined Foundation Tags"
Run Profile: InlineUi

Source: src/Tools/Structural/FoundationTags/manifest.yml:20-29

Move Combined Foundation Tags

Repositions foundation tags to specific corners of their tagged footings:

Tag Collection: Finds structural foundation tags matching configured family patterns
Footing Resolution: Retrieves tagged footing (host or linked)
Corner Calculation: Computes footing corners using geometry tessellation
Position Assignment: Moves tag to the corner specified by the tag name/type

Source: src/Tools/Structural/FoundationTags/Features/CombinedFoundationTagsMover.cs:58-116

Command: DBTools.MoveCombinedFoundationTags
Display Text: "Move Combined Tags"
Run Profile: InlineUi

Source: src/Tools/Structural/FoundationTags/manifest.yml:30-39

View-Activated Auto-Update

When enabled, the tool automatically runs the Update Combined Tags operation when activating floor or ceiling plan views.

If shared-parameter prerequisites are invalid during auto-update, the tool sets warning core.structural.combined_tags, skips execution, and shows a prerequisite banner once per document session.

Source: src/Tools/Structural/FoundationTags/Hooks/CombinedTagsViewActivatedTask.cs Source: src/Tools/Structural/FoundationTags/Features/SharedParameters/FoundationTagsSharedParameterInstaller.cs

Supported View Types:

FloorPlan
CeilingPlan

Source: src/Tools/Structural/FoundationTags/Hooks/CombinedTagsViewActivatedTask.cs:48

Architecture

Directory Structure

src/Tools/Structural/FoundationTags/
+-- Features/                    # Core feature implementations
|   +-- CombinedFoundationTagsUpdater.cs    # Update logic
|   +-- CombinedFoundationTagsMover.cs      # Move logic
|   +-- FoundationTagsGeometry.cs           # Pure geometry calculations
|   +-- UpdateCombinedFoundationTagsCommand.cs
|   +-- MoveCombinedFoundationTagsCommand.cs
+-- Hooks/                       # Event handlers
|   +-- CombinedTagsViewActivatedTask.cs    # Auto-update on view activation
+-- Settings/                    # Configuration
|   +-- FoundationTagsSettings.cs
|   +-- FoundationTagsSettingsPackContext.cs
|   +-- FoundationTagsSettingsPackView.xaml
+-- Tests/                       # Unit tests
|   +-- FoundationTagsGeometryTests.cs
+-- FoundationTagsToolModule.cs  # DI registration
+-- manifest.yml                 # Tool manifest

Key Components

FoundationTagsToolModule

The module class registers settings, services, and settings packs with the dependency injection container.

Source: src/Tools/Structural/FoundationTags/FoundationTagsToolModule.cs:14-91

Registration Points:

RegisterSettings: Binds FoundationTagsSettings to configuration section Tools.FoundationTags
RegisterServices: Registers CombinedTagsViewActivatedTask as IViewActivatedTask
RegisterSettingsPacks: Creates settings UI with warning definitions

Source: src/Tools/Structural/FoundationTags/FoundationTagsToolModule.cs:16-81

CombinedFoundationTagsUpdater

The core service that updates pier and footing parameters.

Source: src/Tools/Structural/FoundationTags/Features/CombinedFoundationTagsUpdater.cs:16-275

Processing Flow:

Collect piers matching configured family patterns
Collect footings matching configured family patterns
For each pier: calculate and set Foundation Pier Top
For each footing: find nearest pier and set association parameters
Create selection sets for modified and skipped elements

Pier-Footing Association:

Uses 2D distance (X, Y only) to find nearest pier
Maximum distance threshold: 2 feet (squared distance = 4.0)
Clears association if no pier found within threshold

Source: src/Tools/Structural/FoundationTags/Features/CombinedFoundationTagsUpdater.cs:167

CombinedFoundationTagsMover

The service that repositions tags to footing corners.

Source: src/Tools/Structural/FoundationTags/Features/CombinedFoundationTagsMover.cs:18-376

Corner Selection Algorithm:

Extract footing geometry points via tessellation
Project corners onto view coordinate system (right/up axes)
Select corner based on tag name using dot product projection

Supported Corner Names:

"Top Right"
"Top Left"
"Bottom Right"
"Bottom Left"

Source: src/Tools/Structural/FoundationTags/Features/FoundationTagsGeometry.cs:142-149

FoundationTagsGeometry

A pure, testable geometry module with no Revit dependencies.

Source: src/Tools/Structural/FoundationTags/Features/FoundationTagsGeometry.cs:112-250

Functions:

Function	Purpose
`SelectCornerByViewOrientation`	Selects corner based on view direction vectors
`FindNearestPoint2D`	Finds nearest candidate point within threshold
`IsValidCornerName`	Validates corner name strings

Source: src/Tools/Structural/FoundationTags/Features/FoundationTagsGeometry.cs:123-249

Data Types:

Type	Description
`Point2D`	2D point for distance calculations
`Point3D`	3D point/vector for projections
`FootingCornerPoints`	Four corners of a rectangular footing
`NearestPointResult`	Result of nearest point search

Source: src/Tools/Structural/FoundationTags/Features/FoundationTagsGeometry.cs:11-106

Settings

Configuration Section

Path: Tools.FoundationTags

Source: src/Tools/Structural/FoundationTags/manifest.yml:7

FoundationTagsSettings

Settings class implementing IAutoUpdateSettings.

Source: src/Tools/Structural/FoundationTags/Settings/FoundationTagsSettings.cs:9-50

Property	Type	Default	Description
`AutoUpdateEnabled`	`bool`	`true`	Enable auto-update on view activation
`HasWarning`	`bool`	`false`	Session-only warning state mirrored into Settings UI (not persisted to disk). Tool enable/disable is driven by warning `core.structural.combined_tags`.
`TagFamilyPatterns`	`List<string>`	See below	Regex patterns for tag families
`PierFamilyPatterns`	`List<string>`	See below	Regex patterns for pier families
`FootingFamilyPatterns`	`List<string>`	See below	Regex patterns for footing families

Source: src/Tools/Structural/FoundationTags/Settings/FoundationTagsSettings.cs:14-49

Warning + remediation flow

Active-document prerequisite checks toggle warning core.structural.combined_tags to disable Foundation Tags commands when required shared parameters are missing/mismatched.
Settings warning cards can expose a Fix action when the owning settings pack context supports remediation (Foundation Tags uses this to run Install/Repair).

Source: src/Tools/Structural/FoundationTags/Hooks/FoundationTagsPrerequisiteMonitorTask.cs:1
Source: src/DBTools.Core/Settings/Shell/SettingsWarningViewModel.cs:1

Default Patterns

Tag Family Patterns (Move Combined Tags):

^DB Pier and Foundation Combined Tag(?: No Elevations)?$

Source: src/Tools/Structural/FoundationTags/Settings/FoundationTagsSettings.cs

Pier Family Patterns (Update Combined Tags):

^Foundation Pier(?: - Round)?$

Source: src/Tools/Structural/FoundationTags/Settings/FoundationTagsSettings.cs

Footing Family Patterns (Update Combined Tags):

^(?:Footing|Pile Cap)-Rectangular$

Source: src/Tools/Structural/FoundationTags/Settings/FoundationTagsSettings.cs

Settings UI

The settings pack provides a configuration panel with:

Auto-Update Toggle: Enable/disable automatic tag updates
Tag Family Patterns: Up to 3 regex patterns for matching tag families
Pier Family Patterns: Up to 3 regex patterns for matching pier families
Footing Family Patterns: Up to 3 regex patterns for matching footing families

Source: src/Tools/Structural/FoundationTags/Settings/FoundationTagsSettingsPackContext.cs:35-48

UI Features:

Pattern validation with regex syntax checking
Add/remove pattern buttons (max 3 per group)
Warning state management with clear action
Pending changes detection

Source: src/Tools/Structural/FoundationTags/Settings/FoundationTagsSettingsPackContext.cs:132-166

Warning System

The tool uses a warning system to disable functionality when issues occur.

Warning Definition:

ID: core.structural.combined_tags
Title: "Combined Foundation Tags Disabled"
Message: "Combined foundation tag updates are disabled due to a warning. Clear the warning to re-enable."

Source: src/Tools/Structural/FoundationTags/manifest.yml:12-18

Disabled Tools When Warning Active:

DBTools.UpdateCombinedFoundationTags
DBTools.MoveCombinedFoundationTags
DBTools.OrganizeFoundationTypes

Source: src/Tools/Structural/FoundationTags/manifest.yml:15-18

Prerequisite Enforcement Mode

Manual command runs and view-activated auto-update now perform strict, non-mutating prerequisite validation.
If required shared parameters are missing/mismatched (including GUID mismatch), the command fails immediately, activates warning core.structural.combined_tags, and does not attempt in-command repair.

Repair remains an explicit settings action via Install/Repair Required Parameters in the Foundation Tags settings pack.

Repair behavior:

Install/Repair deletes all conflicting parameter definitions that share the required parameter names but do not match the required GUID (including duplicate-name collisions), then re-binds the correct shared parameter definitions from the DBTools shared parameter file.
The Combined Tags updater reads/writes these prerequisite parameters by GUID (not name) to ensure deterministic behavior even in models that previously had name collisions.

Source: src/Tools/Structural/FoundationTags/Features/SharedParameters/FoundationTagsSharedParameterInstaller.cs:221 Source: src/Tools/Structural/FoundationTags/Features/SharedParameters/FoundationTagsSharedParameterInstaller.cs:384 Source: src/Tools/Structural/FoundationTags/Features/CombinedFoundationTagsUpdater.cs:141 Source: src/Tools/Structural/FoundationTags/Features/CombinedFoundationTagsUpdater.cs:183 Source: src/Tools/Structural/FoundationTags/Features/UpdateCombinedFoundationTagsHandler.cs:51 Source: src/Tools/Structural/FoundationTags/Features/MoveCombinedFoundationTagsHandler.cs:47 Source: src/Tools/Structural/FoundationTags/Hooks/CombinedTagsViewActivatedTask.cs:64

Manifest

id: DBTools.Structural.FoundationTags
assembly: DBTools
moduleType: DBTools.Structural.FoundationTags.FoundationTagsToolModule
order: 0
tool:
  settings:
    configSection: Tools.FoundationTags
  settingsPacks:
    - key: structural.foundation_tags
      title: "Combined Foundation Tags"
      warnings:
        - id: core.structural.combined_tags
          title: "Combined Foundation Tags Disabled"
          message: "Combined foundation tag updates are disabled due to a warning. Clear the warning to re-enable."
          disableTools:
            - DBTools.UpdateCombinedFoundationTags
            - DBTools.MoveCombinedFoundationTags
            - DBTools.OrganizeFoundationTypes
  ribbonTools:
    - internalName: DBTools.UpdateCombinedFoundationTags
      commandType: DBTools.Structural.FoundationTags.UpdateCombinedFoundationTagsCommand
      availabilityType: DBTools.App.Tools.Availability.DbtActiveViewAvailability
      runProfile: InlineUi
      displayText: "Update Combined\nFoundation Tags"
      iconBaseKey: update_combined
      tooltip: "Update combined foundation tag instances"
      controlKind: SplitButtonItem
      splitGroup: foundation_tags
      order: 0
    - internalName: DBTools.MoveCombinedFoundationTags
      commandType: DBTools.Structural.FoundationTags.MoveCombinedFoundationTagsCommand
      availabilityType: DBTools.App.Tools.Availability.DbtActiveViewAvailability
      runProfile: InlineUi
      displayText: "Move Combined Tags"
      iconBaseKey: move_combined
      tooltip: "Move combined foundation tags to corner positions"
      controlKind: SplitButtonItem
      splitGroup: foundation_tags
      order: 1

Source: src/Tools/Structural/FoundationTags/manifest.yml:1-39

Integration Points

Revit API Integration

The tool interacts with Revit through standard API patterns:

FilteredElementCollector: Queries piers, footings, and tags
FamilyInstance.Location: Extracts element positions
Parameter.Set/ClearValue: Updates element parameters
IndependentTag.TagHeadPosition: Repositions tags
SelectionFilterElement: Creates selection sets for results
RevitLinkInstance: Supports linked model elements

Source: src/Tools/Structural/FoundationTags/Features/CombinedFoundationTagsMover.cs:67-189

Transaction Management

Operations use the ITransactionRunner interface for transaction management:

_tx.RunAsync(_doc, "DB Tools - Update Combined Foundation Tags...", doc =>
{
    // Parameter updates
});

Source: src/Tools/Structural/FoundationTags/Features/CombinedFoundationTagsUpdater.cs:96-222

System Architecture - Overall system design
Organize Foundation Types - Related foundation tool

Testing

The tool includes unit tests for the geometry module:

Test File: FoundationTagsGeometryTests.cs

Source: src/Tools/Structural/FoundationTags/Tests/FoundationTagsGeometryTests.cs:12

Test Categories:

Corner selection by view orientation
Rotated view handling
Case-insensitive corner name matching
Invalid input handling
Nearest point 2D search
Corner name validation

Source: src/Tools/Structural/FoundationTags/Tests/FoundationTagsGeometryTests.cs:24-432

Run headless tests:

dotnet test src/Tools/Structural/FoundationTags/Tests/DBTools.Structural.FoundationTags.Tests.csproj -c Release

Documentation Status: Complete

Last Updated: 2026-01-24

Source Review: Verified against source files in src/Tools/Structural/FoundationTags/

Table of Contents

Foundation Tags

Overview

Features

Core Functionality

Ribbon Commands

Update Combined Foundation Tags

Move Combined Foundation Tags

View-Activated Auto-Update

Architecture

Directory Structure

Key Components

FoundationTagsToolModule

CombinedFoundationTagsUpdater

CombinedFoundationTagsMover

FoundationTagsGeometry

Settings

Configuration Section

FoundationTagsSettings

Warning + remediation flow

Default Patterns

Settings UI

Warning System

Prerequisite Enforcement Mode

Manifest

Integration Points

Revit API Integration

Transaction Management

Related Documentation

Testing