Critical Warnings
ALWAYS expect Direct Shapes on receive. Speckle NEVER creates native Revit elements (walls, doors, floors, beams) when loading data into Revit. Every received object becomes a Direct Shape (generic model). There is NO native element reconstruction. Plan workflows with this constraint from the start.
NEVER rely on custom properties surviving a round-trip back into Revit. Custom properties from Speckle model objects CANNOT be loaded into Revit. Properties are preserved in Speckle's data model and visible in the web viewer, but Revit does NOT attach them to received Direct Shapes.
NEVER expect plans, sections, elevations, or orthographic 3D views to publish. Revit ONLY publishes 3D perspective views. All 2D documentation views and orthographic 3D views are silently excluded.
ALWAYS verify reference point alignment between publish and receive operations. Mismatched reference point settings (Internal Origin vs. Project Base vs. Survey Point) cause objects to appear at incorrect positions. Use the SAME setting on both ends of the workflow.
NEVER assume object categories can be modified after loading. Direct Shapes receive a default category assignment that CANNOT be changed post-load.
Quick Reference
Supported Versions
| Revit Version | Connector Support | OS |
|---|---|---|
| 2022 | Yes | Windows only |
| 2023 | Yes | Windows only |
| 2024 | Yes | Windows only |
| 2025 | Yes | Windows only |
| 2026 | Yes | Windows only |
Data Schema Hierarchy
File > Level > Category > Type > RevitObject
RevitObject Schema
RevitObject extends DataObject with these connector-specific fields:
| Field | Type | Description |
|---|---|---|
type |
string | Element type name (e.g., "Basic Wall - 200mm"). This is the type NAME, NEVER the Revit TypeId. |
family |
string | Family classification |
category |
string | Revit category (Walls, Doors, Windows, etc.) |
level |
string | Associated building level |
location |
Point or Curve | Element position geometry |
referencePointTransform |
4x4 matrix | Transformation based on reference point settings during publish |
views |
Camera[] | Saved 3D perspective view cameras |
displayValue |
Mesh[] | Visual geometry (meshes, lines, points) |
properties |
dict | All captured parameters and metadata |
Proxy Types Used by Revit
| Proxy Type | Purpose |
|---|---|
| RenderMaterial | Color (RGB), opacity, metallic, roughness for element materials |
| Level | Elevation data and level names for floor associations |
| Group | Functional grouping of elements |
Publishing (Revit to Speckle)
Three Publishing Modes
| Mode | Description | Use Case |
|---|---|---|
| Manual Selection | Select specific elements in the Revit viewport before publishing | Targeted exports, quick sharing of specific elements |
| View-Based | Filter and publish elements visible in a specific Revit view | Discipline-specific exports, filtered model sharing |
| Category-Based | Publish all elements belonging to selected categories | Full-model exports by element type |
All modes publish visible elements from the Model category (walls, floors, beams, columns) plus visible gridlines from the Annotation category.
Publishing Settings
| Setting | Default | Description |
|---|---|---|
| Include Linked Models | ON | Linked models appear as separate File collections in Speckle |
| Reference Point | Internal Origin | Coordinate base: Internal Origin, Project Base, or Survey Point |
| Send Rebars As Volumetric | OFF | Exports rebars as solids instead of curves. WARNING: significant performance impact when enabled. |
Properties Captured on Publish
Every published RevitObject includes:
- Element metadata: Element ID, category, workset
- Instance parameters: All instance-level parameter values
- Type parameters: All type-level parameter values
- Material quantities: Volume and area per material
- Structural material properties: Density, compressive strength (where applicable)
3D View Publishing Rules
- ONLY 3D perspective views are published
- Plans are NEVER published
- Sections are NEVER published
- Elevations are NEVER published
- Orthographic 3D views are NEVER published
- Published views appear as Camera objects in the
viewsfield
Receiving (Speckle to Revit)
Direct Shape Behavior
ALL received objects become Direct Shapes. This is a fundamental architectural constraint of the Speckle Revit connector:
| Source Object | Result in Revit |
|---|---|
| Revit wall | Direct Shape |
| Revit door | Direct Shape |
| Rhino Brep | Direct Shape |
| Grasshopper geometry | Direct Shape |
| Tekla beam | Direct Shape |
| IFC element | Direct Shape |
There are ZERO exceptions. Native element reconstruction does NOT exist.
Receive Settings
| Setting | Description |
|---|---|
| Receive Blocks as Families | Toggle for block instance handling — loads blocks as Revit families |
| Reference Point | Align received geometry to Internal Origin, Project Base, or Survey Point |
Material Handling on Receive
- Existing Revit materials with matching names are REUSED (not duplicated)
- Direct Shapes allow material editing after loading
- Family-based blocks (when "Receive Blocks as Families" is ON) also allow material editing
View Creation on Receive
3D views from the source model are automatically created as 3D views in Revit.
Coordinate Systems
Three Reference Points
| Reference Point | Description | When to Use |
|---|---|---|
| Internal Origin | Revit's absolute internal coordinate origin (0,0,0) | Default. Use when all teams agree on Internal Origin placement. |
| Project Base | User-defined project reference point | Use for site-specific positioning across disciplines. |
| Survey Point | Real-world survey coordinate reference | Use when geo-referencing is required (civil/infrastructure projects). |
Coordination Rules
- ALWAYS use the same reference point on publish AND receive
- The
referencePointTransformfield on RevitObject stores the 4x4 transformation matrix applied during publish - Mismatched reference points between source and destination cause positional offset errors
- When federating models from multiple Revit files, ALL files MUST use the same reference point setting
Linked Model Coordinate Handling
When "Include Linked Models" is ON:
- Each linked model publishes as a separate File collection
- Linked models inherit the reference point setting of the host file
- Verify that linked files share the same coordinate system before publishing
Linked Models
Publishing Linked Models
- Enabled by default ("Include Linked Models" toggle)
- Each linked Revit file appears as a separate File collection in Speckle
- Linked model elements are published with their own properties and metadata
- The host file's reference point setting applies to all linked models
Common Linked Model Issues
| Issue | Cause | Solution |
|---|---|---|
| Offset positioning | Different shared coordinates in linked files | ALWAYS verify shared coordinates before publishing |
| Missing linked content | Linked file not loaded in Revit | Ensure all linked files are loaded (not unloaded) before publishing |
| Duplicate elements | Overlapping elements between host and linked files | Review model scope before publishing |
Rebar Handling
Two Rebar Modes
| Mode | Setting | Output | Performance |
|---|---|---|---|
| Default (curves) | "Send Rebars As Volumetric" OFF | Rebar centerline curves | Fast |
| Volumetric (solids) | "Send Rebars As Volumetric" ON | Rebar solid geometry | Slow — significant performance impact |
When to Use Volumetric Rebars
- Use volumetric mode ONLY when visual solid representation is required (e.g., clash detection, visualization)
- NEVER use volumetric mode for large models with thousands of rebars — performance will degrade severely
- Default curve mode is sufficient for quantity takeoffs and structural analysis workflows
Materials
Material Properties Published
| Property | Type | Description |
|---|---|---|
| Color (RGB) | integer | Red, green, blue color values |
| Opacity | float | Material transparency (0.0 = transparent, 1.0 = opaque) |
| Metallic | float | Metallic appearance factor |
| Roughness | float | Surface roughness factor |
Material Round-Trip Rules
- Materials publish as RenderMaterial proxies with color, opacity, metallic, and roughness
- On receive, existing Revit materials with matching names are reused
- Material editing is possible on Direct Shapes and family-based blocks
- Textures are NEVER transferred — Speckle does NOT support texture mapping
Known Limitations
| Limitation | Impact | Workaround |
|---|---|---|
| No native element recreation on receive | ALL objects become Direct Shapes | Accept this constraint; use Speckle for coordination, not round-trip editing |
| No custom property import on receive | Speckle properties not attached to Revit elements | View properties in Speckle web viewer; use Power BI for property analysis |
| No 2D view publishing | Plans, sections, elevations excluded | Export 2D documentation through other channels (PDF, DWG) |
| Categories fixed after load | Cannot reclassify Direct Shapes | Plan category assignments before loading |
| No nested RevitObjects | Geometry exclusively in displayValue |
Access child elements through collection hierarchy, not object nesting |
type field is name, not TypeId |
Cannot programmatically match Revit TypeIds | Use type for display only; match by family + type name combination |
| No texture support | Only basic material properties transfer | Apply textures manually in the receiving application |
| Volumetric rebar performance | Large rebar models slow significantly | Use curve mode for large models; volumetric only for targeted exports |
Revit-Specific Workflow Patterns
Pattern 1: Revit to Grasshopper to Revit
- Publish from Revit (any mode) with correct reference point
- Load in Grasshopper → objects become Data Objects
- Manipulate geometry/properties in Grasshopper
- Publish back from Grasshopper
- Load in Revit → ALL objects become Direct Shapes (no native walls/floors)
Pattern 2: Multi-Discipline Coordination
- Each discipline publishes from Revit to the same Speckle project
- ALL teams MUST use the same reference point setting
- Federated model visible in web viewer
- Use Power BI connector for cross-discipline quantity analysis
Pattern 3: Design Review with External Teams
- Publish model from Revit (view-based mode for filtered content)
- External teams view in Speckle web viewer (no Revit license needed)
- Comments and issues tracked in Speckle
- Properties visible in viewer despite no Revit access
Reference Links
- references/methods.md -- Connector settings, RevitObject fields, and proxy references
- references/examples.md -- Step-by-step publishing and receiving workflows
- references/anti-patterns.md -- Common mistakes and misconceptions