Bim Scripting

BIM Scripting

Comprehensive reference for automating Building Information Modeling workflows through scripting, API access, and interoperability platforms. This skill covers the full spectrum of BIM automation --- from visual programming with Dynamo through deep Revit API scripting, pyRevit extension development, IFC/openBIM data exchange, model checking, automated documentation, and cross-platform interoperability via Speckle, BHoM, and Rhino.Inside.Revit.

---

1. BIM Automation Philosophy

Why Script BIM

BIM models are databases disguised as 3D geometry. Every wall, door, room, and duct segment carries structured data --- type, dimensions, material, cost code, fire rating, acoustic class, phase, workset, design option. Manual manipulation of that data does not scale. A 200-unit residential project may contain 40,000+ elements, each with 30--80 parameters. Changing a naming convention, verifying parameter completeness, or exporting coordinated drawing sets by hand is not just slow --- it is error-prone and unrepeatable.

Scripting BIM means treating the model as a programmable data source:

• Read element properties at scale (audit, validate, report).
• Write parameter values in batch (standards enforcement, data enrichment).
• Create elements procedurally (repetitive layouts, adaptive placement).
• Transform geometry computationally (facade panelization, structural optimization).
• Export deliverables automatically (sheets to PDF, models to IFC, data to dashboards).

Manual vs. Automated BIM Workflows

| Workflow | Manual Approach | Automated Approach | Time Savings | |---|---|---|---| | Parameter QA | Open each element, check value | Script scans all elements, flags violations | 95% | | Sheet creation | Place views, adjust crops, add tags one by one | Script generates sheets from template rules | 90% | | Clash detection | Visual inspection in section views | Navisworks / script-based interference check | 85% | | Export to IFC | File > Export > IFC, configure, repeat per model | Batch script exports all linked models with preset mappings | 80% | | Room finish schedule | Manual schedule, manual formatting | API-generated schedule with conditional formatting | 75% | | Design option comparison | Duplicate views, switch options, compare | Script generates comparison report with metrics | 90% | | Naming convention enforcement | Manual review of browser tree | FilteredElementCollector + regex validation | 98% |

ROI of BIM Automation

The return on investment for BIM scripting follows a clear pattern:

1. First script --- 2-8 hours to develop, saves 1-4 hours per use. Break-even after 2-3 uses.
2. Script library (20-50 tools) --- 200-500 hours to develop, saves 10-30 hours per project. Break-even within 1-2 projects.
3. Custom application --- 500-2000 hours to develop, saves 50-200 hours per project. Break-even within 3-5 projects.
4. Enterprise platform --- 2000-10,000 hours to develop, transforms entire practice workflow.

The Automation Spectrum

Level 1: Visual Programming (Dynamo, Grasshopper)
  - Lowest barrier to entry
  - Best for designers who think visually
  - Limited scalability and version control
  - Good for: one-off design explorations, parameter mapping, geometry generation

Level 2: Scripting (Python in Dynamo, pyRevit, RevitPythonShell)
  - Moderate barrier to entry
  - Full API access with Python convenience
  - Version-controllable, shareable
  - Good for: batch operations, custom tools, data workflows

Level 3: Custom Tools (C# add-ins, pyRevit extensions)
  - Higher barrier to entry
  - Compiled performance, custom UI, ribbon integration
  - Deployable to teams
  - Good for: production tools, firm-wide standards enforcement

Level 4: Full Applications (standalone apps, web dashboards, microservices)
  - Highest barrier to entry
  - Complete control over UX and data pipeline
  - Cloud-scalable, multi-user
  - Good for: enterprise BIM management, cross-project analytics

When to Automate vs. When to Model Manually

Automate when:

• The task repeats across projects or phases.
• The task involves more than 50 elements.
• Consistency and auditability are critical (QA/QC, code compliance).
• The output feeds downstream processes (cost, energy, structural analysis).
• Human error risk is high (naming, classification, spatial containment).

Model manually when:

• The task is a one-time creative act (early concept massing).
• Judgment and spatial intuition outweigh procedural logic.
• The element count is small and the rules are ambiguous.
• The cost of developing automation exceeds the cost of manual work.

BIM Maturity Levels and Automation

| BIM Level | Description | Automation Role | |---|---|---| | Level 0 | 2D CAD, no BIM | CAD scripting (AutoLISP, VBA) for drawing automation | | Level 1 | 3D modeling, 2D documentation | Basic Dynamo scripts, parameter management | | Level 2 | Federated models, structured data exchange | IFC workflows, clash detection, model checking | | Level 3 | Integrated single model, full lifecycle data | API-driven analytics, real-time dashboards, AI-assisted QA | | Level 4 (emerging) | Digital twin, IoT-connected, predictive | Continuous model sync, ML-driven optimization, autonomous agents |

---

2. Revit API Fundamentals

Architecture

The Revit API is a .NET framework (C# or VB.NET natively, Python via IronPython or CPython with RevitPythonShell/pyRevit). The object hierarchy:

UIApplication
  └── Application           (Revit application-level settings, version info)
       └── Document          (the .rvt file; model database)
            ├── Elements      (everything in the model)
            ├── Views         (plans, sections, 3D views, schedules)
            ├── Phases        (existing, new construction, demolition)
            ├── DesignOptions  (option sets and options)
            ├── Worksets       (worksharing partitions)
            └── Settings       (project units, line styles, fill patterns)

Element Types

Every object in a Revit model inherits from Element. Key subclasses:

| Class | Description | Example | |---|---|---| | FamilyInstance | Placed instance of a loadable family | Door, window, furniture, fixture | | Wall | System family: wall element | Basic Wall, Curtain Wall, Stacked Wall | | Floor | System family: floor slab | Generic Floor, composite assemblies | | Roof | System family: roof element | Basic Roof, extrusion roof | | Ceiling | System family: ceiling element | Compound ceiling, basic ceiling | | FamilyInstance (structural) | Columns, beams, braces | Steel W-shapes, concrete columns | | Room | Spatial element for architectural spaces | Bounded by room-bounding elements | | Area | Spatial element for area plans | Gross area, rentable area | | View | Any view in the model | ViewPlan, ViewSection, View3D, ViewSheet | | ViewSheet | A sheet for documentation | Contains viewport placements | | ViewSchedule | A schedule/quantity takeoff | Tabular data extraction | | Group | Grouped elements | Model groups, detail groups | | Level | Datum: horizontal reference plane | Defines story heights | | Grid | Datum: vertical reference plane | Structural grid lines | | ReferencePlane | Construction plane | Alignment references |

Categories, Families, Types, Instances

This four-level hierarchy is central to Revit:

Category        (e.g., Doors)
  └── Family      (e.g., Single-Flush)
       └── Type     (e.g., 36" x 84")
            └── Instance  (placed door #1, #2, #3...)

• Category: broad classification (Walls, Doors, Floors, Furniture). Each has a BuiltInCategory enum.
• Family: a parametric definition (.rfa file for loadable families; system families are built-in).
• Type: a named set of parameter values within a family (dimensions, materials).
• Instance: a placed occurrence with instance-specific parameters (location, room, mark).

Parameters

Parameters store all non-geometric data on elements.

| Parameter Kind | Scope | Definition | Access | |---|---|---|---| | Built-in | Hardcoded by Revit | Predefined (e.g., WALL_BASE_OFFSET) | element.get_Parameter(BuiltInParameter.WALL_BASE_OFFSET) | | Project | One project file | Defined in Project Parameters dialog | element.LookupParameter("MyParam") | | Shared | Across projects/families | Defined in Shared Parameters file (.txt) | element.get_Parameter(guid) or by name | | Family | Inside .rfa family | Defined in Family Editor | Exposed as type or instance parameter | | Global | Project-wide value | Not element-bound; referenced by formulas | GlobalParametersManager |

Parameter storage types:

• StorageType.String --- text
• StorageType.Integer --- integers and YesNo (0/1)
• StorageType.Double --- real numbers (always in internal units)
• StorageType.ElementId --- reference to another element (material, type, level)

Transactions

Every model modification must occur inside a Transaction. Without it, the API throws an InvalidOperationException.

# Python (pyRevit / RevitPythonShell)
from Autodesk.Revit.DB import Transaction

doc = __revit__.ActiveUIDocument.Document
t = Transaction(doc, "Batch Update Parameters")
t.Start()

try:
    # ... modify elements ...
    t.Commit()
except Exception as e:
    t.RollBack()
    print("Error: {}".format(e))

Transaction types:

• Transaction --- standard single transaction (most common).
• TransactionGroup --- wraps multiple transactions; can assimilate (merge into one undo) or roll back all.
• SubTransaction --- nested within a Transaction; can roll back independently without aborting the parent.

FilteredElementCollector

The primary mechanism for querying elements in a Revit model. It operates as a builder pattern with filters:

from Autodesk.Revit.DB import (
    FilteredElementCollector, BuiltInCategory,
    ElementCategoryFilter, ElementClassFilter
)

# All walls in the model
walls = FilteredElementCollector(doc) \
    .OfCategory(BuiltInCategory.OST_Walls) \
    .WhereElementIsNotElementType() \
    .ToElements()

# All door types (not instances)
door_types = FilteredElementCollector(doc) \
    .OfCategory(BuiltInCategory.OST_Doors) \
    .WhereElementIsElementType() \
    .ToElements()

# All family instances of a specific class
instances = FilteredElementCollector(doc) \
    .OfClass(FamilyInstance) \
    .ToElements()

# Elements in a specific view
view_elements = FilteredElementCollector(doc, view.Id) \
    .OfCategory(BuiltInCategory.OST_Walls) \
    .ToElements()

Geometry Access

Extracting geometry from Revit elements:

Element
  └── get_Geometry(Options)
       └── GeometryElement (iterable)
            ├── Solid
            │    ├── Faces (FaceArray)
            │    │    └── Face → Surface, UV domain, normal
            │    └── Edges (EdgeArray)
            │         └── Edge → Curve
            ├── GeometryInstance (for family instances)
            │    └── GetInstanceGeometry() → GeometryElement
            ├── Curve (for line-based elements)
            ├── Point
            └── PolyLine

Units

Revit internal units are always:

• Length: feet
• Angle: radians
• Area: square feet
• Volume: cubic feet

Use UnitUtils.ConvertFromInternalUnits() and UnitUtils.ConvertToInternalUnits() for conversion. In Revit 2022+, use UnitTypeId instead of DisplayUnitType.

Events

The Revit API provides application and document-level events:

• Application.DocumentOpened / DocumentClosing / DocumentSaved
• Application.ViewActivated
• Application.DialogBoxShowing (intercept and auto-dismiss dialogs)
• Document.DocumentChanged (react to element modifications)
• UIApplication.Idling (periodic background processing)

External Commands, Applications, Events

| Type | Purpose | Lifecycle | |---|---|---| | IExternalCommand | Single button click action | Runs once per invocation | | IExternalApplication | Ribbon tab/panel setup, startup logic | Runs at Revit startup/shutdown | | IExternalDBApplication | DB-level (no UI) startup logic | For services, updaters | | IExternalEventHandler | Thread-safe model modification from external threads | Raised via ExternalEvent |

C# vs. Python for Revit API

| Criterion | C# | Python (IronPython/CPython) | |---|---|---| | Performance | Compiled; fastest | Interpreted; slower for large loops | | Debugging | Full Visual Studio debugger | Print statements, limited debugger | | Deployment | DLL add-in; requires compilation | Script file; instant edit-run cycle | | Learning curve | Steeper (typed language, project setup) | Gentler (dynamic typing, REPL) | | API coverage | 100% | 100% (same .NET API via clr) | | Ecosystem | NuGet packages, .NET libraries | Python packages (limited in IronPython) | | UI creation | WPF, WinForms with full designer | WPF possible but harder; rpw simplifies | | Best for | Production add-ins, enterprise tools | Rapid prototyping, small utilities, pyRevit |

---

3. Dynamo for Revit

Core Advantages

Dynamo is a visual programming environment integrated with Revit (ships with Revit since 2017). Key strengths:

• Visual dataflow --- nodes connected by wires; intuitive for non-programmers.
• Live Revit connection --- read/write model elements in real time.
• Geometry preview --- 3D preview of computational geometry before committing to Revit.
• Extensibility --- custom nodes in Python, C#, or DesignScript; package manager ecosystem.

Revit-Specific Nodes

Dynamo provides dedicated Revit node categories:

• Selection: Select Model Element, Select Elements by Category, All Elements of Category
• Create: Wall.ByCurveAndHeight, Floor.ByOutlineTypeAndLevel, FamilyInstance.ByPoint
• Modify: Element.SetParameterByName, Element.MoveByVector, Element.OverrideColorInView
• Query: Element.GetParameterValueByName, Element.BoundingBox, Room.Boundaries

Dynamo Player

Dynamo Player exposes Dynamo scripts as simple button-click tools for end users who do not need to understand the graph. Configure inputs as user-facing prompts. Best practice: design scripts specifically for Player with clear input labels and minimal required interaction.

Geometry Kernels

Dynamo uses two separate geometry engines:

1. DesignScript / ASM (Autodesk Shape Manager) --- Dynamo's native geometry kernel.

Creates Points, Curves, Surfaces, Solids in Dynamo's 3D preview.

1. Revit geometry --- the actual BIM model geometry.

These are not interchangeable. A Dynamo Surface is not a Revit Face. Converting between them requires explicit nodes:

• Surface.ByPatch (Dynamo) vs. FaceWall.Create (Revit)
• Curve.ByPoints (Dynamo) vs. ModelCurve.ByCurve (Revit)

Common Revit Workflows in Dynamo

1. Room-based floor finish placement --- query room boundaries, offset curves, create floor elements by outline.
2. Adaptive component placement --- distribute families along curves or surfaces with parameter-driven spacing.
3. Parameter read/write --- bulk read element parameters to Excel, modify, write back.
4. View creation --- generate scope boxes, create dependent views per scope box, apply view templates.
5. Sheet setup --- create sheets from list, place viewports at coordinates, populate titleblock parameters.
6. Keynote management --- read keynote table, validate against model, update keynote parameters.
7. Area analysis --- extract room areas, calculate ratios (net-to-gross, circulation percentage), color-code by metric.

Essential Packages

| Package | Author | Key Capabilities | |---|---|---| | Clockwork | Andreas Dieckmann | 500+ utility nodes; view manipulation, element filtering, string operations | | Rhythm | John Pierson | Revit-focused; sheet management, view manipulation, element creation | | archi-lab | Konrad S

…

Source & license

This open-source skill is cataloged on AgentStack and links to its original source — we do not rehost the code.

• Author: Amanbh997
• Source: Amanbh997/Claude-skills-for-Computational-Designers
• License: MIT

Install and usage instructions live in the source repository linked above.